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