Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst

   1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
   2 .. c:namespace:: V4L
   3
   4 .. _VIDIOC_G_TUNER:
   5
   6 ************************************
   7 ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
   8 ************************************
   9
  10 Name
  11 ====
  12
  13 VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
  14
  15 Synopsis
  16 ========
  17
  18 .. c:macro:: VIDIOC_G_TUNER
  19
  20 ``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)``
  21
  22 .. c:macro:: VIDIOC_S_TUNER
  23
  24 ``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)``
  25
  26 Arguments
  27 =========
  28
  29 ``fd``
  30     File descriptor returned by :c:func:`open()`.
  31
  32 ``argp``
  33     Pointer to struct :c:type:`v4l2_tuner`.
  34
  35 Description
  36 ===========
  37
  38 To query the attributes of a tuner applications initialize the ``index``
  39 field and zero out the ``reserved`` array of a struct
  40 :c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl
  41 with a pointer to this structure. Drivers fill the rest of the structure
  42 or return an ``EINVAL`` error code when the index is out of bounds. To
  43 enumerate all tuners applications shall begin at index zero,
  44 incrementing by one until the driver returns ``EINVAL``.
  45
  46 Tuners have two writable properties, the audio mode and the radio
  47 frequency. To change the audio mode, applications initialize the
  48 ``index``, ``audmode`` and ``reserved`` fields and call the
  49 ``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
  50 which is determined by the current video input. Drivers may choose a
  51 different audio mode if the requested mode is invalid or unsupported.
  52 Since this is a write-only ioctl, it does not return the actually
  53 selected audio mode.
  54
  55 :ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
  56 ``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
  57 to zero. The term 'tuner' means SDR receiver in this context.
  58
  59 To change the radio frequency the
  60 :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
  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 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 186
 187 .. c:type:: v4l2_tuner_type
 188
 189 .. flat-table:: enum v4l2_tuner_type
 190     :header-rows:  0
 191     :stub-columns: 0
 192     :widths:       3 1 6
 193
 194     * - ``V4L2_TUNER_RADIO``
 195       - 1
 196       - Tuner supports radio
 197     * - ``V4L2_TUNER_ANALOG_TV``
 198       - 2
 199       - Tuner supports analog TV
 200     * - ``V4L2_TUNER_SDR``
 201       - 4
 202       - Tuner controls the A/D and/or D/A block of a
 203         Software Digital Radio (SDR)
 204     * - ``V4L2_TUNER_RF``
 205       - 5
 206       - Tuner controls the RF part of a Software Digital Radio (SDR)
 207
 208 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 209
 210 .. _tuner-capability:
 211
 212 .. cssclass:: longtable
 213
 214 .. flat-table:: Tuner and Modulator Capability Flags
 215     :header-rows:  0
 216     :stub-columns: 0
 217     :widths:       3 1 4
 218
 219     * - ``V4L2_TUNER_CAP_LOW``
 220       - 0x0001
 221       - When set, tuning frequencies are expressed in units of 62.5 Hz
 222         instead of 62.5 kHz.
 223     * - ``V4L2_TUNER_CAP_NORM``
 224       - 0x0002
 225       - This is a multi-standard tuner; the video standard can or must be
 226         switched. (B/G PAL tuners for example are typically not considered
 227         multi-standard because the video standard is automatically
 228         determined from the frequency band.) The set of supported video
 229         standards is available from the struct
 230         :c:type:`v4l2_input` pointing to this tuner, see the
 231         description of ioctl :ref:`VIDIOC_ENUMINPUT`
 232         for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
 233         capability.
 234     * - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
 235       - 0x0004
 236       - If set, then this tuner supports the hardware seek functionality
 237         where the seek stops when it reaches the end of the frequency
 238         range.
 239     * - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
 240       - 0x0008
 241       - If set, then this tuner supports the hardware seek functionality
 242         where the seek wraps around when it reaches the end of the
 243         frequency range.
 244     * - ``V4L2_TUNER_CAP_STEREO``
 245       - 0x0010
 246       - Stereo audio reception is supported.
 247     * - ``V4L2_TUNER_CAP_LANG1``
 248       - 0x0040
 249       - Reception of the primary language of a bilingual audio program is
 250         supported. Bilingual audio is a feature of two-channel systems,
 251         transmitting the primary language monaural on the main audio
 252         carrier and a secondary language monaural on a second carrier.
 253         Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
 254     * - ``V4L2_TUNER_CAP_LANG2``
 255       - 0x0020
 256       - Reception of the secondary language of a bilingual audio program
 257         is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
 258         capability.
 259     * - ``V4L2_TUNER_CAP_SAP``
 260       - 0x0020
 261       - Reception of a secondary audio program is supported. This is a
 262         feature of the BTSC system which accompanies the NTSC video
 263         standard. Two audio carriers are available for mono or stereo
 264         transmissions of a primary language, and an independent third
 265         carrier for a monaural secondary language. Only
 266         ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
 267
 268         .. note::
 269
 270            The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP``
 271            flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
 272            supports the ``V4L2_STD_NTSC_M`` video standard.
 273     * - ``V4L2_TUNER_CAP_RDS``
 274       - 0x0080
 275       - RDS capture is supported. This capability is only valid for radio
 276         tuners.
 277     * - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
 278       - 0x0100
 279       - The RDS data is passed as unparsed RDS blocks.
 280     * - ``V4L2_TUNER_CAP_RDS_CONTROLS``
 281       - 0x0200
 282       - The RDS data is parsed by the hardware and set via controls.
 283     * - ``V4L2_TUNER_CAP_FREQ_BANDS``
 284       - 0x0400
 285       - The :ref:`VIDIOC_ENUM_FREQ_BANDS`
 286         ioctl can be used to enumerate the available frequency bands.
 287     * - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
 288       - 0x0800
 289       - The range to search when using the hardware seek functionality is
 290         programmable, see
 291         :ref:`VIDIOC_S_HW_FREQ_SEEK` for
 292         details.
 293     * - ``V4L2_TUNER_CAP_1HZ``
 294       - 0x1000
 295       - When set, tuning frequencies are expressed in units of 1 Hz
 296         instead of 62.5 kHz.
 297
 298
 299 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 300
 301 .. _tuner-rxsubchans:
 302
 303 .. flat-table:: Tuner Audio Reception Flags
 304     :header-rows:  0
 305     :stub-columns: 0
 306     :widths:       3 1 4
 307
 308     * - ``V4L2_TUNER_SUB_MONO``
 309       - 0x0001
 310       - The tuner receives a mono audio signal.
 311     * - ``V4L2_TUNER_SUB_STEREO``
 312       - 0x0002
 313       - The tuner receives a stereo audio signal.
 314     * - ``V4L2_TUNER_SUB_LANG1``
 315       - 0x0008
 316       - The tuner receives the primary language of a bilingual audio
 317         signal. Drivers must clear this flag when the current video
 318         standard is ``V4L2_STD_NTSC_M``.
 319     * - ``V4L2_TUNER_SUB_LANG2``
 320       - 0x0004
 321       - The tuner receives the secondary language of a bilingual audio
 322         signal (or a second audio program).
 323     * - ``V4L2_TUNER_SUB_SAP``
 324       - 0x0004
 325       - The tuner receives a Second Audio Program.
 326
 327         .. note::
 328
 329            The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP``
 330            flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies
 331            when the current video standard is ``V4L2_STD_NTSC_M``.
 332     * - ``V4L2_TUNER_SUB_RDS``
 333       - 0x0010
 334       - The tuner receives an RDS channel.
 335
 336
 337 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 338
 339 .. _tuner-audmode:
 340
 341 .. flat-table:: Tuner Audio Modes
 342     :header-rows:  0
 343     :stub-columns: 0
 344     :widths:       3 1 4
 345
 346     * - ``V4L2_TUNER_MODE_MONO``
 347       - 0
 348       - Play mono audio. When the tuner receives a stereo signal this a
 349         down-mix of the left and right channel. When the tuner receives a
 350         bilingual or SAP signal this mode selects the primary language.
 351     * - ``V4L2_TUNER_MODE_STEREO``
 352       - 1
 353       - Play stereo audio. When the tuner receives bilingual audio it may
 354         play different languages on the left and right channel or the
 355         primary language is played on both channels.
 356
 357         Playing different languages in this mode is deprecated. New
 358         drivers should do this only in ``MODE_LANG1_LANG2``.
 359
 360         When the tuner receives no stereo signal or does not support
 361         stereo reception the driver shall fall back to ``MODE_MONO``.
 362     * - ``V4L2_TUNER_MODE_LANG1``
 363       - 3
 364       - Play the primary language, mono or stereo. Only
 365         ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 366     * - ``V4L2_TUNER_MODE_LANG2``
 367       - 2
 368       - Play the secondary language, mono. When the tuner receives no
 369         bilingual audio or SAP, or their reception is not supported the
 370         driver shall fall back to mono or stereo mode. Only
 371         ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 372     * - ``V4L2_TUNER_MODE_SAP``
 373       - 2
 374       - Play the Second Audio Program. When the tuner receives no
 375         bilingual audio or SAP, or their reception is not supported the
 376         driver shall fall back to mono or stereo mode. Only
 377         ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 378
 379         .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP``
 380            are synonyms.
 381     * - ``V4L2_TUNER_MODE_LANG1_LANG2``
 382       - 4
 383       - Play the primary language on the left channel, the secondary
 384         language on the right channel. When the tuner receives no
 385         bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
 386         ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
 387         mode.
 388
 389 .. raw:: latex
 390
 391     \scriptsize
 392
 393 .. tabularcolumns:: |p{1.5cm}|p{1.5cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|
 394
 395 .. _tuner-matrix:
 396
 397 .. flat-table:: Tuner Audio Matrix
 398     :header-rows:  2
 399     :stub-columns: 0
 400     :widths: 7 7 14 14 14 14
 401
 402     * -
 403       - :cspan:`4` Selected ``V4L2_TUNER_MODE_``
 404     * - Received ``V4L2_TUNER_SUB_``
 405       - ``MONO``
 406       - ``STEREO``
 407       - ``LANG1``
 408       - ``LANG2 = SAP``
 409       - ``LANG1_LANG2``\ [#f1]_
 410     * - ``MONO``
 411       - Mono
 412       - Mono/Mono
 413       - Mono
 414       - Mono
 415       - Mono/Mono
 416     * - ``MONO | SAP``
 417       - Mono
 418       - Mono/Mono
 419       - Mono
 420       - SAP
 421       - Mono/SAP (preferred) or Mono/Mono
 422     * - ``STEREO``
 423       - L+R
 424       - L/R
 425       - Stereo L/R (preferred) or Mono L+R
 426       - Stereo L/R (preferred) or Mono L+R
 427       - L/R (preferred) or L+R/L+R
 428     * - ``STEREO | SAP``
 429       - L+R
 430       - L/R
 431       - Stereo L/R (preferred) or Mono L+R
 432       - SAP
 433       - L+R/SAP (preferred) or L/R or L+R/L+R
 434     * - ``LANG1 | LANG2``
 435       - Language 1
 436       - Lang1/Lang2 (deprecated\ [#f2]_) or Lang1/Lang1
 437       - Language 1
 438       - Language 2
 439       - Lang1/Lang2 (preferred) or Lang1/Lang1
 440
 441 .. raw:: latex
 442
 443     \normalsize
 444
 445 Return Value
 446 ============
 447
 448 On success 0 is returned, on error -1 and the ``errno`` variable is set
 449 appropriately. The generic error codes are described at the
 450 :ref:`Generic Error Codes <gen-errors>` chapter.
 451
 452 EINVAL
 453     The struct :c:type:`v4l2_tuner` ``index`` is out of
 454     bounds.
 455
 456 .. [#f1]
 457    This mode has been added in Linux 2.6.17 and may not be supported by
 458    older drivers.
 459
 460 .. [#f2]
 461    Playback of both languages in ``MODE_STEREO`` is deprecated. In the
 462    future drivers should produce only the primary language in this mode.
 463    Applications should request ``MODE_LANG1_LANG2`` to record both
 464    languages or a stereo signal.