Documentation/media/uapi/v4l/vidioc-g-modulator.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_MODULATOR:
   4
   5 ********************************************
   6 ioctl VIDIOC_G_MODULATOR, VIDIOC_S_MODULATOR
   7 ********************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_MODULATOR - VIDIOC_S_MODULATOR - Get or set modulator attributes
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, VIDIOC_G_MODULATOR, struct v4l2_modulator *argp )
  19     :name: VIDIOC_G_MODULATOR
  20
  21 .. c:function:: int ioctl( int fd, VIDIOC_S_MODULATOR, const struct v4l2_modulator *argp )
  22     :name: VIDIOC_S_MODULATOR
  23
  24
  25 Arguments
  26 =========
  27
  28 ``fd``
  29     File descriptor returned by :ref:`open() <func-open>`.
  30
  31 ``argp``
  32     Pointer to struct :c:type:`v4l2_modulator`.
  33
  34
  35 Description
  36 ===========
  37
  38 To query the attributes of a modulator applications initialize the
  39 ``index`` field and zero out the ``reserved`` array of a struct
  40 :c:type:`v4l2_modulator` and call the
  41 :ref:`VIDIOC_G_MODULATOR <VIDIOC_G_MODULATOR>` ioctl with a pointer to this structure. Drivers
  42 fill the rest of the structure or return an ``EINVAL`` error code when the
  43 index is out of bounds. To enumerate all modulators applications shall
  44 begin at index zero, incrementing by one until the driver returns
  45 EINVAL.
  46
  47 Modulators have two writable properties, an audio modulation set and the
  48 radio frequency. To change the modulated audio subprograms, applications
  49 initialize the ``index`` and ``txsubchans`` fields and the ``reserved``
  50 array and call the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl. Drivers may choose a
  51 different audio modulation if the request cannot be satisfied. However
  52 this is a write-only ioctl, it does not return the actual audio
  53 modulation selected.
  54
  55 :ref:`SDR <sdr>` specific modulator types are ``V4L2_TUNER_SDR`` and
  56 ``V4L2_TUNER_RF``. For SDR devices ``txsubchans`` field must be
  57 initialized to zero. The term 'modulator' means SDR transmitter in this
  58 context.
  59
  60 To change the radio frequency the
  61 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
  62
  63
  64 .. tabularcolumns:: |p{2.9cm}|p{2.9cm}|p{5.8cm}|p{2.9cm}|p{3.0cm}|
  65
  66 .. c:type:: v4l2_modulator
  67
  68 .. flat-table:: struct v4l2_modulator
  69     :header-rows:  0
  70     :stub-columns: 0
  71     :widths:       1 1 2 1 1
  72
  73     * - __u32
  74       - ``index``
  75       - Identifies the modulator, set by the application.
  76     * - __u8
  77       - ``name``\ [32]
  78       - Name of the modulator, a NUL-terminated ASCII string.
  79
  80         This information is intended for the user.
  81     * - __u32
  82       - ``capability``
  83       - Modulator capability flags. No flags are defined for this field,
  84         the tuner flags in struct :c:type:`v4l2_tuner` are
  85         used accordingly. The audio flags indicate the ability to encode
  86         audio subprograms. They will *not* change for example with the
  87         current video standard.
  88     * - __u32
  89       - ``rangelow``
  90       - The lowest tunable frequency in units of 62.5 KHz, or if the
  91         ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
  92         62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
  93         set, in units of 1 Hz.
  94     * - __u32
  95       - ``rangehigh``
  96       - The highest tunable frequency in units of 62.5 KHz, or if the
  97         ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units of
  98         62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` is
  99         set, in units of 1 Hz.
 100     * - __u32
 101       - ``txsubchans``
 102       - With this field applications can determine how audio sub-carriers
 103         shall be modulated. It contains a set of flags as defined in
 104         :ref:`modulator-txsubchans`.
 105
 106         .. note::
 107
 108            The tuner ``rxsubchans`` flags  are reused, but the
 109            semantics are different. Video output devices
 110            are assumed to have an analog or PCM audio input with 1-3
 111            channels. The ``txsubchans`` flags select one or more channels
 112            for modulation, together with some audio subprogram indicator,
 113            for example, a stereo pilot tone.
 114     * - __u32
 115       - ``type``
 116       - :cspan:`2` Type of the modulator, see :c:type:`v4l2_tuner_type`.
 117     * - __u32
 118       - ``reserved``\ [3]
 119       - Reserved for future extensions.
 120
 121         Drivers and applications must set the array to zero.
 122
 123
 124
 125 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 126
 127 .. _modulator-txsubchans:
 128
 129 .. flat-table:: Modulator Audio Transmission Flags
 130     :header-rows:  0
 131     :stub-columns: 0
 132     :widths:       3 1 4
 133
 134     * - ``V4L2_TUNER_SUB_MONO``
 135       - 0x0001
 136       - Modulate channel 1 as mono audio, when the input has more
 137         channels, a down-mix of channel 1 and 2. This flag does not
 138         combine with ``V4L2_TUNER_SUB_STEREO`` or
 139         ``V4L2_TUNER_SUB_LANG1``.
 140     * - ``V4L2_TUNER_SUB_STEREO``
 141       - 0x0002
 142       - Modulate channel 1 and 2 as left and right channel of a stereo
 143         audio signal. When the input has only one channel or two channels
 144         and ``V4L2_TUNER_SUB_SAP`` is also set, channel 1 is encoded as
 145         left and right channel. This flag does not combine with
 146         ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_LANG1``. When the
 147         driver does not support stereo audio it shall fall back to mono.
 148     * - ``V4L2_TUNER_SUB_LANG1``
 149       - 0x0008
 150       - Modulate channel 1 and 2 as primary and secondary language of a
 151         bilingual audio signal. When the input has only one channel it is
 152         used for both languages. It is not possible to encode the primary
 153         or secondary language only. This flag does not combine with
 154         ``V4L2_TUNER_SUB_MONO``, ``V4L2_TUNER_SUB_STEREO`` or
 155         ``V4L2_TUNER_SUB_SAP``. If the hardware does not support the
 156         respective audio matrix, or the current video standard does not
 157         permit bilingual audio the :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall
 158         return an ``EINVAL`` error code and the driver shall fall back to mono
 159         or stereo mode.
 160     * - ``V4L2_TUNER_SUB_LANG2``
 161       - 0x0004
 162       - Same effect as ``V4L2_TUNER_SUB_SAP``.
 163     * - ``V4L2_TUNER_SUB_SAP``
 164       - 0x0004
 165       - When combined with ``V4L2_TUNER_SUB_MONO`` the first channel is
 166         encoded as mono audio, the last channel as Second Audio Program.
 167         When the input has only one channel it is used for both audio
 168         tracks. When the input has three channels the mono track is a
 169         down-mix of channel 1 and 2. When combined with
 170         ``V4L2_TUNER_SUB_STEREO`` channel 1 and 2 are encoded as left and
 171         right stereo audio, channel 3 as Second Audio Program. When the
 172         input has only two channels, the first is encoded as left and
 173         right channel and the second as SAP. When the input has only one
 174         channel it is used for all audio tracks. It is not possible to
 175         encode a Second Audio Program only. This flag must combine with
 176         ``V4L2_TUNER_SUB_MONO`` or ``V4L2_TUNER_SUB_STEREO``. If the
 177         hardware does not support the respective audio matrix, or the
 178         current video standard does not permit SAP the
 179         :ref:`VIDIOC_S_MODULATOR <VIDIOC_G_MODULATOR>` ioctl shall return an ``EINVAL`` error code and
 180         driver shall fall back to mono or stereo mode.
 181     * - ``V4L2_TUNER_SUB_RDS``
 182       - 0x0010
 183       - Enable the RDS encoder for a radio FM transmitter.
 184
 185
 186 Return Value
 187 ============
 188
 189 On success 0 is returned, on error -1 and the ``errno`` variable is set
 190 appropriately. The generic error codes are described at the
 191 :ref:`Generic Error Codes <gen-errors>` chapter.
 192
 193 EINVAL
 194     The struct :c:type:`v4l2_modulator` ``index`` is
 195     out of bounds.