1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Sliced VBI Data Interface</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="LINUX MEDIA INFRASTRUCTURE API"><link rel="up" href="devices.html" title="Chapter 4. Interfaces"><link rel="prev" href="raw-vbi.html" title="Raw VBI Data Interface"><link rel="next" href="ttx.html" title="Teletext Interface"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Sliced VBI Data Interface</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="raw-vbi.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Interfaces</th><td width="20%" align="right"> <a accesskey="n" href="ttx.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="sliced"></a>Sliced VBI Data Interface</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="sliced.html#idp1105589692">Querying Capabilities</a></span></dt><dt><span class="section"><a href="sliced.html#idp1105592452">Supplemental Functions</a></span></dt><dt><span class="section"><a href="sliced.html#sliced-vbi-format-negotitation">Sliced VBI Format Negotiation</a></span></dt><dt><span class="section"><a href="sliced.html#idp1105654204">Reading and writing sliced VBI data</a></span></dt><dt><span class="section"><a href="sliced.html#idp1105675332">Sliced VBI Data in MPEG Streams</a></span></dt></dl></div><p>VBI stands for Vertical Blanking Interval, a gap in the 2sequence of lines of an analog video signal. During VBI no picture 3information is transmitted, allowing some time while the electron beam 4of a cathode ray tube TV returns to the top of the screen.</p><p>Sliced VBI devices use hardware to demodulate data transmitted 5in the VBI. V4L2 drivers shall <span class="emphasis"><em>not</em></span> do this by 6software, see also the <a class="link" href="raw-vbi.html" title="Raw VBI Data Interface">raw VBI 7interface</a>. The data is passed as short packets of fixed size, 8covering one scan line each. The number of packets per video frame is 9variable.</p><p>Sliced VBI capture and output devices are accessed through the 10same character special files as raw VBI devices. When a driver 11supports both interfaces, the default function of a 12<code class="filename">/dev/vbi</code> device is <span class="emphasis"><em>raw</em></span> VBI 13capturing or output, and the sliced VBI function is only available 14after calling the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl as defined below. Likewise a 15<code class="filename">/dev/video</code> device may support the sliced VBI API, 16however the default function here is video capturing or output. 17Different file descriptors must be used to pass raw and sliced VBI 18data simultaneously, if this is supported by the driver.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105589692"></a>Querying Capabilities</h3></div></div></div><p>Devices supporting the sliced VBI capturing or output API 19set the <code class="constant">V4L2_CAP_SLICED_VBI_CAPTURE</code> or 20<code class="constant">V4L2_CAP_SLICED_VBI_OUTPUT</code> flag respectively, in 21the <em class="structfield"><code>capabilities</code></em> field of struct <a class="link" href="vidioc-querycap.html#v4l2-capability" title="Table A.93. struct v4l2_capability">v4l2_capability</a> 22returned by the <a class="link" href="vidioc-querycap.html" title="ioctl VIDIOC_QUERYCAP"><code class="constant">VIDIOC_QUERYCAP</code></a> ioctl. At least one of the 23read/write, streaming or asynchronous <a class="link" href="io.html" title="Chapter 3. Input/Output">I/O 24methods</a> must be supported. Sliced VBI devices may have a tuner 25or modulator.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105592452"></a>Supplemental Functions</h3></div></div></div><p>Sliced VBI devices shall support <a class="link" href="video.html" title="Video Inputs and Outputs">video 26input or output</a> and <a class="link" href="tuner.html" title="Tuners and Modulators">tuner or 27modulator</a> ioctls if they have these capabilities, and they may 28support <a class="link" href="control.html" title="User Controls">control</a> ioctls. The <a class="link" href="standard.html" title="Video Standards">video standard</a> ioctls provide information 29vital to program a sliced VBI device, therefore must be 30supported.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="sliced-vbi-format-negotitation"></a>Sliced VBI Format Negotiation</h3></div></div></div><p>To find out which data services are supported by the 31hardware applications can call the <a class="link" href="vidioc-g-sliced-vbi-cap.html" title="ioctl VIDIOC_G_SLICED_VBI_CAP"><code class="constant">VIDIOC_G_SLICED_VBI_CAP</code></a> ioctl. 32All drivers implementing the sliced VBI interface must support this 33ioctl. The results may differ from those of the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl 34when the number of VBI lines the hardware can capture or output per 35frame, or the number of services it can identify on a given line are 36limited. For example on PAL line 16 the hardware may be able to look 37for a VPS or Teletext signal, but not both at the same time.</p><p>To determine the currently selected services applications 38set the <em class="structfield"><code>type </code></em> field of struct <a class="link" href="vidioc-g-fmt.html#v4l2-format" title="Table A.72. struct v4l2_format">v4l2_format</a> to 39<code class="constant"> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</code> or <code class="constant"> 40V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</code>, and the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a> 41ioctl fills the <em class="structfield"><code>fmt.sliced</code></em> member, a 42struct <a class="link" href="sliced.html#v4l2-sliced-vbi-format" title="Table 4.6. struct v4l2_sliced_vbi_format">v4l2_sliced_vbi_format</a>.</p><p>Applications can request different parameters by 43initializing or modifying the <em class="structfield"><code>fmt.sliced</code></em> 44member and calling the <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl with a pointer to the 45<span class="structname">v4l2_format</span> structure.</p><p>The sliced VBI API is more complicated than the raw VBI API 46because the hardware must be told which VBI service to expect on each 47scan line. Not all services may be supported by the hardware on all 48lines (this is especially true for VBI output where Teletext is often 49unsupported and other services can only be inserted in one specific 50line). In many cases, however, it is sufficient to just set the 51<em class="structfield"><code>service_set</code></em> field to the required services 52and let the driver fill the <em class="structfield"><code>service_lines</code></em> 53array according to hardware capabilities. Only if more precise control 54is needed should the programmer set the 55<em class="structfield"><code>service_lines</code></em> array explicitly.</p><p>The <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl modifies the parameters 56according to hardware capabilities. When the driver allocates 57resources at this point, it may return an <span class="errorcode">EBUSY</span> error code if the required 58resources are temporarily unavailable. Other resource allocation 59points which may return <span class="errorcode">EBUSY</span> can be the 60<a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMON</code></a> ioctl and the first <a class="link" href="func-read.html" title="V4L2 read()"><code class="function">read()</code></a>, <a class="link" href="func-write.html" title="V4L2 write()"><code class="function">write()</code></a> and 61<a class="link" href="func-select.html" title="V4L2 select()"><code class="function">select()</code></a> call.</p><div class="table"><a name="v4l2-sliced-vbi-format"></a><p class="title"><b>Table 4.6. struct 62<span class="structname">v4l2_sliced_vbi_format</span></b></p><div class="table-contents"><table summary="struct 63v4l2_sliced_vbi_format" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"><col class="c4"><col class="c5"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>service_set</code></em></td><td colspan="3" valign="top"><p>If 64<em class="structfield"><code>service_set</code></em> is non-zero when passed with 65<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> or <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_TRY_FMT</code></a>, the 66<em class="structfield"><code>service_lines</code></em> array will be filled by the 67driver according to the services specified in this field. For example, 68if <em class="structfield"><code>service_set</code></em> is initialized with 69<code class="constant">V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</code>, a 70driver for the cx25840 video decoder sets lines 7-22 of both 71fields<a href="#ftn.idp1105614212" class="footnote" name="idp1105614212"><sup class="footnote">[a]</sup></a> to <code class="constant">V4L2_SLICED_TELETEXT_B</code> 72and line 23 of the first field to 73<code class="constant">V4L2_SLICED_WSS_625</code>. If 74<em class="structfield"><code>service_set</code></em> is set to zero, then the values 75of <em class="structfield"><code>service_lines</code></em> will be used instead. 76</p><p>On return the driver sets this field to the union of all 77elements of the returned <em class="structfield"><code>service_lines</code></em> 78array. It may contain less services than requested, perhaps just one, 79if the hardware cannot handle more services simultaneously. It may be 80empty (zero) if none of the requested services are supported by the 81hardware.</p></td></tr><tr><td valign="top">__u16</td><td valign="top"><em class="structfield"><code>service_lines</code></em>[2][24]</td><td colspan="3" valign="top"><p>Applications initialize this 82array with sets of data services the driver shall look for or insert 83on the respective scan line. Subject to hardware capabilities drivers 84return the requested set, a subset, which may be just a single 85service, or an empty set. When the hardware cannot handle multiple 86services on the same line the driver shall choose one. No assumptions 87can be made on which service the driver chooses.</p><p>Data 88services are defined in <a class="xref" href="sliced.html#vbi-services2" title="Table 4.7. Sliced VBI services">Table 4.7, “Sliced VBI services”</a>. Array indices 89map to ITU-R line numbers (see also <a class="xref" href="raw-vbi.html#vbi-525" title="Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)">Figure 4.2, “ITU-R 525 line numbering (M/NTSC and M/PAL)”</a> and <a class="xref" href="raw-vbi.html#vbi-625" title="Figure 4.3. ITU-R 625 line numbering">Figure 4.3, “ITU-R 625 line numbering”</a>) as follows: </p></td></tr><tr><td valign="top"> </td><td valign="top"> </td><td valign="top">Element</td><td valign="top">525 line systems</td><td valign="top">625 line systems</td></tr><tr><td valign="top"> </td><td valign="top"> </td><td valign="top"><em class="structfield"><code>service_lines</code></em>[0][1]</td><td align="center" valign="top">1</td><td align="center" valign="top">1</td></tr><tr><td valign="top"> </td><td valign="top"> </td><td valign="top"><em class="structfield"><code>service_lines</code></em>[0][23]</td><td align="center" valign="top">23</td><td align="center" valign="top">23</td></tr><tr><td valign="top"> </td><td valign="top"> </td><td valign="top"><em class="structfield"><code>service_lines</code></em>[1][1]</td><td align="center" valign="top">264</td><td align="center" valign="top">314</td></tr><tr><td valign="top"> </td><td valign="top"> </td><td valign="top"><em class="structfield"><code>service_lines</code></em>[1][23]</td><td align="center" valign="top">286</td><td align="center" valign="top">336</td></tr><tr><td valign="top"> </td><td valign="top"> </td><td colspan="3" valign="top">Drivers must set 90<em class="structfield"><code>service_lines</code></em>[0][0] and 91<em class="structfield"><code>service_lines</code></em>[1][0] to zero. 92The <code class="constant">V4L2_VBI_ITU_525_F1_START</code>, 93<code class="constant">V4L2_VBI_ITU_525_F2_START</code>, 94<code class="constant">V4L2_VBI_ITU_625_F1_START</code> and 95<code class="constant">V4L2_VBI_ITU_625_F2_START</code> defines give the start 96line numbers for each field for each 525 or 625 line format as a 97convenience. Don't forget that ITU line numbering starts at 1, not 0. 98</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>io_size</code></em></td><td colspan="3" valign="top">Maximum number of bytes passed by 99one <a class="link" href="func-read.html" title="V4L2 read()"><code class="function">read()</code></a> or <a class="link" href="func-write.html" title="V4L2 write()"><code class="function">write()</code></a> call, and the buffer size in bytes for 100the <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_QBUF</code></a> and <a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_DQBUF</code></a> ioctl. Drivers set this field to 101the size of struct <a class="link" href="sliced.html#v4l2-sliced-vbi-data" title="Table 4.8. struct v4l2_sliced_vbi_data">v4l2_sliced_vbi_data</a> times the number of non-zero 102elements in the returned <em class="structfield"><code>service_lines</code></em> 103array (that is the number of lines potentially carrying data).</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>reserved</code></em>[2]</td><td colspan="3" valign="top">This array is reserved for future 104extensions. Applications and drivers must set it to zero.</td></tr></tbody><tbody class="footnotes"><tr><td colspan="5"><div id="ftn.idp1105614212" class="footnote"><p><a href="#idp1105614212" class="para"><sup class="para">[a] </sup></a>According to <a class="link" href="bi01.html#ets300706" title='ETS 300 706 "Enhanced Teletext specification"'>ETS 300 706</a> lines 6-22 of the 105first field and lines 5-22 of the second field may carry Teletext 106data.</p></div></td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="vbi-services2"></a><p class="title"><b>Table 4.7. Sliced VBI services</b></p><div class="table-contents"><table summary="Sliced VBI services" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"><col class="c4"><col class="c5"></colgroup><thead><tr><th>Symbol</th><th>Value</th><th>Reference</th><th>Lines, usually</th><th>Payload</th></tr></thead><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_SLICED_TELETEXT_B</code> 107(Teletext System B)</td><td valign="top">0x0001</td><td valign="top"><a class="xref" href="bi01.html#ets300706" title='ETS 300 706 "Enhanced Teletext specification"'>[<abbr class="abbrev">ETS 300 706</abbr>]</a>, <a class="xref" href="bi01.html#itu653" title='ITU-R Recommendation BT.653-3 "Teletext systems"'>[<abbr class="abbrev">ITU BT.653</abbr>]</a></td><td valign="top">PAL/SECAM line 7-22, 320-335 (second field 7-22)</td><td valign="top">Last 42 of the 45 byte Teletext packet, that is 108without clock run-in and framing code, lsb first transmitted.</td></tr><tr><td valign="top"><code class="constant">V4L2_SLICED_VPS</code></td><td valign="top">0x0400</td><td valign="top"><a class="xref" href="bi01.html#ets300231" title='ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)"'>[<abbr class="abbrev">ETS 300 231</abbr>]</a></td><td valign="top">PAL line 16</td><td valign="top">Byte number 3 to 15 according to Figure 9 of 109ETS 300 231, lsb first transmitted.</td></tr><tr><td valign="top"><code class="constant">V4L2_SLICED_CAPTION_525</code></td><td valign="top">0x1000</td><td valign="top"><a class="xref" href="bi01.html#cea608" title='CEA-608-E R-2014 "Line 21 Data Services"'>[<abbr class="abbrev">CEA 608-E</abbr>]</a></td><td valign="top">NTSC line 21, 284 (second field 21)</td><td valign="top">Two bytes in transmission order, including parity 110bit, lsb first transmitted.</td></tr><tr><td valign="top"><code class="constant">V4L2_SLICED_WSS_625</code></td><td valign="top">0x4000</td><td valign="top"><a class="xref" href="bi01.html#itu1119" title='ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)"'>[<abbr class="abbrev">ITU BT.1119</abbr>]</a>, <a class="xref" href="bi01.html#en300294" title='EN 300 294 "625-line television Wide Screen Signalling (WSS)"'>[<abbr class="abbrev">EN 300 294</abbr>]</a></td><td valign="top">PAL/SECAM line 23</td><td valign="top"><pre class="screen"> 111Byte 0 1 112 msb lsb msb lsb 113 Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 114</pre></td></tr><tr><td valign="top"><code class="constant">V4L2_SLICED_VBI_525</code></td><td valign="top">0x1000</td><td colspan="3" valign="top">Set of services applicable to 525 115line systems.</td></tr><tr><td valign="top"><code class="constant">V4L2_SLICED_VBI_625</code></td><td valign="top">0x4401</td><td colspan="3" valign="top">Set of services applicable to 625 116line systems.</td></tr></tbody></table></div></div><br class="table-break"><p>Drivers may return an <span class="errorcode">EINVAL</span> error code when applications attempt to 117read or write data without prior format negotiation, after switching 118the video standard (which may invalidate the negotiated VBI 119parameters) and after switching the video input (which may change the 120video standard as a side effect). The <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl may return 121an <span class="errorcode">EBUSY</span> error code when applications attempt to change the format while i/o is 122in progress (between a <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMON</code></a> and <a class="link" href="vidioc-streamon.html" title="ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF"><code class="constant">VIDIOC_STREAMOFF</code></a> call, 123and after the first <a class="link" href="func-read.html" title="V4L2 read()"><code class="function">read()</code></a> or <a class="link" href="func-write.html" title="V4L2 write()"><code class="function">write()</code></a> call).</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105654204"></a>Reading and writing sliced VBI data</h3></div></div></div><p>A single <a class="link" href="func-read.html" title="V4L2 read()"><code class="function">read()</code></a> or <a class="link" href="func-write.html" title="V4L2 write()"><code class="function">write()</code></a> call must pass all data 124belonging to one video frame. That is an array of 125<span class="structname">v4l2_sliced_vbi_data</span> structures with one or 126more elements and a total size not exceeding 127<em class="structfield"><code>io_size</code></em> bytes. Likewise in streaming I/O 128mode one buffer of <em class="structfield"><code>io_size</code></em> bytes must 129contain data of one video frame. The <em class="structfield"><code>id</code></em> of 130unused <span class="structname">v4l2_sliced_vbi_data</span> elements must be 131zero.</p><div class="table"><a name="v4l2-sliced-vbi-data"></a><p class="title"><b>Table 4.8. struct 132<span class="structname">v4l2_sliced_vbi_data</span></b></p><div class="table-contents"><table summary="struct 133v4l2_sliced_vbi_data" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>id</code></em></td><td valign="top">A flag from <a class="xref" href="vidioc-g-sliced-vbi-cap.html#vbi-services" title="Table A.86. Sliced VBI services">Table A.86, “Sliced VBI services”</a> 134identifying the type of data in this packet. Only a single bit must be 135set. When the <em class="structfield"><code>id</code></em> of a captured packet is 136zero, the packet is empty and the contents of other fields are 137undefined. Applications shall ignore empty packets. When the 138<em class="structfield"><code>id</code></em> of a packet for output is zero the 139contents of the <em class="structfield"><code>data</code></em> field are undefined 140and the driver must no longer insert data on the requested 141<em class="structfield"><code>field</code></em> and 142<em class="structfield"><code>line</code></em>.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>field</code></em></td><td valign="top">The video field number this data has been captured 143from, or shall be inserted at. <code class="constant">0</code> for the first 144field, <code class="constant">1</code> for the second field.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>line</code></em></td><td valign="top">The field (as opposed to frame) line number this 145data has been captured from, or shall be inserted at. See <a class="xref" href="raw-vbi.html#vbi-525" title="Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)">Figure 4.2, “ITU-R 525 line numbering (M/NTSC and M/PAL)”</a> and <a class="xref" href="raw-vbi.html#vbi-625" title="Figure 4.3. ITU-R 625 line numbering">Figure 4.3, “ITU-R 625 line numbering”</a> for valid 146values. Sliced VBI capture devices can set the line number of all 147packets to <code class="constant">0</code> if the hardware cannot reliably 148identify scan lines. The field number must always be valid.</td></tr><tr><td valign="top">__u32</td><td valign="top"><em class="structfield"><code>reserved</code></em></td><td valign="top">This field is reserved for future extensions. 149Applications and drivers must set it to zero.</td></tr><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>data</code></em>[48]</td><td valign="top">The packet payload. See <a class="xref" href="vidioc-g-sliced-vbi-cap.html#vbi-services" title="Table A.86. Sliced VBI services">Table A.86, “Sliced VBI services”</a> for the contents and number of 150bytes passed for each data type. The contents of padding bytes at the 151end of this array are undefined, drivers and applications shall ignore 152them.</td></tr></tbody></table></div></div><br class="table-break"><p>Packets are always passed in ascending line number order, 153without duplicate line numbers. The <a class="link" href="func-write.html" title="V4L2 write()"><code class="function">write()</code></a> function and the 154<a class="link" href="vidioc-qbuf.html" title="ioctl VIDIOC_QBUF, VIDIOC_DQBUF"><code class="constant">VIDIOC_QBUF</code></a> ioctl must return an <span class="errorcode">EINVAL</span> error code when applications violate 155this rule. They must also return an <span class="errorcode">EINVAL</span> error code when applications pass an 156incorrect field or line number, or a combination of 157<em class="structfield"><code>field</code></em>, <em class="structfield"><code>line</code></em> and 158<em class="structfield"><code>id</code></em> which has not been negotiated with the 159<a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_G_FMT</code></a> or <a class="link" href="vidioc-g-fmt.html" title="ioctl VIDIOC_G_FMT, VIDIOC_S_FMT, VIDIOC_TRY_FMT"><code class="constant">VIDIOC_S_FMT</code></a> ioctl. When the line numbers are 160unknown the driver must pass the packets in transmitted order. The 161driver can insert empty packets with <em class="structfield"><code>id</code></em> set 162to zero anywhere in the packet array.</p><p>To assure synchronization and to distinguish from frame 163dropping, when a captured frame does not carry any of the requested 164data services drivers must pass one or more empty packets. When an 165application fails to pass VBI data in time for output, the driver 166must output the last VPS and WSS packet again, and disable the output 167of Closed Caption and Teletext data, or output data which is ignored 168by Closed Caption and Teletext decoders.</p><p>A sliced VBI device may support <a class="link" href="io.html#rw" title="Read/Write">read/write</a> and/or streaming (<a class="link" href="mmap.html" title="Streaming I/O (Memory Mapping)">memory mapping</a> and/or <a class="link" href="userp.html" title="Streaming I/O (User Pointers)">user 169pointer</a>) I/O. The latter bears the possibility of synchronizing 170video and VBI data by using buffer timestamps.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="idp1105675332"></a>Sliced VBI Data in MPEG Streams</h3></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="sliced.html#idp1105680308">MPEG Stream Embedded, Sliced VBI Data Format: NONE</a></span></dt><dt><span class="section"><a href="sliced.html#idp1105681804">MPEG Stream Embedded, Sliced VBI Data Format: IVTV</a></span></dt></dl></div><p>If a device can produce an MPEG output stream, it may be 171capable of providing <a class="link" href="sliced.html#sliced-vbi-format-negotitation" title="Sliced VBI Format Negotiation">negotiated sliced VBI 172services</a> as data embedded in the MPEG stream. Users or 173applications control this sliced VBI data insertion with the <a class="link" href="extended-controls.html#v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</a> 174control.</p><p>If the driver does not provide the <a class="link" href="extended-controls.html#v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</a> 175control, or only allows that control to be set to <a class="link" href="extended-controls.html#v4l2-mpeg-stream-vbi-fmt"><code class="constant"> 176V4L2_MPEG_STREAM_VBI_FMT_NONE</code></a>, then the device 177cannot embed sliced VBI data in the MPEG stream.</p><p>The <a class="link" href="extended-controls.html#v4l2-mpeg-stream-vbi-fmt"> 178V4L2_CID_MPEG_STREAM_VBI_FMT</a> control does not implicitly set 179the device driver to capture nor cease capturing sliced VBI data. The 180control only indicates to embed sliced VBI data in the MPEG stream, if 181an application has negotiated sliced VBI service be captured.</p><p>It may also be the case that a device can embed sliced VBI 182data in only certain types of MPEG streams: for example in an MPEG-2 183PS but not an MPEG-2 TS. In this situation, if sliced VBI data 184insertion is requested, the sliced VBI data will be embedded in MPEG 185stream types when supported, and silently omitted from MPEG stream 186types where sliced VBI data insertion is not supported by the device. 187</p><p>The following subsections specify the format of the 188embedded sliced VBI data.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="idp1105680308"></a>MPEG Stream Embedded, Sliced VBI Data Format: NONE</h4></div></div></div><p>The <a class="link" href="extended-controls.html#v4l2-mpeg-stream-vbi-fmt"><code class="constant"> 189V4L2_MPEG_STREAM_VBI_FMT_NONE</code></a> embedded sliced VBI 190format shall be interpreted by drivers as a control to cease 191embedding sliced VBI data in MPEG streams. Neither the device nor 192driver shall insert "empty" embedded sliced VBI data packets in the 193MPEG stream when this format is set. No MPEG stream data structures 194are specified for this format.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="idp1105681804"></a>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</h4></div></div></div><p>The <a class="link" href="extended-controls.html#v4l2-mpeg-stream-vbi-fmt"><code class="constant"> 195V4L2_MPEG_STREAM_VBI_FMT_IVTV</code></a> embedded sliced VBI 196format, when supported, indicates to the driver to embed up to 36 197lines of sliced VBI data per frame in an MPEG-2 <span class="emphasis"><em>Private 198Stream 1 PES</em></span> packet encapsulated in an MPEG-2 <span class="emphasis"><em> 199Program Pack</em></span> in the MPEG stream.</p><p><span class="emphasis"><em>Historical context</em></span>: This format 200specification originates from a custom, embedded, sliced VBI data 201format used by the <code class="filename">ivtv</code> driver. This format 202has already been informally specified in the kernel sources in the 203file <code class="filename">Documentation/video4linux/cx2341x/README.vbi</code> 204. The maximum size of the payload and other aspects of this format 205are driven by the CX23415 MPEG decoder's capabilities and limitations 206with respect to extracting, decoding, and displaying sliced VBI data 207embedded within an MPEG stream.</p><p>This format's use is <span class="emphasis"><em>not</em></span> exclusive to 208the <code class="filename">ivtv</code> driver <span class="emphasis"><em>nor</em></span> 209exclusive to CX2341x devices, as the sliced VBI data packet insertion 210into the MPEG stream is implemented in driver software. At least the 211<code class="filename">cx18</code> driver provides sliced VBI data insertion 212into an MPEG-2 PS in this format as well.</p><p>The following definitions specify the payload of the 213MPEG-2 <span class="emphasis"><em>Private Stream 1 PES</em></span> packets that contain 214sliced VBI data when <a class="link" href="extended-controls.html#v4l2-mpeg-stream-vbi-fmt"> 215<code class="constant">V4L2_MPEG_STREAM_VBI_FMT_IVTV</code></a> is set. 216(The MPEG-2 <span class="emphasis"><em>Private Stream 1 PES</em></span> packet header 217and encapsulating MPEG-2 <span class="emphasis"><em>Program Pack</em></span> header are 218not detailed here. Please refer to the MPEG-2 specifications for 219details on those packet headers.)</p><p>The payload of the MPEG-2 <span class="emphasis"><em>Private Stream 1 PES 220</em></span> packets that contain sliced VBI data is specified by 221struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-fmt-ivtv" title="Table 4.9. struct v4l2_mpeg_vbi_fmt_ivtv">v4l2_mpeg_vbi_fmt_ivtv</a>. The payload is variable 222length, depending on the actual number of lines of sliced VBI data 223present in a video frame. The payload may be padded at the end with 224unspecified fill bytes to align the end of the payload to a 4-byte 225boundary. The payload shall never exceed 1552 bytes (2 fields with 22618 lines/field with 43 bytes of data/line and a 4 byte magic number). 227</p><div class="table"><a name="v4l2-mpeg-vbi-fmt-ivtv"></a><p class="title"><b>Table 4.9. struct <span class="structname">v4l2_mpeg_vbi_fmt_ivtv</span> 228 </b></p><div class="table-contents"><table summary="struct v4l2_mpeg_vbi_fmt_ivtv 229 " width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"><col class="c4"></colgroup><tbody valign="top"><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>magic</code></em>[4]</td><td valign="top"> </td><td valign="top">A "magic" constant from <a class="xref" href="sliced.html#v4l2-mpeg-vbi-fmt-ivtv-magic" title="Table 4.10. Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field">Table 4.10, “Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv 230 <em class="structfield"><code>magic</code></em> field”</a> that indicates 231this is a valid sliced VBI data payload and also indicates which 232member of the anonymous union, <em class="structfield"><code>itv0</code></em> or 233<em class="structfield"><code>ITV0</code></em>, to use for the payload data.</td></tr><tr><td valign="top">union</td><td valign="top">(anonymous)</td><td class="auto-generated"> </td><td class="auto-generated"> </td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-itv0" title="Table 4.11. struct v4l2_mpeg_vbi_itv0"> 234 <span class="structname">v4l2_mpeg_vbi_itv0</span></a> 235 </td><td valign="top"><em class="structfield"><code>itv0</code></em></td><td valign="top">The primary form of the sliced VBI data payload 236that contains anywhere from 1 to 35 lines of sliced VBI data. 237Line masks are provided in this form of the payload indicating 238which VBI lines are provided.</td></tr><tr><td valign="top"> </td><td valign="top">struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-itv0-1" title="Table 4.12. struct v4l2_mpeg_vbi_ITV0"> 239 <span class="structname">v4l2_mpeg_vbi_ITV0</span></a> 240 </td><td valign="top"><em class="structfield"><code>ITV0</code></em></td><td valign="top">An alternate form of the sliced VBI data payload 241used when 36 lines of sliced VBI data are present. No line masks are 242provided in this form of the payload; all valid line mask bits are 243implcitly set.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-mpeg-vbi-fmt-ivtv-magic"></a><p class="title"><b>Table 4.10. Magic Constants for struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-fmt-ivtv" title="Table 4.9. struct v4l2_mpeg_vbi_fmt_ivtv">v4l2_mpeg_vbi_fmt_ivtv</a> 244 <em class="structfield"><code>magic</code></em> field</b></p><div class="table-contents"><table summary="Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv 245 magic field" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th align="left">Defined Symbol</th><th align="left">Value</th><th align="left">Description</th></tr></thead><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_MPEG_VBI_IVTV_MAGIC0</code> 246 </td><td valign="top">"itv0"</td><td valign="top">Indicates the <em class="structfield"><code>itv0</code></em> 247member of the union in struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-fmt-ivtv" title="Table 4.9. struct v4l2_mpeg_vbi_fmt_ivtv">v4l2_mpeg_vbi_fmt_ivtv</a> is valid.</td></tr><tr><td valign="top"><code class="constant">V4L2_MPEG_VBI_IVTV_MAGIC1</code> 248 </td><td valign="top">"ITV0"</td><td valign="top">Indicates the <em class="structfield"><code>ITV0</code></em> 249member of the union in struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-fmt-ivtv" title="Table 4.9. struct v4l2_mpeg_vbi_fmt_ivtv">v4l2_mpeg_vbi_fmt_ivtv</a> is valid and 250that 36 lines of sliced VBI data are present.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-mpeg-vbi-itv0"></a><p class="title"><b>Table 4.11. struct <span class="structname">v4l2_mpeg_vbi_itv0</span> 251 </b></p><div class="table-contents"><table summary="struct v4l2_mpeg_vbi_itv0 252 " width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__le32</td><td valign="top"><em class="structfield"><code>linemask</code></em>[2]</td><td valign="top"><p>Bitmasks indicating the VBI service lines 253present. These <em class="structfield"><code>linemask</code></em> values are stored 254in little endian byte order in the MPEG stream. Some reference 255<em class="structfield"><code>linemask</code></em> bit positions with their 256corresponding VBI line number and video field are given below. 257b<sub>0</sub> indicates the least significant bit of a 258<em class="structfield"><code>linemask</code></em> value:</p><pre class="screen"> 259<em class="structfield"><code>linemask</code></em>[0] b<sub>0</sub>: line 6 first field 260<em class="structfield"><code>linemask</code></em>[0] b<sub>17</sub>: line 23 first field 261<em class="structfield"><code>linemask</code></em>[0] b<sub>18</sub>: line 6 second field 262<em class="structfield"><code>linemask</code></em>[0] b<sub>31</sub>: line 19 second field 263<em class="structfield"><code>linemask</code></em>[1] b<sub>0</sub>: line 20 second field 264<em class="structfield"><code>linemask</code></em>[1] b<sub>3</sub>: line 23 second field 265<em class="structfield"><code>linemask</code></em>[1] b<sub>4</sub>-b<sub>31</sub>: unused and set to 0</pre></td></tr><tr><td valign="top">struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-itv0-line" title="Table 4.13. struct v4l2_mpeg_vbi_itv0_line"> 266 <span class="structname">v4l2_mpeg_vbi_itv0_line</span></a> 267 </td><td valign="top"><em class="structfield"><code>line</code></em>[35]</td><td valign="top">This is a variable length array that holds from 1 268to 35 lines of sliced VBI data. The sliced VBI data lines present 269correspond to the bits set in the <em class="structfield"><code>linemask</code></em> 270array, starting from b<sub>0</sub> of <em class="structfield"><code> 271linemask</code></em>[0] up through b<sub>31</sub> of 272<em class="structfield"><code>linemask</code></em>[0], and from b<sub>0 273</sub> of <em class="structfield"><code>linemask</code></em>[1] up through b 274<sub>3</sub> of <em class="structfield"><code>linemask</code></em>[1]. 275<em class="structfield"><code>line</code></em>[0] corresponds to the first bit 276found set in the <em class="structfield"><code>linemask</code></em> array, 277<em class="structfield"><code>line</code></em>[1] corresponds to the second bit 278found set in the <em class="structfield"><code>linemask</code></em> array, etc. 279If no <em class="structfield"><code>linemask</code></em> array bits are set, then 280<em class="structfield"><code>line</code></em>[0] may contain one line of 281unspecified data that should be ignored by applications.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-mpeg-vbi-itv0-1"></a><p class="title"><b>Table 4.12. struct <span class="structname">v4l2_mpeg_vbi_ITV0</span> 282 </b></p><div class="table-contents"><table summary="struct v4l2_mpeg_vbi_ITV0 283 " width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-itv0-line" title="Table 4.13. struct v4l2_mpeg_vbi_itv0_line"> 284 <span class="structname">v4l2_mpeg_vbi_itv0_line</span></a> 285 </td><td valign="top"><em class="structfield"><code>line</code></em>[36]</td><td valign="top">A fixed length array of 36 lines of sliced VBI 286data. <em class="structfield"><code>line</code></em>[0] through <em class="structfield"><code>line 287</code></em>[17] correspond to lines 6 through 23 of the 288first field. <em class="structfield"><code>line</code></em>[18] through 289<em class="structfield"><code>line</code></em>[35] corresponds to lines 6 290through 23 of the second field.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="v4l2-mpeg-vbi-itv0-line"></a><p class="title"><b>Table 4.13. struct <span class="structname">v4l2_mpeg_vbi_itv0_line</span> 291 </b></p><div class="table-contents"><table summary="struct v4l2_mpeg_vbi_itv0_line 292 " width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><tbody valign="top"><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>id</code></em></td><td valign="top">A line identifier value from 293<a class="xref" href="sliced.html#ITV0-Line-Identifier-Constants" title="Table 4.14. Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field">Table 4.14, “Line Identifiers for struct <span class="structname"> 294v4l2_mpeg_vbi_itv0_line</span> <em class="structfield"><code>id 295</code></em> field”</a> that indicates 296the type of sliced VBI data stored on this line.</td></tr><tr><td valign="top">__u8</td><td valign="top"><em class="structfield"><code>data</code></em>[42]</td><td valign="top">The sliced VBI data for the line.</td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="ITV0-Line-Identifier-Constants"></a><p class="title"><b>Table 4.14. Line Identifiers for struct <a class="link" href="sliced.html#v4l2-mpeg-vbi-itv0-line" title="Table 4.13. struct v4l2_mpeg_vbi_itv0_line"><span class="structname"> 297v4l2_mpeg_vbi_itv0_line</span></a> <em class="structfield"><code>id 298</code></em> field</b></p><div class="table-contents"><table summary="Line Identifiers for struct 299v4l2_mpeg_vbi_itv0_line id 300 field" width="100%" border="0"><colgroup><col class="c1"><col class="c2"><col class="c3"></colgroup><thead><tr><th align="left">Defined Symbol</th><th align="left">Value</th><th align="left">Description</th></tr></thead><tbody valign="top"><tr><td valign="top"><code class="constant">V4L2_MPEG_VBI_IVTV_TELETEXT_B</code> 301 </td><td valign="top">1</td><td valign="top">Refer to <a class="link" href="sliced.html#vbi-services2" title="Table 4.7. Sliced VBI services"> 302Sliced VBI services</a> for a description of the line payload.</td></tr><tr><td valign="top"><code class="constant">V4L2_MPEG_VBI_IVTV_CAPTION_525</code> 303 </td><td valign="top">4</td><td valign="top">Refer to <a class="link" href="sliced.html#vbi-services2" title="Table 4.7. Sliced VBI services"> 304Sliced VBI services</a> for a description of the line payload.</td></tr><tr><td valign="top"><code class="constant">V4L2_MPEG_VBI_IVTV_WSS_625</code> 305 </td><td valign="top">5</td><td valign="top">Refer to <a class="link" href="sliced.html#vbi-services2" title="Table 4.7. Sliced VBI services"> 306Sliced VBI services</a> for a description of the line payload.</td></tr><tr><td valign="top"><code class="constant">V4L2_MPEG_VBI_IVTV_VPS</code> 307 </td><td valign="top">7</td><td valign="top">Refer to <a class="link" href="sliced.html#vbi-services2" title="Table 4.7. Sliced VBI services"> 308Sliced VBI services</a> for a description of the line payload.</td></tr></tbody></table></div></div><br class="table-break"></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="raw-vbi.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="devices.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ttx.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Raw VBI Data Interface </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Teletext Interface</td></tr></table></div></body></html> 309