Documentation/DocBook/media/v4l/vidioc-g-sliced-vbi-cap.xml - kernel/bruno - Git at Google

 <refentry id="vidioc-g-sliced-vbi-cap">
   <refmeta>
     <refentrytitle>ioctl VIDIOC_G_SLICED_VBI_CAP</refentrytitle>
     &manvol;
   </refmeta>

   <refnamediv>
     <refname>VIDIOC_G_SLICED_VBI_CAP</refname>
     <refpurpose>Query sliced VBI capabilities</refpurpose>
   </refnamediv>

   <refsynopsisdiv>
     <funcsynopsis>
       <funcprototype>
 	<funcdef>int <function>ioctl</function></funcdef>
 	<paramdef>int <parameter>fd</parameter></paramdef>
 	<paramdef>int <parameter>request</parameter></paramdef>
 	<paramdef>struct v4l2_sliced_vbi_cap *<parameter>argp</parameter></paramdef>
       </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>

   <refsect1>
     <title>Arguments</title>

     <variablelist>
       <varlistentry>
 	<term><parameter>fd</parameter></term>
 	<listitem>
 	  <para>&fd;</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>request</parameter></term>
 	<listitem>
 	  <para>VIDIOC_G_SLICED_VBI_CAP</para>
 	</listitem>
       </varlistentry>
       <varlistentry>
 	<term><parameter>argp</parameter></term>
 	<listitem>
 	  <para></para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>

   <refsect1>
     <title>Description</title>

     <para>To find out which data services are supported by a sliced
 VBI capture or output device, applications initialize the
 <structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;,
 clear the <structfield>reserved</structfield> array and
 call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The
 driver fills in the remaining fields or returns an &EINVAL; if the
 sliced VBI API is unsupported or <structfield>type</structfield>
 is invalid.</para>

     <para>Note the <structfield>type</structfield> field was added,
 and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para>

     <table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap">
       <title>struct <structname>v4l2_sliced_vbi_cap</structname></title>
       <tgroup cols="5">
 	<colspec colname="c1" colwidth="3*" />
 	<colspec colname="c2" colwidth="3*" />
 	<colspec colname="c3" colwidth="2*" />
 	<colspec colname="c4" colwidth="2*" />
 	<colspec colname="c5" colwidth="2*" />
 	<spanspec spanname="hspan" namest="c3" nameend="c5" />
 	<tbody valign="top">
 	  <row>
 	    <entry>__u16</entry>
 	    <entry><structfield>service_set</structfield></entry>
 	    <entry spanname="hspan">A set of all data services
 supported by the driver. Equal to the union of all elements of the
 <structfield>service_lines </structfield> array.</entry>
 	  </row>
 	  <row>
 	    <entry>__u16</entry>
 	    <entry><structfield>service_lines</structfield>[2][24]</entry>
 	    <entry spanname="hspan">Each element of this array
 contains a set of data services the hardware can look for or insert
 into a particular scan line. Data services are defined in <xref
 		linkend="vbi-services" />. Array indices map to ITU-R
 line numbers (see also <xref
 		linkend="vbi-525" /> and <xref
 linkend="vbi-625" />) as follows:</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry>Element</entry>
 	    <entry>525 line systems</entry>
 	    <entry>625 line systems</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry><structfield>service_lines</structfield>[0][1]</entry>
 	    <entry align="center">1</entry>
 	    <entry align="center">1</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry><structfield>service_lines</structfield>[0][23]</entry>
 	    <entry align="center">23</entry>
 	    <entry align="center">23</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry><structfield>service_lines</structfield>[1][1]</entry>
 	    <entry align="center">264</entry>
 	    <entry align="center">314</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry><structfield>service_lines</structfield>[1][23]</entry>
 	    <entry align="center">286</entry>
 	    <entry align="center">336</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry spanname="hspan">The number of VBI lines the
 hardware can capture or output per frame, or the number of services it
 can identify on a given line may be limited. For example on PAL line
 16 the hardware may be able to look for a VPS or Teletext signal, but
 not both at the same time. Applications can learn about these limits
 using the &VIDIOC-S-FMT; ioctl as described in <xref
 		linkend="sliced" />.</entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	  </row>
 	  <row>
 	    <entry></entry>
 	    <entry></entry>
 	    <entry spanname="hspan">Drivers must set
 <structfield>service_lines</structfield>[0][0] and
 <structfield>service_lines</structfield>[1][0] to zero.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>type</structfield></entry>
 	    <entry>Type of the data stream, see <xref
 		  linkend="v4l2-buf-type" />. Should be
 <constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or
 <constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry>
 	  </row>
 	  <row>
 	    <entry>__u32</entry>
 	    <entry><structfield>reserved</structfield>[3]</entry>
 	    <entry spanname="hspan">This array is reserved for future
 extensions. Applications and drivers must set it to zero.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>

     <!-- See also dev-sliced-vbi.sgml -->
     <table pgwide="1" frame="none" id="vbi-services">
       <title>Sliced VBI services</title>
       <tgroup cols="5">
 	<colspec colname="c1" colwidth="2*" />
 	<colspec colname="c2" colwidth="1*" />
 	<colspec colname="c3" colwidth="1*" />
 	<colspec colname="c4" colwidth="2*" />
 	<colspec colname="c5" colwidth="2*" />
 	<spanspec spanname='rlp' namest='c3' nameend='c5' />
 	<thead>
 	  <row>
 	    <entry>Symbol</entry>
 	    <entry>Value</entry>
 	    <entry>Reference</entry>
 	    <entry>Lines, usually</entry>
 	    <entry>Payload</entry>
 	  </row>
 	</thead>
 	<tbody valign="top">
 	  <row>
 	    <entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext
 System B)</entry>
 	    <entry>0x0001</entry>
 	    <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
 	    <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
 	    <entry>Last 42 of the 45 byte Teletext packet, that is
 without clock run-in and framing code, lsb first transmitted.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_SLICED_VPS</constant></entry>
 	    <entry>0x0400</entry>
 	    <entry><xref linkend="ets300231" /></entry>
 	    <entry>PAL line 16</entry>
 	    <entry>Byte number 3 to 15 according to Figure 9 of
 ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
 	    <entry>0x1000</entry>
 	    <entry><xref linkend="eia608" /></entry>
 	    <entry>NTSC line 21, 284 (second field 21)</entry>
 	    <entry>Two bytes in transmission order, including parity
 bit, lsb first transmitted.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
 	    <entry>0x4000</entry>
 	    <entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry>
 	    <entry>PAL/SECAM line 23</entry>
 	    <entry><screen>
 Byte        0                 1
      msb         lsb  msb           lsb
 Bit  7 6 5 4 3 2 1 0  x x 13 12 11 10 9
 </screen></entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
 	    <entry>0x1000</entry>
 	    <entry spanname="rlp">Set of services applicable to 525
 line systems.</entry>
 	  </row>
 	  <row>
 	    <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
 	    <entry>0x4401</entry>
 	    <entry spanname="rlp">Set of services applicable to 625
 line systems.</entry>
 	  </row>
 	</tbody>
       </tgroup>
     </table>

   </refsect1>

   <refsect1>
     &return-value;

     <variablelist>
       <varlistentry>
 	<term><errorcode>EINVAL</errorcode></term>
 	<listitem>
 	  <para>The value in the <structfield>type</structfield> field is
 wrong.</para>
 	</listitem>
       </varlistentry>
     </variablelist>
   </refsect1>
 </refentry>
	<refentry id="vidioc-g-sliced-vbi-cap">
	<refmeta>
	<refentrytitle>ioctl VIDIOC_G_SLICED_VBI_CAP</refentrytitle>
	&manvol;
	</refmeta>

	<refnamediv>
	<refname>VIDIOC_G_SLICED_VBI_CAP</refname>
	<refpurpose>Query sliced VBI capabilities</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
	<funcsynopsis>
	<funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>struct v4l2_sliced_vbi_cap *<parameter>argp</parameter></paramdef>
	</funcprototype>
	</funcsynopsis>
	</refsynopsisdiv>

	<refsect1>
	<title>Arguments</title>

	<variablelist>
	<varlistentry>
	<term><parameter>fd</parameter></term>
	<listitem>
	<para>&fd;</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term><parameter>request</parameter></term>
	<listitem>
	<para>VIDIOC_G_SLICED_VBI_CAP</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term><parameter>argp</parameter></term>
	<listitem>
	<para></para>
	</listitem>
	</varlistentry>
	</variablelist>
	</refsect1>

	<refsect1>
	<title>Description</title>

	<para>To find out which data services are supported by a sliced
	VBI capture or output device, applications initialize the
	<structfield>type</structfield> field of a &v4l2-sliced-vbi-cap;,
	clear the <structfield>reserved</structfield> array and
	call the <constant>VIDIOC_G_SLICED_VBI_CAP</constant> ioctl. The
	driver fills in the remaining fields or returns an &EINVAL; if the
	sliced VBI API is unsupported or <structfield>type</structfield>
	is invalid.</para>

	<para>Note the <structfield>type</structfield> field was added,
	and the ioctl changed from read-only to write-read, in Linux 2.6.19.</para>

	<table pgwide="1" frame="none" id="v4l2-sliced-vbi-cap">
	<title>struct <structname>v4l2_sliced_vbi_cap</structname></title>
	<tgroup cols="5">
	<colspec colname="c1" colwidth="3*" />
	<colspec colname="c2" colwidth="3*" />
	<colspec colname="c3" colwidth="2*" />
	<colspec colname="c4" colwidth="2*" />
	<colspec colname="c5" colwidth="2*" />
	<spanspec spanname="hspan" namest="c3" nameend="c5" />
	<tbody valign="top">
	<row>
	<entry>__u16</entry>
	<entry><structfield>service_set</structfield></entry>
	<entry spanname="hspan">A set of all data services
	supported by the driver. Equal to the union of all elements of the
	<structfield>service_lines </structfield> array.</entry>
	</row>
	<row>
	<entry>__u16</entry>
	<entry><structfield>service_lines</structfield>[2][24]</entry>
	<entry spanname="hspan">Each element of this array
	contains a set of data services the hardware can look for or insert
	into a particular scan line. Data services are defined in <xref
	linkend="vbi-services" />. Array indices map to ITU-R
	line numbers (see also <xref
	linkend="vbi-525" /> and <xref
	linkend="vbi-625" />) as follows:</entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry>Element</entry>
	<entry>525 line systems</entry>
	<entry>625 line systems</entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry><structfield>service_lines</structfield>[0][1]</entry>
	<entry align="center">1</entry>
	<entry align="center">1</entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry><structfield>service_lines</structfield>[0][23]</entry>
	<entry align="center">23</entry>
	<entry align="center">23</entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry><structfield>service_lines</structfield>[1][1]</entry>
	<entry align="center">264</entry>
	<entry align="center">314</entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry><structfield>service_lines</structfield>[1][23]</entry>
	<entry align="center">286</entry>
	<entry align="center">336</entry>
	</row>
	<row>
	<entry></entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry spanname="hspan">The number of VBI lines the
	hardware can capture or output per frame, or the number of services it
	can identify on a given line may be limited. For example on PAL line
	16 the hardware may be able to look for a VPS or Teletext signal, but
	not both at the same time. Applications can learn about these limits
	using the &VIDIOC-S-FMT; ioctl as described in <xref
	linkend="sliced" />.</entry>
	</row>
	<row>
	<entry></entry>
	</row>
	<row>
	<entry></entry>
	<entry></entry>
	<entry spanname="hspan">Drivers must set
	<structfield>service_lines</structfield>[0][0] and
	<structfield>service_lines</structfield>[1][0] to zero.</entry>
	</row>
	<row>
	<entry>__u32</entry>
	<entry><structfield>type</structfield></entry>
	<entry>Type of the data stream, see <xref
	linkend="v4l2-buf-type" />. Should be
	<constant>V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or
	<constant>V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>.</entry>
	</row>
	<row>
	<entry>__u32</entry>
	<entry><structfield>reserved</structfield>[3]</entry>
	<entry spanname="hspan">This array is reserved for future
	extensions. Applications and drivers must set it to zero.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	<!-- See also dev-sliced-vbi.sgml -->
	<table pgwide="1" frame="none" id="vbi-services">
	<title>Sliced VBI services</title>
	<tgroup cols="5">
	<colspec colname="c1" colwidth="2*" />
	<colspec colname="c2" colwidth="1*" />
	<colspec colname="c3" colwidth="1*" />
	<colspec colname="c4" colwidth="2*" />
	<colspec colname="c5" colwidth="2*" />
	<spanspec spanname='rlp' namest='c3' nameend='c5' />
	<thead>
	<row>
	<entry>Symbol</entry>
	<entry>Value</entry>
	<entry>Reference</entry>
	<entry>Lines, usually</entry>
	<entry>Payload</entry>
	</row>
	</thead>
	<tbody valign="top">
	<row>
	<entry><constant>V4L2_SLICED_TELETEXT_B</constant> (Teletext
	System B)</entry>
	<entry>0x0001</entry>
	<entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
	<entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
	<entry>Last 42 of the 45 byte Teletext packet, that is
	without clock run-in and framing code, lsb first transmitted.</entry>
	</row>
	<row>
	<entry><constant>V4L2_SLICED_VPS</constant></entry>
	<entry>0x0400</entry>
	<entry><xref linkend="ets300231" /></entry>
	<entry>PAL line 16</entry>
	<entry>Byte number 3 to 15 according to Figure 9 of
	ETS 300 231, lsb first transmitted.</entry>
	</row>
	<row>
	<entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
	<entry>0x1000</entry>
	<entry><xref linkend="eia608" /></entry>
	<entry>NTSC line 21, 284 (second field 21)</entry>
	<entry>Two bytes in transmission order, including parity
	bit, lsb first transmitted.</entry>
	</row>
	<row>
	<entry><constant>V4L2_SLICED_WSS_625</constant></entry>
	<entry>0x4000</entry>
	<entry><xref linkend="en300294" />, <xref linkend="itu1119" /></entry>
	<entry>PAL/SECAM line 23</entry>
	<entry><screen>
	Byte 0 1
	msb lsb msb lsb
	Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
	</screen></entry>
	</row>
	<row>
	<entry><constant>V4L2_SLICED_VBI_525</constant></entry>
	<entry>0x1000</entry>
	<entry spanname="rlp">Set of services applicable to 525
	line systems.</entry>
	</row>
	<row>
	<entry><constant>V4L2_SLICED_VBI_625</constant></entry>
	<entry>0x4401</entry>
	<entry spanname="rlp">Set of services applicable to 625
	line systems.</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	</refsect1>

	<refsect1>
	&return-value;

	<variablelist>
	<varlistentry>
	<term><errorcode>EINVAL</errorcode></term>
	<listitem>
	<para>The value in the <structfield>type</structfield> field is
	wrong.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</refsect1>
	</refentry>