Commit | Line | Data |
---|---|---|
059b1c5b | 1 | .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
407e84cd | 2 | .. c:namespace:: V4L |
82559ac0 | 3 | |
af4a4d0d | 4 | .. _VIDIOC_G_TUNER: |
5377d91f MH |
5 | |
6 | ************************************ | |
7 | ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER | |
8 | ************************************ | |
9 | ||
15e7d615 | 10 | Name |
586027ce | 11 | ==== |
5377d91f | 12 | |
586027ce | 13 | VIDIOC_G_TUNER - VIDIOC_S_TUNER - Get or set tuner attributes |
5377d91f | 14 | |
15e7d615 | 15 | Synopsis |
5377d91f MH |
16 | ======== |
17 | ||
407e84cd MCC |
18 | .. c:macro:: VIDIOC_G_TUNER |
19 | ||
20 | ``int ioctl(int fd, VIDIOC_G_TUNER, struct v4l2_tuner *argp)`` | |
5377d91f | 21 | |
407e84cd | 22 | .. c:macro:: VIDIOC_S_TUNER |
5377d91f | 23 | |
407e84cd | 24 | ``int ioctl(int fd, VIDIOC_S_TUNER, const struct v4l2_tuner *argp)`` |
586027ce | 25 | |
15e7d615 | 26 | Arguments |
5377d91f MH |
27 | ========= |
28 | ||
29 | ``fd`` | |
407e84cd | 30 | File descriptor returned by :c:func:`open()`. |
5377d91f | 31 | |
5377d91f | 32 | ``argp`` |
1473c75e | 33 | Pointer to struct :c:type:`v4l2_tuner`. |
5377d91f | 34 | |
15e7d615 | 35 | Description |
5377d91f MH |
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 | |
e8be7e97 | 40 | :c:type:`v4l2_tuner` and call the ``VIDIOC_G_TUNER`` ioctl |
5377d91f | 41 | with a pointer to this structure. Drivers fill the rest of the structure |
cdb4af0f | 42 | or return an ``EINVAL`` error code when the index is out of bounds. To |
5377d91f | 43 | enumerate all tuners applications shall begin at index zero, |
cdb4af0f | 44 | incrementing by one until the driver returns ``EINVAL``. |
5377d91f MH |
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 | |
af4a4d0d | 60 | :ref:`VIDIOC_S_FREQUENCY <VIDIOC_G_FREQUENCY>` ioctl is available. |
5377d91f | 61 | |
fea13a69 | 62 | .. tabularcolumns:: |p{1.3cm}|p{3.0cm}|p{7.0cm}|p{5.8cm}| |
11d7512b | 63 | |
e8be7e97 | 64 | .. c:type:: v4l2_tuner |
5377d91f | 65 | |
11d7512b MCC |
66 | .. cssclass:: longtable |
67 | ||
5377d91f MH |
68 | .. flat-table:: struct v4l2_tuner |
69 | :header-rows: 0 | |
70 | :stub-columns: 0 | |
71 | ||
c2b66caf LP |
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. | |
5377d91f MH |
183 | |
184 | ||
fea13a69 | 185 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| |
5bd4bb78 | 186 | |
56683d7d | 187 | .. c:type:: v4l2_tuner_type |
fa92b04d | 188 | |
5377d91f MH |
189 | .. flat-table:: enum v4l2_tuner_type |
190 | :header-rows: 0 | |
191 | :stub-columns: 0 | |
e19c1779 | 192 | :widths: 3 1 6 |
5377d91f | 193 | |
c2b66caf LP |
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 | |
84512f3e | 203 | Software Digital Radio (SDR) |
c2b66caf LP |
204 | * - ``V4L2_TUNER_RF`` |
205 | - 5 | |
84512f3e | 206 | - Tuner controls the RF part of a Software Digital Radio (SDR) |
5377d91f | 207 | |
fea13a69 | 208 | .. tabularcolumns:: |p{7.0cm}|p{2.2cm}|p{8.1cm}| |
5bd4bb78 | 209 | |
fa92b04d MCC |
210 | .. _tuner-capability: |
211 | ||
11d7512b MCC |
212 | .. cssclass:: longtable |
213 | ||
5377d91f MH |
214 | .. flat-table:: Tuner and Modulator Capability Flags |
215 | :header-rows: 0 | |
216 | :stub-columns: 0 | |
217 | :widths: 3 1 4 | |
218 | ||
c2b66caf LP |
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. | |
5377d91f MH |
297 | |
298 | ||
fea13a69 MCC |
299 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| |
300 | ||
c4a1bff9 MCC |
301 | .. _tuner-rxsubchans: |
302 | ||
5377d91f MH |
303 | .. flat-table:: Tuner Audio Reception Flags |
304 | :header-rows: 0 | |
305 | :stub-columns: 0 | |
306 | :widths: 3 1 4 | |
307 | ||
c2b66caf LP |
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. | |
5377d91f MH |
335 | |
336 | ||
fea13a69 | 337 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| |
5bd4bb78 | 338 | |
fa92b04d MCC |
339 | .. _tuner-audmode: |
340 | ||
5377d91f MH |
341 | .. flat-table:: Tuner Audio Modes |
342 | :header-rows: 0 | |
343 | :stub-columns: 0 | |
344 | :widths: 3 1 4 | |
345 | ||
c2b66caf LP |
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. | |
5377d91f | 388 | |
11d7512b | 389 | .. raw:: latex |
5377d91f | 390 | |
70b074df | 391 | \scriptsize |
5377d91f | 392 | |
4d643696 MCC |
393 | .. tabularcolumns:: |p{1.5cm}|p{1.5cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}| |
394 | ||
5377d91f MH |
395 | .. _tuner-matrix: |
396 | ||
397 | .. flat-table:: Tuner Audio Matrix | |
398 | :header-rows: 2 | |
399 | :stub-columns: 0 | |
4d643696 | 400 | :widths: 7 7 14 14 14 14 |
5377d91f | 401 | |
c2b66caf | 402 | * - |
4d643696 | 403 | - :cspan:`4` Selected ``V4L2_TUNER_MODE_`` |
c2b66caf LP |
404 | * - Received ``V4L2_TUNER_SUB_`` |
405 | - ``MONO`` | |
406 | - ``STEREO`` | |
407 | - ``LANG1`` | |
408 | - ``LANG2 = SAP`` | |
4d643696 | 409 | - ``LANG1_LANG2``\ [#f1]_ |
c2b66caf LP |
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 | |
4d643696 | 436 | - Lang1/Lang2 (deprecated\ [#f2]_) or Lang1/Lang1 |
c2b66caf LP |
437 | - Language 1 |
438 | - Language 2 | |
439 | - Lang1/Lang2 (preferred) or Lang1/Lang1 | |
5377d91f | 440 | |
11d7512b MCC |
441 | .. raw:: latex |
442 | ||
70b074df | 443 | \normalsize |
5377d91f | 444 | |
15e7d615 | 445 | Return Value |
5377d91f MH |
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 | |
e8be7e97 | 453 | The struct :c:type:`v4l2_tuner` ``index`` is out of |
5377d91f MH |
454 | bounds. |
455 | ||
4855307b | 456 | .. [#f1] |
5377d91f MH |
457 | This mode has been added in Linux 2.6.17 and may not be supported by |
458 | older drivers. | |
459 | ||
4855307b | 460 | .. [#f2] |
5377d91f MH |
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. |