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 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 259
 260 .. flat-table:: enum v4l2_tuner_type
 261     :header-rows:  0
 262     :stub-columns: 0
 263     :widths:       3 1 6
 264
 265
 266     -  .. row 1
 267
 268        -  ``V4L2_TUNER_RADIO``
 269
 270        -  1
 271
 272        - Tuner supports radio
 273
 274     -  .. row 2
 275
 276        -  ``V4L2_TUNER_ANALOG_TV``
 277
 278        -  2
 279
 280        - Tuner supports analog TV
 281
 282     -  .. row 3
 283
 284        -  ``V4L2_TUNER_SDR``
 285
 286        -  4
 287
 288        - Tuner controls the A/D and/or D/A block of a
 289          Sofware Digital Radio (SDR)
 290
 291     -  .. row 4
 292
 293        -  ``V4L2_TUNER_RF``
 294
 295        -  5
 296
 297        - Tuner controls the RF part of a Sofware Digital Radio (SDR)
 298
 299
 300 .. _tuner-capability:
 301
 302 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 303
 304 .. flat-table:: Tuner and Modulator Capability Flags
 305     :header-rows:  0
 306     :stub-columns: 0
 307     :widths:       3 1 4
 308
 309
 310     -  .. row 1
 311
 312        -  ``V4L2_TUNER_CAP_LOW``
 313
 314        -  0x0001
 315
 316        -  When set, tuning frequencies are expressed in units of 62.5 Hz
 317           instead of 62.5 kHz.
 318
 319     -  .. row 2
 320
 321        -  ``V4L2_TUNER_CAP_NORM``
 322
 323        -  0x0002
 324
 325        -  This is a multi-standard tuner; the video standard can or must be
 326           switched. (B/G PAL tuners for example are typically not considered
 327           multi-standard because the video standard is automatically
 328           determined from the frequency band.) The set of supported video
 329           standards is available from the struct
 330           :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the
 331           description of ioctl :ref:`VIDIOC_ENUMINPUT`
 332           for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
 333           capability.
 334
 335     -  .. row 3
 336
 337        -  ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
 338
 339        -  0x0004
 340
 341        -  If set, then this tuner supports the hardware seek functionality
 342           where the seek stops when it reaches the end of the frequency
 343           range.
 344
 345     -  .. row 4
 346
 347        -  ``V4L2_TUNER_CAP_HWSEEK_WRAP``
 348
 349        -  0x0008
 350
 351        -  If set, then this tuner supports the hardware seek functionality
 352           where the seek wraps around when it reaches the end of the
 353           frequency range.
 354
 355     -  .. row 5
 356
 357        -  ``V4L2_TUNER_CAP_STEREO``
 358
 359        -  0x0010
 360
 361        -  Stereo audio reception is supported.
 362
 363     -  .. row 6
 364
 365        -  ``V4L2_TUNER_CAP_LANG1``
 366
 367        -  0x0040
 368
 369        -  Reception of the primary language of a bilingual audio program is
 370           supported. Bilingual audio is a feature of two-channel systems,
 371           transmitting the primary language monaural on the main audio
 372           carrier and a secondary language monaural on a second carrier.
 373           Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
 374
 375     -  .. row 7
 376
 377        -  ``V4L2_TUNER_CAP_LANG2``
 378
 379        -  0x0020
 380
 381        -  Reception of the secondary language of a bilingual audio program
 382           is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
 383           capability.
 384
 385     -  .. row 8
 386
 387        -  ``V4L2_TUNER_CAP_SAP``
 388
 389        -  0x0020
 390
 391        -  Reception of a secondary audio program is supported. This is a
 392           feature of the BTSC system which accompanies the NTSC video
 393           standard. Two audio carriers are available for mono or stereo
 394           transmissions of a primary language, and an independent third
 395           carrier for a monaural secondary language. Only
 396           ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
 397
 398           .. note::
 399
 400              The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP``
 401              flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
 402              supports the ``V4L2_STD_NTSC_M`` video standard.
 403
 404     -  .. row 9
 405
 406        -  ``V4L2_TUNER_CAP_RDS``
 407
 408        -  0x0080
 409
 410        -  RDS capture is supported. This capability is only valid for radio
 411           tuners.
 412
 413     -  .. row 10
 414
 415        -  ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
 416
 417        -  0x0100
 418
 419        -  The RDS data is passed as unparsed RDS blocks.
 420
 421     -  .. row 11
 422
 423        -  ``V4L2_TUNER_CAP_RDS_CONTROLS``
 424
 425        -  0x0200
 426
 427        -  The RDS data is parsed by the hardware and set via controls.
 428
 429     -  .. row 12
 430
 431        -  ``V4L2_TUNER_CAP_FREQ_BANDS``
 432
 433        -  0x0400
 434
 435        -  The :ref:`VIDIOC_ENUM_FREQ_BANDS`
 436           ioctl can be used to enumerate the available frequency bands.
 437
 438     -  .. row 13
 439
 440        -  ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``
 441
 442        -  0x0800
 443
 444        -  The range to search when using the hardware seek functionality is
 445           programmable, see
 446           :ref:`VIDIOC_S_HW_FREQ_SEEK` for
 447           details.
 448
 449     -  .. row 14
 450
 451        -  ``V4L2_TUNER_CAP_1HZ``
 452
 453        -  0x1000
 454
 455        -  When set, tuning frequencies are expressed in units of 1 Hz
 456           instead of 62.5 kHz.
 457
 458
 459
 460 .. _tuner-rxsubchans:
 461
 462 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 463
 464 .. flat-table:: Tuner Audio Reception Flags
 465     :header-rows:  0
 466     :stub-columns: 0
 467     :widths:       3 1 4
 468
 469
 470     -  .. row 1
 471
 472        -  ``V4L2_TUNER_SUB_MONO``
 473
 474        -  0x0001
 475
 476        -  The tuner receives a mono audio signal.
 477
 478     -  .. row 2
 479
 480        -  ``V4L2_TUNER_SUB_STEREO``
 481
 482        -  0x0002
 483
 484        -  The tuner receives a stereo audio signal.
 485
 486     -  .. row 3
 487
 488        -  ``V4L2_TUNER_SUB_LANG1``
 489
 490        -  0x0008
 491
 492        -  The tuner receives the primary language of a bilingual audio
 493           signal. Drivers must clear this flag when the current video
 494           standard is ``V4L2_STD_NTSC_M``.
 495
 496     -  .. row 4
 497
 498        -  ``V4L2_TUNER_SUB_LANG2``
 499
 500        -  0x0004
 501
 502        -  The tuner receives the secondary language of a bilingual audio
 503           signal (or a second audio program).
 504
 505     -  .. row 5
 506
 507        -  ``V4L2_TUNER_SUB_SAP``
 508
 509        -  0x0004
 510
 511        -  The tuner receives a Second Audio Program.
 512
 513           .. note::
 514
 515              The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP``
 516              flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies
 517              when the current video standard is ``V4L2_STD_NTSC_M``.
 518
 519     -  .. row 6
 520
 521        -  ``V4L2_TUNER_SUB_RDS``
 522
 523        -  0x0010
 524
 525        -  The tuner receives an RDS channel.
 526
 527
 528
 529 .. _tuner-audmode:
 530
 531 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
 532
 533 .. flat-table:: Tuner Audio Modes
 534     :header-rows:  0
 535     :stub-columns: 0
 536     :widths:       3 1 4
 537
 538
 539     -  .. row 1
 540
 541        -  ``V4L2_TUNER_MODE_MONO``
 542
 543        -  0
 544
 545        -  Play mono audio. When the tuner receives a stereo signal this a
 546           down-mix of the left and right channel. When the tuner receives a
 547           bilingual or SAP signal this mode selects the primary language.
 548
 549     -  .. row 2
 550
 551        -  ``V4L2_TUNER_MODE_STEREO``
 552
 553        -  1
 554
 555        -  Play stereo audio. When the tuner receives bilingual audio it may
 556           play different languages on the left and right channel or the
 557           primary language is played on both channels.
 558
 559           Playing different languages in this mode is deprecated. New
 560           drivers should do this only in ``MODE_LANG1_LANG2``.
 561
 562           When the tuner receives no stereo signal or does not support
 563           stereo reception the driver shall fall back to ``MODE_MONO``.
 564
 565     -  .. row 3
 566
 567        -  ``V4L2_TUNER_MODE_LANG1``
 568
 569        -  3
 570
 571        -  Play the primary language, mono or stereo. Only
 572           ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 573
 574     -  .. row 4
 575
 576        -  ``V4L2_TUNER_MODE_LANG2``
 577
 578        -  2
 579
 580        -  Play the secondary language, mono. When the tuner receives no
 581           bilingual audio or SAP, or their reception is not supported the
 582           driver shall fall back to mono or stereo mode. Only
 583           ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 584
 585     -  .. row 5
 586
 587        -  ``V4L2_TUNER_MODE_SAP``
 588
 589        -  2
 590
 591        -  Play the Second Audio Program. When the tuner receives no
 592           bilingual audio or SAP, or their reception is not supported the
 593           driver shall fall back to mono or stereo mode. Only
 594           ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
 595
 596           .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP``
 597              are synonyms.
 598
 599     -  .. row 6
 600
 601        -  ``V4L2_TUNER_MODE_LANG1_LANG2``
 602
 603        -  4
 604
 605        -  Play the primary language on the left channel, the secondary
 606           language on the right channel. When the tuner receives no
 607           bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
 608           ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
 609           mode.
 610
 611
 612
 613 .. _tuner-matrix:
 614
 615 .. flat-table:: Tuner Audio Matrix
 616     :header-rows:  2
 617     :stub-columns: 0
 618
 619
 620     -  .. row 1
 621
 622        -
 623        -  :cspan:`5` Selected ``V4L2_TUNER_MODE_``
 624
 625     -  .. row 2
 626
 627        -  Received ``V4L2_TUNER_SUB_``
 628
 629        -  ``MONO``
 630
 631        -  ``STEREO``
 632
 633        -  ``LANG1``
 634
 635        -  ``LANG2 = SAP``
 636
 637        -  ``LANG1_LANG2``\  [#f1]_
 638
 639     -  .. row 3
 640
 641        -  ``MONO``
 642
 643        -  Mono
 644
 645        -  Mono/Mono
 646
 647        -  Mono
 648
 649        -  Mono
 650
 651        -  Mono/Mono
 652
 653     -  .. row 4
 654
 655        -  ``MONO | SAP``
 656
 657        -  Mono
 658
 659        -  Mono/Mono
 660
 661        -  Mono
 662
 663        -  SAP
 664
 665        -  Mono/SAP (preferred) or Mono/Mono
 666
 667     -  .. row 5
 668
 669        -  ``STEREO``
 670
 671        -  L+R
 672
 673        -  L/R
 674
 675        -  Stereo L/R (preferred) or Mono L+R
 676
 677        -  Stereo L/R (preferred) or Mono L+R
 678
 679        -  L/R (preferred) or L+R/L+R
 680
 681     -  .. row 6
 682
 683        -  ``STEREO | SAP``
 684
 685        -  L+R
 686
 687        -  L/R
 688
 689        -  Stereo L/R (preferred) or Mono L+R
 690
 691        -  SAP
 692
 693        -  L+R/SAP (preferred) or L/R or L+R/L+R
 694
 695     -  .. row 7
 696
 697        -  ``LANG1 | LANG2``
 698
 699        -  Language 1
 700
 701        -  Lang1/Lang2 (deprecated [#f2]_) or Lang1/Lang1
 702
 703        -  Language 1
 704
 705        -  Language 2
 706
 707        -  Lang1/Lang2 (preferred) or Lang1/Lang1
 708
 709
 710 Return Value
 711 ============
 712
 713 On success 0 is returned, on error -1 and the ``errno`` variable is set
 714 appropriately. The generic error codes are described at the
 715 :ref:`Generic Error Codes <gen-errors>` chapter.
 716
 717 EINVAL
 718     The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of
 719     bounds.
 720
 721 .. [#f1]
 722    This mode has been added in Linux 2.6.17 and may not be supported by
 723    older drivers.
 724
 725 .. [#f2]
 726    Playback of both languages in ``MODE_STEREO`` is deprecated. In the
 727    future drivers should produce only the primary language in this mode.
 728    Applications should request ``MODE_LANG1_LANG2`` to record both
 729    languages or a stereo signal.