| blob | bd98c734c06b68f34be7a1ce40c426fb2befdd23 |
1 <refentry id="vidioc-g-tuner">
2 <refmeta>
3 <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle>
4 &manvol;
5 </refmeta>
7 <refnamediv>
8 <refname>VIDIOC_G_TUNER</refname>
9 <refname>VIDIOC_S_TUNER</refname>
10 <refpurpose>Get or set tuner attributes</refpurpose>
11 </refnamediv>
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>struct v4l2_tuner
20 *<parameter>argp</parameter></paramdef>
21 </funcprototype>
22 </funcsynopsis>
23 <funcsynopsis>
24 <funcprototype>
25 <funcdef>int <function>ioctl</function></funcdef>
26 <paramdef>int <parameter>fd</parameter></paramdef>
27 <paramdef>int <parameter>request</parameter></paramdef>
28 <paramdef>const struct v4l2_tuner
29 *<parameter>argp</parameter></paramdef>
30 </funcprototype>
31 </funcsynopsis>
32 </refsynopsisdiv>
34 <refsect1>
35 <title>Arguments</title>
37 <variablelist>
38 <varlistentry>
39 <term><parameter>fd</parameter></term>
40 <listitem>
41 <para>&fd;</para>
42 </listitem>
43 </varlistentry>
44 <varlistentry>
45 <term><parameter>request</parameter></term>
46 <listitem>
47 <para>VIDIOC_G_TUNER, VIDIOC_S_TUNER</para>
48 </listitem>
49 </varlistentry>
50 <varlistentry>
51 <term><parameter>argp</parameter></term>
52 <listitem>
53 <para></para>
54 </listitem>
55 </varlistentry>
56 </variablelist>
57 </refsect1>
59 <refsect1>
60 <title>Description</title>
62 <para>To query the attributes of a tuner applications initialize the
63 <structfield>index</structfield> field and zero out the
64 <structfield>reserved</structfield> array of a &v4l2-tuner; and call the
65 <constant>VIDIOC_G_TUNER</constant> ioctl with a pointer to this
66 structure. Drivers fill the rest of the structure or return an
67 &EINVAL; when the index is out of bounds. To enumerate all tuners
68 applications shall begin at index zero, incrementing by one until the
69 driver returns <errorcode>EINVAL</errorcode>.</para>
71 <para>Tuners have two writable properties, the audio mode and
72 the radio frequency. To change the audio mode, applications initialize
73 the <structfield>index</structfield>,
74 <structfield>audmode</structfield> and
75 <structfield>reserved</structfield> fields and call the
76 <constant>VIDIOC_S_TUNER</constant> ioctl. This will
77 <emphasis>not</emphasis> change the current tuner, which is determined
78 by the current video input. Drivers may choose a different audio mode
79 if the requested mode is invalid or unsupported. Since this is a
80 <!-- FIXME -->write-only ioctl, it does not return the actually
81 selected audio mode.</para>
83 <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
84 is available.</para>
86 <table pgwide="1" frame="none" id="v4l2-tuner">
87 <title>struct <structname>v4l2_tuner</structname></title>
88 <tgroup cols="3">
89 <colspec colname="c1" colwidth="1*" />
90 <colspec colname="c2" colwidth="1*" />
91 <colspec colname="c3" colwidth="1*" />
92 <colspec colname="c4" colwidth="1*" />
93 <spanspec spanname="hspan" namest="c3" nameend="c4" />
94 <tbody valign="top">
95 <row>
96 <entry>__u32</entry>
97 <entry><structfield>index</structfield></entry>
98 <entry spanname="hspan">Identifies the tuner, set by the
99 application.</entry>
100 </row>
101 <row>
102 <entry>__u8</entry>
103 <entry><structfield>name</structfield>[32]</entry>
104 <entry spanname="hspan"><para>Name of the tuner, a
105 NUL-terminated ASCII string. This information is intended for the
106 user.<!-- FIXME Video inputs already have a name, the purpose of this
107 field is not quite clear.--></para></entry>
108 </row>
109 <row>
110 <entry>&v4l2-tuner-type;</entry>
111 <entry><structfield>type</structfield></entry>
112 <entry spanname="hspan">Type of the tuner, see <xref
113 linkend="v4l2-tuner-type" />.</entry>
114 </row>
115 <row>
116 <entry>__u32</entry>
117 <entry><structfield>capability</structfield></entry>
118 <entry spanname="hspan"><para>Tuner capability flags, see
119 <xref linkend="tuner-capability" />. Audio flags indicate the ability
120 to decode audio subprograms. They will <emphasis>not</emphasis>
121 change, for example with the current video standard.</para><para>When
122 the structure refers to a radio tuner only the
123 <constant>V4L2_TUNER_CAP_LOW</constant>,
124 <constant>V4L2_TUNER_CAP_STEREO</constant> and
125 <constant>V4L2_TUNER_CAP_RDS</constant> flags can be set.</para></entry>
126 </row>
127 <row>
128 <entry>__u32</entry>
129 <entry><structfield>rangelow</structfield></entry>
130 <entry spanname="hspan">The lowest tunable frequency in
131 units of 62.5 kHz, or if the <structfield>capability</structfield>
132 flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
133 Hz.</entry>
134 </row>
135 <row>
136 <entry>__u32</entry>
137 <entry><structfield>rangehigh</structfield></entry>
138 <entry spanname="hspan">The highest tunable frequency in
139 units of 62.5 kHz, or if the <structfield>capability</structfield>
140 flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
141 Hz.</entry>
142 </row>
143 <row>
144 <entry>__u32</entry>
145 <entry><structfield>rxsubchans</structfield></entry>
146 <entry spanname="hspan"><para>Some tuners or audio
147 decoders can determine the received audio subprograms by analyzing
148 audio carriers, pilot tones or other indicators. To pass this
149 information drivers set flags defined in <xref
150 linkend="tuner-rxsubchans" /> in this field. For
151 example:</para></entry>
152 </row>
153 <row>
154 <entry></entry>
155 <entry></entry>
156 <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
157 <entry>receiving mono audio</entry>
158 </row>
159 <row>
160 <entry></entry>
161 <entry></entry>
162 <entry><constant>STEREO | SAP</constant></entry>
163 <entry>receiving stereo audio and a secondary audio
164 program</entry>
165 </row>
166 <row>
167 <entry></entry>
168 <entry></entry>
169 <entry><constant>MONO | STEREO</constant></entry>
170 <entry>receiving mono or stereo audio, the hardware cannot
171 distinguish</entry>
172 </row>
173 <row>
174 <entry></entry>
175 <entry></entry>
176 <entry><constant>LANG1 | LANG2</constant></entry>
177 <entry>receiving bilingual audio</entry>
178 </row>
179 <row>
180 <entry></entry>
181 <entry></entry>
182 <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry>
183 <entry>receiving mono, stereo or bilingual
184 audio</entry>
185 </row>
186 <row>
187 <entry></entry>
188 <entry></entry>
189 <entry spanname="hspan"><para>When the
190 <constant>V4L2_TUNER_CAP_STEREO</constant>,
191 <constant>_LANG1</constant>, <constant>_LANG2</constant> or
192 <constant>_SAP</constant> flag is cleared in the
193 <structfield>capability</structfield> field, the corresponding
194 <constant>V4L2_TUNER_SUB_</constant> flag must not be set
195 here.</para><para>This field is valid only if this is the tuner of the
196 current video input, or when the structure refers to a radio
197 tuner.</para></entry>
198 </row>
199 <row>
200 <entry>__u32</entry>
201 <entry><structfield>audmode</structfield></entry>
202 <entry spanname="hspan"><para>The selected audio mode, see
203 <xref linkend="tuner-audmode" /> for valid values. The audio mode does
204 not affect audio subprogram detection, and like a <link
205 linkend="control">control</link> it does not automatically change
206 unless the requested mode is invalid or unsupported. See <xref
207 linkend="tuner-matrix" /> for possible results when
208 the selected and received audio programs do not
209 match.</para><para>Currently this is the only field of struct
210 <structname>v4l2_tuner</structname> applications can
211 change.</para></entry>
212 </row>
213 <row>
214 <entry>__u32</entry>
215 <entry><structfield>signal</structfield></entry>
216 <entry spanname="hspan">The signal strength if known, ranging
217 from 0 to 65535. Higher values indicate a better signal.</entry>
218 </row>
219 <row>
220 <entry>__s32</entry>
221 <entry><structfield>afc</structfield></entry>
222 <entry spanname="hspan">Automatic frequency control: When the
223 <structfield>afc</structfield> value is negative, the frequency is too
224 low, when positive too high.<!-- FIXME need example what to do when it never
225 settles at zero, &ie; range is what? --></entry>
226 </row>
227 <row>
228 <entry>__u32</entry>
229 <entry><structfield>reserved</structfield>[4]</entry>
230 <entry spanname="hspan">Reserved for future extensions. Drivers and
231 applications must set the array to zero.</entry>
232 </row>
233 </tbody>
234 </tgroup>
235 </table>
237 <table pgwide="1" frame="none" id="v4l2-tuner-type">
238 <title>enum v4l2_tuner_type</title>
239 <tgroup cols="3">
240 &cs-def;
241 <tbody valign="top">
242 <row>
243 <entry><constant>V4L2_TUNER_RADIO</constant></entry>
244 <entry>1</entry>
245 <entry></entry>
246 </row>
247 <row>
248 <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry>
249 <entry>2</entry>
250 <entry></entry>
251 </row>
252 </tbody>
253 </tgroup>
254 </table>
256 <table pgwide="1" frame="none" id="tuner-capability">
257 <title>Tuner and Modulator Capability Flags</title>
258 <tgroup cols="3">
259 &cs-def;
260 <tbody valign="top">
261 <row>
262 <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry>
263 <entry>0x0001</entry>
264 <entry>When set, tuning frequencies are expressed in units of
265 62.5 Hz, otherwise in units of 62.5 kHz.</entry>
266 </row>
267 <row>
268 <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry>
269 <entry>0x0002</entry>
270 <entry>This is a multi-standard tuner; the video standard
271 can or must be switched. (B/G PAL tuners for example are typically not
272 considered multi-standard because the video standard is automatically
273 determined from the frequency band.) The set of supported video
274 standards is available from the &v4l2-input; pointing to this tuner,
275 see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only
276 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
277 </row>
278 <row>
279 <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry>
280 <entry>0x0010</entry>
281 <entry>Stereo audio reception is supported.</entry>
282 </row>
283 <row>
284 <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry>
285 <entry>0x0040</entry>
286 <entry>Reception of the primary language of a bilingual
287 audio program is supported. Bilingual audio is a feature of
288 two-channel systems, transmitting the primary language monaural on the
289 main audio carrier and a secondary language monaural on a second
290 carrier. Only
291 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
292 </row>
293 <row>
294 <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry>
295 <entry>0x0020</entry>
296 <entry>Reception of the secondary language of a bilingual
297 audio program is supported. Only
298 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
299 </row>
300 <row>
301 <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry>
302 <entry>0x0020</entry>
303 <entry><para>Reception of a secondary audio program is
304 supported. This is a feature of the BTSC system which accompanies the
305 NTSC video standard. Two audio carriers are available for mono or
306 stereo transmissions of a primary language, and an independent third
307 carrier for a monaural secondary language. Only
308 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the
309 <constant>V4L2_TUNER_CAP_LANG2</constant> and
310 <constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms.
311 <constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner
312 supports the <constant>V4L2_STD_NTSC_M</constant> video
313 standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry>
314 </row>
315 <row>
316 <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry>
317 <entry>0x0080</entry>
318 <entry>RDS capture is supported. This capability is only valid for
319 radio tuners.</entry>
320 </row>
321 </tbody>
322 </tgroup>
323 </table>
325 <table pgwide="1" frame="none" id="tuner-rxsubchans">
326 <title>Tuner Audio Reception Flags</title>
327 <tgroup cols="3">
328 &cs-def;
329 <tbody valign="top">
330 <row>
331 <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
332 <entry>0x0001</entry>
333 <entry>The tuner receives a mono audio signal.</entry>
334 </row>
335 <row>
336 <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
337 <entry>0x0002</entry>
338 <entry>The tuner receives a stereo audio signal.</entry>
339 </row>
340 <row>
341 <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
342 <entry>0x0008</entry>
343 <entry>The tuner receives the primary language of a
344 bilingual audio signal. Drivers must clear this flag when the current
345 video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
346 </row>
347 <row>
348 <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
349 <entry>0x0004</entry>
350 <entry>The tuner receives the secondary language of a
351 bilingual audio signal (or a second audio program).</entry>
352 </row>
353 <row>
354 <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
355 <entry>0x0004</entry>
356 <entry>The tuner receives a Second Audio Program. Note the
357 <constant>V4L2_TUNER_SUB_LANG2</constant> and
358 <constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The
359 <constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the
360 current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
361 </row>
362 <row>
363 <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
364 <entry>0x0010</entry>
365 <entry>The tuner receives an RDS channel.</entry>
366 </row>
367 </tbody>
368 </tgroup>
369 </table>
371 <table pgwide="1" frame="none" id="tuner-audmode">
372 <title>Tuner Audio Modes</title>
373 <tgroup cols="3">
374 &cs-def;
375 <tbody valign="top">
376 <row>
377 <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry>
378 <entry>0</entry>
379 <entry>Play mono audio. When the tuner receives a stereo
380 signal this a down-mix of the left and right channel. When the tuner
381 receives a bilingual or SAP signal this mode selects the primary
382 language.</entry>
383 </row>
384 <row>
385 <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry>
386 <entry>1</entry>
387 <entry><para>Play stereo audio. When the tuner receives
388 bilingual audio it may play different languages on the left and right
389 channel or the primary language is played on both channels.</para><para>Playing
390 different languages in this mode is
391 deprecated. New drivers should do this only in
392 <constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner
393 receives no stereo signal or does not support stereo reception the
394 driver shall fall back to <constant>MODE_MONO</constant>.</para></entry>
395 </row>
396 <row>
397 <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry>
398 <entry>3</entry>
399 <entry>Play the primary language, mono or stereo. Only
400 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
401 mode.</entry>
402 </row>
403 <row>
404 <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry>
405 <entry>2</entry>
406 <entry>Play the secondary language, mono. When the tuner
407 receives no bilingual audio or SAP, or their reception is not
408 supported the driver shall fall back to mono or stereo mode. Only
409 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
410 mode.</entry>
411 </row>
412 <row>
413 <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry>
414 <entry>2</entry>
415 <entry>Play the Second Audio Program. When the tuner
416 receives no bilingual audio or SAP, or their reception is not
417 supported the driver shall fall back to mono or stereo mode. Only
418 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode.
419 Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and
420 <constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry>
421 </row>
422 <row>
423 <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry>
424 <entry>4</entry>
425 <entry>Play the primary language on the left channel, the
426 secondary language on the right channel. When the tuner receives no
427 bilingual audio or SAP, it shall fall back to
428 <constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>.
429 Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
430 mode.</entry>
431 </row>
432 </tbody>
433 </tgroup>
434 </table>
436 <table pgwide="1" frame="all" id="tuner-matrix">
437 <title>Tuner Audio Matrix</title>
438 <tgroup cols="6" align="center">
439 <colspec align="left" />
440 <colspec colname="c2" colwidth="1*" />
441 <colspec colwidth="1*" />
442 <colspec colwidth="1*" />
443 <colspec colnum="6" colname="c6" colwidth="1*" />
444 <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" />
445 <thead>
446 <row>
447 <entry></entry>
448 <entry spanname="hspan">Selected
449 <constant>V4L2_TUNER_MODE_</constant></entry>
450 </row>
451 <row>
452 <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry>
453 <entry><constant>MONO</constant></entry>
454 <entry><constant>STEREO</constant></entry>
455 <entry><constant>LANG1</constant></entry>
456 <entry><constant>LANG2 = SAP</constant></entry>
457 <entry><constant>LANG1_LANG2</constant><footnote><para>This
458 mode has been added in Linux 2.6.17 and may not be supported by older
459 drivers.</para></footnote></entry>
460 </row>
461 </thead>
462 <tbody valign="top">
463 <row>
464 <entry><constant>MONO</constant></entry>
465 <entry>Mono</entry>
466 <entry>Mono/Mono</entry>
467 <entry>Mono</entry>
468 <entry>Mono</entry>
469 <entry>Mono/Mono</entry>
470 </row>
471 <row>
472 <entry><constant>MONO | SAP</constant></entry>
473 <entry>Mono</entry>
474 <entry>Mono/Mono</entry>
475 <entry>Mono</entry>
476 <entry>SAP</entry>
477 <entry>Mono/SAP (preferred) or Mono/Mono</entry>
478 </row>
479 <row>
480 <entry><constant>STEREO</constant></entry>
481 <entry>L+R</entry>
482 <entry>L/R</entry>
483 <entry>Stereo L/R (preferred) or Mono L+R</entry>
484 <entry>Stereo L/R (preferred) or Mono L+R</entry>
485 <entry>L/R (preferred) or L+R/L+R</entry>
486 </row>
487 <row>
488 <entry><constant>STEREO | SAP</constant></entry>
489 <entry>L+R</entry>
490 <entry>L/R</entry>
491 <entry>Stereo L/R (preferred) or Mono L+R</entry>
492 <entry>SAP</entry>
493 <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry>
494 </row>
495 <row>
496 <entry><constant>LANG1 | LANG2</constant></entry>
497 <entry>Language 1</entry>
498 <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of
499 both languages in <constant>MODE_STEREO</constant> is deprecated. In
500 the future drivers should produce only the primary language in this
501 mode. Applications should request
502 <constant>MODE_LANG1_LANG2</constant> to record both languages or a
503 stereo signal.</para></footnote>) or
504 Lang1/Lang1</entry>
505 <entry>Language 1</entry>
506 <entry>Language 2</entry>
507 <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry>
508 </row>
509 </tbody>
510 </tgroup>
511 </table>
512 </refsect1>
514 <refsect1>
515 &return-value;
517 <variablelist>
518 <varlistentry>
519 <term><errorcode>EINVAL</errorcode></term>
520 <listitem>
521 <para>The &v4l2-tuner; <structfield>index</structfield> is
522 out of bounds.</para>
523 </listitem>
524 </varlistentry>
525 </variablelist>
526 </refsect1>
527 </refentry>
529 <!--
530 Local Variables:
531 mode: sgml
532 sgml-parent-document: "v4l2.sgml"
533 indent-tabs-mode: nil
534 End:
535 -->