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************************************ 13ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER 14************************************ 15 16Name 17==== 18 19VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes 20 21 22Synopsis 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 32Arguments 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 42Description 43=========== 44 45To query the attributes of a tuner applications initialize the ``index`` 46field and zero out the ``reserved`` array of a struct 47:c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl 48with a pointer to this structure. Drivers fill the rest of the structure 49or return an ``EINVAL`` error code when the index is out of bounds. To 50enumerate all tuners applications shall begin at index zero, 51incrementing by one until the driver returns ``EINVAL``. 52 53Tuners have two writable properties, the audio mode and the radio 54frequency. 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, 57which is determined by the current video input. Drivers may choose a 58different audio mode if the requested mode is invalid or unsupported. 59Since this is a write-only ioctl, it does not return the actually 60selected 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 64to zero. The term 'tuner' means SDR receiver in this context. 65 66To 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 457Return Value 458============ 459 460On success 0 is returned, on error -1 and the ``errno`` variable is set 461appropriately. The generic error codes are described at the 462:ref:`Generic Error Codes <gen-errors>` chapter. 463 464EINVAL 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. 477