| 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 | .. cpp:function:: int ioctl( int fd, int request, struct v4l2_tuner *argp ) |
| 19 | |
| 20 | .. cpp:function:: int ioctl( int fd, int request, const struct v4l2_tuner *argp ) |
| 21 | |
| 22 | |
| 23 | Arguments |
| 24 | ========= |
| 25 | |
| 26 | ``fd`` |
| 27 | File descriptor returned by :ref:`open() <func-open>`. |
| 28 | |
| 29 | ``request`` |
| 30 | VIDIOC_G_TUNER, VIDIOC_S_TUNER |
| 31 | |
| 32 | ``argp`` |
| 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 | :ref:`v4l2_tuner <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 | .. _v4l2-tuner: |
| 64 | |
| 65 | .. flat-table:: struct v4l2_tuner |
| 66 | :header-rows: 0 |
| 67 | :stub-columns: 0 |
| 68 | |
| 69 | |
| 70 | - .. row 1 |
| 71 | |
| 72 | - __u32 |
| 73 | |
| 74 | - ``index`` |
| 75 | |
| 76 | - :cspan:`1` Identifies the tuner, set by the application. |
| 77 | |
| 78 | - .. row 2 |
| 79 | |
| 80 | - __u8 |
| 81 | |
| 82 | - ``name``\ [32] |
| 83 | |
| 84 | - :cspan:`1` |
| 85 | |
| 86 | Name of the tuner, a NUL-terminated ASCII string. This information |
| 87 | is intended for the user. |
| 88 | |
| 89 | - .. row 3 |
| 90 | |
| 91 | - __u32 |
| 92 | |
| 93 | - ``type`` |
| 94 | |
| 95 | - :cspan:`1` Type of the tuner, see :ref:`v4l2-tuner-type`. |
| 96 | |
| 97 | - .. row 4 |
| 98 | |
| 99 | - __u32 |
| 100 | |
| 101 | - ``capability`` |
| 102 | |
| 103 | - :cspan:`1` |
| 104 | |
| 105 | Tuner capability flags, see :ref:`tuner-capability`. Audio flags |
| 106 | indicate the ability to decode audio subprograms. They will *not* |
| 107 | change, for example with the current video standard. |
| 108 | |
| 109 | When the structure refers to a radio tuner the |
| 110 | ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and |
| 111 | ``V4L2_TUNER_CAP_NORM`` flags can't be used. |
| 112 | |
| 113 | If multiple frequency bands are supported, then ``capability`` is |
| 114 | the union of all ``capability`` fields of each struct |
| 115 | :ref:`v4l2_frequency_band <v4l2-frequency-band>`. |
| 116 | |
| 117 | - .. row 5 |
| 118 | |
| 119 | - __u32 |
| 120 | |
| 121 | - ``rangelow`` |
| 122 | |
| 123 | - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or |
| 124 | if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units |
| 125 | of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ`` |
| 126 | is set, in units of 1 Hz. If multiple frequency bands are |
| 127 | supported, then ``rangelow`` is the lowest frequency of all the |
| 128 | frequency bands. |
| 129 | |
| 130 | - .. row 6 |
| 131 | |
| 132 | - __u32 |
| 133 | |
| 134 | - ``rangehigh`` |
| 135 | |
| 136 | - :cspan:`1` The highest tunable frequency in units of 62.5 kHz, |
| 137 | or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in |
| 138 | units of 62.5 Hz, or if the ``capability`` flag |
| 139 | ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple |
| 140 | frequency bands are supported, then ``rangehigh`` is the highest |
| 141 | frequency of all the frequency bands. |
| 142 | |
| 143 | - .. row 7 |
| 144 | |
| 145 | - __u32 |
| 146 | |
| 147 | - ``rxsubchans`` |
| 148 | |
| 149 | - :cspan:`1` |
| 150 | |
| 151 | Some tuners or audio decoders can determine the received audio |
| 152 | subprograms by analyzing audio carriers, pilot tones or other |
| 153 | indicators. To pass this information drivers set flags defined in |
| 154 | :ref:`tuner-rxsubchans` in this field. For example: |
| 155 | |
| 156 | - .. row 8 |
| 157 | |
| 158 | - |
| 159 | - |
| 160 | - ``V4L2_TUNER_SUB_MONO`` |
| 161 | |
| 162 | - receiving mono audio |
| 163 | |
| 164 | - .. row 9 |
| 165 | |
| 166 | - |
| 167 | - |
| 168 | - ``STEREO | SAP`` |
| 169 | |
| 170 | - receiving stereo audio and a secondary audio program |
| 171 | |
| 172 | - .. row 10 |
| 173 | |
| 174 | - |
| 175 | - |
| 176 | - ``MONO | STEREO`` |
| 177 | |
| 178 | - receiving mono or stereo audio, the hardware cannot distinguish |
| 179 | |
| 180 | - .. row 11 |
| 181 | |
| 182 | - |
| 183 | - |
| 184 | - ``LANG1 | LANG2`` |
| 185 | |
| 186 | - receiving bilingual audio |
| 187 | |
| 188 | - .. row 12 |
| 189 | |
| 190 | - |
| 191 | - |
| 192 | - ``MONO | STEREO | LANG1 | LANG2`` |
| 193 | |
| 194 | - receiving mono, stereo or bilingual audio |
| 195 | |
| 196 | - .. row 13 |
| 197 | |
| 198 | - |
| 199 | - |
| 200 | - :cspan:`1` |
| 201 | |
| 202 | When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or |
| 203 | ``_SAP`` flag is cleared in the ``capability`` field, the |
| 204 | corresponding ``V4L2_TUNER_SUB_`` flag must not be set here. |
| 205 | |
| 206 | This field is valid only if this is the tuner of the current video |
| 207 | input, or when the structure refers to a radio tuner. |
| 208 | |
| 209 | - .. row 14 |
| 210 | |
| 211 | - __u32 |
| 212 | |
| 213 | - ``audmode`` |
| 214 | |
| 215 | - :cspan:`1` |
| 216 | |
| 217 | The selected audio mode, see :ref:`tuner-audmode` for valid |
| 218 | values. The audio mode does not affect audio subprogram detection, |
| 219 | and like a :ref:`control` it does not automatically |
| 220 | change unless the requested mode is invalid or unsupported. See |
| 221 | :ref:`tuner-matrix` for possible results when the selected and |
| 222 | received audio programs do not match. |
| 223 | |
| 224 | Currently this is the only field of struct |
| 225 | :ref:`struct v4l2_tuner <v4l2-tuner>` applications can change. |
| 226 | |
| 227 | - .. row 15 |
| 228 | |
| 229 | - __u32 |
| 230 | |
| 231 | - ``signal`` |
| 232 | |
| 233 | - :cspan:`1` The signal strength if known, ranging from 0 to |
| 234 | 65535. Higher values indicate a better signal. |
| 235 | |
| 236 | - .. row 16 |
| 237 | |
| 238 | - __s32 |
| 239 | |
| 240 | - ``afc`` |
| 241 | |
| 242 | - :cspan:`1` Automatic frequency control: When the ``afc`` value |
| 243 | is negative, the frequency is too low, when positive too high. |
| 244 | |
| 245 | - .. row 17 |
| 246 | |
| 247 | - __u32 |
| 248 | |
| 249 | - ``reserved``\ [4] |
| 250 | |
| 251 | - :cspan:`1` Reserved for future extensions. Drivers and |
| 252 | applications must set the array to zero. |
| 253 | |
| 254 | |
| 255 | |
| 256 | .. _v4l2-tuner-type: |
| 257 | |
| 258 | .. flat-table:: enum v4l2_tuner_type |
| 259 | :header-rows: 0 |
| 260 | :stub-columns: 0 |
| 261 | :widths: 3 1 4 |
| 262 | |
| 263 | |
| 264 | - .. row 1 |
| 265 | |
| 266 | - ``V4L2_TUNER_RADIO`` |
| 267 | |
| 268 | - 1 |
| 269 | |
| 270 | - |
| 271 | |
| 272 | - .. row 2 |
| 273 | |
| 274 | - ``V4L2_TUNER_ANALOG_TV`` |
| 275 | |
| 276 | - 2 |
| 277 | |
| 278 | - |
| 279 | |
| 280 | - .. row 3 |
| 281 | |
| 282 | - ``V4L2_TUNER_SDR`` |
| 283 | |
| 284 | - 4 |
| 285 | |
| 286 | - |
| 287 | |
| 288 | - .. row 4 |
| 289 | |
| 290 | - ``V4L2_TUNER_RF`` |
| 291 | |
| 292 | - 5 |
| 293 | |
| 294 | - |
| 295 | |
| 296 | |
| 297 | |
| 298 | .. _tuner-capability: |
| 299 | |
| 300 | .. flat-table:: Tuner and Modulator Capability Flags |
| 301 | :header-rows: 0 |
| 302 | :stub-columns: 0 |
| 303 | :widths: 3 1 4 |
| 304 | |
| 305 | |
| 306 | - .. row 1 |
| 307 | |
| 308 | - ``V4L2_TUNER_CAP_LOW`` |
| 309 | |
| 310 | - 0x0001 |
| 311 | |
| 312 | - When set, tuning frequencies are expressed in units of 62.5 Hz |
| 313 | instead of 62.5 kHz. |
| 314 | |
| 315 | - .. row 2 |
| 316 | |
| 317 | - ``V4L2_TUNER_CAP_NORM`` |
| 318 | |
| 319 | - 0x0002 |
| 320 | |
| 321 | - This is a multi-standard tuner; the video standard can or must be |
| 322 | switched. (B/G PAL tuners for example are typically not considered |
| 323 | multi-standard because the video standard is automatically |
| 324 | determined from the frequency band.) The set of supported video |
| 325 | standards is available from the struct |
| 326 | :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the |
| 327 | description of ioctl :ref:`VIDIOC_ENUMINPUT` |
| 328 | for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this |
| 329 | capability. |
| 330 | |
| 331 | - .. row 3 |
| 332 | |
| 333 | - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED`` |
| 334 | |
| 335 | - 0x0004 |
| 336 | |
| 337 | - If set, then this tuner supports the hardware seek functionality |
| 338 | where the seek stops when it reaches the end of the frequency |
| 339 | range. |
| 340 | |
| 341 | - .. row 4 |
| 342 | |
| 343 | - ``V4L2_TUNER_CAP_HWSEEK_WRAP`` |
| 344 | |
| 345 | - 0x0008 |
| 346 | |
| 347 | - If set, then this tuner supports the hardware seek functionality |
| 348 | where the seek wraps around when it reaches the end of the |
| 349 | frequency range. |
| 350 | |
| 351 | - .. row 5 |
| 352 | |
| 353 | - ``V4L2_TUNER_CAP_STEREO`` |
| 354 | |
| 355 | - 0x0010 |
| 356 | |
| 357 | - Stereo audio reception is supported. |
| 358 | |
| 359 | - .. row 6 |
| 360 | |
| 361 | - ``V4L2_TUNER_CAP_LANG1`` |
| 362 | |
| 363 | - 0x0040 |
| 364 | |
| 365 | - Reception of the primary language of a bilingual audio program is |
| 366 | supported. Bilingual audio is a feature of two-channel systems, |
| 367 | transmitting the primary language monaural on the main audio |
| 368 | carrier and a secondary language monaural on a second carrier. |
| 369 | Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability. |
| 370 | |
| 371 | - .. row 7 |
| 372 | |
| 373 | - ``V4L2_TUNER_CAP_LANG2`` |
| 374 | |
| 375 | - 0x0020 |
| 376 | |
| 377 | - Reception of the secondary language of a bilingual audio program |
| 378 | is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this |
| 379 | capability. |
| 380 | |
| 381 | - .. row 8 |
| 382 | |
| 383 | - ``V4L2_TUNER_CAP_SAP`` |
| 384 | |
| 385 | - 0x0020 |
| 386 | |
| 387 | - Reception of a secondary audio program is supported. This is a |
| 388 | feature of the BTSC system which accompanies the NTSC video |
| 389 | standard. Two audio carriers are available for mono or stereo |
| 390 | transmissions of a primary language, and an independent third |
| 391 | carrier for a monaural secondary language. Only |
| 392 | ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability. |
| 393 | |
| 394 | .. note:: The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` |
| 395 | flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner |
| 396 | supports the ``V4L2_STD_NTSC_M`` video standard. |
| 397 | |
| 398 | - .. row 9 |
| 399 | |
| 400 | - ``V4L2_TUNER_CAP_RDS`` |
| 401 | |
| 402 | - 0x0080 |
| 403 | |
| 404 | - RDS capture is supported. This capability is only valid for radio |
| 405 | tuners. |
| 406 | |
| 407 | - .. row 10 |
| 408 | |
| 409 | - ``V4L2_TUNER_CAP_RDS_BLOCK_IO`` |
| 410 | |
| 411 | - 0x0100 |
| 412 | |
| 413 | - The RDS data is passed as unparsed RDS blocks. |
| 414 | |
| 415 | - .. row 11 |
| 416 | |
| 417 | - ``V4L2_TUNER_CAP_RDS_CONTROLS`` |
| 418 | |
| 419 | - 0x0200 |
| 420 | |
| 421 | - The RDS data is parsed by the hardware and set via controls. |
| 422 | |
| 423 | - .. row 12 |
| 424 | |
| 425 | - ``V4L2_TUNER_CAP_FREQ_BANDS`` |
| 426 | |
| 427 | - 0x0400 |
| 428 | |
| 429 | - The :ref:`VIDIOC_ENUM_FREQ_BANDS` |
| 430 | ioctl can be used to enumerate the available frequency bands. |
| 431 | |
| 432 | - .. row 13 |
| 433 | |
| 434 | - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM`` |
| 435 | |
| 436 | - 0x0800 |
| 437 | |
| 438 | - The range to search when using the hardware seek functionality is |
| 439 | programmable, see |
| 440 | :ref:`VIDIOC_S_HW_FREQ_SEEK` for |
| 441 | details. |
| 442 | |
| 443 | - .. row 14 |
| 444 | |
| 445 | - ``V4L2_TUNER_CAP_1HZ`` |
| 446 | |
| 447 | - 0x1000 |
| 448 | |
| 449 | - When set, tuning frequencies are expressed in units of 1 Hz |
| 450 | instead of 62.5 kHz. |
| 451 | |
| 452 | |
| 453 | |
| 454 | .. _tuner-rxsubchans: |
| 455 | |
| 456 | .. flat-table:: Tuner Audio Reception Flags |
| 457 | :header-rows: 0 |
| 458 | :stub-columns: 0 |
| 459 | :widths: 3 1 4 |
| 460 | |
| 461 | |
| 462 | - .. row 1 |
| 463 | |
| 464 | - ``V4L2_TUNER_SUB_MONO`` |
| 465 | |
| 466 | - 0x0001 |
| 467 | |
| 468 | - The tuner receives a mono audio signal. |
| 469 | |
| 470 | - .. row 2 |
| 471 | |
| 472 | - ``V4L2_TUNER_SUB_STEREO`` |
| 473 | |
| 474 | - 0x0002 |
| 475 | |
| 476 | - The tuner receives a stereo audio signal. |
| 477 | |
| 478 | - .. row 3 |
| 479 | |
| 480 | - ``V4L2_TUNER_SUB_LANG1`` |
| 481 | |
| 482 | - 0x0008 |
| 483 | |
| 484 | - The tuner receives the primary language of a bilingual audio |
| 485 | signal. Drivers must clear this flag when the current video |
| 486 | standard is ``V4L2_STD_NTSC_M``. |
| 487 | |
| 488 | - .. row 4 |
| 489 | |
| 490 | - ``V4L2_TUNER_SUB_LANG2`` |
| 491 | |
| 492 | - 0x0004 |
| 493 | |
| 494 | - The tuner receives the secondary language of a bilingual audio |
| 495 | signal (or a second audio program). |
| 496 | |
| 497 | - .. row 5 |
| 498 | |
| 499 | - ``V4L2_TUNER_SUB_SAP`` |
| 500 | |
| 501 | - 0x0004 |
| 502 | |
| 503 | - The tuner receives a Second Audio Program. |
| 504 | |
| 505 | .. note:: The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` |
| 506 | flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies |
| 507 | when the current video standard is ``V4L2_STD_NTSC_M``. |
| 508 | |
| 509 | - .. row 6 |
| 510 | |
| 511 | - ``V4L2_TUNER_SUB_RDS`` |
| 512 | |
| 513 | - 0x0010 |
| 514 | |
| 515 | - The tuner receives an RDS channel. |
| 516 | |
| 517 | |
| 518 | |
| 519 | .. _tuner-audmode: |
| 520 | |
| 521 | .. flat-table:: Tuner Audio Modes |
| 522 | :header-rows: 0 |
| 523 | :stub-columns: 0 |
| 524 | :widths: 3 1 4 |
| 525 | |
| 526 | |
| 527 | - .. row 1 |
| 528 | |
| 529 | - ``V4L2_TUNER_MODE_MONO`` |
| 530 | |
| 531 | - 0 |
| 532 | |
| 533 | - Play mono audio. When the tuner receives a stereo signal this a |
| 534 | down-mix of the left and right channel. When the tuner receives a |
| 535 | bilingual or SAP signal this mode selects the primary language. |
| 536 | |
| 537 | - .. row 2 |
| 538 | |
| 539 | - ``V4L2_TUNER_MODE_STEREO`` |
| 540 | |
| 541 | - 1 |
| 542 | |
| 543 | - Play stereo audio. When the tuner receives bilingual audio it may |
| 544 | play different languages on the left and right channel or the |
| 545 | primary language is played on both channels. |
| 546 | |
| 547 | Playing different languages in this mode is deprecated. New |
| 548 | drivers should do this only in ``MODE_LANG1_LANG2``. |
| 549 | |
| 550 | When the tuner receives no stereo signal or does not support |
| 551 | stereo reception the driver shall fall back to ``MODE_MONO``. |
| 552 | |
| 553 | - .. row 3 |
| 554 | |
| 555 | - ``V4L2_TUNER_MODE_LANG1`` |
| 556 | |
| 557 | - 3 |
| 558 | |
| 559 | - Play the primary language, mono or stereo. Only |
| 560 | ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. |
| 561 | |
| 562 | - .. row 4 |
| 563 | |
| 564 | - ``V4L2_TUNER_MODE_LANG2`` |
| 565 | |
| 566 | - 2 |
| 567 | |
| 568 | - Play the secondary language, mono. When the tuner receives no |
| 569 | bilingual audio or SAP, or their reception is not supported the |
| 570 | driver shall fall back to mono or stereo mode. Only |
| 571 | ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. |
| 572 | |
| 573 | - .. row 5 |
| 574 | |
| 575 | - ``V4L2_TUNER_MODE_SAP`` |
| 576 | |
| 577 | - 2 |
| 578 | |
| 579 | - Play the Second Audio Program. When the tuner receives no |
| 580 | bilingual audio or SAP, or their reception is not supported the |
| 581 | driver shall fall back to mono or stereo mode. Only |
| 582 | ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. |
| 583 | |
| 584 | .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` |
| 585 | are synonyms. |
| 586 | |
| 587 | - .. row 6 |
| 588 | |
| 589 | - ``V4L2_TUNER_MODE_LANG1_LANG2`` |
| 590 | |
| 591 | - 4 |
| 592 | |
| 593 | - Play the primary language on the left channel, the secondary |
| 594 | language on the right channel. When the tuner receives no |
| 595 | bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or |
| 596 | ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this |
| 597 | mode. |
| 598 | |
| 599 | |
| 600 | |
| 601 | .. _tuner-matrix: |
| 602 | |
| 603 | .. flat-table:: Tuner Audio Matrix |
| 604 | :header-rows: 2 |
| 605 | :stub-columns: 0 |
| 606 | |
| 607 | |
| 608 | - .. row 1 |
| 609 | |
| 610 | - |
| 611 | - :cspan:`5` Selected ``V4L2_TUNER_MODE_`` |
| 612 | |
| 613 | - .. row 2 |
| 614 | |
| 615 | - Received ``V4L2_TUNER_SUB_`` |
| 616 | |
| 617 | - ``MONO`` |
| 618 | |
| 619 | - ``STEREO`` |
| 620 | |
| 621 | - ``LANG1`` |
| 622 | |
| 623 | - ``LANG2 = SAP`` |
| 624 | |
| 625 | - ``LANG1_LANG2``\ [1]_ |
| 626 | |
| 627 | - .. row 3 |
| 628 | |
| 629 | - ``MONO`` |
| 630 | |
| 631 | - Mono |
| 632 | |
| 633 | - Mono/Mono |
| 634 | |
| 635 | - Mono |
| 636 | |
| 637 | - Mono |
| 638 | |
| 639 | - Mono/Mono |
| 640 | |
| 641 | - .. row 4 |
| 642 | |
| 643 | - ``MONO | SAP`` |
| 644 | |
| 645 | - Mono |
| 646 | |
| 647 | - Mono/Mono |
| 648 | |
| 649 | - Mono |
| 650 | |
| 651 | - SAP |
| 652 | |
| 653 | - Mono/SAP (preferred) or Mono/Mono |
| 654 | |
| 655 | - .. row 5 |
| 656 | |
| 657 | - ``STEREO`` |
| 658 | |
| 659 | - L+R |
| 660 | |
| 661 | - L/R |
| 662 | |
| 663 | - Stereo L/R (preferred) or Mono L+R |
| 664 | |
| 665 | - Stereo L/R (preferred) or Mono L+R |
| 666 | |
| 667 | - L/R (preferred) or L+R/L+R |
| 668 | |
| 669 | - .. row 6 |
| 670 | |
| 671 | - ``STEREO | SAP`` |
| 672 | |
| 673 | - L+R |
| 674 | |
| 675 | - L/R |
| 676 | |
| 677 | - Stereo L/R (preferred) or Mono L+R |
| 678 | |
| 679 | - SAP |
| 680 | |
| 681 | - L+R/SAP (preferred) or L/R or L+R/L+R |
| 682 | |
| 683 | - .. row 7 |
| 684 | |
| 685 | - ``LANG1 | LANG2`` |
| 686 | |
| 687 | - Language 1 |
| 688 | |
| 689 | - Lang1/Lang2 (deprecated [2]_) or Lang1/Lang1 |
| 690 | |
| 691 | - Language 1 |
| 692 | |
| 693 | - Language 2 |
| 694 | |
| 695 | - Lang1/Lang2 (preferred) or Lang1/Lang1 |
| 696 | |
| 697 | |
| 698 | Return Value |
| 699 | ============ |
| 700 | |
| 701 | On success 0 is returned, on error -1 and the ``errno`` variable is set |
| 702 | appropriately. The generic error codes are described at the |
| 703 | :ref:`Generic Error Codes <gen-errors>` chapter. |
| 704 | |
| 705 | EINVAL |
| 706 | The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of |
| 707 | bounds. |
| 708 | |
| 709 | .. [1] |
| 710 | This mode has been added in Linux 2.6.17 and may not be supported by |
| 711 | older drivers. |
| 712 | |
| 713 | .. [2] |
| 714 | Playback of both languages in ``MODE_STEREO`` is deprecated. In the |
| 715 | future drivers should produce only the primary language in this mode. |
| 716 | Applications should request ``MODE_LANG1_LANG2`` to record both |
| 717 | languages or a stereo signal. |