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