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