1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: V4L
3
4 .. _VIDIOC_G_TUNER:
5
6 ************************************
7 ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
8 ************************************
9
10 Name
11 ====
12
13 VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
14
15 Synopsis
16 ========
17
18 .. c:macro:: VIDIOC_G_TUNER
19
20 ``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)``
21
22 .. c:macro:: VIDIOC_S_TUNER
23
24 ``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)``
25
26 Arguments
27 =========
28
29 ``fd``
30 File descriptor returned by :c:func:`open()`.
31
32 ``argp``
33 Pointer to struct :c:type:`v4l2_tuner`.
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 :c:type:`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 .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}|
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 * - __u32
73 - ``index``
74 - :cspan:`1` Identifies the tuner, set by the application.
75 * - __u8
76 - ``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 * - __u32
83 - ``type``
84 - :cspan:`1` Type of the tuner, see :c:type:`v4l2_tuner_type`.
85 * - __u32
86 - ``capability``
87 - :cspan:`1`
88
89 Tuner capability flags, see :ref:`tuner-capability`. Audio flags
90 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 the
94 ``V4L2_TUNER_CAP_LANG1``, ``V4L2_TUNER_CAP_LANG2`` and
95 ``V4L2_TUNER_CAP_NORM`` flags can't be used.
96
97 If multiple frequency bands are supported, then ``capability`` is
98 the union of all ``capability`` fields of each struct
99 :c:type:`v4l2_frequency_band`.
100 * - __u32
101 - ``rangelow``
102 - :cspan:`1` The lowest tunable frequency in units of 62.5 kHz, or
103 if the ``capability`` flag ``V4L2_TUNER_CAP_LOW`` is set, in units
104 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 are
106 supported, then ``rangelow`` is the lowest frequency of all the
107 frequency bands.
108 * - __u32
109 - ``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, in
112 units of 62.5 Hz, or if the ``capability`` flag
113 ``V4L2_TUNER_CAP_1HZ`` is set, in units of 1 Hz. If multiple
114 frequency bands are supported, then ``rangehigh`` is the highest
115 frequency of all the frequency bands.
116 * - __u32
117 - ``rxsubchans``
118 - :cspan:`1`
119
120 Some tuners or audio decoders can determine the received audio
121 subprograms by analyzing audio carriers, pilot tones or other
122 indicators. To pass this information drivers set flags defined in
123 :ref:`tuner-rxsubchans` in this field. For example:
124 * -
125 -
126 - ``V4L2_TUNER_SUB_MONO``
127 - receiving mono audio
128 * -
129 -
130 - ``STEREO | SAP``
131 - receiving stereo audio and a secondary audio program
132 * -
133 -
134 - ``MONO | STEREO``
135 - receiving mono or stereo audio, the hardware cannot distinguish
136 * -
137 -
138 - ``LANG1 | LANG2``
139 - receiving bilingual audio
140 * -
141 -
142 - ``MONO | STEREO | LANG1 | LANG2``
143 - receiving mono, stereo or bilingual audio
144 * -
145 -
146 - :cspan:`1`
147
148 When the ``V4L2_TUNER_CAP_STEREO``, ``_LANG1``, ``_LANG2`` or
149 ``_SAP`` flag is cleared in the ``capability`` field, the
150 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 video
153 input, or when the structure refers to a radio tuner.
154 * - __u32
155 - ``audmode``
156 - :cspan:`1`
157
158 The selected audio mode, see :ref:`tuner-audmode` for valid
159 values. The audio mode does not affect audio subprogram detection,
160 and like a :ref:`control` it does not automatically
161 change unless the requested mode is invalid or unsupported. See
162 :ref:`tuner-matrix` for possible results when the selected and
163 received audio programs do not match.
164
165 Currently this is the only field of struct
166 struct :c:type:`v4l2_tuner` applications can change.
167 * - __u32
168 - ``signal``
169 - :cspan:`1` The signal strength if known.
170
171 Ranging from 0 to 65535. Higher values indicate a better signal.
172 * - __s32
173 - ``afc``
174 - :cspan:`1` Automatic frequency control.
175
176 When the ``afc`` value is negative, the frequency is too
177 low, when positive too high.
178 * - __u32
179 - ``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_type
188
189 .. flat-table:: enum v4l2_tuner_type
190 :header-rows: 0
191 :stub-columns: 0
192 :widths: 3 1 6
193
194 * - ``V4L2_TUNER_RADIO``
195 - 1
196 - Tuner supports radio
197 * - ``V4L2_TUNER_ANALOG_TV``
198 - 2
199 - Tuner supports analog TV
200 * - ``V4L2_TUNER_SDR``
201 - 4
202 - Tuner controls the A/D and/or D/A block of a
203 Software Digital Radio (SDR)
204 * - ``V4L2_TUNER_RF``
205 - 5
206 - 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:: longtable
213
214 .. flat-table:: Tuner and Modulator Capability Flags
215 :header-rows: 0
216 :stub-columns: 0
217 :widths: 3 1 4
218
219 * - ``V4L2_TUNER_CAP_LOW``
220 - 0x0001
221 - When set, tuning frequencies are expressed in units of 62.5 Hz
222 instead of 62.5 kHz.
223 * - ``V4L2_TUNER_CAP_NORM``
224 - 0x0002
225 - This is a multi-standard tuner; the video standard can or must be
226 switched. (B/G PAL tuners for example are typically not considered
227 multi-standard because the video standard is automatically
228 determined from the frequency band.) The set of supported video
229 standards is available from the struct
230 :c:type:`v4l2_input` pointing to this tuner, see the
231 description of ioctl :ref:`VIDIOC_ENUMINPUT`
232 for details. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
233 capability.
234 * - ``V4L2_TUNER_CAP_HWSEEK_BOUNDED``
235 - 0x0004
236 - If set, then this tuner supports the hardware seek functionality
237 where the seek stops when it reaches the end of the frequency
238 range.
239 * - ``V4L2_TUNER_CAP_HWSEEK_WRAP``
240 - 0x0008
241 - If set, then this tuner supports the hardware seek functionality
242 where the seek wraps around when it reaches the end of the
243 frequency range.
244 * - ``V4L2_TUNER_CAP_STEREO``
245 - 0x0010
246 - Stereo audio reception is supported.
247 * - ``V4L2_TUNER_CAP_LANG1``
248 - 0x0040
249 - Reception of the primary language of a bilingual audio program is
250 supported. Bilingual audio is a feature of two-channel systems,
251 transmitting the primary language monaural on the main audio
252 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 - 0x0020
256 - Reception of the secondary language of a bilingual audio program
257 is supported. Only ``V4L2_TUNER_ANALOG_TV`` tuners can have this
258 capability.
259 * - ``V4L2_TUNER_CAP_SAP``
260 - 0x0020
261 - Reception of a secondary audio program is supported. This is a
262 feature of the BTSC system which accompanies the NTSC video
263 standard. Two audio carriers are available for mono or stereo
264 transmissions of a primary language, and an independent third
265 carrier for a monaural secondary language. Only
266 ``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 tuner
272 supports the ``V4L2_STD_NTSC_M`` video standard.
273 * - ``V4L2_TUNER_CAP_RDS``
274 - 0x0080
275 - RDS capture is supported. This capability is only valid for radio
276 tuners.
277 * - ``V4L2_TUNER_CAP_RDS_BLOCK_IO``
278 - 0x0100
279 - The RDS data is passed as unparsed RDS blocks.
280 * - ``V4L2_TUNER_CAP_RDS_CONTROLS``
281 - 0x0200
282 - The RDS data is parsed by the hardware and set via controls.
283 * - ``V4L2_TUNER_CAP_FREQ_BANDS``
284 - 0x0400
285 - 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 - 0x0800
289 - The range to search when using the hardware seek functionality is
290 programmable, see
291 :ref:`VIDIOC_S_HW_FREQ_SEEK` for
292 details.
293 * - ``V4L2_TUNER_CAP_1HZ``
294 - 0x1000
295 - When set, tuning frequencies are expressed in units of 1 Hz
296 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 Flags
304 :header-rows: 0
305 :stub-columns: 0
306 :widths: 3 1 4
307
308 * - ``V4L2_TUNER_SUB_MONO``
309 - 0x0001
310 - The tuner receives a mono audio signal.
311 * - ``V4L2_TUNER_SUB_STEREO``
312 - 0x0002
313 - The tuner receives a stereo audio signal.
314 * - ``V4L2_TUNER_SUB_LANG1``
315 - 0x0008
316 - The tuner receives the primary language of a bilingual audio
317 signal. Drivers must clear this flag when the current video
318 standard is ``V4L2_STD_NTSC_M``.
319 * - ``V4L2_TUNER_SUB_LANG2``
320 - 0x0004
321 - The tuner receives the secondary language of a bilingual audio
322 signal (or a second audio program).
323 * - ``V4L2_TUNER_SUB_SAP``
324 - 0x0004
325 - 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 applies
331 when the current video standard is ``V4L2_STD_NTSC_M``.
332 * - ``V4L2_TUNER_SUB_RDS``
333 - 0x0010
334 - 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 Modes
342 :header-rows: 0
343 :stub-columns: 0
344 :widths: 3 1 4
345
346 * - ``V4L2_TUNER_MODE_MONO``
347 - 0
348 - Play mono audio. When the tuner receives a stereo signal this a
349 down-mix of the left and right channel. When the tuner receives a
350 bilingual or SAP signal this mode selects the primary language.
351 * - ``V4L2_TUNER_MODE_STEREO``
352 - 1
353 - Play stereo audio. When the tuner receives bilingual audio it may
354 play different languages on the left and right channel or the
355 primary language is played on both channels.
356
357 Playing different languages in this mode is deprecated. New
358 drivers should do this only in ``MODE_LANG1_LANG2``.
359
360 When the tuner receives no stereo signal or does not support
361 stereo reception the driver shall fall back to ``MODE_MONO``.
362 * - ``V4L2_TUNER_MODE_LANG1``
363 - 3
364 - Play the primary language, mono or stereo. Only
365 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
366 * - ``V4L2_TUNER_MODE_LANG2``
367 - 2
368 - Play the secondary language, mono. When the tuner receives no
369 bilingual audio or SAP, or their reception is not supported the
370 driver shall fall back to mono or stereo mode. Only
371 ``V4L2_TUNER_ANALOG_TV`` tuners support this mode.
372 * - ``V4L2_TUNER_MODE_SAP``
373 - 2
374 - Play the Second Audio Program. When the tuner receives no
375 bilingual audio or SAP, or their reception is not supported the
376 driver shall fall back to mono or stereo mode. Only
377 ``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 - 4
383 - Play the primary language on the left channel, the secondary
384 language on the right channel. When the tuner receives no
385 bilingual audio or SAP, it shall fall back to ``MODE_LANG1`` or
386 ``MODE_MONO``. Only ``V4L2_TUNER_ANALOG_TV`` tuners support this
387 mode.
388
389 .. raw:: latex
390
391 \scriptsize
392
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 Matrix
398 :header-rows: 2
399 :stub-columns: 0
400 :widths: 7 7 14 14 14 14
401
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 - Mono
412 - Mono/Mono
413 - Mono
414 - Mono
415 - Mono/Mono
416 * - ``MONO | SAP``
417 - Mono
418 - Mono/Mono
419 - Mono
420 - SAP
421 - Mono/SAP (preferred) or Mono/Mono
422 * - ``STEREO``
423 - L+R
424 - L/R
425 - Stereo L/R (preferred) or Mono L+R
426 - Stereo L/R (preferred) or Mono L+R
427 - L/R (preferred) or L+R/L+R
428 * - ``STEREO | SAP``
429 - L+R
430 - L/R
431 - Stereo L/R (preferred) or Mono L+R
432 - SAP
433 - L+R/SAP (preferred) or L/R or L+R/L+R
434 * - ``LANG1 | LANG2``
435 - Language 1
436 - Lang1/Lang2 (deprecated\ [#f2]_) or Lang1/Lang1
437 - Language 1
438 - Language 2
439 - Lang1/Lang2 (preferred) or Lang1/Lang1
440
441 .. raw:: latex
442
443 \normalsize
444
445 Return Value
446 ============
447
448 On success 0 is returned, on error -1 and the ``errno`` variable is set
449 appropriately. The generic error codes are described at the
450 :ref:`Generic Error Codes <gen-errors>` chapter.
451
452 EINVAL
453 The struct :c:type:`v4l2_tuner` ``index`` is out of
454 bounds.
455
456 .. [#f1]
457 This mode has been added in Linux 2.6.17 and may not be supported by
458 older drivers.
459
460 .. [#f2]
461 Playback of both languages in ``MODE_STEREO`` is deprecated. In the
462 future drivers should produce only the primary language in this mode.
463 Applications should request ``MODE_LANG1_LANG2`` to record both
464 languages or a stereo signal.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.