2009-09-13 22:16:04 -03:00
|
|
|
<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 id="sliced-vbi-format-negotitation">
|
|
|
|
|
<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 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 300 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
|
2014-07-18 02:58:42 -03:00
|
|
|
<structfield>service_lines</structfield>[1][0] to zero.
|
|
|
|
|
The <constant>V4L2_VBI_ITU_525_F1_START</constant>,
|
|
|
|
|
<constant>V4L2_VBI_ITU_525_F2_START</constant>,
|
|
|
|
|
<constant>V4L2_VBI_ITU_625_F1_START</constant> and
|
|
|
|
|
<constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start
|
|
|
|
|
line numbers for each field for each 525 or 625 line format as a
|
|
|
|
|
convenience. Don't forget that ITU line numbering starts at 1, not 0.
|
|
|
|
|
</entry>
|
2009-09-13 22:16:04 -03:00
|
|
|
</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 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="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>
|
|
|
|
|
|
|
|
|
|
<section>
|
|
|
|
|
<title>Sliced VBI Data in MPEG Streams</title>
|
|
|
|
|
|
|
|
|
|
<para>If a device can produce an MPEG output stream, it may be
|
|
|
|
|
capable of providing <link
|
|
|
|
|
linkend="sliced-vbi-format-negotitation">negotiated sliced VBI
|
|
|
|
|
services</link> as data embedded in the MPEG stream. Users or
|
|
|
|
|
applications control this sliced VBI data insertion with the <link
|
|
|
|
|
linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
|
|
|
|
|
control.</para>
|
|
|
|
|
|
|
|
|
|
<para>If the driver does not provide the <link
|
|
|
|
|
linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
|
|
|
|
|
control, or only allows that control to be set to <link
|
|
|
|
|
linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
|
|
|
|
|
V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device
|
|
|
|
|
cannot embed sliced VBI data in the MPEG stream.</para>
|
|
|
|
|
|
|
|
|
|
<para>The <link linkend="v4l2-mpeg-stream-vbi-fmt">
|
|
|
|
|
V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set
|
|
|
|
|
the device driver to capture nor cease capturing sliced VBI data. The
|
|
|
|
|
control only indicates to embed sliced VBI data in the MPEG stream, if
|
|
|
|
|
an application has negotiated sliced VBI service be captured.</para>
|
|
|
|
|
|
|
|
|
|
<para>It may also be the case that a device can embed sliced VBI
|
|
|
|
|
data in only certain types of MPEG streams: for example in an MPEG-2
|
|
|
|
|
PS but not an MPEG-2 TS. In this situation, if sliced VBI data
|
|
|
|
|
insertion is requested, the sliced VBI data will be embedded in MPEG
|
|
|
|
|
stream types when supported, and silently omitted from MPEG stream
|
|
|
|
|
types where sliced VBI data insertion is not supported by the device.
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<para>The following subsections specify the format of the
|
|
|
|
|
embedded sliced VBI data.</para>
|
|
|
|
|
|
|
|
|
|
<section>
|
|
|
|
|
<title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title>
|
|
|
|
|
<para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
|
|
|
|
|
V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI
|
|
|
|
|
format shall be interpreted by drivers as a control to cease
|
|
|
|
|
embedding sliced VBI data in MPEG streams. Neither the device nor
|
|
|
|
|
driver shall insert "empty" embedded sliced VBI data packets in the
|
|
|
|
|
MPEG stream when this format is set. No MPEG stream data structures
|
|
|
|
|
are specified for this format.</para>
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section>
|
|
|
|
|
<title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title>
|
|
|
|
|
<para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
|
|
|
|
|
V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI
|
|
|
|
|
format, when supported, indicates to the driver to embed up to 36
|
|
|
|
|
lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private
|
|
|
|
|
Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis>
|
|
|
|
|
Program Pack</emphasis> in the MPEG stream.</para>
|
|
|
|
|
|
|
|
|
|
<para><emphasis>Historical context</emphasis>: This format
|
|
|
|
|
specification originates from a custom, embedded, sliced VBI data
|
|
|
|
|
format used by the <filename>ivtv</filename> driver. This format
|
|
|
|
|
has already been informally specified in the kernel sources in the
|
|
|
|
|
file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>
|
|
|
|
|
. The maximum size of the payload and other aspects of this format
|
|
|
|
|
are driven by the CX23415 MPEG decoder's capabilities and limitations
|
|
|
|
|
with respect to extracting, decoding, and displaying sliced VBI data
|
|
|
|
|
embedded within an MPEG stream.</para>
|
|
|
|
|
|
|
|
|
|
<para>This format's use is <emphasis>not</emphasis> exclusive to
|
|
|
|
|
the <filename>ivtv</filename> driver <emphasis>nor</emphasis>
|
|
|
|
|
exclusive to CX2341x devices, as the sliced VBI data packet insertion
|
|
|
|
|
into the MPEG stream is implemented in driver software. At least the
|
|
|
|
|
<filename>cx18</filename> driver provides sliced VBI data insertion
|
|
|
|
|
into an MPEG-2 PS in this format as well.</para>
|
|
|
|
|
|
|
|
|
|
<para>The following definitions specify the payload of the
|
|
|
|
|
MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain
|
|
|
|
|
sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt">
|
|
|
|
|
<constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set.
|
|
|
|
|
(The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header
|
|
|
|
|
and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are
|
|
|
|
|
not detailed here. Please refer to the MPEG-2 specifications for
|
|
|
|
|
details on those packet headers.)</para>
|
|
|
|
|
|
|
|
|
|
<para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES
|
|
|
|
|
</emphasis> packets that contain sliced VBI data is specified by
|
|
|
|
|
&v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable
|
|
|
|
|
length, depending on the actual number of lines of sliced VBI data
|
|
|
|
|
present in a video frame. The payload may be padded at the end with
|
|
|
|
|
unspecified fill bytes to align the end of the payload to a 4-byte
|
|
|
|
|
boundary. The payload shall never exceed 1552 bytes (2 fields with
|
|
|
|
|
18 lines/field with 43 bytes of data/line and a 4 byte magic number).
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv">
|
|
|
|
|
<title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname>
|
|
|
|
|
</title>
|
|
|
|
|
<tgroup cols="4">
|
|
|
|
|
&cs-ustr;
|
|
|
|
|
<tbody valign="top">
|
|
|
|
|
<row>
|
|
|
|
|
<entry>__u8</entry>
|
|
|
|
|
<entry><structfield>magic</structfield>[4]</entry>
|
|
|
|
|
<entry></entry>
|
|
|
|
|
<entry>A "magic" constant from <xref
|
|
|
|
|
linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates
|
|
|
|
|
this is a valid sliced VBI data payload and also indicates which
|
|
|
|
|
member of the anonymous union, <structfield>itv0</structfield> or
|
|
|
|
|
<structfield>ITV0</structfield>, to use for the payload data.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>union</entry>
|
|
|
|
|
<entry>(anonymous)</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry></entry>
|
|
|
|
|
<entry>struct <link linkend="v4l2-mpeg-vbi-itv0">
|
|
|
|
|
<structname>v4l2_mpeg_vbi_itv0</structname></link>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry><structfield>itv0</structfield></entry>
|
|
|
|
|
<entry>The primary form of the sliced VBI data payload
|
|
|
|
|
that contains anywhere from 1 to 35 lines of sliced VBI data.
|
|
|
|
|
Line masks are provided in this form of the payload indicating
|
|
|
|
|
which VBI lines are provided.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry></entry>
|
|
|
|
|
<entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1">
|
|
|
|
|
<structname>v4l2_mpeg_vbi_ITV0</structname></link>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry><structfield>ITV0</structfield></entry>
|
|
|
|
|
<entry>An alternate form of the sliced VBI data payload
|
|
|
|
|
used when 36 lines of sliced VBI data are present. No line masks are
|
|
|
|
|
provided in this form of the payload; all valid line mask bits are
|
|
|
|
|
implcitly set.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic">
|
|
|
|
|
<title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv;
|
|
|
|
|
<structfield>magic</structfield> field</title>
|
|
|
|
|
<tgroup cols="3">
|
|
|
|
|
&cs-def;
|
|
|
|
|
<thead>
|
|
|
|
|
<row>
|
|
|
|
|
<entry align="left">Defined Symbol</entry>
|
|
|
|
|
<entry align="left">Value</entry>
|
|
|
|
|
<entry align="left">Description</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</thead>
|
|
|
|
|
<tbody valign="top">
|
|
|
|
|
<row>
|
|
|
|
|
<entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>"itv0"</entry>
|
|
|
|
|
<entry>Indicates the <structfield>itv0</structfield>
|
|
|
|
|
member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>"ITV0"</entry>
|
|
|
|
|
<entry>Indicates the <structfield>ITV0</structfield>
|
|
|
|
|
member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and
|
|
|
|
|
that 36 lines of sliced VBI data are present.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0">
|
|
|
|
|
<title>struct <structname>v4l2_mpeg_vbi_itv0</structname>
|
|
|
|
|
</title>
|
|
|
|
|
<tgroup cols="3">
|
|
|
|
|
&cs-str;
|
|
|
|
|
<tbody valign="top">
|
|
|
|
|
<row>
|
|
|
|
|
<entry>__le32</entry>
|
|
|
|
|
<entry><structfield>linemask</structfield>[2]</entry>
|
|
|
|
|
<entry><para>Bitmasks indicating the VBI service lines
|
|
|
|
|
present. These <structfield>linemask</structfield> values are stored
|
|
|
|
|
in little endian byte order in the MPEG stream. Some reference
|
|
|
|
|
<structfield>linemask</structfield> bit positions with their
|
|
|
|
|
corresponding VBI line number and video field are given below.
|
|
|
|
|
b<subscript>0</subscript> indicates the least significant bit of a
|
|
|
|
|
<structfield>linemask</structfield> value:<screen>
|
|
|
|
|
<structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field
|
|
|
|
|
<structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field
|
|
|
|
|
<structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field
|
|
|
|
|
<structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field
|
|
|
|
|
<structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field
|
|
|
|
|
<structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field
|
|
|
|
|
<structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
|
|
|
|
|
<structname>v4l2_mpeg_vbi_itv0_line</structname></link>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry><structfield>line</structfield>[35]</entry>
|
|
|
|
|
<entry>This is a variable length array that holds from 1
|
|
|
|
|
to 35 lines of sliced VBI data. The sliced VBI data lines present
|
|
|
|
|
correspond to the bits set in the <structfield>linemask</structfield>
|
|
|
|
|
array, starting from b<subscript>0</subscript> of <structfield>
|
|
|
|
|
linemask</structfield>[0] up through b<subscript>31</subscript> of
|
|
|
|
|
<structfield>linemask</structfield>[0], and from b<subscript>0
|
|
|
|
|
</subscript> of <structfield>linemask</structfield>[1] up through b
|
|
|
|
|
<subscript>3</subscript> of <structfield>linemask</structfield>[1].
|
|
|
|
|
<structfield>line</structfield>[0] corresponds to the first bit
|
|
|
|
|
found set in the <structfield>linemask</structfield> array,
|
|
|
|
|
<structfield>line</structfield>[1] corresponds to the second bit
|
|
|
|
|
found set in the <structfield>linemask</structfield> array, etc.
|
|
|
|
|
If no <structfield>linemask</structfield> array bits are set, then
|
|
|
|
|
<structfield>line</structfield>[0] may contain one line of
|
|
|
|
|
unspecified data that should be ignored by applications.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1">
|
|
|
|
|
<title>struct <structname>v4l2_mpeg_vbi_ITV0</structname>
|
|
|
|
|
</title>
|
|
|
|
|
<tgroup cols="3">
|
|
|
|
|
&cs-str;
|
|
|
|
|
<tbody valign="top">
|
|
|
|
|
<row>
|
|
|
|
|
<entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
|
|
|
|
|
<structname>v4l2_mpeg_vbi_itv0_line</structname></link>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry><structfield>line</structfield>[36]</entry>
|
|
|
|
|
<entry>A fixed length array of 36 lines of sliced VBI
|
|
|
|
|
data. <structfield>line</structfield>[0] through <structfield>line
|
|
|
|
|
</structfield>[17] correspond to lines 6 through 23 of the
|
|
|
|
|
first field. <structfield>line</structfield>[18] through
|
|
|
|
|
<structfield>line</structfield>[35] corresponds to lines 6
|
|
|
|
|
through 23 of the second field.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line">
|
|
|
|
|
<title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname>
|
|
|
|
|
</title>
|
|
|
|
|
<tgroup cols="3">
|
|
|
|
|
&cs-str;
|
|
|
|
|
<tbody valign="top">
|
|
|
|
|
<row>
|
|
|
|
|
<entry>__u8</entry>
|
|
|
|
|
<entry><structfield>id</structfield></entry>
|
|
|
|
|
<entry>A line identifier value from
|
|
|
|
|
<xref linkend="ITV0-Line-Identifier-Constants" /> that indicates
|
|
|
|
|
the type of sliced VBI data stored on this line.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry>__u8</entry>
|
|
|
|
|
<entry><structfield>data</structfield>[42]</entry>
|
|
|
|
|
<entry>The sliced VBI data for the line.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants">
|
|
|
|
|
<title>Line Identifiers for struct <link
|
|
|
|
|
linkend="v4l2-mpeg-vbi-itv0-line"><structname>
|
|
|
|
|
v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id
|
|
|
|
|
</structfield> field</title>
|
|
|
|
|
<tgroup cols="3">
|
|
|
|
|
&cs-def;
|
|
|
|
|
<thead>
|
|
|
|
|
<row>
|
|
|
|
|
<entry align="left">Defined Symbol</entry>
|
|
|
|
|
<entry align="left">Value</entry>
|
|
|
|
|
<entry align="left">Description</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</thead>
|
|
|
|
|
<tbody valign="top">
|
|
|
|
|
<row>
|
|
|
|
|
<entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>1</entry>
|
|
|
|
|
<entry>Refer to <link linkend="vbi-services2">
|
|
|
|
|
Sliced VBI services</link> for a description of the line payload.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>4</entry>
|
|
|
|
|
<entry>Refer to <link linkend="vbi-services2">
|
|
|
|
|
Sliced VBI services</link> for a description of the line payload.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>5</entry>
|
|
|
|
|
<entry>Refer to <link linkend="vbi-services2">
|
|
|
|
|
Sliced VBI services</link> for a description of the line payload.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
<row>
|
|
|
|
|
<entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant>
|
|
|
|
|
</entry>
|
|
|
|
|
<entry>7</entry>
|
|
|
|
|
<entry>Refer to <link linkend="vbi-services2">
|
|
|
|
|
Sliced VBI services</link> for a description of the line payload.</entry>
|
|
|
|
|
</row>
|
|
|
|
|
</tbody>
|
|
|
|
|
</tgroup>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
</section>
|
|
|
|
|
</section>
|
