1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2.. c:namespace:: V4L
3
4.. _VIDIOC_G_TUNER:
5
6************************************
7ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
8************************************
9
10Name
11====
12
13VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
14
15Synopsis
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
26Arguments
27=========
28
29``fd``
30    File descriptor returned by :c:func:`open()`.
31
32``argp``
33    Pointer to struct :c:type:`v4l2_tuner`.
34
35Description
36===========
37
38To query the attributes of a tuner applications initialize the ``index``
39field and zero out the ``reserved`` array of a struct
40:c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl
41with a pointer to this structure. Drivers fill the rest of the structure
42or return an ``EINVAL`` error code when the index is out of bounds. To
43enumerate 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 radio
47frequency. 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,
50which is determined by the current video input. Drivers may choose a
51different audio mode if the requested mode is invalid or unsupported.
52Since this is a write-only ioctl, it does not return the actually
53selected 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
57to zero. The term 'tuner' means SDR receiver in this context.
58
59To 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{6.6cm}|p{6.6cm}|
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.7cm}|
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{6.6cm}|p{2.2cm}|p{8.7cm}|
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.7cm}|
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.7cm}|
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
445Return Value
446============
447
448On success 0 is returned, on error -1 and the ``errno`` variable is set
449appropriately. The generic error codes are described at the
450:ref:`Generic Error Codes <gen-errors>` chapter.
451
452EINVAL
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.
465