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

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