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