vidioc-g-tuner.rst 15.4 KB
Newer Older
1 2
.. -*- coding: utf-8; mode: rst -*-

3
.. _VIDIOC_G_TUNER:
4 5 6 7 8

************************************
ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
************************************

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 27 28 29 30 31 32 33 34
=========

``fd``
    File descriptor returned by :ref:`open() <func-open>`.

``request``
    VIDIOC_G_TUNER, VIDIOC_S_TUNER

``argp``


35
Description
36 37 38 39 40 41
===========

To query the attributes of a tuner applications initialize the ``index``
field and zero out the ``reserved`` array of a struct
:ref:`v4l2_tuner <v4l2-tuner>` and call the ``VIDIOC_G_TUNER`` ioctl
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 47 48 49 50 51 52 53 54 55 56 57 58 59

Tuners have two writable properties, the audio mode and the radio
frequency. To change the audio mode, applications initialize the
``index``, ``audmode`` and ``reserved`` fields and call the
``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,
which is determined by the current video input. Drivers may choose a
different audio mode if the requested mode is invalid or unsupported.
Since this is a write-only ioctl, it does not return the actually
selected audio mode.

:ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and
``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized
to zero. The term 'tuner' means SDR receiver in this context.

To change the radio frequency the
60
:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85


.. _v4l2-tuner:

.. flat-table:: struct v4l2_tuner
    :header-rows:  0
    :stub-columns: 0


    -  .. row 1

       -  __u32

       -  ``index``

       -  :cspan:`1` Identifies the tuner, set by the application.

    -  .. row 2

       -  __u8

       -  ``name``\ [32]

       -  :cspan:`1`

86 87
	  Name of the tuner, a NUL-terminated ASCII string. This information
	  is intended for the user.
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104

    -  .. row 3

       -  __u32

       -  ``type``

       -  :cspan:`1` Type of the tuner, see :ref:`v4l2-tuner-type`.

    -  .. row 4

       -  __u32

       -  ``capability``

       -  :cspan:`1`

105 106 107
	  Tuner capability flags, see :ref:`tuner-capability`. Audio flags
	  indicate the ability to decode audio subprograms. They will *not*
	  change, for example with the current video standard.
108

109 110 111
	  When the structure refers to a radio tuner the
	  ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
	  ``V4L2_TUNER_CAP_NORM`` flags can't be used.
112

113 114 115
	  If multiple frequency bands are supported, then ``capability`` is
	  the union of all ``capability`` fields of each struct
	  :ref:`v4l2_frequency_band <v4l2-frequency-band>`.
116 117 118 119 120 121 122 123

    -  .. row 5

       -  __u32

       -  ``rangelow``

       -  :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
124 125 126 127 128
	  if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
	  of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``
	  is set, in units of 1 Hz. If multiple frequency bands are
	  supported, then ``rangelow`` is the lowest frequency of all the
	  frequency bands.
129 130 131 132 133 134 135 136

    -  .. row 6

       -  __u32

       -  ``rangehigh``

       -  :cspan:`1` The highest tunable frequency in units of 62.5 kHz,
137 138 139 140 141
	  or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in
	  units of 62.5 Hz, or if the ``capability`` flag
	  ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
	  frequency bands are supported, then ``rangehigh`` is the highest
	  frequency of all the frequency bands.
142 143 144 145 146 147 148 149 150

    -  .. row 7

       -  __u32

       -  ``rxsubchans``

       -  :cspan:`1`

151 152 153 154
	  Some tuners or audio decoders can determine the received audio
	  subprograms by analyzing audio carriers, pilot tones or other
	  indicators. To pass this information drivers set flags defined in
	  :ref:`tuner-rxsubchans` in this field. For example:
155 156 157

    -  .. row 8

158 159
       -
       -
160 161 162 163 164 165
       -  ``V4L2_TUNER_SUB_MONO``

       -  receiving mono audio

    -  .. row 9

166 167
       -
       -
168 169 170 171 172 173
       -  ``STEREO | SAP``

       -  receiving stereo audio and a secondary audio program

    -  .. row 10

174 175
       -
       -
176 177 178 179 180 181
       -  ``MONO | STEREO``

       -  receiving mono or stereo audio, the hardware cannot distinguish

    -  .. row 11

