Merge branch 'v4l_for_linus' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab...
[linux-2.6.git] / Documentation / DocBook / media / v4l / vidioc-g-tuner.xml
1 <refentry id="vidioc-g-tuner">
2   <refmeta>
3     <refentrytitle>ioctl VIDIOC_G_TUNER, VIDIOC_S_TUNER</refentrytitle>
4     &manvol;
5   </refmeta>
6
7   <refnamediv>
8     <refname>VIDIOC_G_TUNER</refname>
9     <refname>VIDIOC_S_TUNER</refname>
10     <refpurpose>Get or set tuner attributes</refpurpose>
11   </refnamediv>
12
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>
33
34   <refsect1>
35     <title>Arguments</title>
36
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>
58
59   <refsect1>
60     <title>Description</title>
61
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>
70
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>
82
83     <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
84 is available.</para>
85
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>
236
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>
255
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&nbsp;Hz, otherwise in units of 62.5&nbsp;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           <row>
322         <entry><constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant></entry>
323         <entry>0x0100</entry>
324         <entry>The RDS data is passed as unparsed RDS blocks.</entry>
325           </row>
326           <row>
327         <entry><constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant></entry>
328         <entry>0x0200</entry>
329         <entry>The RDS data is parsed by the hardware and set via controls.</entry>
330           </row>
331         </tbody>
332       </tgroup>
333     </table>
334
335     <table pgwide="1" frame="none" id="tuner-rxsubchans">
336       <title>Tuner Audio Reception Flags</title>
337       <tgroup cols="3">
338         &cs-def;
339         <tbody valign="top">
340           <row>
341             <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
342             <entry>0x0001</entry>
343             <entry>The tuner receives a mono audio signal.</entry>
344           </row>
345           <row>
346             <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
347             <entry>0x0002</entry>
348             <entry>The tuner receives a stereo audio signal.</entry>
349           </row>
350           <row>
351             <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
352             <entry>0x0008</entry>
353             <entry>The tuner receives the primary language of a
354 bilingual audio signal. Drivers must clear this flag when the current
355 video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
356           </row>
357           <row>
358             <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
359             <entry>0x0004</entry>
360             <entry>The tuner receives the secondary language of a
361 bilingual audio signal (or a second audio program).</entry>
362           </row>
363           <row>
364             <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
365             <entry>0x0004</entry>
366             <entry>The tuner receives a Second Audio Program. Note the
367 <constant>V4L2_TUNER_SUB_LANG2</constant> and
368 <constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The
369 <constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the
370 current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
371           </row>
372           <row>
373             <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
374             <entry>0x0010</entry>
375             <entry>The tuner receives an RDS channel.</entry>
376           </row>
377         </tbody>
378       </tgroup>
379     </table>
380
381     <table pgwide="1" frame="none" id="tuner-audmode">
382       <title>Tuner Audio Modes</title>
383       <tgroup cols="3">
384         &cs-def;
385         <tbody valign="top">
386           <row>
387             <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry>
388             <entry>0</entry>
389             <entry>Play mono audio. When the tuner receives a stereo
390 signal this a down-mix of the left and right channel. When the tuner
391 receives a bilingual or SAP signal this mode selects the primary
392 language.</entry>
393           </row>
394           <row>
395             <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry>
396             <entry>1</entry>
397             <entry><para>Play stereo audio. When the tuner receives
398 bilingual audio it may play different languages on the left and right
399 channel or the primary language is played on both channels.</para><para>Playing
400 different languages in this mode is
401 deprecated. New drivers should do this only in
402 <constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner
403 receives no stereo signal or does not support stereo reception the
404 driver shall fall back to <constant>MODE_MONO</constant>.</para></entry>
405           </row>
406           <row>
407             <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry>
408             <entry>3</entry>
409             <entry>Play the primary language, mono or stereo. Only
410 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
411 mode.</entry>
412           </row>
413           <row>
414             <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry>
415             <entry>2</entry>
416             <entry>Play the secondary language, mono. When the tuner
417 receives no bilingual audio or SAP, or their reception is not
418 supported the driver shall fall back to mono or stereo mode. Only
419 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
420 mode.</entry>
421           </row>
422           <row>
423             <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry>
424             <entry>2</entry>
425             <entry>Play the Second Audio Program. When the tuner
426 receives no bilingual audio or SAP, or their reception is not
427 supported the driver shall fall back to mono or stereo mode. Only
428 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode.
429 Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and
430 <constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry>
431           </row>
432           <row>
433             <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry>
434             <entry>4</entry>
435             <entry>Play the primary language on the left channel, the
436 secondary language on the right channel. When the tuner receives no
437 bilingual audio or SAP, it shall fall back to
438 <constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>.
439 Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
440 mode.</entry>
441           </row>
442         </tbody>
443       </tgroup>
444     </table>
445
446     <table pgwide="1" frame="all" id="tuner-matrix">
447       <title>Tuner Audio Matrix</title>
448       <tgroup cols="6" align="center">
449         <colspec align="left" />
450         <colspec colname="c2" colwidth="1*" />
451         <colspec colwidth="1*" />
452         <colspec colwidth="1*" />
453         <colspec colnum="6" colname="c6" colwidth="1*" />
454         <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" />
455         <thead>
456           <row>
457             <entry></entry>
458             <entry spanname="hspan">Selected
459 <constant>V4L2_TUNER_MODE_</constant></entry>
460           </row>
461           <row>
462             <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry>
463             <entry><constant>MONO</constant></entry>
464             <entry><constant>STEREO</constant></entry>
465             <entry><constant>LANG1</constant></entry>
466             <entry><constant>LANG2 = SAP</constant></entry>
467             <entry><constant>LANG1_LANG2</constant><footnote><para>This
468 mode has been added in Linux 2.6.17 and may not be supported by older
469 drivers.</para></footnote></entry>
470           </row>
471         </thead>
472         <tbody valign="top">
473           <row>
474             <entry><constant>MONO</constant></entry>
475             <entry>Mono</entry>
476             <entry>Mono/Mono</entry>
477             <entry>Mono</entry>
478             <entry>Mono</entry>
479             <entry>Mono/Mono</entry>
480           </row>
481           <row>
482             <entry><constant>MONO | SAP</constant></entry>
483             <entry>Mono</entry>
484             <entry>Mono/Mono</entry>
485             <entry>Mono</entry>
486             <entry>SAP</entry>
487             <entry>Mono/SAP (preferred) or Mono/Mono</entry>
488           </row>
489           <row>
490             <entry><constant>STEREO</constant></entry>
491             <entry>L+R</entry>
492             <entry>L/R</entry>
493             <entry>Stereo L/R (preferred) or Mono L+R</entry>
494             <entry>Stereo L/R (preferred) or Mono L+R</entry>
495             <entry>L/R (preferred) or L+R/L+R</entry>
496           </row>
497           <row>
498             <entry><constant>STEREO | SAP</constant></entry>
499             <entry>L+R</entry>
500             <entry>L/R</entry>
501             <entry>Stereo L/R (preferred) or Mono L+R</entry>
502             <entry>SAP</entry>
503             <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry>
504           </row>
505           <row>
506             <entry><constant>LANG1 | LANG2</constant></entry>
507             <entry>Language&nbsp;1</entry>
508             <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of
509 both languages in <constant>MODE_STEREO</constant> is deprecated. In
510 the future drivers should produce only the primary language in this
511 mode. Applications should request
512 <constant>MODE_LANG1_LANG2</constant> to record both languages or a
513 stereo signal.</para></footnote>) or
514 Lang1/Lang1</entry>
515             <entry>Language&nbsp;1</entry>
516             <entry>Language&nbsp;2</entry>
517             <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry>
518           </row>
519         </tbody>
520       </tgroup>
521     </table>
522   </refsect1>
523
524   <refsect1>
525     &return-value;
526
527     <variablelist>
528       <varlistentry>
529         <term><errorcode>EINVAL</errorcode></term>
530         <listitem>
531           <para>The &v4l2-tuner; <structfield>index</structfield> is
532 out of bounds.</para>
533         </listitem>
534       </varlistentry>
535     </variablelist>
536   </refsect1>
537 </refentry>