← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-lowlatency/precise

« back to all changes in this revision

Viewing changes to Documentation/DocBook/media/v4l/dev-sliced-vbi.xml

  • Committer: Package Import Robot
  • Author(s): Alessio Igor Bogani
  • Date: 2011-10-26 11:13:05 UTC
  • Revision ID: package-import@ubuntu.com-20111026111305-tz023xykf0i6eosh
Tags: upstream-3.2.0
Import upstream version 3.2.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
Documentation/DocBook/media/v4l/dev-sliced-vbi.xml
 
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&nbsp;300&nbsp;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&nbsp;300&nbsp;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>
 
700
 
 
701
 
 
702
<!--
 
703
Local Variables:
 
704
mode: sgml
 
705
sgml-parent-document: "v4l2.sgml"
 
706
indent-tabs-mode: nil
 
707
End:
 
708
 -->