182 183
       -
       -
184 185 186 187 188 189
       -  ``LANG1 | LANG2``

       -  receiving bilingual audio

    -  .. row 12

190 191
       -
       -
192 193 194 195 196 197
       -  ``MONO | STEREO | LANG1 | LANG2``

       -  receiving mono, stereo or bilingual audio

    -  .. row 13

198 199
       -
       -
200 201
       -  :cspan:`1`

202 203 204
	  When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
	  ``_SAP`` flag is cleared in the ``capability`` field, the
	  corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.
205

206 207
	  This field is valid only if this is the tuner of the current video
	  input, or when the structure refers to a radio tuner.
208 209 210 211 212 213 214 215 216

    -  .. row 14

       -  __u32

       -  ``audmode``

       -  :cspan:`1`

217 218 219 220 221 222
	  The selected audio mode, see :ref:`tuner-audmode` for valid
	  values. The audio mode does not affect audio subprogram detection,
	  and like a :ref:`control` it does not automatically
	  change unless the requested mode is invalid or unsupported. See
	  :ref:`tuner-matrix` for possible results when the selected and
	  received audio programs do not match.
223

224 225
	  Currently this is the only field of struct
	  :ref:`struct v4l2_tuner <v4l2-tuner>` applications can change.
226 227 228 229 230 231 232 233

    -  .. row 15

       -  __u32

       -  ``signal``

       -  :cspan:`1` The signal strength if known, ranging from 0 to
234
	  65535. Higher values indicate a better signal.
235 236 237 238 239 240 241 242

    -  .. row 16

       -  __s32

       -  ``afc``

       -  :cspan:`1` Automatic frequency control: When the ``afc`` value
243
	  is negative, the frequency is too low, when positive too high.
244 245 246 247 248 249 250 251

    -  .. row 17

       -  __u32

       -  ``reserved``\ [4]

       -  :cspan:`1` Reserved for future extensions. Drivers and
252
	  applications must set the array to zero.
253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269



.. _v4l2-tuner-type:

.. flat-table:: enum v4l2_tuner_type
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_TUNER_RADIO``

       -  1

270
       -
271 272 273 274 275 276 277

    -  .. row 2

       -  ``V4L2_TUNER_ANALOG_TV``

       -  2

278
       -
279 280 281 282 283 284 285

    -  .. row 3

       -  ``V4L2_TUNER_SDR``

       -  4

286
       -
287 288 289 290 291 292 293

    -  .. row 4

       -  ``V4L2_TUNER_RF``

       -  5

294
       -
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312



.. _tuner-capability:

.. flat-table:: Tuner and Modulator Capability Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_TUNER_CAP_LOW``

       -  0x0001

       -  When set, tuning frequencies are expressed in units of 62.5 Hz
313
	  instead of 62.5 kHz.
314 315 316 317 318 319 320 321

    -  .. row 2

       -  ``V4L2_TUNER_CAP_NORM``

       -  0x0002

       -  This is a multi-standard tuner; the video standard can or must be
322 323 324 325 326 327 328 329
	  switched. (B/G PAL tuners for example are typically not considered
	  multi-standard because the video standard is automatically
	  determined from the frequency band.) The set of supported video
	  standards is available from the struct
	  :ref:`v4l2_input <v4l2-input>` pointing to this tuner, see the
	  description of ioctl :ref:`VIDIOC_ENUMINPUT`
	  for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
	  capability.
330 331 332 333 334 335 336 337

    -  .. row 3

       -  ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``

       -  0x0004

       -  If set, then this tuner supports the hardware seek functionality
338 339
	  where the seek stops when it reaches the end of the frequency
	  range.
340 341 342 343 344 345 346 347

    -  .. row 4

       -  ``V4L2_TUNER_CAP_HWSEEK_WRAP``

       -  0x0008

       -  If set, then this tuner supports the hardware seek functionality
348 349
	  where the seek wraps around when it reaches the end of the
	  frequency range.
350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365

    -  .. row 5

       -  ``V4L2_TUNER_CAP_STEREO``

       -  0x0010

       -  Stereo audio reception is supported.

    -  .. row 6

       -  ``V4L2_TUNER_CAP_LANG1``

       -  0x0040

       -  Reception of the primary language of a bilingual audio program is
