vidioc-g-tuner.rst (14793B)
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2.. c:namespace:: V4L 3 4.. _VIDIOC_G_TUNER: 5 6************************************ 7ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER 8************************************ 9 10Name 11==== 12 13VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes 14 15Synopsis 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 26Arguments 27========= 28 29``fd`` 30 File descriptor returned by :c:func:`open()`. 31 32``argp`` 33 Pointer to struct :c:type:`v4l2_tuner`. 34 35Description 36=========== 37 38To query the attributes of a tuner applications initialize the ``index`` 39field and zero out the ``reserved`` array of a struct 40:c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl 41with a pointer to this structure. Drivers fill the rest of the structure 42or return an ``EINVAL`` error code when the index is out of bounds. To 43enumerate all tuners applications shall begin at index zero, 44incrementing by one until the driver returns ``EINVAL``. 45 46Tuners have two writable properties, the audio mode and the radio 47frequency. 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, 50which is determined by the current video input. Drivers may choose a 51different audio mode if the requested mode is invalid or unsupported. 52Since this is a write-only ioctl, it does not return the actually 53selected 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 57to zero. The term 'tuner' means SDR receiver in this context. 58 59To 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{7.0cm}|p{5.8cm}| 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.5cm}| 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{7.0cm}|p{2.2cm}|p{8.1cm}| 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.5cm}| 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.5cm}| 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 445Return Value 446============ 447 448On success 0 is returned, on error -1 and the ``errno`` variable is set 449appropriately. The generic error codes are described at the 450:ref:`Generic Error Codes <gen-errors>` chapter. 451 452EINVAL 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.