Commit | Line | Data |
---|---|---|
8e080c2e MCC |
1 | <title>Sliced VBI Data Interface</title> |
2 | ||
3 | <para>VBI stands for Vertical Blanking Interval, a gap in the | |
4 | sequence of lines of an analog video signal. During VBI no picture | |
5 | information is transmitted, allowing some time while the electron beam | |
6 | of a cathode ray tube TV returns to the top of the screen.</para> | |
7 | ||
8 | <para>Sliced VBI devices use hardware to demodulate data transmitted | |
9 | in the VBI. V4L2 drivers shall <emphasis>not</emphasis> do this by | |
10 | software, see also the <link linkend="raw-vbi">raw VBI | |
11 | interface</link>. The data is passed as short packets of fixed size, | |
12 | covering one scan line each. The number of packets per video frame is | |
13 | variable.</para> | |
14 | ||
15 | <para>Sliced VBI capture and output devices are accessed through the | |
16 | same character special files as raw VBI devices. When a driver | |
17 | supports both interfaces, the default function of a | |
18 | <filename>/dev/vbi</filename> device is <emphasis>raw</emphasis> VBI | |
19 | capturing or output, and the sliced VBI function is only available | |
20 | after calling the &VIDIOC-S-FMT; ioctl as defined below. Likewise a | |
21 | <filename>/dev/video</filename> device may support the sliced VBI API, | |
22 | however the default function here is video capturing or output. | |
23 | Different file descriptors must be used to pass raw and sliced VBI | |
24 | data simultaneously, if this is supported by the driver.</para> | |
25 | ||
26 | <section> | |
27 | <title>Querying Capabilities</title> | |
28 | ||
29 | <para>Devices supporting the sliced VBI capturing or output API | |
30 | set the <constant>V4L2_CAP_SLICED_VBI_CAPTURE</constant> or | |
31 | <constant>V4L2_CAP_SLICED_VBI_OUTPUT</constant> flag respectively, in | |
32 | the <structfield>capabilities</structfield> field of &v4l2-capability; | |
33 | returned by the &VIDIOC-QUERYCAP; ioctl. At least one of the | |
34 | read/write, streaming or asynchronous <link linkend="io">I/O | |
35 | methods</link> must be supported. Sliced VBI devices may have a tuner | |
36 | or modulator.</para> | |
37 | </section> | |
38 | ||
39 | <section> | |
40 | <title>Supplemental Functions</title> | |
41 | ||
42 | <para>Sliced VBI devices shall support <link linkend="video">video | |
43 | input or output</link> and <link linkend="tuner">tuner or | |
44 | modulator</link> ioctls if they have these capabilities, and they may | |
45 | support <link linkend="control">control</link> ioctls. The <link | |
46 | linkend="standard">video standard</link> ioctls provide information | |
47 | vital to program a sliced VBI device, therefore must be | |
48 | supported.</para> | |
49 | </section> | |
50 | ||
51 | <section id="sliced-vbi-format-negotitation"> | |
52 | <title>Sliced VBI Format Negotiation</title> | |
53 | ||
54 | <para>To find out which data services are supported by the | |
55 | hardware applications can call the &VIDIOC-G-SLICED-VBI-CAP; ioctl. | |
56 | All drivers implementing the sliced VBI interface must support this | |
57 | ioctl. The results may differ from those of the &VIDIOC-S-FMT; ioctl | |
58 | when the number of VBI lines the hardware can capture or output per | |
59 | frame, or the number of services it can identify on a given line are | |
60 | limited. For example on PAL line 16 the hardware may be able to look | |
61 | for a VPS or Teletext signal, but not both at the same time.</para> | |
62 | ||
63 | <para>To determine the currently selected services applications | |
64 | set the <structfield>type </structfield> field of &v4l2-format; to | |
65 | <constant> V4L2_BUF_TYPE_SLICED_VBI_CAPTURE</constant> or <constant> | |
66 | V4L2_BUF_TYPE_SLICED_VBI_OUTPUT</constant>, and the &VIDIOC-G-FMT; | |
67 | ioctl fills the <structfield>fmt.sliced</structfield> member, a | |
68 | &v4l2-sliced-vbi-format;.</para> | |
69 | ||
70 | <para>Applications can request different parameters by | |
71 | initializing or modifying the <structfield>fmt.sliced</structfield> | |
72 | member and calling the &VIDIOC-S-FMT; ioctl with a pointer to the | |
73 | <structname>v4l2_format</structname> structure.</para> | |
74 | ||
75 | <para>The sliced VBI API is more complicated than the raw VBI API | |
76 | because the hardware must be told which VBI service to expect on each | |
77 | scan line. Not all services may be supported by the hardware on all | |
78 | lines (this is especially true for VBI output where Teletext is often | |
79 | unsupported and other services can only be inserted in one specific | |
80 | line). In many cases, however, it is sufficient to just set the | |
81 | <structfield>service_set</structfield> field to the required services | |
82 | and let the driver fill the <structfield>service_lines</structfield> | |
83 | array according to hardware capabilities. Only if more precise control | |
84 | is needed should the programmer set the | |
85 | <structfield>service_lines</structfield> array explicitly.</para> | |
86 | ||
87 | <para>The &VIDIOC-S-FMT; ioctl modifies the parameters | |
88 | according to hardware capabilities. When the driver allocates | |
89 | resources at this point, it may return an &EBUSY; if the required | |
90 | resources are temporarily unavailable. Other resource allocation | |
91 | points which may return <errorcode>EBUSY</errorcode> can be the | |
92 | &VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and | |
93 | &func-select; call.</para> | |
94 | ||
95 | <table frame="none" pgwide="1" id="v4l2-sliced-vbi-format"> | |
96 | <title>struct | |
97 | <structname>v4l2_sliced_vbi_format</structname></title> | |
98 | <tgroup cols="5"> | |
99 | <colspec colname="c1" colwidth="3*" /> | |
100 | <colspec colname="c2" colwidth="3*" /> | |
101 | <colspec colname="c3" colwidth="2*" /> | |
102 | <colspec colname="c4" colwidth="2*" /> | |
103 | <colspec colname="c5" colwidth="2*" /> | |
104 | <spanspec namest="c3" nameend="c5" spanname="hspan" /> | |
105 | <tbody valign="top"> | |
106 | <row> | |
107 | <entry>__u32</entry> | |
108 | <entry><structfield>service_set</structfield></entry> | |
109 | <entry spanname="hspan"><para>If | |
110 | <structfield>service_set</structfield> is non-zero when passed with | |
111 | &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the | |
112 | <structfield>service_lines</structfield> array will be filled by the | |
113 | driver according to the services specified in this field. For example, | |
114 | if <structfield>service_set</structfield> is initialized with | |
115 | <constant>V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625</constant>, a | |
116 | driver for the cx25840 video decoder sets lines 7-22 of both | |
117 | fields<footnote><para>According to <link | |
118 | linkend="ets300706">ETS 300 706</link> lines 6-22 of the | |
119 | first field and lines 5-22 of the second field may carry Teletext | |
120 | data.</para></footnote> to <constant>V4L2_SLICED_TELETEXT_B</constant> | |
121 | and line 23 of the first field to | |
122 | <constant>V4L2_SLICED_WSS_625</constant>. If | |
123 | <structfield>service_set</structfield> is set to zero, then the values | |
124 | of <structfield>service_lines</structfield> will be used instead. | |
125 | </para><para>On return the driver sets this field to the union of all | |
126 | elements of the returned <structfield>service_lines</structfield> | |
127 | array. It may contain less services than requested, perhaps just one, | |
128 | if the hardware cannot handle more services simultaneously. It may be | |
129 | empty (zero) if none of the requested services are supported by the | |
130 | hardware.</para></entry> | |
131 | </row> | |
132 | <row> | |
133 | <entry>__u16</entry> | |
134 | <entry><structfield>service_lines</structfield>[2][24]</entry> | |
135 | <entry spanname="hspan"><para>Applications initialize this | |
136 | array with sets of data services the driver shall look for or insert | |
137 | on the respective scan line. Subject to hardware capabilities drivers | |
138 | return the requested set, a subset, which may be just a single | |
139 | service, or an empty set. When the hardware cannot handle multiple | |
140 | services on the same line the driver shall choose one. No assumptions | |
141 | can be made on which service the driver chooses.</para><para>Data | |
142 | services are defined in <xref linkend="vbi-services2" />. Array indices | |
143 | map to ITU-R line numbers (see also <xref linkend="vbi-525" /> and <xref | |
144 | linkend="vbi-625" />) as follows: <!-- No nested | |
145 | tables, sigh. --></para></entry> | |
146 | </row> | |
147 | <row> | |
148 | <entry></entry> | |
149 | <entry></entry> | |
150 | <entry>Element</entry> | |
151 | <entry>525 line systems</entry> | |
152 | <entry>625 line systems</entry> | |
153 | </row> | |
154 | <row> | |
155 | <entry></entry> | |
156 | <entry></entry> | |
157 | <entry><structfield>service_lines</structfield>[0][1]</entry> | |
158 | <entry align="center">1</entry> | |
159 | <entry align="center">1</entry> | |
160 | </row> | |
161 | <row> | |
162 | <entry></entry> | |
163 | <entry></entry> | |
164 | <entry><structfield>service_lines</structfield>[0][23]</entry> | |
165 | <entry align="center">23</entry> | |
166 | <entry align="center">23</entry> | |
167 | </row> | |
168 | <row> | |
169 | <entry></entry> | |
170 | <entry></entry> | |
171 | <entry><structfield>service_lines</structfield>[1][1]</entry> | |
172 | <entry align="center">264</entry> | |
173 | <entry align="center">314</entry> | |
174 | </row> | |
175 | <row> | |
176 | <entry></entry> | |
177 | <entry></entry> | |
178 | <entry><structfield>service_lines</structfield>[1][23]</entry> | |
179 | <entry align="center">286</entry> | |
180 | <entry align="center">336</entry> | |
181 | </row> | |
182 | <!-- End of line numbers table. --> | |
183 | <row> | |
184 | <entry></entry> | |
185 | <entry></entry> | |
186 | <entry spanname="hspan">Drivers must set | |
187 | <structfield>service_lines</structfield>[0][0] and | |
188 | <structfield>service_lines</structfield>[1][0] to zero.</entry> | |
189 | </row> | |
190 | <row> | |
191 | <entry>__u32</entry> | |
192 | <entry><structfield>io_size</structfield></entry> | |
193 | <entry spanname="hspan">Maximum number of bytes passed by | |
194 | one &func-read; or &func-write; call, and the buffer size in bytes for | |
195 | the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to | |
196 | the size of &v4l2-sliced-vbi-data; times the number of non-zero | |
197 | elements in the returned <structfield>service_lines</structfield> | |
198 | array (that is the number of lines potentially carrying data).</entry> | |
199 | </row> | |
200 | <row> | |
201 | <entry>__u32</entry> | |
202 | <entry><structfield>reserved</structfield>[2]</entry> | |
203 | <entry spanname="hspan">This array is reserved for future | |
204 | extensions. Applications and drivers must set it to zero.</entry> | |
205 | </row> | |
206 | </tbody> | |
207 | </tgroup> | |
208 | </table> | |
209 | ||
210 | <!-- See also vidioc-g-sliced-vbi-cap.sgml --> | |
211 | <table frame="none" pgwide="1" id="vbi-services2"> | |
212 | <title>Sliced VBI services</title> | |
213 | <tgroup cols="5"> | |
214 | <colspec colname="c1" colwidth="2*" /> | |
215 | <colspec colname="c2" colwidth="1*" /> | |
216 | <colspec colname="c3" colwidth="1*" /> | |
217 | <colspec colname="c4" colwidth="2*" /> | |
218 | <colspec colname="c5" colwidth="2*" /> | |
219 | <spanspec namest="c3" nameend="c5" spanname="rlp" /> | |
220 | <thead> | |
221 | <row> | |
222 | <entry>Symbol</entry> | |
223 | <entry>Value</entry> | |
224 | <entry>Reference</entry> | |
225 | <entry>Lines, usually</entry> | |
226 | <entry>Payload</entry> | |
227 | </row> | |
228 | </thead> | |
229 | <tbody valign="top"> | |
230 | <row> | |
231 | <entry><constant>V4L2_SLICED_TELETEXT_B</constant> | |
232 | (Teletext System B)</entry> | |
233 | <entry>0x0001</entry> | |
234 | <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry> | |
235 | <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry> | |
236 | <entry>Last 42 of the 45 byte Teletext packet, that is | |
237 | without clock run-in and framing code, lsb first transmitted.</entry> | |
238 | </row> | |
239 | <row> | |
240 | <entry><constant>V4L2_SLICED_VPS</constant></entry> | |
241 | <entry>0x0400</entry> | |
242 | <entry><xref linkend="ets300231" /></entry> | |
243 | <entry>PAL line 16</entry> | |
244 | <entry>Byte number 3 to 15 according to Figure 9 of | |
245 | ETS 300 231, lsb first transmitted.</entry> | |
246 | </row> | |
247 | <row> | |
248 | <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry> | |
249 | <entry>0x1000</entry> | |
250 | <entry><xref linkend="eia608" /></entry> | |
251 | <entry>NTSC line 21, 284 (second field 21)</entry> | |
252 | <entry>Two bytes in transmission order, including parity | |
253 | bit, lsb first transmitted.</entry> | |
254 | </row> | |
255 | <row> | |
256 | <entry><constant>V4L2_SLICED_WSS_625</constant></entry> | |
257 | <entry>0x4000</entry> | |
258 | <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry> | |
259 | <entry>PAL/SECAM line 23</entry> | |
260 | <entry><screen> | |
261 | Byte 0 1 | |
262 | msb lsb msb lsb | |
263 | Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 | |
264 | </screen></entry> | |
265 | </row> | |
266 | <row> | |
267 | <entry><constant>V4L2_SLICED_VBI_525</constant></entry> | |
268 | <entry>0x1000</entry> | |
269 | <entry spanname="rlp">Set of services applicable to 525 | |
270 | line systems.</entry> | |
271 | </row> | |
272 | <row> | |
273 | <entry><constant>V4L2_SLICED_VBI_625</constant></entry> | |
274 | <entry>0x4401</entry> | |
275 | <entry spanname="rlp">Set of services applicable to 625 | |
276 | line systems.</entry> | |
277 | </row> | |
278 | </tbody> | |
279 | </tgroup> | |
280 | </table> | |
281 | ||
282 | <para>Drivers may return an &EINVAL; when applications attempt to | |
283 | read or write data without prior format negotiation, after switching | |
284 | the video standard (which may invalidate the negotiated VBI | |
285 | parameters) and after switching the video input (which may change the | |
286 | video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return | |
287 | an &EBUSY; when applications attempt to change the format while i/o is | |
288 | in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call, | |
289 | and after the first &func-read; or &func-write; call).</para> | |
290 | </section> | |
291 | ||
292 | <section> | |
293 | <title>Reading and writing sliced VBI data</title> | |
294 | ||
295 | <para>A single &func-read; or &func-write; call must pass all data | |
296 | belonging to one video frame. That is an array of | |
297 | <structname>v4l2_sliced_vbi_data</structname> structures with one or | |
298 | more elements and a total size not exceeding | |
299 | <structfield>io_size</structfield> bytes. Likewise in streaming I/O | |
300 | mode one buffer of <structfield>io_size</structfield> bytes must | |
301 | contain data of one video frame. The <structfield>id</structfield> of | |
302 | unused <structname>v4l2_sliced_vbi_data</structname> elements must be | |
303 | zero.</para> | |
304 | ||
305 | <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data"> | |
306 | <title>struct | |
307 | <structname>v4l2_sliced_vbi_data</structname></title> | |
308 | <tgroup cols="3"> | |
309 | &cs-def; | |
310 | <tbody valign="top"> | |
311 | <row> | |
312 | <entry>__u32</entry> | |
313 | <entry><structfield>id</structfield></entry> | |
314 | <entry>A flag from <xref linkend="vbi-services" /> | |
315 | identifying the type of data in this packet. Only a single bit must be | |
316 | set. When the <structfield>id</structfield> of a captured packet is | |
317 | zero, the packet is empty and the contents of other fields are | |
318 | undefined. Applications shall ignore empty packets. When the | |
319 | <structfield>id</structfield> of a packet for output is zero the | |
320 | contents of the <structfield>data</structfield> field are undefined | |
321 | and the driver must no longer insert data on the requested | |
322 | <structfield>field</structfield> and | |
323 | <structfield>line</structfield>.</entry> | |
324 | </row> | |
325 | <row> | |
326 | <entry>__u32</entry> | |
327 | <entry><structfield>field</structfield></entry> | |
328 | <entry>The video field number this data has been captured | |
329 | from, or shall be inserted at. <constant>0</constant> for the first | |
330 | field, <constant>1</constant> for the second field.</entry> | |
331 | </row> | |
332 | <row> | |
333 | <entry>__u32</entry> | |
334 | <entry><structfield>line</structfield></entry> | |
335 | <entry>The field (as opposed to frame) line number this | |
336 | data has been captured from, or shall be inserted at. See <xref | |
337 | linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid | |
338 | values. Sliced VBI capture devices can set the line number of all | |
339 | packets to <constant>0</constant> if the hardware cannot reliably | |
340 | identify scan lines. The field number must always be valid.</entry> | |
341 | </row> | |
342 | <row> | |
343 | <entry>__u32</entry> | |
344 | <entry><structfield>reserved</structfield></entry> | |
345 | <entry>This field is reserved for future extensions. | |
346 | Applications and drivers must set it to zero.</entry> | |
347 | </row> | |
348 | <row> | |
349 | <entry>__u8</entry> | |
350 | <entry><structfield>data</structfield>[48]</entry> | |
351 | <entry>The packet payload. See <xref | |
352 | linkend="vbi-services" /> for the contents and number of | |
353 | bytes passed for each data type. The contents of padding bytes at the | |
354 | end of this array are undefined, drivers and applications shall ignore | |
355 | them.</entry> | |
356 | </row> | |
357 | </tbody> | |
358 | </tgroup> | |
359 | </table> | |
360 | ||
361 | <para>Packets are always passed in ascending line number order, | |
362 | without duplicate line numbers. The &func-write; function and the | |
363 | &VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate | |
364 | this rule. They must also return an &EINVAL; when applications pass an | |
365 | incorrect field or line number, or a combination of | |
366 | <structfield>field</structfield>, <structfield>line</structfield> and | |
367 | <structfield>id</structfield> which has not been negotiated with the | |
368 | &VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are | |
369 | unknown the driver must pass the packets in transmitted order. The | |
370 | driver can insert empty packets with <structfield>id</structfield> set | |
371 | to zero anywhere in the packet array.</para> | |
372 | ||
373 | <para>To assure synchronization and to distinguish from frame | |
374 | dropping, when a captured frame does not carry any of the requested | |
375 | data services drivers must pass one or more empty packets. When an | |
376 | application fails to pass VBI data in time for output, the driver | |
377 | must output the last VPS and WSS packet again, and disable the output | |
378 | of Closed Caption and Teletext data, or output data which is ignored | |
379 | by Closed Caption and Teletext decoders.</para> | |
380 | ||
381 | <para>A sliced VBI device may support <link | |
382 | linkend="rw">read/write</link> and/or streaming (<link | |
383 | linkend="mmap">memory mapping</link> and/or <link linkend="userp">user | |
384 | pointer</link>) I/O. The latter bears the possibility of synchronizing | |
385 | video and VBI data by using buffer timestamps.</para> | |
386 | ||
387 | </section> | |
388 | ||
389 | <section> | |
390 | <title>Sliced VBI Data in MPEG Streams</title> | |
391 | ||
392 | <para>If a device can produce an MPEG output stream, it may be | |
393 | capable of providing <link | |
394 | linkend="sliced-vbi-format-negotitation">negotiated sliced VBI | |
395 | services</link> as data embedded in the MPEG stream. Users or | |
396 | applications control this sliced VBI data insertion with the <link | |
397 | linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> | |
398 | control.</para> | |
399 | ||
400 | <para>If the driver does not provide the <link | |
401 | linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link> | |
402 | control, or only allows that control to be set to <link | |
403 | linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | |
404 | V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device | |
405 | cannot embed sliced VBI data in the MPEG stream.</para> | |
406 | ||
407 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"> | |
408 | V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set | |
409 | the device driver to capture nor cease capturing sliced VBI data. The | |
410 | control only indicates to embed sliced VBI data in the MPEG stream, if | |
411 | an application has negotiated sliced VBI service be captured.</para> | |
412 | ||
413 | <para>It may also be the case that a device can embed sliced VBI | |
414 | data in only certain types of MPEG streams: for example in an MPEG-2 | |
415 | PS but not an MPEG-2 TS. In this situation, if sliced VBI data | |
416 | insertion is requested, the sliced VBI data will be embedded in MPEG | |
417 | stream types when supported, and silently omitted from MPEG stream | |
418 | types where sliced VBI data insertion is not supported by the device. | |
419 | </para> | |
420 | ||
421 | <para>The following subsections specify the format of the | |
422 | embedded sliced VBI data.</para> | |
423 | ||
424 | <section> | |
425 | <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title> | |
426 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | |
427 | V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI | |
428 | format shall be interpreted by drivers as a control to cease | |
429 | embedding sliced VBI data in MPEG streams. Neither the device nor | |
430 | driver shall insert "empty" embedded sliced VBI data packets in the | |
431 | MPEG stream when this format is set. No MPEG stream data structures | |
432 | are specified for this format.</para> | |
433 | </section> | |
434 | ||
435 | <section> | |
436 | <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title> | |
437 | <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant> | |
438 | V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI | |
439 | format, when supported, indicates to the driver to embed up to 36 | |
440 | lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private | |
441 | Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis> | |
442 | Program Pack</emphasis> in the MPEG stream.</para> | |
443 | ||
444 | <para><emphasis>Historical context</emphasis>: This format | |
445 | specification originates from a custom, embedded, sliced VBI data | |
446 | format used by the <filename>ivtv</filename> driver. This format | |
447 | has already been informally specified in the kernel sources in the | |
448 | file <filename>Documentation/video4linux/cx2341x/README.vbi</filename> | |
449 | . The maximum size of the payload and other aspects of this format | |
450 | are driven by the CX23415 MPEG decoder's capabilities and limitations | |
451 | with respect to extracting, decoding, and displaying sliced VBI data | |
452 | embedded within an MPEG stream.</para> | |
453 | ||
454 | <para>This format's use is <emphasis>not</emphasis> exclusive to | |
455 | the <filename>ivtv</filename> driver <emphasis>nor</emphasis> | |
456 | exclusive to CX2341x devices, as the sliced VBI data packet insertion | |
457 | into the MPEG stream is implemented in driver software. At least the | |
458 | <filename>cx18</filename> driver provides sliced VBI data insertion | |
459 | into an MPEG-2 PS in this format as well.</para> | |
460 | ||
461 | <para>The following definitions specify the payload of the | |
462 | MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain | |
463 | sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt"> | |
464 | <constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set. | |
465 | (The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header | |
466 | and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are | |
467 | not detailed here. Please refer to the MPEG-2 specifications for | |
468 | details on those packet headers.)</para> | |
469 | ||
470 | <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES | |
471 | </emphasis> packets that contain sliced VBI data is specified by | |
472 | &v4l2-mpeg-vbi-fmt-ivtv;. The payload is variable | |
473 | length, depending on the actual number of lines of sliced VBI data | |
474 | present in a video frame. The payload may be padded at the end with | |
475 | unspecified fill bytes to align the end of the payload to a 4-byte | |
476 | boundary. The payload shall never exceed 1552 bytes (2 fields with | |
477 | 18 lines/field with 43 bytes of data/line and a 4 byte magic number). | |
478 | </para> | |
479 | ||
480 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv"> | |
481 | <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname> | |
482 | </title> | |
483 | <tgroup cols="4"> | |
484 | &cs-ustr; | |
485 | <tbody valign="top"> | |
486 | <row> | |
487 | <entry>__u8</entry> | |
488 | <entry><structfield>magic</structfield>[4]</entry> | |
489 | <entry></entry> | |
490 | <entry>A "magic" constant from <xref | |
491 | linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates | |
492 | this is a valid sliced VBI data payload and also indicates which | |
493 | member of the anonymous union, <structfield>itv0</structfield> or | |
494 | <structfield>ITV0</structfield>, to use for the payload data.</entry> | |
495 | </row> | |
496 | <row> | |
497 | <entry>union</entry> | |
498 | <entry>(anonymous)</entry> | |
499 | </row> | |
500 | <row> | |
501 | <entry></entry> | |
502 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0"> | |
503 | <structname>v4l2_mpeg_vbi_itv0</structname></link> | |
504 | </entry> | |
505 | <entry><structfield>itv0</structfield></entry> | |
506 | <entry>The primary form of the sliced VBI data payload | |
507 | that contains anywhere from 1 to 35 lines of sliced VBI data. | |
508 | Line masks are provided in this form of the payload indicating | |
509 | which VBI lines are provided.</entry> | |
510 | </row> | |
511 | <row> | |
512 | <entry></entry> | |
513 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1"> | |
514 | <structname>v4l2_mpeg_vbi_ITV0</structname></link> | |
515 | </entry> | |
516 | <entry><structfield>ITV0</structfield></entry> | |
517 | <entry>An alternate form of the sliced VBI data payload | |
518 | used when 36 lines of sliced VBI data are present. No line masks are | |
519 | provided in this form of the payload; all valid line mask bits are | |
520 | implcitly set.</entry> | |
521 | </row> | |
522 | </tbody> | |
523 | </tgroup> | |
524 | </table> | |
525 | ||
526 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic"> | |
527 | <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv; | |
528 | <structfield>magic</structfield> field</title> | |
529 | <tgroup cols="3"> | |
530 | &cs-def; | |
531 | <thead> | |
532 | <row> | |
533 | <entry align="left">Defined Symbol</entry> | |
534 | <entry align="left">Value</entry> | |
535 | <entry align="left">Description</entry> | |
536 | </row> | |
537 | </thead> | |
538 | <tbody valign="top"> | |
539 | <row> | |
540 | <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</constant> | |
541 | </entry> | |
542 | <entry>"itv0"</entry> | |
543 | <entry>Indicates the <structfield>itv0</structfield> | |
544 | member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid.</entry> | |
545 | </row> | |
546 | <row> | |
547 | <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant> | |
548 | </entry> | |
549 | <entry>"ITV0"</entry> | |
550 | <entry>Indicates the <structfield>ITV0</structfield> | |
551 | member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and | |
552 | that 36 lines of sliced VBI data are present.</entry> | |
553 | </row> | |
554 | </tbody> | |
555 | </tgroup> | |
556 | </table> | |
557 | ||
558 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0"> | |
559 | <title>struct <structname>v4l2_mpeg_vbi_itv0</structname> | |
560 | </title> | |
561 | <tgroup cols="3"> | |
562 | &cs-str; | |
563 | <tbody valign="top"> | |
564 | <row> | |
565 | <entry>__le32</entry> | |
566 | <entry><structfield>linemask</structfield>[2]</entry> | |
567 | <entry><para>Bitmasks indicating the VBI service lines | |
568 | present. These <structfield>linemask</structfield> values are stored | |
569 | in little endian byte order in the MPEG stream. Some reference | |
570 | <structfield>linemask</structfield> bit positions with their | |
571 | corresponding VBI line number and video field are given below. | |
572 | b<subscript>0</subscript> indicates the least significant bit of a | |
573 | <structfield>linemask</structfield> value:<screen> | |
574 | <structfield>linemask</structfield>[0] b<subscript>0</subscript>: line 6 first field | |
575 | <structfield>linemask</structfield>[0] b<subscript>17</subscript>: line 23 first field | |
576 | <structfield>linemask</structfield>[0] b<subscript>18</subscript>: line 6 second field | |
577 | <structfield>linemask</structfield>[0] b<subscript>31</subscript>: line 19 second field | |
578 | <structfield>linemask</structfield>[1] b<subscript>0</subscript>: line 20 second field | |
579 | <structfield>linemask</structfield>[1] b<subscript>3</subscript>: line 23 second field | |
580 | <structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>: unused and set to 0</screen></para></entry> | |
581 | </row> | |
582 | <row> | |
583 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> | |
584 | <structname>v4l2_mpeg_vbi_itv0_line</structname></link> | |
585 | </entry> | |
586 | <entry><structfield>line</structfield>[35]</entry> | |
587 | <entry>This is a variable length array that holds from 1 | |
588 | to 35 lines of sliced VBI data. The sliced VBI data lines present | |
589 | correspond to the bits set in the <structfield>linemask</structfield> | |
590 | array, starting from b<subscript>0</subscript> of <structfield> | |
591 | linemask</structfield>[0] up through b<subscript>31</subscript> of | |
592 | <structfield>linemask</structfield>[0], and from b<subscript>0 | |
593 | </subscript> of <structfield>linemask</structfield>[1] up through b | |
594 | <subscript>3</subscript> of <structfield>linemask</structfield>[1]. | |
595 | <structfield>line</structfield>[0] corresponds to the first bit | |
596 | found set in the <structfield>linemask</structfield> array, | |
597 | <structfield>line</structfield>[1] corresponds to the second bit | |
598 | found set in the <structfield>linemask</structfield> array, etc. | |
599 | If no <structfield>linemask</structfield> array bits are set, then | |
600 | <structfield>line</structfield>[0] may contain one line of | |
601 | unspecified data that should be ignored by applications.</entry> | |
602 | </row> | |
603 | </tbody> | |
604 | </tgroup> | |
605 | </table> | |
606 | ||
607 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1"> | |
608 | <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname> | |
609 | </title> | |
610 | <tgroup cols="3"> | |
611 | &cs-str; | |
612 | <tbody valign="top"> | |
613 | <row> | |
614 | <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line"> | |
615 | <structname>v4l2_mpeg_vbi_itv0_line</structname></link> | |
616 | </entry> | |
617 | <entry><structfield>line</structfield>[36]</entry> | |
618 | <entry>A fixed length array of 36 lines of sliced VBI | |
619 | data. <structfield>line</structfield>[0] through <structfield>line | |
620 | </structfield>[17] correspond to lines 6 through 23 of the | |
621 | first field. <structfield>line</structfield>[18] through | |
622 | <structfield>line</structfield>[35] corresponds to lines 6 | |
623 | through 23 of the second field.</entry> | |
624 | </row> | |
625 | </tbody> | |
626 | </tgroup> | |
627 | </table> | |
628 | ||
629 | <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line"> | |
630 | <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname> | |
631 | </title> | |
632 | <tgroup cols="3"> | |
633 | &cs-str; | |
634 | <tbody valign="top"> | |
635 | <row> | |
636 | <entry>__u8</entry> | |
637 | <entry><structfield>id</structfield></entry> | |
638 | <entry>A line identifier value from | |
639 | <xref linkend="ITV0-Line-Identifier-Constants" /> that indicates | |
640 | the type of sliced VBI data stored on this line.</entry> | |
641 | </row> | |
642 | <row> | |
643 | <entry>__u8</entry> | |
644 | <entry><structfield>data</structfield>[42]</entry> | |
645 | <entry>The sliced VBI data for the line.</entry> | |
646 | </row> | |
647 | </tbody> | |
648 | </tgroup> | |
649 | </table> | |
650 | ||
651 | <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants"> | |
652 | <title>Line Identifiers for struct <link | |
653 | linkend="v4l2-mpeg-vbi-itv0-line"><structname> | |
654 | v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id | |
655 | </structfield> field</title> | |
656 | <tgroup cols="3"> | |
657 | &cs-def; | |
658 | <thead> | |
659 | <row> | |
660 | <entry align="left">Defined Symbol</entry> | |
661 | <entry align="left">Value</entry> | |
662 | <entry align="left">Description</entry> | |
663 | </row> | |
664 | </thead> | |
665 | <tbody valign="top"> | |
666 | <row> | |
667 | <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant> | |
668 | </entry> | |
669 | <entry>1</entry> | |
670 | <entry>Refer to <link linkend="vbi-services2"> | |
671 | Sliced VBI services</link> for a description of the line payload.</entry> | |
672 | </row> | |
673 | <row> | |
674 | <entry><constant>V4L2_MPEG_VBI_IVTV_CAPTION_525</constant> | |
675 | </entry> | |
676 | <entry>4</entry> | |
677 | <entry>Refer to <link linkend="vbi-services2"> | |
678 | Sliced VBI services</link> for a description of the line payload.</entry> | |
679 | </row> | |
680 | <row> | |
681 | <entry><constant>V4L2_MPEG_VBI_IVTV_WSS_625</constant> | |
682 | </entry> | |
683 | <entry>5</entry> | |
684 | <entry>Refer to <link linkend="vbi-services2"> | |
685 | Sliced VBI services</link> for a description of the line payload.</entry> | |
686 | </row> | |
687 | <row> | |
688 | <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant> | |
689 | </entry> | |
690 | <entry>7</entry> | |
691 | <entry>Refer to <link linkend="vbi-services2"> | |
692 | Sliced VBI services</link> for a description of the line payload.</entry> | |
693 | </row> | |
694 | </tbody> | |
695 | </tgroup> | |
696 | </table> | |
697 | ||
698 | </section> | |
699 | </section> |