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