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 .. 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``\  [#f1]_
 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 [#f2]_) 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 .. [#f1]
 710    This mode has been added in Linux 2.6.17 and may not be supported by
 711    older drivers.
 712
 713 .. [#f2]
 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.