366 367 368 369
	  supported. Bilingual audio is a feature of two-channel systems,
	  transmitting the primary language monaural on the main audio
	  carrier and a secondary language monaural on a second carrier.
	  Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
370 371 372 373 374 375 376 377

    -  .. row 7

       -  ``V4L2_TUNER_CAP_LANG2``

       -  0x0020

       -  Reception of the secondary language of a bilingual audio program
378 379
	  is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
	  capability.
380 381 382 383 384 385 386 387

    -  .. row 8

       -  ``V4L2_TUNER_CAP_SAP``

       -  0x0020

       -  Reception of a secondary audio program is supported. This is a
388 389 390 391 392
	  feature of the BTSC system which accompanies the NTSC video
	  standard. Two audio carriers are available for mono or stereo
	  transmissions of a primary language, and an independent third
	  carrier for a monaural secondary language. Only
	  ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.
393

394 395 396
	  Note the ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP`` flags
	  are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner
	  supports the ``V4L2_STD_NTSC_M`` video standard.
397 398 399 400 401 402 403 404

    -  .. row 9

       -  ``V4L2_TUNER_CAP_RDS``

       -  0x0080

       -  RDS capture is supported. This capability is only valid for radio
405
	  tuners.
406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428

    -  .. row 10

       -  ``V4L2_TUNER_CAP_RDS_BLOCK_IO``

       -  0x0100

       -  The RDS data is passed as unparsed RDS blocks.

    -  .. row 11

       -  ``V4L2_TUNER_CAP_RDS_CONTROLS``

       -  0x0200

       -  The RDS data is parsed by the hardware and set via controls.

    -  .. row 12

       -  ``V4L2_TUNER_CAP_FREQ_BANDS``

       -  0x0400

429
       -  The :ref:`VIDIOC_ENUM_FREQ_BANDS`
430
	  ioctl can be used to enumerate the available frequency bands.
431 432 433 434 435 436 437 438

    -  .. row 13

       -  ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``

       -  0x0800

       -  The range to search when using the hardware seek functionality is
439 440 441
	  programmable, see
	  :ref:`VIDIOC_S_HW_FREQ_SEEK` for
	  details.
442 443 444 445 446 447 448 449

    -  .. row 14

       -  ``V4L2_TUNER_CAP_1HZ``

       -  0x1000

       -  When set, tuning frequencies are expressed in units of 1 Hz
450
	  instead of 62.5 kHz.
451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484



.. _tuner-rxsubchans:

.. flat-table:: Tuner Audio Reception Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_TUNER_SUB_MONO``

       -  0x0001

       -  The tuner receives a mono audio signal.

    -  .. row 2

       -  ``V4L2_TUNER_SUB_STEREO``

       -  0x0002

       -  The tuner receives a stereo audio signal.

    -  .. row 3

       -  ``V4L2_TUNER_SUB_LANG1``

       -  0x0008

       -  The tuner receives the primary language of a bilingual audio
485 486
	  signal. Drivers must clear this flag when the current video
	  standard is ``V4L2_STD_NTSC_M``.
487 488 489 490 491 492 493 494

    -  .. row 4

       -  ``V4L2_TUNER_SUB_LANG2``

       -  0x0004

       -  The tuner receives the secondary language of a bilingual audio
495
	  signal (or a second audio program).
496 497 498 499 500 501 502 503

    -  .. row 5

       -  ``V4L2_TUNER_SUB_SAP``

       -  0x0004

       -  The tuner receives a Second Audio Program. Note the
504 505 506
	  ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP`` flags are
	  synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies when the current
	  video standard is ``V4L2_STD_NTSC_M``.
507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532

    -  .. row 6

       -  ``V4L2_TUNER_SUB_RDS``

       -  0x0010

       -  The tuner receives an RDS channel.



.. _tuner-audmode:

.. flat-table:: Tuner Audio Modes
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4


    -  .. row 1

       -  ``V4L2_TUNER_MODE_MONO``

       -  0

       -  Play mono audio. When the tuner receives a stereo signal this a
