projects / deliverable / linux.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Merge branch 'pm-sleep'
[deliverable/linux.git] / Documentation / DocBook / media / v4l / vidioc-g-tuner.xml
CommitLineData
8e080c2e
MCC		 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
66structure. Drivers fill the rest of the structure or return an
67&EINVAL; when the index is out of bounds. To enumerate all tuners
68applications shall begin at index zero, incrementing by one until the
69driver returns <errorcode>EINVAL</errorcode>.</para>
70
71 <para>Tuners have two writable properties, the audio mode and
72the radio frequency. To change the audio mode, applications initialize
73the <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
78by the current video input. Drivers may choose a different audio mode
79if the requested mode is invalid or unsupported. Since this is a
80<!-- FIXME -->write-only ioctl, it does not return the actually
81selected audio mode.</para>
82
83 <para>To change the radio frequency the &VIDIOC-S-FREQUENCY; ioctl
84is 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
99application.</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
105NUL-terminated ASCII string. This information is intended for the
106user.<!-- FIXME Video inputs already have a name, the purpose of this
107field is not quite clear.--></para></entry>
108 </row>
109 <row>
6016af82 110 <entry>__u32</entry>
8e080c2e
MCC		 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
120to decode audio subprograms. They will <emphasis>not</emphasis>
121change, for example with the current video standard.</para><para>When
50121317
HV		 122the structure refers to a radio tuner the
123<constant>V4L2_TUNER_CAP_LANG1</constant>,
124<constant>V4L2_TUNER_CAP_LANG2</constant> and
125<constant>V4L2_TUNER_CAP_NORM</constant> flags can't be used.</para>
126<para>If multiple frequency bands are supported, then
127<structfield>capability</structfield> is the union of all
467548aa 128<structfield>capability</structfield> fields of each &v4l2-frequency-band;.
50121317 129</para></entry>
8e080c2e
MCC		 130 </row>
131 <row>
132 <entry>__u32</entry>
133 <entry><structfield>rangelow</structfield></entry>
134 <entry spanname="hspan">The lowest tunable frequency in
135units of 62.5 kHz, or if the <structfield>capability</structfield>
136flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
50121317
HV		 137Hz. If multiple frequency bands are supported, then
138<structfield>rangelow</structfield> is the lowest frequency
139of all the frequency bands.</entry>
8e080c2e
MCC		 140 </row>
141 <row>
142 <entry>__u32</entry>
143 <entry><structfield>rangehigh</structfield></entry>
144 <entry spanname="hspan">The highest tunable frequency in
145units of 62.5 kHz, or if the <structfield>capability</structfield>
146flag <constant>V4L2_TUNER_CAP_LOW</constant> is set, in units of 62.5
50121317
HV		 147Hz. If multiple frequency bands are supported, then
148<structfield>rangehigh</structfield> is the highest frequency
149of all the frequency bands.</entry>
8e080c2e
MCC		 150 </row>
151 <row>
152 <entry>__u32</entry>
153 <entry><structfield>rxsubchans</structfield></entry>
154 <entry spanname="hspan"><para>Some tuners or audio
155decoders can determine the received audio subprograms by analyzing
156audio carriers, pilot tones or other indicators. To pass this
157information drivers set flags defined in <xref
158 linkend="tuner-rxsubchans" /> in this field. For
159example:</para></entry>
160 </row>
161 <row>
162 <entry></entry>
163 <entry></entry>
164 <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
165 <entry>receiving mono audio</entry>
166 </row>
167 <row>
168 <entry></entry>
169 <entry></entry>
170 <entry><constant>STEREO | SAP</constant></entry>
171 <entry>receiving stereo audio and a secondary audio
172program</entry>
173 </row>
174 <row>
175 <entry></entry>
176 <entry></entry>
177 <entry><constant>MONO | STEREO</constant></entry>
178 <entry>receiving mono or stereo audio, the hardware cannot
179distinguish</entry>
180 </row>
181 <row>
182 <entry></entry>
183 <entry></entry>
184 <entry><constant>LANG1 | LANG2</constant></entry>
185 <entry>receiving bilingual audio</entry>
186 </row>
187 <row>
188 <entry></entry>
189 <entry></entry>
190 <entry><constant>MONO | STEREO | LANG1 | LANG2</constant></entry>
191 <entry>receiving mono, stereo or bilingual
192audio</entry>
193 </row>
194 <row>
195 <entry></entry>
196 <entry></entry>
197 <entry spanname="hspan"><para>When the
198<constant>V4L2_TUNER_CAP_STEREO</constant>,
199<constant>_LANG1</constant>, <constant>_LANG2</constant> or
200<constant>_SAP</constant> flag is cleared in the
201<structfield>capability</structfield> field, the corresponding
202<constant>V4L2_TUNER_SUB_</constant> flag must not be set
203here.</para><para>This field is valid only if this is the tuner of the
204current video input, or when the structure refers to a radio
205tuner.</para></entry>
206 </row>
207 <row>
208 <entry>__u32</entry>
209 <entry><structfield>audmode</structfield></entry>
210 <entry spanname="hspan"><para>The selected audio mode, see
211<xref linkend="tuner-audmode" /> for valid values. The audio mode does
212not affect audio subprogram detection, and like a <link
213linkend="control">control</link> it does not automatically change
214unless the requested mode is invalid or unsupported. See <xref
215 linkend="tuner-matrix" /> for possible results when
216the selected and received audio programs do not
217match.</para><para>Currently this is the only field of struct
218<structname>v4l2_tuner</structname> applications can
219change.</para></entry>
220 </row>
221 <row>
222 <entry>__u32</entry>
223 <entry><structfield>signal</structfield></entry>
224 <entry spanname="hspan">The signal strength if known, ranging
225from 0 to 65535. Higher values indicate a better signal.</entry>
226 </row>
227 <row>
228 <entry>__s32</entry>
229 <entry><structfield>afc</structfield></entry>
230 <entry spanname="hspan">Automatic frequency control: When the
231<structfield>afc</structfield> value is negative, the frequency is too
232low, when positive too high.<!-- FIXME need example what to do when it never
233settles at zero, &ie; range is what? --></entry>
234 </row>
235 <row>
236 <entry>__u32</entry>
237 <entry><structfield>reserved</structfield>[4]</entry>
238 <entry spanname="hspan">Reserved for future extensions. Drivers and
239applications must set the array to zero.</entry>
240 </row>
241 </tbody>
242 </tgroup>
243 </table>
244
245 <table pgwide="1" frame="none" id="v4l2-tuner-type">
246 <title>enum v4l2_tuner_type</title>
247 <tgroup cols="3">
248 &cs-def;
249 <tbody valign="top">
250 <row>
251 <entry><constant>V4L2_TUNER_RADIO</constant></entry>
252 <entry>1</entry>
253 <entry></entry>
254 </row>
255 <row>
256 <entry><constant>V4L2_TUNER_ANALOG_TV</constant></entry>
257 <entry>2</entry>
258 <entry></entry>
259 </row>
260 </tbody>
261 </tgroup>
262 </table>
263
264 <table pgwide="1" frame="none" id="tuner-capability">
265 <title>Tuner and Modulator Capability Flags</title>
266 <tgroup cols="3">
267 &cs-def;
268 <tbody valign="top">
269 <row>
270 <entry><constant>V4L2_TUNER_CAP_LOW</constant></entry>
271 <entry>0x0001</entry>
272 <entry>When set, tuning frequencies are expressed in units of
27362.5&nbsp;Hz, otherwise in units of 62.5&nbsp;kHz.</entry>
274 </row>
275 <row>
276 <entry><constant>V4L2_TUNER_CAP_NORM</constant></entry>
277 <entry>0x0002</entry>
278 <entry>This is a multi-standard tuner; the video standard
279can or must be switched. (B/G PAL tuners for example are typically not
280 considered multi-standard because the video standard is automatically
281 determined from the frequency band.) The set of supported video
282 standards is available from the &v4l2-input; pointing to this tuner,
283 see the description of ioctl &VIDIOC-ENUMINPUT; for details. Only
284 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
285 </row>
e4cca4ed
HV		 286 <row>
287 <entry><constant>V4L2_TUNER_CAP_HWSEEK_BOUNDED</constant></entry>
288 <entry>0x0004</entry>
289 <entry>If set, then this tuner supports the hardware seek functionality
290 where the seek stops when it reaches the end of the frequency range.</entry>
291 </row>
292 <row>
293 <entry><constant>V4L2_TUNER_CAP_HWSEEK_WRAP</constant></entry>
294 <entry>0x0008</entry>
295 <entry>If set, then this tuner supports the hardware seek functionality
296 where the seek wraps around when it reaches the end of the frequency range.</entry>
297 </row>
8e080c2e
MCC		 298 <row>
299 <entry><constant>V4L2_TUNER_CAP_STEREO</constant></entry>
300 <entry>0x0010</entry>
301 <entry>Stereo audio reception is supported.</entry>
302 </row>
303 <row>
304 <entry><constant>V4L2_TUNER_CAP_LANG1</constant></entry>
305 <entry>0x0040</entry>
306 <entry>Reception of the primary language of a bilingual
307audio program is supported. Bilingual audio is a feature of
308two-channel systems, transmitting the primary language monaural on the
309main audio carrier and a secondary language monaural on a second
310carrier. Only
311 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
312 </row>
313 <row>
314 <entry><constant>V4L2_TUNER_CAP_LANG2</constant></entry>
315 <entry>0x0020</entry>
316 <entry>Reception of the secondary language of a bilingual
317audio program is supported. Only
318 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</entry>
319 </row>
320 <row>
321 <entry><constant>V4L2_TUNER_CAP_SAP</constant></entry>
322 <entry>0x0020</entry>
323 <entry><para>Reception of a secondary audio program is
324supported. This is a feature of the BTSC system which accompanies the
325NTSC video standard. Two audio carriers are available for mono or
326stereo transmissions of a primary language, and an independent third
327carrier for a monaural secondary language. Only
328 <constant>V4L2_TUNER_ANALOG_TV</constant> tuners can have this capability.</para><para>Note the
329<constant>V4L2_TUNER_CAP_LANG2</constant> and
330<constant>V4L2_TUNER_CAP_SAP</constant> flags are synonyms.
331<constant>V4L2_TUNER_CAP_SAP</constant> applies when the tuner
332supports the <constant>V4L2_STD_NTSC_M</constant> video
333standard.</para><!-- FIXME what if PAL+NTSC and Bi but not SAP? --></entry>
334 </row>
335 <row>
336 <entry><constant>V4L2_TUNER_CAP_RDS</constant></entry>
337 <entry>0x0080</entry>
338 <entry>RDS capture is supported. This capability is only valid for
339radio tuners.</entry>
340 </row>
146d35b0
HV		 341 <row>
342 <entry><constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant></entry>
343 <entry>0x0100</entry>
344 <entry>The RDS data is passed as unparsed RDS blocks.</entry>
345 </row>
346 <row>
347 <entry><constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant></entry>
348 <entry>0x0200</entry>
349 <entry>The RDS data is parsed by the hardware and set via controls.</entry>
350 </row>
50121317
HV		 351 <row>
352 <entry><constant>V4L2_TUNER_CAP_FREQ_BANDS</constant></entry>
353 <entry>0x0400</entry>
354 <entry>The &VIDIOC-ENUM-FREQ-BANDS; ioctl can be used to enumerate
355 the available frequency bands.</entry>
356 </row>
8e080c2e
MCC		 357 </tbody>
358 </tgroup>
359 </table>
360
361 <table pgwide="1" frame="none" id="tuner-rxsubchans">
362 <title>Tuner Audio Reception Flags</title>
363 <tgroup cols="3">
364 &cs-def;
365 <tbody valign="top">
366 <row>
367 <entry><constant>V4L2_TUNER_SUB_MONO</constant></entry>
368 <entry>0x0001</entry>
369 <entry>The tuner receives a mono audio signal.</entry>
370 </row>
371 <row>
372 <entry><constant>V4L2_TUNER_SUB_STEREO</constant></entry>
373 <entry>0x0002</entry>
374 <entry>The tuner receives a stereo audio signal.</entry>
375 </row>
376 <row>
377 <entry><constant>V4L2_TUNER_SUB_LANG1</constant></entry>
378 <entry>0x0008</entry>
379 <entry>The tuner receives the primary language of a
380bilingual audio signal. Drivers must clear this flag when the current
381video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
382 </row>
383 <row>
384 <entry><constant>V4L2_TUNER_SUB_LANG2</constant></entry>
385 <entry>0x0004</entry>
386 <entry>The tuner receives the secondary language of a
387bilingual audio signal (or a second audio program).</entry>
388 </row>
389 <row>
390 <entry><constant>V4L2_TUNER_SUB_SAP</constant></entry>
391 <entry>0x0004</entry>
392 <entry>The tuner receives a Second Audio Program. Note the
393<constant>V4L2_TUNER_SUB_LANG2</constant> and
394<constant>V4L2_TUNER_SUB_SAP</constant> flags are synonyms. The
395<constant>V4L2_TUNER_SUB_SAP</constant> flag applies when the
396current video standard is <constant>V4L2_STD_NTSC_M</constant>.</entry>
397 </row>
398 <row>
399 <entry><constant>V4L2_TUNER_SUB_RDS</constant></entry>
400 <entry>0x0010</entry>
401 <entry>The tuner receives an RDS channel.</entry>
402 </row>
403 </tbody>
404 </tgroup>
405 </table>
406
407 <table pgwide="1" frame="none" id="tuner-audmode">
408 <title>Tuner Audio Modes</title>
409 <tgroup cols="3">
410 &cs-def;
411 <tbody valign="top">
412 <row>
413 <entry><constant>V4L2_TUNER_MODE_MONO</constant></entry>
414 <entry>0</entry>
415 <entry>Play mono audio. When the tuner receives a stereo
416signal this a down-mix of the left and right channel. When the tuner
417receives a bilingual or SAP signal this mode selects the primary
418language.</entry>
419 </row>
420 <row>
421 <entry><constant>V4L2_TUNER_MODE_STEREO</constant></entry>
422 <entry>1</entry>
423 <entry><para>Play stereo audio. When the tuner receives
424bilingual audio it may play different languages on the left and right
425channel or the primary language is played on both channels.</para><para>Playing
426different languages in this mode is
427deprecated. New drivers should do this only in
428<constant>MODE_LANG1_LANG2</constant>.</para><para>When the tuner
429receives no stereo signal or does not support stereo reception the
430driver shall fall back to <constant>MODE_MONO</constant>.</para></entry>
431 </row>
432 <row>
433 <entry><constant>V4L2_TUNER_MODE_LANG1</constant></entry>
434 <entry>3</entry>
435 <entry>Play the primary language, mono or stereo. Only
436<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
437mode.</entry>
438 </row>
439 <row>
440 <entry><constant>V4L2_TUNER_MODE_LANG2</constant></entry>
441 <entry>2</entry>
442 <entry>Play the secondary language, mono. When the tuner
443receives no bilingual audio or SAP, or their reception is not
444supported the driver shall fall back to mono or stereo mode. Only
445<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
446mode.</entry>
447 </row>
448 <row>
449 <entry><constant>V4L2_TUNER_MODE_SAP</constant></entry>
450 <entry>2</entry>
451 <entry>Play the Second Audio Program. When the tuner
452receives no bilingual audio or SAP, or their reception is not
453supported the driver shall fall back to mono or stereo mode. Only
454<constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this mode.
455Note the <constant>V4L2_TUNER_MODE_LANG2</constant> and
456<constant>V4L2_TUNER_MODE_SAP</constant> are synonyms.</entry>
457 </row>
458 <row>
459 <entry><constant>V4L2_TUNER_MODE_LANG1_LANG2</constant></entry>
460 <entry>4</entry>
461 <entry>Play the primary language on the left channel, the
462secondary language on the right channel. When the tuner receives no
463bilingual audio or SAP, it shall fall back to
464<constant>MODE_LANG1</constant> or <constant>MODE_MONO</constant>.
465Only <constant>V4L2_TUNER_ANALOG_TV</constant> tuners support this
466mode.</entry>
467 </row>
468 </tbody>
469 </tgroup>
470 </table>
471
472 <table pgwide="1" frame="all" id="tuner-matrix">
473 <title>Tuner Audio Matrix</title>
474 <tgroup cols="6" align="center">
475 <colspec align="left" />
476 <colspec colname="c2" colwidth="1*" />
477 <colspec colwidth="1*" />
478 <colspec colwidth="1*" />
479 <colspec colnum="6" colname="c6" colwidth="1*" />
480 <spanspec namest="c2" nameend="c6" spanname="hspan" align="center" />
481 <thead>
482 <row>
483 <entry></entry>
484 <entry spanname="hspan">Selected
485<constant>V4L2_TUNER_MODE_</constant></entry>
486 </row>
487 <row>
488 <entry>Received <constant>V4L2_TUNER_SUB_</constant></entry>
489 <entry><constant>MONO</constant></entry>
490 <entry><constant>STEREO</constant></entry>
491 <entry><constant>LANG1</constant></entry>
492 <entry><constant>LANG2 = SAP</constant></entry>
493 <entry><constant>LANG1_LANG2</constant><footnote><para>This
494mode has been added in Linux 2.6.17 and may not be supported by older
495drivers.</para></footnote></entry>
496 </row>
497 </thead>
498 <tbody valign="top">
499 <row>
500 <entry><constant>MONO</constant></entry>
501 <entry>Mono</entry>
502 <entry>Mono/Mono</entry>
503 <entry>Mono</entry>
504 <entry>Mono</entry>
505 <entry>Mono/Mono</entry>
506 </row>
507 <row>
508 <entry><constant>MONO | SAP</constant></entry>
509 <entry>Mono</entry>
510 <entry>Mono/Mono</entry>
511 <entry>Mono</entry>
512 <entry>SAP</entry>
513 <entry>Mono/SAP (preferred) or Mono/Mono</entry>
514 </row>
515 <row>
516 <entry><constant>STEREO</constant></entry>
517 <entry>L+R</entry>
518 <entry>L/R</entry>
519 <entry>Stereo L/R (preferred) or Mono L+R</entry>
520 <entry>Stereo L/R (preferred) or Mono L+R</entry>
521 <entry>L/R (preferred) or L+R/L+R</entry>
522 </row>
523 <row>
524 <entry><constant>STEREO | SAP</constant></entry>
525 <entry>L+R</entry>
526 <entry>L/R</entry>
527 <entry>Stereo L/R (preferred) or Mono L+R</entry>
528 <entry>SAP</entry>
529 <entry>L+R/SAP (preferred) or L/R or L+R/L+R</entry>
530 </row>
531 <row>
532 <entry><constant>LANG1 | LANG2</constant></entry>
533 <entry>Language&nbsp;1</entry>
534 <entry>Lang1/Lang2 (deprecated<footnote><para>Playback of
535both languages in <constant>MODE_STEREO</constant> is deprecated. In
536the future drivers should produce only the primary language in this
537mode. Applications should request
538<constant>MODE_LANG1_LANG2</constant> to record both languages or a
539stereo signal.</para></footnote>) or
540Lang1/Lang1</entry>
541 <entry>Language&nbsp;1</entry>
542 <entry>Language&nbsp;2</entry>
543 <entry>Lang1/Lang2 (preferred) or Lang1/Lang1</entry>
544 </row>
545 </tbody>
546 </tgroup>
547 </table>
548 </refsect1>
549
550 <refsect1>
551 &return-value;
552
553 <variablelist>
554 <varlistentry>
555 <term><errorcode>EINVAL</errorcode></term>
556 <listitem>
557 <para>The &v4l2-tuner; <structfield>index</structfield> is
558out of bounds.</para>
559 </listitem>
560 </varlistentry>
561 </variablelist>
562 </refsect1>
563</refentry>
Linux kernel - Deliverables
This page took 0.211468 seconds and 5 git commands to generate.