path: root/v4l2-spec/dev-sliced-vbi.sgml

  <title>Sliced VBI Data Interface</title>

  <para>VBI stands for Vertical Blanking Interval, a gap in the
sequence of lines of an analog video signal. During VBI no picture
information is transmitted, allowing some time while the electron beam
of a cathode ray tube TV returns to the top of the screen.</para>

  <para>Sliced VBI devices use hardware to demodulate data transmitted
in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by
software, see also the <link linkend="raw-vbi">raw VBI
interface</link>. The data is passed as short packets of fixed size,
covering one scan line each. The number of packets per video frame is
variable.</para>

  <para>Sliced VBI capture and output devices are accessed through the
same character special files as raw VBI devices. When a driver
supports both interfaces, the default function of a
<filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI
capturing or output, and the sliced VBI function is only available
after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a
<filename>/dev/video</filename> device may support the sliced VBI API,
however the default function here is video capturing or output.
Different file descriptors must be used to pass raw and sliced VBI
data simultaneously, if this is supported by the driver.</para>

  <section>
    <title>Querying Capabilities</title>

    <para>Devices supporting the sliced VBI capturing or output API
set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or
<constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in
the <structfield>capabilities</structfield> field of &v4l2-capability;
returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the
read/write, streaming or asynchronous <link linkend="io">I/O
methods</link> must be supported. Sliced VBI devices may have a tuner
or modulator.</para>
  </section>

  <section>
    <title>Supplemental Functions</title>

    <para>Sliced VBI devices shall support <link linkend="video">video
input or output</link> and <link linkend="tuner">tuner or
modulator</link> ioctls if they have these capabilities, and they may
support <link linkend="control">control</link> ioctls. The <link
linkend="standard">video standard</link> ioctls provide information
vital to program a sliced VBI device, therefore must be
supported.</para>
  </section>

  <section>
    <title>Sliced VBI Format Negotiation</title>

    <para>To find out which data services are supported by the
hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl.
All drivers implementing the sliced VBI interface must support this
ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl
when 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 are
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.</para>

    <para>To determine the currently selected services applications
set the <structfield>type </structfield> field of &v4l2-format; to
<constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant>
V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT;
ioctl fills the <structfield>fmt.sliced</structfield> member, a
&v4l2-sliced-vbi-format;.</para>

    <para>Applications can request different parameters by
initializing or modifying the <structfield>fmt.sliced</structfield>
member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the
<structname>v4l2_format</structname> structure.</para>

    <para>The sliced VBI API is more complicated than the raw VBI API
because the hardware must be told which VBI service to expect on each
scan line. Not all services may be supported by the hardware on all
lines (this is especially true for VBI output where Teletext is often
unsupported and other services can only be inserted in one specific
line). In many cases, however, it is sufficient to just set the
<structfield>service_set</structfield> field to the required services
and let the driver fill the <structfield>service_lines</structfield>
array according to hardware capabilities. Only if more precise control
is needed should the programmer set the
<structfield>service_lines</structfield> array explicitly.</para>

    <para>The &VIDIOC-S-FMT; ioctl returns an &EINVAL; only when the
given parameters are ambiguous, otherwise it modifies the parameters
according to hardware capabilities. When the driver allocates
resources at this point, it may return an &EBUSY; if the required
resources are temporarily unavailable. Other resource allocation
points which may return <errorcode>EBUSY</errorcode> can be the
&VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and
&func-select; call.</para>

    <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format">
      <title>struct
<structname>v4l2_sliced_vbi_format</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 namest="c3" nameend="c5" spanname="hspan">
	<tbody valign="top">
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>service_set</structfield></entry>
	    <entry spanname="hspan"><para>If
<structfield>service_set</structfield> is non-zero when passed with
&VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the
<structfield>service_lines</structfield> array will be filled by the
driver according to the services specified in this field. For example,
if <structfield>service_set</structfield> is initialized with
<constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a
driver for the cx25840 video decoder sets lines 7-22 of both
fields<footnote><para>According to <link
linkend="ets300706">ETS&nbsp;300&nbsp;706</link> lines 6-22 of the
first field and lines 5-22 of the second field may carry Teletext
data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant>
and line 23 of the first field to
<constant>V4L2_SLICED_WSS_625</constant>. If
<structfield>service_set</structfield> is set to zero, then the values
of <structfield>service_lines</structfield> will be used instead.
</para><para>On return the driver sets this field to the union of all
elements of the returned <structfield>service_lines</structfield>
array. It may contain less services than requested, perhaps just one,
if the hardware cannot handle more services simultaneously. It may be
empty (zero) if none of the requested services are supported by the
hardware.</para></entry>
	  </row>
	  <row>
	    <entry>__u16</entry>
	    <entry><structfield>service_lines</structfield>[2][24]</entry>
	    <entry spanname="hspan"><para>Applications initialize this
