[media] DocBook: Use the generic ioctl error codes for all V4L ioctl's
[linux-2.6/linux-acpi-2.6/ibm-acpi-2.6.git] / Documentation / DocBook / media / v4l / vidioc-g-sliced-vbi-cap.xml
blob71741daaf7252a8d612ce744072b528e5b7a156b
1 <refentry id="vidioc-g-sliced-vbi-cap">
2   <refmeta>
3     <refentrytitle>ioctl VIDIOC_G_SLICED_VBI_CAP</refentrytitle>
4     &manvol;
5   </refmeta>
7   <refnamediv>
8     <refname>VIDIOC_G_SLICED_VBI_CAP</refname>
9     <refpurpose>Query sliced VBI capabilities</refpurpose>
10   </refnamediv>
12   <refsynopsisdiv>
13     <funcsynopsis>
14       <funcprototype>
15         <funcdef>int <function>ioctl</function></funcdef>
16         <paramdef>int <parameter>fd</parameter></paramdef>
17         <paramdef>int <parameter>request</parameter></paramdef>
18         <paramdef>struct v4l2_sliced_vbi_cap *<parameter>argp</parameter></paramdef>
19       </funcprototype>
20     </funcsynopsis>
21   </refsynopsisdiv>
23   <refsect1>
24     <title>Arguments</title>
26     <variablelist>
27       <varlistentry>
28         <term><parameter>fd</parameter></term>
29         <listitem>
30           <para>&fd;</para>
31         </listitem>
32       </varlistentry>
33       <varlistentry>
34         <term><parameter>request</parameter></term>
35         <listitem>
36           <para>VIDIOC_G_SLICED_VBI_CAP</para>
37         </listitem>
38       </varlistentry>
39       <varlistentry>
40         <term><parameter>argp</parameter></term>
41         <listitem>
42           <para></para>
43         </listitem>
44       </varlistentry>
45     </variablelist>
46   </refsect1>
48   <refsect1>
49     <title>Description</title>
51     <para>To find out which data services are supported by a sliced
52 VBI capture or output device, applications initialize the
53 <structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;,
54 clear the <structfield>reserved</structfield> array and
55 call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The
56 driver fills in the remaining fields or returns an &EINVAL; if the
57 sliced VBI API is unsupported or <structfield>type</structfield>
58 is invalid.</para>
60     <para>Note the <structfield>type</structfield> field was added,
61 and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para>
63     <table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap">
64       <title>struct <structname>v4l2_sliced_vbi_cap</structname></title>
65       <tgroup cols="5">
66         <colspec colname="c1" colwidth="3*" />
67         <colspec colname="c2" colwidth="3*" />
68         <colspec colname="c3" colwidth="2*" />
69         <colspec colname="c4" colwidth="2*" />
70         <colspec colname="c5" colwidth="2*" />
71         <spanspec spanname="hspan" namest="c3" nameend="c5" />
72         <tbody valign="top">
73           <row>
74             <entry>__u16</entry>
75             <entry><structfield>service_set</structfield></entry>
76             <entry spanname="hspan">A set of all data services
77 supported by the driver. Equal to the union of all elements of the
78 <structfield>service_lines </structfield> array.</entry>
79           </row>
80           <row>
81             <entry>__u16</entry>
82             <entry><structfield>service_lines</structfield>[2][24]</entry>
83             <entry spanname="hspan">Each element of this array
84 contains a set of data services the hardware can look for or insert
85 into a particular scan line. Data services are defined in <xref
86                 linkend="vbi-services" />. Array indices map to ITU-R
87 line numbers (see also <xref
88                 linkend="vbi-525" /> and <xref
89 linkend="vbi-625" />) as follows:</entry>
90           </row>
91           <row>
92             <entry></entry>
93             <entry></entry>
94             <entry>Element</entry>
95             <entry>525 line systems</entry>
96             <entry>625 line systems</entry>
97           </row>
98           <row>
99             <entry></entry>
100             <entry></entry>
101             <entry><structfield>service_lines</structfield>[0][1]</entry>
102             <entry align="center">1</entry>
103             <entry align="center">1</entry>
104           </row>
105           <row>
106             <entry></entry>
107             <entry></entry>
108             <entry><structfield>service_lines</structfield>[0][23]</entry>
109             <entry align="center">23</entry>
110             <entry align="center">23</entry>
111           </row>
112           <row>
113             <entry></entry>
114             <entry></entry>
115             <entry><structfield>service_lines</structfield>[1][1]</entry>
116             <entry align="center">264</entry>
117             <entry align="center">314</entry>
118           </row>
119           <row>
120             <entry></entry>
121             <entry></entry>
122             <entry><structfield>service_lines</structfield>[1][23]</entry>
123             <entry align="center">286</entry>
124             <entry align="center">336</entry>
125           </row>
126           <row>
127             <entry></entry>
128           </row>
129           <row>
130             <entry></entry>
131             <entry></entry>
132             <entry spanname="hspan">The number of VBI lines the
133 hardware can capture or output per frame, or the number of services it
134 can identify on a given line may be limited. For example on PAL line
135 16 the hardware may be able to look for a VPS or Teletext signal, but
136 not both at the same time. Applications can learn about these limits
137 using the &VIDIOC-S-FMT; ioctl as described in <xref
138                 linkend="sliced" />.</entry>
139           </row>
140           <row>
141             <entry></entry>
142           </row>
143           <row>
144             <entry></entry>
145             <entry></entry>
146             <entry spanname="hspan">Drivers must set
147 <structfield>service_lines</structfield>[0][0] and
148 <structfield>service_lines</structfield>[1][0] to zero.</entry>
149           </row>
150           <row>
151             <entry>&v4l2-buf-type;</entry>
152             <entry><structfield>type</structfield></entry>
153             <entry>Type of the data stream, see <xref
154                   linkend="v4l2-buf-type" />. Should be
155 <constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or
156 <constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry>
157           </row>
158           <row>
159             <entry>__u32</entry>
160             <entry><structfield>reserved</structfield>[3]</entry>
161             <entry spanname="hspan">This array is reserved for future
162 extensions. Applications and drivers must set it to zero.</entry>
163           </row>
164         </tbody>
165       </tgroup>
166     </table>
168     <!-- See also dev-sliced-vbi.sgml -->
169     <table pgwide="1" frame="none" id="vbi-services">
170       <title>Sliced VBI services</title>
171       <tgroup cols="5">
172         <colspec colname="c1" colwidth="2*" />
173         <colspec colname="c2" colwidth="1*" />
174         <colspec colname="c3" colwidth="1*" />
175         <colspec colname="c4" colwidth="2*" />
176         <colspec colname="c5" colwidth="2*" />
177         <spanspec spanname='rlp' namest='c3' nameend='c5' />
178         <thead>
179           <row>
180             <entry>Symbol</entry>
181             <entry>Value</entry>
182             <entry>Reference</entry>
183             <entry>Lines, usually</entry>
184             <entry>Payload</entry>
185           </row>
186         </thead>
187         <tbody valign="top">
188           <row>
189             <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext
190 System B)</entry>
191             <entry>0x0001</entry>
192             <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
193             <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
194             <entry>Last 42 of the 45 byte Teletext packet, that is
195 without clock run-in and framing code, lsb first transmitted.</entry>
196           </row>
197           <row>
198             <entry><constant>V4L2_SLICED_VPS</constant></entry>
199             <entry>0x0400</entry>
200             <entry><xref linkend="ets300231" /></entry>
201             <entry>PAL line 16</entry>
202             <entry>Byte number 3 to 15 according to Figure 9 of
203 ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
204           </row>
205           <row>
206             <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
207             <entry>0x1000</entry>
208             <entry><xref linkend="eia608" /></entry>
209             <entry>NTSC line 21, 284 (second field 21)</entry>
210             <entry>Two bytes in transmission order, including parity
211 bit, lsb first transmitted.</entry>
212           </row>
213           <row>
214             <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
215             <entry>0x4000</entry>
216             <entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry>
217             <entry>PAL/SECAM line 23</entry>
218             <entry><screen>
219 Byte        0                 1
220      msb         lsb  msb           lsb
221 Bit  7 6 5 4 3 2 1 0  x x 13 12 11 10 9
222 </screen></entry>
223           </row>
224           <row>
225             <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
226             <entry>0x1000</entry>
227             <entry spanname="rlp">Set of services applicable to 525
228 line systems.</entry>
229           </row>
230           <row>
231             <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
232             <entry>0x4401</entry>
233             <entry spanname="rlp">Set of services applicable to 625
234 line systems.</entry>
235           </row>
236         </tbody>
237       </tgroup>
238     </table>
240   </refsect1>
242   <refsect1>
243     &return-value;
245     <variablelist>
246       <varlistentry>
247         <term><errorcode>EINVAL</errorcode></term>
248         <listitem>
249           <para>The value in the <structfield>type</structfield> field is
250 wrong.</para>
251         </listitem>
252       </varlistentry>
253     </variablelist>
254   </refsect1>
255 </refentry>