533 534
	  down-mix of the left and right channel. When the tuner receives a
	  bilingual or SAP signal this mode selects the primary language.
535 536 537 538 539 540 541 542

    -  .. row 2

       -  ``V4L2_TUNER_MODE_STEREO``

       -  1

       -  Play stereo audio. When the tuner receives bilingual audio it may
543 544
	  play different languages on the left and right channel or the
	  primary language is played on both channels.
545

546 547
	  Playing different languages in this mode is deprecated. New
	  drivers should do this only in ``MODE_LANG1_LANG2``.
548

549 550
	  When the tuner receives no stereo signal or does not support
	  stereo reception the driver shall fall back to ``MODE_MONO``.
551 552 553 554 555 556 557 558

    -  .. row 3

       -  ``V4L2_TUNER_MODE_LANG1``

       -  3

       -  Play the primary language, mono or stereo. Only
559
	  ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
560 561 562 563 564 565 566 567

    -  .. row 4

       -  ``V4L2_TUNER_MODE_LANG2``

       -  2

       -  Play the secondary language, mono. When the tuner receives no
568 569 570
	  bilingual audio or SAP, or their reception is not supported the
	  driver shall fall back to mono or stereo mode. Only
	  ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
571 572 573 574 575 576 577 578

    -  .. row 5

       -  ``V4L2_TUNER_MODE_SAP``

       -  2

       -  Play the Second Audio Program. When the tuner receives no
579 580 581 582 583
	  bilingual audio or SAP, or their reception is not supported the
	  driver shall fall back to mono or stereo mode. Only
	  ``V4L2_TUNER_ANALOG_TV`` tuners support this mode. Note the
	  ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP`` are
	  synonyms.
584 585 586 587 588 589 590 591

    -  .. row 6

       -  ``V4L2_TUNER_MODE_LANG1_LANG2``

       -  4

       -  Play the primary language on the left channel, the secondary
592 593 594 595
	  language on the right channel. When the tuner receives no
	  bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
	  ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
	  mode.
596 597 598 599 600 601 602 603 604 605 606 607



.. _tuner-matrix:

.. flat-table:: Tuner Audio Matrix
    :header-rows:  2
    :stub-columns: 0


    -  .. row 1

608
       -
609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695
       -  :cspan:`5` Selected ``V4L2_TUNER_MODE_``

    -  .. row 2

       -  Received ``V4L2_TUNER_SUB_``

       -  ``MONO``

       -  ``STEREO``

       -  ``LANG1``

       -  ``LANG2 = SAP``

       -  ``LANG1_LANG2``\  [1]_

    -  .. row 3

       -  ``MONO``

       -  Mono

       -  Mono/Mono

       -  Mono

       -  Mono

       -  Mono/Mono

    -  .. row 4

       -  ``MONO | SAP``

       -  Mono

       -  Mono/Mono

       -  Mono

       -  SAP

       -  Mono/SAP (preferred) or Mono/Mono

    -  .. row 5

       -  ``STEREO``

       -  L+R

       -  L/R

       -  Stereo L/R (preferred) or Mono L+R

       -  Stereo L/R (preferred) or Mono L+R

       -  L/R (preferred) or L+R/L+R

    -  .. row 6

       -  ``STEREO | SAP``

       -  L+R

       -  L/R

       -  Stereo L/R (preferred) or Mono L+R

       -  SAP

       -  L+R/SAP (preferred) or L/R or L+R/L+R

    -  .. row 7

       -  ``LANG1 | LANG2``

       -  Language 1

       -  Lang1/Lang2 (deprecated [2]_) or Lang1/Lang1

       -  Language 1

       -  Language 2

       -  Lang1/Lang2 (preferred) or Lang1/Lang1


696
Return Value
697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The struct :ref:`v4l2_tuner <v4l2-tuner>` ``index`` is out of
    bounds.

.. [1]
   This mode has been added in Linux 2.6.17 and may not be supported by
   older drivers.

.. [2]
   Playback of both languages in ``MODE_STEREO`` is deprecated. In the
   future drivers should produce only the primary language in this mode.
   Applications should request ``MODE_LANG1_LANG2`` to record both
   languages or a stereo signal.