GNU Linux-libre 4.14.295-gnu1
[releases.git] / Documentation / media / uapi / v4l / vidioc-g-tuner.rst
1 .. -*- coding: utf-8; mode: rst -*-
2
3 .. _VIDIOC_G_TUNER:
4
5 ************************************
6 ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER
7 ************************************
8
9 Name
10 ====
11
12 VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes
13
14
15 Synopsis
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
25 Arguments
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
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
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
450 Return Value
451 ============
452
453 On success 0 is returned, on error -1 and the ``errno`` variable is set
454 appropriately. The generic error codes are described at the
455 :ref:`Generic Error Codes <gen-errors>` chapter.
456
457 EINVAL
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.