array with sets of data services the driver shall look for or insert
on the respective scan line. Subject to hardware capabilities drivers
return the requested set, a subset, which may be just a single
service, or an empty set. When the hardware cannot handle multiple
services on the same line the driver shall choose one. No assumptions
can be made on which service the driver chooses.</para><para>Data
services are defined in <xref linkend="vbi-services2">. Array indices
map to ITU-R line numbers (see also <xref linkend="vbi-525"> and <xref
		  linkend="vbi-625">) as follows: <!-- No nested
tables, sigh. --></para></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>
	  <!-- End of line numbers table. -->
	  <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>io_size</structfield></entry>
	    <entry spanname="hspan">Maximum number of bytes passed by
one &func-read; or &func-write; call, and the buffer size in bytes for
the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
the size of &v4l2-sliced-vbi-data; times the number of non-zero
elements in the returned <structfield>service_lines</structfield>
array (that is the number of lines potentially carrying data).</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>reserved</structfield>[2]</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 vidioc-g-sliced-vbi-cap.sgml -->
    <table frame="none" pgwide="1" id="vbi-services2">
      <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 namest="c3" nameend="c5" spanname="rlp">
	<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="itu1119">, <xref linkend="en300294"></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>

    <para>Drivers may return an &EINVAL; when applications attempt to
read or write data without prior format negotiation, after switching
the video standard (which may invalidate the negotiated VBI
parameters) and after switching the video input (which may change the
video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
an &EBUSY; when applications attempt to change the format while i/o is
in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
and after the first &func-read; or &func-write; call).</para>
  </section>

  <section>
    <title>Reading and writing sliced VBI data</title>

    <para>A single &func-read; or &func-write; call must pass all data
belonging to one video frame. That is an array of
<structname>v4l2_sliced_vbi_data</structname> structures with one or
more elements and a total size not exceeding
<structfield>io_size</structfield> bytes. Likewise in streaming I/O
mode one buffer of <structfield>io_size</structfield> bytes must
contain data of one video frame. The <structfield>id</structfield> of
unused <structname>v4l2_sliced_vbi_data</structname> elements must be
zero.</para>

    <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data">
      <title>struct
<structname>v4l2_sliced_vbi_data</structname></title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>id</structfield></entry>
	    <entry>A flag from <xref linkend="vbi-services">
identifying the type of data in this packet. Only a single bit must be
set. When the <structfield>id</structfield> of a captured packet is
zero, the packet is empty and the contents of other fields are
undefined. Applications shall ignore empty packets. When the
<structfield>id</structfield> of a packet for output is zero the
contents of the <structfield>data</structfield> field are undefined
and the driver must no longer insert data on the requested
<structfield>field</structfield> and
<structfield>line</structfield>.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>field</structfield></entry>
	    <entry>The video field number this data has been captured
from, or shall be inserted at. <constant>0</constant> for the first
field, <constant>1</constant> for the second field.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>line</structfield></entry>
	    <entry>The field (as opposed to frame) line number this
data has been captured from, or shall be inserted at. See <xref
	    linkend="vbi-525"> and <xref linkend="vbi-625"> for valid
values. Sliced VBI capture devices can set the line number of all
packets to <constant>0</constant> if the hardware cannot reliably
identify scan lines. The field number must always be valid.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>reserved</structfield></entry>
	    <entry>This field is reserved for future extensions.
Applications and drivers must set it to zero.</entry>
	  </row>
	  <row>
	    <entry>__u8</entry>
	    <entry><structfield>data</structfield>[48]</entry>
	    <entry>The packet payload. See <xref
	    linkend="vbi-services"> for the contents and number of
bytes passed for each data type. The contents of padding bytes at the
end of this array are undefined, drivers and applications shall ignore
them.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <para>Packets are always passed in ascending line number order,
without duplicate line numbers. The &func-write; function and the
&VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
this rule. They must also return an &EINVAL; when applications pass an
incorrect field or line number, or a combination of
<structfield>field</structfield>, <structfield>line</structfield> and
<structfield>id</structfield> which has not been negotiated with the
&VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are
unknown the driver must pass the packets in transmitted order. The
driver can insert empty packets with <structfield>id</structfield> set
to zero anywhere in the packet array.</para>

    <para>To assure synchronization and to distinguish from frame
dropping, when a captured frame does not carry any of the requested
data services drivers must pass one or more empty packets. When an
application fails to pass VBI data in time for output, the driver
must output the last VPS and WSS packet again, and disable the output
of Closed Caption and Teletext data, or output data which is ignored
by Closed Caption and Teletext decoders.</para>

    <para>A sliced VBI device may support <link
linkend="rw">read/write</link> and/or streaming (<link
linkend="mmap">memory mapping</link> and/or <link linkend="userp">user
pointer</link>) I/O. The latter bears the possibility of synchronizing
video and VBI data by using buffer timestamps.</para>

  </section>

<!--
Local Variables:
mode: sgml
sgml-parent-document: "v4l2.sgml"
indent-tabs-mode: nil
End:
 -->