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