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

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _VIDIOC_G_TUNER:
   4
   5 ************************************
   6 ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
   7 ************************************
   8
   9 Name
  10 ====
  11
  12 VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. c:function:: int ioctl( int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp )
  19     :name: VIDIOC_G_TUNER
  20
  21 .. c:function:: int ioctl( int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp )
  22     :name: VIDIOC_S_TUNER
  23
  24
  25 Arguments
  26 =========
  27
  28 ``fd``
  29     File descriptor returned by :ref:`open() <func-open>`.
  30
  31 ``argp``
  32
  33
  34 Description
  35 ===========
  36
  37 To query the attributes of a tuner applications initialize the ``index``
  38 field and zero out the ``reserved`` array of a struct
  39 :c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl
  40 with a pointer to this structure. Drivers fill the rest of the structure
  41 or return an ``EINVAL`` error code when the index is out of bounds. To
  42 enumerate all tuners applications shall begin at index zero,
  43 incrementing by one until the driver returns ``EINVAL``.
  44
  45 Tuners have two writable properties, the audio mode and the radio
  46 frequency. To change the audio mode, applications initialize the
  47 ``index``, ``audmode`` and ``reserved`` fields and call the
  48 ``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
  49 which is determined by the current video input. Drivers may choose a
  50 different audio mode if the requested mode is invalid or unsupported.
  51 Since this is a write-only ioctl, it does not return the actually
  52 selected audio mode.
  53
  54 :ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
  55 ``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
  56 to zero. The term 'tuner' means SDR receiver in this context.
  57
  58 To change the radio frequency the
  59 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
  60
  61
  62  .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{6.6cm}|p{6.6cm}|
  63
  64 .. c:type:: v4l2_tuner
  65
  66 .. cssclass:: longtable
  67
  68 .. flat-table:: struct v4l2_tuner
  69     :header-rows:  0
  70     :stub-columns: 0
  71
  72     * - __u32
  73       - ``index``
  74       - :cspan:`1` Identifies the tuner, set by the application.
  75     * - __u8
  76       - ``name``\ [32]
  77       - :cspan:`1`
  78
  79         Name of the tuner, a NUL-terminated ASCII string.
  80
  81         This information is intended for the user.
  82     * - __u32
  83       - ``type``
  84       - :cspan:`1` Type of the tuner, see :c:type:`v4l2_tuner_type`.
  85     * - __u32
  86       - ``capability``
  87       - :cspan:`1`
  88
  89         Tuner capability flags, see :ref:`tuner-capability`. Audio flags
  90         indicate the ability to decode audio subprograms. They will *not*
  91         change, for example with the current video standard.
  92
  93         When the structure refers to a radio tuner the
  94         ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
  95         ``V4L2_TUNER_CAP_NORM`` flags can't be used.
  96
  97         If multiple frequency bands are supported, then ``capability`` is
  98         the union of all ``capability`` fields of each struct
  99         :c:type:`v4l2_frequency_band`.
 100     * - __u32
 101       - ``rangelow``
 102       - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
 103         if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
 104         of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
 105         is set, in units of 1 Hz. If multiple frequency bands are
 106         supported, then ``rangelow`` is the lowest frequency of all the
 107         frequency bands.
 108     * - __u32
 109       - ``rangehigh``
 110       - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
 111         or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
 112         units of 62.5 Hz, or if the ``capability`` flag
 113         ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
 114         frequency bands are supported, then ``rangehigh`` is the highest
 115         frequency of all the frequency bands.
 116     * - __u32
 117       - ``rxsubchans``
 118       - :cspan:`1`
 119
 120         Some tuners or audio decoders can determine the received audio
 121         subprograms by analyzing audio carriers, pilot tones or other
 122         indicators. To pass this information drivers set flags defined in
 123         :ref:`tuner-rxsubchans` in this field. For example:
 124     * -
 125       -
 126       - ``V4L2_TUNER_SUB_MONO``
 127       - receiving mono audio
 128     * -
 129       -
 130       - ``STEREO | SAP``
 131       - receiving stereo audio and a secondary audio program
 132     * -
 133       -
 134       - ``MONO | STEREO``
 135       - receiving mono or stereo audio, the hardware cannot distinguish
 136     * -
 137       -
 138       - ``LANG1 | LANG2``
 139       - receiving bilingual audio
 140     * -
 141       -
 142       - ``MONO | STEREO | LANG1 | LANG2``
 143       - receiving mono, stereo or bilingual audio
 144     * -
 145       -
 146       - :cspan:`1`
 147
 148         When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
 149         ``_SAP`` flag is cleared in the ``capability`` field, the
 150         corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.
 151
 152         This field is valid only if this is the tuner of the current video
 153         input, or when the structure refers to a radio tuner.
 154     * - __u32
 155       - ``audmode``
 156       - :cspan:`1`
 157
 158         The selected audio mode, see :ref:`tuner-audmode` for valid
 159         values. The audio mode does not affect audio subprogram detection,
 160         and like a :ref:`control` it does not automatically
 161         change unless the requested mode is invalid or unsupported. See
 162         :ref:`tuner-matrix` for possible results when the selected and
 163         received audio programs do not match.
 164
 165         Currently this is the only field of struct
 166         struct :c:type:`v4l2_tuner` applications can change.
 167     * - __u32
 168       - ``signal``
 169       - :cspan:`1` The signal strength if known.
 170
 171         Ranging from 0 to 65535. Higher values indicate a better signal.
 172     * - __s32
 173       - ``afc``
 174       - :cspan:`1` Automatic frequency control.
 175
 176         When the ``afc`` value is negative, the frequency is too
 177         low, when positive too high.
 178     * - __u32
 179       - ``reserved``\ [4]
 180       - :cspan:`1` Reserved for future extensions.
 181
 182         Drivers and applications must set the array to zero.
 183
 184
 185
 186 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 187
 188 .. c:type:: v4l2_tuner_type
 189
 190 .. flat-table:: enum v4l2_tuner_type
 191     :header-rows:  0
 192     :stub-columns: 0
 193     :widths:       3 1 6
 194
 195     * - ``V4L2_TUNER_RADIO``
 196       - 1
 197       - Tuner supports radio
 198     * - ``V4L2_TUNER_ANALOG_TV``
 199       - 2
 200       - Tuner supports analog TV
 201     * - ``V4L2_TUNER_SDR``
 202       - 4
 203       - Tuner controls the A/D and/or D/A block of a
 204         Software Digital Radio (SDR)
 205     * - ``V4L2_TUNER_RF``
 206       - 5
 207       - Tuner controls the RF part of a Software Digital Radio (SDR)
 208
 209
 210 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 211
 212 .. _tuner-capability:
 213
 214 .. cssclass:: longtable
 215
 216 .. flat-table:: Tuner and Modulator Capability Flags
 217     :header-rows:  0
 218     :stub-columns: 0
 219     :widths:       3 1 4
 220
 221     * - ``V4L2_TUNER_CAP_LOW``
 222       - 0x0001
 223       - When set, tuning frequencies are expressed in units of 62.5 Hz
 224         instead of 62.5 kHz.
 225     * - ``V4L2_TUNER_CAP_NORM``
 226       - 0x0002
 227       - This is a multi-standard tuner; the video standard can or must be
 228         switched. (B/G PAL tuners for example are typically not considered
 229         multi-standard because the video standard is automatically
 230         determined from the frequency band.) The set of supported video
 231         standards is available from the struct
 232         :c:type:`v4l2_input` pointing to this tuner, see the
 233         description of ioctl :ref:`VIDIOC_ENUMINPUT`
 234         for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
 235         capability.
 236     * - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
 237       - 0x0004
 238       - If set, then this tuner supports the hardware seek functionality
 239         where the seek stops when it reaches the end of the frequency
 240         range.
 241     * - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
 242       - 0x0008
 243       - If set, then this tuner supports the hardware seek functionality
 244         where the seek wraps around when it reaches the end of the
 245         frequency range.
 246     * - ``V4L2_TUNER_CAP_STEREO``
 247       - 0x0010
 248       - Stereo audio reception is supported.
 249     * - ``V4L2_TUNER_CAP_LANG1``
 250       - 0x0040
 251       - Reception of the primary language of a bilingual audio program is
 252         supported. Bilingual audio is a feature of two-channel systems,
 253         transmitting the primary language monaural on the main audio
 254         carrier and a secondary language monaural on a second carrier.
 255         Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
 256     * - ``V4L2_TUNER_CAP_LANG2``
 257       - 0x0020
 258       - Reception of the secondary language of a bilingual audio program
 259         is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
 260         capability.
 261     * - ``V4L2_TUNER_CAP_SAP``
 262       - 0x0020
 263       - Reception of a secondary audio program is supported. This is a
 264         feature of the BTSC system which accompanies the NTSC video
 265         standard. Two audio carriers are available for mono or stereo
 266         transmissions of a primary language, and an independent third
 267         carrier for a monaural secondary language. Only
 268         ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
 269
 270         .. note::
 271
 272            The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP``
 273            flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
 274            supports the ``V4L2_STD_NTSC_M`` video standard.
 275     * - ``V4L2_TUNER_CAP_RDS``
 276       - 0x0080
 277       - RDS capture is supported. This capability is only valid for radio
 278         tuners.
 279     * - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
 280       - 0x0100
 281       - The RDS data is passed as unparsed RDS blocks.
 282     * - ``V4L2_TUNER_CAP_RDS_CONTROLS``
 283       - 0x0200
 284       - The RDS data is parsed by the hardware and set via controls.
 285     * - ``V4L2_TUNER_CAP_FREQ_BANDS``
 286       - 0x0400
 287       - The :ref:`VIDIOC_ENUM_FREQ_BANDS`
 288         ioctl can be used to enumerate the available frequency bands.
 289     * - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
 290       - 0x0800
 291       - The range to search when using the hardware seek functionality is
 292         programmable, see
 293         :ref:`VIDIOC_S_HW_FREQ_SEEK` for
 294         details.
 295     * - ``V4L2_TUNER_CAP_1HZ``
 296       - 0x1000
 297       - When set, tuning frequencies are expressed in units of 1 Hz
 298         instead of 62.5 kHz.
 299
 300
 301
 302 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 303
 304 .. _tuner-rxsubchans:
 305
 306 .. flat-table:: Tuner Audio Reception Flags
 307     :header-rows:  0
 308     :stub-columns: 0
 309     :widths:       3 1 4
 310
 311     * - ``V4L2_TUNER_SUB_MONO``
 312       - 0x0001
 313       - The tuner receives a mono audio signal.
 314     * - ``V4L2_TUNER_SUB_STEREO``
 315       - 0x0002
 316       - The tuner receives a stereo audio signal.
 317     * - ``V4L2_TUNER_SUB_LANG1``
 318       - 0x0008
 319       - The tuner receives the primary language of a bilingual audio
 320         signal. Drivers must clear this flag when the current video
 321         standard is ``V4L2_STD_NTSC_M``.
 322     * - ``V4L2_TUNER_SUB_LANG2``
 323       - 0x0004
 324       - The tuner receives the secondary language of a bilingual audio
 325         signal (or a second audio program).
 326     * - ``V4L2_TUNER_SUB_SAP``
 327       - 0x0004
 328       - The tuner receives a Second Audio Program.
 329
 330         .. note::
 331
 332            The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP``
 333            flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies
 334            when the current video standard is ``V4L2_STD_NTSC_M``.
 335     * - ``V4L2_TUNER_SUB_RDS``
 336       - 0x0010
 337       - The tuner receives an RDS channel.
 338
 339
 340
 341 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 342
 343 .. _tuner-audmode:
 344
 345 .. flat-table:: Tuner Audio Modes
 346     :header-rows:  0
 347     :stub-columns: 0
 348     :widths:       3 1 4
 349
 350     * - ``V4L2_TUNER_MODE_MONO``
 351       - 0
 352       - Play mono audio. When the tuner receives a stereo signal this a
 353         down-mix of the left and right channel. When the tuner receives a
 354         bilingual or SAP signal this mode selects the primary language.
 355     * - ``V4L2_TUNER_MODE_STEREO``
 356       - 1
 357       - Play stereo audio. When the tuner receives bilingual audio it may
 358         play different languages on the left and right channel or the
 359         primary language is played on both channels.
 360
 361         Playing different languages in this mode is deprecated. New
 362         drivers should do this only in ``MODE_LANG1_LANG2``.
 363
 364         When the tuner receives no stereo signal or does not support
 365         stereo reception the driver shall fall back to ``MODE_MONO``.
 366     * - ``V4L2_TUNER_MODE_LANG1``
 367       - 3
 368       - Play the primary language, mono or stereo. Only
 369         ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 370     * - ``V4L2_TUNER_MODE_LANG2``
 371       - 2
 372       - Play the secondary language, mono. When the tuner receives no
 373         bilingual audio or SAP, or their reception is not supported the
 374         driver shall fall back to mono or stereo mode. Only
 375         ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 376     * - ``V4L2_TUNER_MODE_SAP``
 377       - 2
 378       - Play the Second Audio Program. When the tuner receives no
 379         bilingual audio or SAP, or their reception is not supported the
 380         driver shall fall back to mono or stereo mode. Only
 381         ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 382
 383         .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP``
 384            are synonyms.
 385     * - ``V4L2_TUNER_MODE_LANG1_LANG2``
 386       - 4
 387       - Play the primary language on the left channel, the secondary
 388         language on the right channel. When the tuner receives no
 389         bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
 390         ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
 391         mode.
 392
 393 .. raw:: latex
 394
 395     \begin{adjustbox}{width=\columnwidth}
 396
 397 .. _tuner-matrix:
 398
 399 .. flat-table:: Tuner Audio Matrix
 400     :header-rows:  2
 401     :stub-columns: 0
 402
 403     * -
 404       - :cspan:`5` Selected ``V4L2_TUNER_MODE_``
 405     * - Received ``V4L2_TUNER_SUB_``
 406       - ``MONO``
 407       - ``STEREO``
 408       - ``LANG1``
 409       - ``LANG2 = SAP``
 410       - ``LANG1_LANG2``\  [#f1]_
 411     * - ``MONO``
 412       - Mono
 413       - Mono/Mono
 414       - Mono
 415       - Mono
 416       - Mono/Mono
 417     * - ``MONO | SAP``
 418       - Mono
 419       - Mono/Mono
 420       - Mono
 421       - SAP
 422       - Mono/SAP (preferred) or Mono/Mono
 423     * - ``STEREO``
 424       - L+R
 425       - L/R
 426       - Stereo L/R (preferred) or Mono L+R
 427       - Stereo L/R (preferred) or Mono L+R
 428       - L/R (preferred) or L+R/L+R
 429     * - ``STEREO | SAP``
 430       - L+R
 431       - L/R
 432       - Stereo L/R (preferred) or Mono L+R
 433       - SAP
 434       - L+R/SAP (preferred) or L/R or L+R/L+R
 435     * - ``LANG1 | LANG2``
 436       - Language 1
 437       - Lang1/Lang2 (deprecated [#f2]_) or Lang1/Lang1
 438       - Language 1
 439       - Language 2
 440       - Lang1/Lang2 (preferred) or Lang1/Lang1
 441
 442 .. raw:: latex
 443
 444     \end{adjustbox}\newline\newline
 445
 446 Return Value
 447 ============
 448
 449 On success 0 is returned, on error -1 and the ``errno`` variable is set
 450 appropriately. The generic error codes are described at the
 451 :ref:`Generic Error Codes <gen-errors>` chapter.
 452
 453 EINVAL
 454     The struct :c:type:`v4l2_tuner` ``index`` is out of
 455     bounds.
 456
 457 .. [#f1]
 458    This mode has been added in Linux 2.6.17 and may not be supported by
 459    older drivers.
 460
 461 .. [#f2]
 462    Playback of both languages in ``MODE_STEREO`` is deprecated. In the
 463    future drivers should produce only the primary language in this mode.
 464    Applications should request ``MODE_LANG1_LANG2`` to record both
 465    languages or a stereo signal.