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