465 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: V4L3 4.. _VIDIOC_G_TUNER:5 6************************************7ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER8************************************9 10Name11====12 13VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes14 15Synopsis16========17 18.. c:macro:: VIDIOC_G_TUNER19 20``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)``21 22.. c:macro:: VIDIOC_S_TUNER23 24``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)``25 26Arguments27=========28 29``fd``30 File descriptor returned by :c:func:`open()`.31 32``argp``33 Pointer to struct :c:type:`v4l2_tuner`.34 35Description36===========37 38To query the attributes of a tuner applications initialize the ``index``39field and zero out the ``reserved`` array of a struct40:c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl41with a pointer to this structure. Drivers fill the rest of the structure42or return an ``EINVAL`` error code when the index is out of bounds. To43enumerate all tuners applications shall begin at index zero,44incrementing by one until the driver returns ``EINVAL``.45 46Tuners have two writable properties, the audio mode and the radio47frequency. To change the audio mode, applications initialize the48``index``, ``audmode`` and ``reserved`` fields and call the49``VIDIOC_S_TUNER`` ioctl. This will *not* change the current tuner,50which is determined by the current video input. Drivers may choose a51different audio mode if the requested mode is invalid or unsupported.52Since this is a write-only ioctl, it does not return the actually53selected audio mode.54 55:ref:`SDR <sdr>` specific tuner types are ``V4L2_TUNER_SDR`` and56``V4L2_TUNER_RF``. For SDR devices ``audmode`` field must be initialized57to zero. The term 'tuner' means SDR receiver in this context.58 59To change the radio frequency the60:ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available.61 62 .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}|63 64.. c:type:: v4l2_tuner65 66.. cssclass:: longtable67 68.. flat-table:: struct v4l2_tuner69 :header-rows: 070 :stub-columns: 071 72 * - __u3273 - ``index``74 - :cspan:`1` Identifies the tuner, set by the application.75 * - __u876 - ``name``\ [32]77 - :cspan:`1`78 79 Name of the tuner, a NUL-terminated ASCII string.80 81 This information is intended for the user.82 * - __u3283 - ``type``84 - :cspan:`1` Type of the tuner, see :c:type:`v4l2_tuner_type`.85 * - __u3286 - ``capability``87 - :cspan:`1`88 89 Tuner capability flags, see :ref:`tuner-capability`. Audio flags90 indicate the ability to decode audio subprograms. They will *not*91 change, for example with the current video standard.92 93 When the structure refers to a radio tuner the94 ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and95 ``V4L2_TUNER_CAP_NORM`` flags can't be used.96 97 If multiple frequency bands are supported, then ``capability`` is98 the union of all ``capability`` fields of each struct99 :c:type:`v4l2_frequency_band`.100 * - __u32101 - ``rangelow``102 - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or103 if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units104 of 62.5 Hz, or if the ``capability`` flag ``V4L2_TUNER_CAP_1HZ``105 is set, in units of 1 Hz. If multiple frequency bands are106 supported, then ``rangelow`` is the lowest frequency of all the107 frequency bands.108 * - __u32109 - ``rangehigh``110 - :cspan:`1` The highest tunable frequency in units of 62.5 kHz,111 or if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in112 units of 62.5 Hz, or if the ``capability`` flag113 ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple114 frequency bands are supported, then ``rangehigh`` is the highest115 frequency of all the frequency bands.116 * - __u32117 - ``rxsubchans``118 - :cspan:`1`119 120 Some tuners or audio decoders can determine the received audio121 subprograms by analyzing audio carriers, pilot tones or other122 indicators. To pass this information drivers set flags defined in123 :ref:`tuner-rxsubchans` in this field. For example:124 * -125 -126 - ``V4L2_TUNER_SUB_MONO``127 - receiving mono audio128 * -129 -130 - ``STEREO | SAP``131 - receiving stereo audio and a secondary audio program132 * -133 -134 - ``MONO | STEREO``135 - receiving mono or stereo audio, the hardware cannot distinguish136 * -137 -138 - ``LANG1 | LANG2``139 - receiving bilingual audio140 * -141 -142 - ``MONO | STEREO | LANG1 | LANG2``143 - receiving mono, stereo or bilingual audio144 * -145 -146 - :cspan:`1`147 148 When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or149 ``_SAP`` flag is cleared in the ``capability`` field, the150 corresponding ``V4L2_TUNER_SUB_`` flag must not be set here.151 152 This field is valid only if this is the tuner of the current video153 input, or when the structure refers to a radio tuner.154 * - __u32155 - ``audmode``156 - :cspan:`1`157 158 The selected audio mode, see :ref:`tuner-audmode` for valid159 values. The audio mode does not affect audio subprogram detection,160 and like a :ref:`control` it does not automatically161 change unless the requested mode is invalid or unsupported. See162 :ref:`tuner-matrix` for possible results when the selected and163 received audio programs do not match.164 165 Currently this is the only field of struct166 struct :c:type:`v4l2_tuner` applications can change.167 * - __u32168 - ``signal``169 - :cspan:`1` The signal strength if known.170 171 Ranging from 0 to 65535. Higher values indicate a better signal.172 * - __s32173 - ``afc``174 - :cspan:`1` Automatic frequency control.175 176 When the ``afc`` value is negative, the frequency is too177 low, when positive too high.178 * - __u32179 - ``reserved``\ [4]180 - :cspan:`1` Reserved for future extensions.181 182 Drivers and applications must set the array to zero.183 184 185.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|186 187.. c:type:: v4l2_tuner_type188 189.. flat-table:: enum v4l2_tuner_type190 :header-rows: 0191 :stub-columns: 0192 :widths: 3 1 6193 194 * - ``V4L2_TUNER_RADIO``195 - 1196 - Tuner supports radio197 * - ``V4L2_TUNER_ANALOG_TV``198 - 2199 - Tuner supports analog TV200 * - ``V4L2_TUNER_SDR``201 - 4202 - Tuner controls the A/D and/or D/A block of a203 Software Digital Radio (SDR)204 * - ``V4L2_TUNER_RF``205 - 5206 - Tuner controls the RF part of a Software Digital Radio (SDR)207 208.. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm}|209 210.. _tuner-capability:211 212.. cssclass:: longtable213 214.. flat-table:: Tuner and Modulator Capability Flags215 :header-rows: 0216 :stub-columns: 0217 :widths: 3 1 4218 219 * - ``V4L2_TUNER_CAP_LOW``220 - 0x0001221 - When set, tuning frequencies are expressed in units of 62.5 Hz222 instead of 62.5 kHz.223 * - ``V4L2_TUNER_CAP_NORM``224 - 0x0002225 - This is a multi-standard tuner; the video standard can or must be226 switched. (B/G PAL tuners for example are typically not considered227 multi-standard because the video standard is automatically228 determined from the frequency band.) The set of supported video229 standards is available from the struct230 :c:type:`v4l2_input` pointing to this tuner, see the231 description of ioctl :ref:`VIDIOC_ENUMINPUT`232 for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this233 capability.234 * - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``235 - 0x0004236 - If set, then this tuner supports the hardware seek functionality237 where the seek stops when it reaches the end of the frequency238 range.239 * - ``V4L2_TUNER_CAP_HWSEEK_WRAP``240 - 0x0008241 - If set, then this tuner supports the hardware seek functionality242 where the seek wraps around when it reaches the end of the243 frequency range.244 * - ``V4L2_TUNER_CAP_STEREO``245 - 0x0010246 - Stereo audio reception is supported.247 * - ``V4L2_TUNER_CAP_LANG1``248 - 0x0040249 - Reception of the primary language of a bilingual audio program is250 supported. Bilingual audio is a feature of two-channel systems,251 transmitting the primary language monaural on the main audio252 carrier and a secondary language monaural on a second carrier.253 Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.254 * - ``V4L2_TUNER_CAP_LANG2``255 - 0x0020256 - Reception of the secondary language of a bilingual audio program257 is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this258 capability.259 * - ``V4L2_TUNER_CAP_SAP``260 - 0x0020261 - Reception of a secondary audio program is supported. This is a262 feature of the BTSC system which accompanies the NTSC video263 standard. Two audio carriers are available for mono or stereo264 transmissions of a primary language, and an independent third265 carrier for a monaural secondary language. Only266 ``V4L2_TUNER_ANALOG_TV`` tuners can have this capability.267 268 .. note::269 270 The ``V4L2_TUNER_CAP_LANG2`` and ``V4L2_TUNER_CAP_SAP``271 flags are synonyms. ``V4L2_TUNER_CAP_SAP`` applies when the tuner272 supports the ``V4L2_STD_NTSC_M`` video standard.273 * - ``V4L2_TUNER_CAP_RDS``274 - 0x0080275 - RDS capture is supported. This capability is only valid for radio276 tuners.277 * - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``278 - 0x0100279 - The RDS data is passed as unparsed RDS blocks.280 * - ``V4L2_TUNER_CAP_RDS_CONTROLS``281 - 0x0200282 - The RDS data is parsed by the hardware and set via controls.283 * - ``V4L2_TUNER_CAP_FREQ_BANDS``284 - 0x0400285 - The :ref:`VIDIOC_ENUM_FREQ_BANDS`286 ioctl can be used to enumerate the available frequency bands.287 * - ``V4L2_TUNER_CAP_HWSEEK_PROG_LIM``288 - 0x0800289 - The range to search when using the hardware seek functionality is290 programmable, see291 :ref:`VIDIOC_S_HW_FREQ_SEEK` for292 details.293 * - ``V4L2_TUNER_CAP_1HZ``294 - 0x1000295 - When set, tuning frequencies are expressed in units of 1 Hz296 instead of 62.5 kHz.297 298 299.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|300 301.. _tuner-rxsubchans:302 303.. flat-table:: Tuner Audio Reception Flags304 :header-rows: 0305 :stub-columns: 0306 :widths: 3 1 4307 308 * - ``V4L2_TUNER_SUB_MONO``309 - 0x0001310 - The tuner receives a mono audio signal.311 * - ``V4L2_TUNER_SUB_STEREO``312 - 0x0002313 - The tuner receives a stereo audio signal.314 * - ``V4L2_TUNER_SUB_LANG1``315 - 0x0008316 - The tuner receives the primary language of a bilingual audio317 signal. Drivers must clear this flag when the current video318 standard is ``V4L2_STD_NTSC_M``.319 * - ``V4L2_TUNER_SUB_LANG2``320 - 0x0004321 - The tuner receives the secondary language of a bilingual audio322 signal (or a second audio program).323 * - ``V4L2_TUNER_SUB_SAP``324 - 0x0004325 - The tuner receives a Second Audio Program.326 327 .. note::328 329 The ``V4L2_TUNER_SUB_LANG2`` and ``V4L2_TUNER_SUB_SAP``330 flags are synonyms. The ``V4L2_TUNER_SUB_SAP`` flag applies331 when the current video standard is ``V4L2_STD_NTSC_M``.332 * - ``V4L2_TUNER_SUB_RDS``333 - 0x0010334 - The tuner receives an RDS channel.335 336 337.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|338 339.. _tuner-audmode:340 341.. flat-table:: Tuner Audio Modes342 :header-rows: 0343 :stub-columns: 0344 :widths: 3 1 4345 346 * - ``V4L2_TUNER_MODE_MONO``347 - 0348 - Play mono audio. When the tuner receives a stereo signal this a349 down-mix of the left and right channel. When the tuner receives a350 bilingual or SAP signal this mode selects the primary language.351 * - ``V4L2_TUNER_MODE_STEREO``352 - 1353 - Play stereo audio. When the tuner receives bilingual audio it may354 play different languages on the left and right channel or the355 primary language is played on both channels.356 357 Playing different languages in this mode is deprecated. New358 drivers should do this only in ``MODE_LANG1_LANG2``.359 360 When the tuner receives no stereo signal or does not support361 stereo reception the driver shall fall back to ``MODE_MONO``.362 * - ``V4L2_TUNER_MODE_LANG1``363 - 3364 - Play the primary language, mono or stereo. Only365 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.366 * - ``V4L2_TUNER_MODE_LANG2``367 - 2368 - Play the secondary language, mono. When the tuner receives no369 bilingual audio or SAP, or their reception is not supported the370 driver shall fall back to mono or stereo mode. Only371 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.372 * - ``V4L2_TUNER_MODE_SAP``373 - 2374 - Play the Second Audio Program. When the tuner receives no375 bilingual audio or SAP, or their reception is not supported the376 driver shall fall back to mono or stereo mode. Only377 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.378 379 .. note:: The ``V4L2_TUNER_MODE_LANG2`` and ``V4L2_TUNER_MODE_SAP``380 are synonyms.381 * - ``V4L2_TUNER_MODE_LANG1_LANG2``382 - 4383 - Play the primary language on the left channel, the secondary384 language on the right channel. When the tuner receives no385 bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or386 ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this387 mode.388 389.. raw:: latex390 391 \scriptsize392 393.. tabularcolumns:: |p{1.5cm}|p{1.5cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|394 395.. _tuner-matrix:396 397.. flat-table:: Tuner Audio Matrix398 :header-rows: 2399 :stub-columns: 0400 :widths: 7 7 14 14 14 14401 402 * -403 - :cspan:`4` Selected ``V4L2_TUNER_MODE_``404 * - Received ``V4L2_TUNER_SUB_``405 - ``MONO``406 - ``STEREO``407 - ``LANG1``408 - ``LANG2 = SAP``409 - ``LANG1_LANG2``\ [#f1]_410 * - ``MONO``411 - Mono412 - Mono/Mono413 - Mono414 - Mono415 - Mono/Mono416 * - ``MONO | SAP``417 - Mono418 - Mono/Mono419 - Mono420 - SAP421 - Mono/SAP (preferred) or Mono/Mono422 * - ``STEREO``423 - L+R424 - L/R425 - Stereo L/R (preferred) or Mono L+R426 - Stereo L/R (preferred) or Mono L+R427 - L/R (preferred) or L+R/L+R428 * - ``STEREO | SAP``429 - L+R430 - L/R431 - Stereo L/R (preferred) or Mono L+R432 - SAP433 - L+R/SAP (preferred) or L/R or L+R/L+R434 * - ``LANG1 | LANG2``435 - Language 1436 - Lang1/Lang2 (deprecated\ [#f2]_) or Lang1/Lang1437 - Language 1438 - Language 2439 - Lang1/Lang2 (preferred) or Lang1/Lang1440 441.. raw:: latex442 443 \normalsize444 445Return Value446============447 448On success 0 is returned, on error -1 and the ``errno`` variable is set449appropriately. The generic error codes are described at the450:ref:`Generic Error Codes <gen-errors>` chapter.451 452EINVAL453 The struct :c:type:`v4l2_tuner` ``index`` is out of454 bounds.455 456.. [#f1]457 This mode has been added in Linux 2.6.17 and may not be supported by458 older drivers.459 460.. [#f2]461 Playback of both languages in ``MODE_STEREO`` is deprecated. In the462 future drivers should produce only the primary language in this mode.463 Applications should request ``MODE_LANG1_LANG2`` to record both464 languages or a stereo signal.465