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.
 189 The <constant>V4L2_VBI_ITU_525_F1_START</constant>,
 190 <constant>V4L2_VBI_ITU_525_F2_START</constant>,
 191 <constant>V4L2_VBI_ITU_625_F1_START</constant> and
 192 <constant>V4L2_VBI_ITU_625_F2_START</constant> defines give the start
 193 line numbers for each field for each 525 or 625 line format as a
 194 convenience.  Don't forget that ITU line numbering starts at 1, not 0.
 195 </entry>
 196           </row>
 197           <row>
 198             <entry>__u32</entry>
 199             <entry><structfield>io_size</structfield></entry>
 200             <entry spanname="hspan">Maximum number of bytes passed by
 201 one &func-read; or &func-write; call, and the buffer size in bytes for
 202 the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to
 203 the size of &v4l2-sliced-vbi-data; times the number of non-zero
 204 elements in the returned <structfield>service_lines</structfield>
 205 array (that is the number of lines potentially carrying data).</entry>
 206           </row>
 207           <row>
 208             <entry>__u32</entry>
 209             <entry><structfield>reserved</structfield>[2]</entry>
 210             <entry spanname="hspan">This array is reserved for future
 211 extensions. Applications and drivers must set it to zero.</entry>
 212           </row>
 213         </tbody>
 214       </tgroup>
 215     </table>
 216
 217     <!-- See also vidioc-g-sliced-vbi-cap.sgml -->
 218     <table frame="none" pgwide="1" id="vbi-services2">
 219       <title>Sliced VBI services</title>
 220       <tgroup cols="5">
 221         <colspec colname="c1" colwidth="2*" />
 222         <colspec colname="c2" colwidth="1*" />
 223         <colspec colname="c3" colwidth="1*" />
 224         <colspec colname="c4" colwidth="2*" />
 225         <colspec colname="c5" colwidth="2*" />
 226         <spanspec namest="c3" nameend="c5" spanname="rlp" />
 227         <thead>
 228           <row>
 229             <entry>Symbol</entry>
 230             <entry>Value</entry>
 231             <entry>Reference</entry>
 232             <entry>Lines, usually</entry>
 233             <entry>Payload</entry>
 234           </row>
 235         </thead>
 236         <tbody valign="top">
 237           <row>
 238             <entry><constant>V4L2_SLICED_TELETEXT_B</constant>
 239 (Teletext System B)</entry>
 240             <entry>0x0001</entry>
 241             <entry><xref linkend="ets300706" />, <xref linkend="itu653" /></entry>
 242             <entry>PAL/SECAM line 7-22, 320-335 (second field 7-22)</entry>
 243             <entry>Last 42 of the 45 byte Teletext packet, that is
 244 without clock run-in and framing code, lsb first transmitted.</entry>
 245           </row>
 246           <row>
 247             <entry><constant>V4L2_SLICED_VPS</constant></entry>
 248             <entry>0x0400</entry>
 249             <entry><xref linkend="ets300231" /></entry>
 250             <entry>PAL line 16</entry>
 251             <entry>Byte number 3 to 15 according to Figure 9 of
 252 ETS&nbsp;300&nbsp;231, lsb first transmitted.</entry>
 253           </row>
 254           <row>
 255             <entry><constant>V4L2_SLICED_CAPTION_525</constant></entry>
 256             <entry>0x1000</entry>
 257             <entry><xref linkend="eia608" /></entry>
 258             <entry>NTSC line 21, 284 (second field 21)</entry>
 259             <entry>Two bytes in transmission order, including parity
 260 bit, lsb first transmitted.</entry>
 261           </row>
 262           <row>
 263             <entry><constant>V4L2_SLICED_WSS_625</constant></entry>
 264             <entry>0x4000</entry>
 265             <entry><xref linkend="itu1119" />, <xref linkend="en300294" /></entry>
 266             <entry>PAL/SECAM line 23</entry>
 267             <entry><screen>
 268 Byte         0                 1
 269       msb         lsb  msb           lsb
 270  Bit  7 6 5 4 3 2 1 0  x x 13 12 11 10 9
 271 </screen></entry>
 272           </row>
 273           <row>
 274             <entry><constant>V4L2_SLICED_VBI_525</constant></entry>
 275             <entry>0x1000</entry>
 276             <entry spanname="rlp">Set of services applicable to 525
 277 line systems.</entry>
 278           </row>
 279           <row>
 280             <entry><constant>V4L2_SLICED_VBI_625</constant></entry>
 281             <entry>0x4401</entry>
 282             <entry spanname="rlp">Set of services applicable to 625
 283 line systems.</entry>
 284           </row>
 285         </tbody>
 286       </tgroup>
 287     </table>
 288
 289     <para>Drivers may return an &EINVAL; when applications attempt to
 290 read or write data without prior format negotiation, after switching
 291 the video standard (which may invalidate the negotiated VBI
 292 parameters) and after switching the video input (which may change the
 293 video standard as a side effect). The &VIDIOC-S-FMT; ioctl may return
 294 an &EBUSY; when applications attempt to change the format while i/o is
 295 in progress (between a &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; call,
 296 and after the first &func-read; or &func-write; call).</para>
 297   </section>
 298
 299   <section>
 300     <title>Reading and writing sliced VBI data</title>
 301
 302     <para>A single &func-read; or &func-write; call must pass all data
 303 belonging to one video frame. That is an array of
 304 <structname>v4l2_sliced_vbi_data</structname> structures with one or
 305 more elements and a total size not exceeding
 306 <structfield>io_size</structfield> bytes. Likewise in streaming I/O
 307 mode one buffer of <structfield>io_size</structfield> bytes must
 308 contain data of one video frame. The <structfield>id</structfield> of
 309 unused <structname>v4l2_sliced_vbi_data</structname> elements must be
 310 zero.</para>
 311
 312     <table frame="none" pgwide="1" id="v4l2-sliced-vbi-data">
 313       <title>struct
 314 <structname>v4l2_sliced_vbi_data</structname></title>
 315       <tgroup cols="3">
 316         &cs-def;
 317         <tbody valign="top">
 318           <row>
 319             <entry>__u32</entry>
 320             <entry><structfield>id</structfield></entry>
 321             <entry>A flag from <xref linkend="vbi-services" />
 322 identifying the type of data in this packet. Only a single bit must be
 323 set. When the <structfield>id</structfield> of a captured packet is
 324 zero, the packet is empty and the contents of other fields are
 325 undefined. Applications shall ignore empty packets. When the
 326 <structfield>id</structfield> of a packet for output is zero the
 327 contents of the <structfield>data</structfield> field are undefined
 328 and the driver must no longer insert data on the requested
 329 <structfield>field</structfield> and
 330 <structfield>line</structfield>.</entry>
 331           </row>
 332           <row>
 333             <entry>__u32</entry>
 334             <entry><structfield>field</structfield></entry>
 335             <entry>The video field number this data has been captured
 336 from, or shall be inserted at. <constant>0</constant> for the first
 337 field, <constant>1</constant> for the second field.</entry>
 338           </row>
 339           <row>
 340             <entry>__u32</entry>
 341             <entry><structfield>line</structfield></entry>
 342             <entry>The field (as opposed to frame) line number this
 343 data has been captured from, or shall be inserted at. See <xref
 344             linkend="vbi-525" /> and <xref linkend="vbi-625" /> for valid
 345 values. Sliced VBI capture devices can set the line number of all
 346 packets to <constant>0</constant> if the hardware cannot reliably
 347 identify scan lines. The field number must always be valid.</entry>
 348           </row>
 349           <row>
 350             <entry>__u32</entry>
 351             <entry><structfield>reserved</structfield></entry>
 352             <entry>This field is reserved for future extensions.
 353 Applications and drivers must set it to zero.</entry>
 354           </row>
 355           <row>
 356             <entry>__u8</entry>
 357             <entry><structfield>data</structfield>[48]</entry>
 358             <entry>The packet payload. See <xref
 359             linkend="vbi-services" /> for the contents and number of
 360 bytes passed for each data type. The contents of padding bytes at the
 361 end of this array are undefined, drivers and applications shall ignore
 362 them.</entry>
 363           </row>
 364         </tbody>
 365       </tgroup>
 366     </table>
 367
 368     <para>Packets are always passed in ascending line number order,
 369 without duplicate line numbers. The &func-write; function and the
 370 &VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate
 371 this rule. They must also return an &EINVAL; when applications pass an
 372 incorrect field or line number, or a combination of
 373 <structfield>field</structfield>, <structfield>line</structfield> and
 374 <structfield>id</structfield> which has not been negotiated with the
 375 &VIDIOC-G-FMT; or &VIDIOC-S-FMT; ioctl. When the line numbers are
 376 unknown the driver must pass the packets in transmitted order. The
 377 driver can insert empty packets with <structfield>id</structfield> set
 378 to zero anywhere in the packet array.</para>
 379
 380     <para>To assure synchronization and to distinguish from frame
 381 dropping, when a captured frame does not carry any of the requested
 382 data services drivers must pass one or more empty packets. When an
 383 application fails to pass VBI data in time for output, the driver
 384 must output the last VPS and WSS packet again, and disable the output
 385 of Closed Caption and Teletext data, or output data which is ignored
 386 by Closed Caption and Teletext decoders.</para>
 387
 388     <para>A sliced VBI device may support <link
 389 linkend="rw">read/write</link> and/or streaming (<link
 390 linkend="mmap">memory mapping</link> and/or <link linkend="userp">user
 391 pointer</link>) I/O. The latter bears the possibility of synchronizing
 392 video and VBI data by using buffer timestamps.</para>
 393
 394   </section>
 395
 396   <section>
 397     <title>Sliced VBI Data in MPEG Streams</title>
 398
 399     <para>If a device can produce an MPEG output stream, it may be
 400 capable of providing <link
 401 linkend="sliced-vbi-format-negotitation">negotiated sliced VBI
 402 services</link> as data embedded in the MPEG stream.  Users or
 403 applications control this sliced VBI data insertion with the <link
 404 linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
 405 control.</para>
 406
 407     <para>If the driver does not provide the <link
 408 linkend="v4l2-mpeg-stream-vbi-fmt">V4L2_CID_MPEG_STREAM_VBI_FMT</link>
 409 control, or only allows that control to be set to <link
 410 linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
 411 V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link>, then the device
 412 cannot embed sliced VBI data in the MPEG stream.</para>
 413
 414     <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt">
 415 V4L2_CID_MPEG_STREAM_VBI_FMT</link> control does not implicitly set
 416 the device driver to capture nor cease capturing sliced VBI data.  The
 417 control only indicates to embed sliced VBI data in the MPEG stream, if
 418 an application has negotiated sliced VBI service be captured.</para>
 419
 420     <para>It may also be the case that a device can embed sliced VBI
 421 data in only certain types of MPEG streams: for example in an MPEG-2
 422 PS but not an MPEG-2 TS.  In this situation, if sliced VBI data
 423 insertion is requested, the sliced VBI data will be embedded in MPEG
 424 stream types when supported, and silently omitted from MPEG stream
 425 types where sliced VBI data insertion is not supported by the device.
 426 </para>
 427
 428     <para>The following subsections specify the format of the
 429 embedded sliced VBI data.</para>
 430
 431   <section>
 432     <title>MPEG Stream Embedded, Sliced VBI Data Format: NONE</title>
 433     <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
 434 V4L2_MPEG_STREAM_VBI_FMT_NONE</constant></link> embedded sliced VBI
 435 format shall be interpreted by drivers as a control to cease
 436 embedding sliced VBI data in MPEG streams.  Neither the device nor
 437 driver shall insert "empty" embedded sliced VBI data packets in the
 438 MPEG stream when this format is set.  No MPEG stream data structures
 439 are specified for this format.</para>
 440   </section>
 441
 442   <section>
 443     <title>MPEG Stream Embedded, Sliced VBI Data Format: IVTV</title>
 444     <para>The <link linkend="v4l2-mpeg-stream-vbi-fmt"><constant>
 445 V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> embedded sliced VBI
 446 format, when supported, indicates to the driver to embed up to 36
 447 lines of sliced VBI data per frame in an MPEG-2 <emphasis>Private
 448 Stream 1 PES</emphasis> packet encapsulated in an MPEG-2 <emphasis>
 449 Program Pack</emphasis> in the MPEG stream.</para>
 450
 451     <para><emphasis>Historical context</emphasis>: This format
 452 specification originates from a custom, embedded, sliced VBI data
 453 format used by the <filename>ivtv</filename> driver.  This format
 454 has already been informally specified in the kernel sources in the
 455 file <filename>Documentation/video4linux/cx2341x/README.vbi</filename>
 456 .  The maximum size of the payload and other aspects of this format
 457 are driven by the CX23415 MPEG decoder's capabilities and limitations
 458 with respect to extracting, decoding, and displaying sliced VBI data
 459 embedded within an MPEG stream.</para>
 460
 461     <para>This format's use is <emphasis>not</emphasis> exclusive to
 462 the <filename>ivtv</filename> driver <emphasis>nor</emphasis>
 463 exclusive to CX2341x devices, as the sliced VBI data packet insertion
 464 into the MPEG stream is implemented in driver software.  At least the
 465 <filename>cx18</filename> driver provides sliced VBI data insertion
 466 into an MPEG-2 PS in this format as well.</para>
 467
 468     <para>The following definitions specify the payload of the
 469 MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packets that contain
 470 sliced VBI data when <link linkend="v4l2-mpeg-stream-vbi-fmt">
 471 <constant>V4L2_MPEG_STREAM_VBI_FMT_IVTV</constant></link> is set.
 472 (The MPEG-2 <emphasis>Private Stream 1 PES</emphasis> packet header
 473 and encapsulating MPEG-2 <emphasis>Program Pack</emphasis> header are
 474 not detailed here.  Please refer to the MPEG-2 specifications for
 475 details on those packet headers.)</para>
 476
 477     <para>The payload of the MPEG-2 <emphasis>Private Stream 1 PES
 478 </emphasis> packets that contain sliced VBI data is specified by
 479 &v4l2-mpeg-vbi-fmt-ivtv;.  The payload is variable
 480 length, depending on the actual number of lines of sliced VBI data
 481 present in a video frame.  The payload may be padded at the end with
 482 unspecified fill bytes to align the end of the payload to a 4-byte
 483 boundary.  The payload shall never exceed 1552 bytes (2 fields with
 484 18 lines/field with 43 bytes of data/line and a 4 byte magic number).
 485 </para>
 486
 487     <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv">
 488       <title>struct <structname>v4l2_mpeg_vbi_fmt_ivtv</structname>
 489       </title>
 490       <tgroup cols="4">
 491         &cs-ustr;
 492         <tbody valign="top">
 493           <row>
 494             <entry>__u8</entry>
 495             <entry><structfield>magic</structfield>[4]</entry>
 496             <entry></entry>
 497             <entry>A "magic" constant from <xref
 498             linkend="v4l2-mpeg-vbi-fmt-ivtv-magic" /> that indicates
 499 this is a valid sliced VBI data payload and also indicates which
 500 member of the anonymous union, <structfield>itv0</structfield> or
 501 <structfield>ITV0</structfield>, to use for the payload data.</entry>
 502           </row>
 503           <row>
 504             <entry>union</entry>
 505             <entry>(anonymous)</entry>
 506           </row>
 507           <row>
 508             <entry></entry>
 509             <entry>struct <link linkend="v4l2-mpeg-vbi-itv0">
 510               <structname>v4l2_mpeg_vbi_itv0</structname></link>
 511             </entry>
 512             <entry><structfield>itv0</structfield></entry>
 513             <entry>The primary form of the sliced VBI data payload
 514 that contains anywhere from 1 to 35 lines of sliced VBI data.
 515 Line masks are provided in this form of the payload indicating
 516 which VBI lines are provided.</entry>
 517           </row>
 518           <row>
 519             <entry></entry>
 520             <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-1">
 521               <structname>v4l2_mpeg_vbi_ITV0</structname></link>
 522             </entry>
 523             <entry><structfield>ITV0</structfield></entry>
 524             <entry>An alternate form of the sliced VBI data payload
 525 used when 36 lines of sliced VBI data are present.  No line masks are
 526 provided in this form of the payload; all valid line mask bits are
 527 implcitly set.</entry>
 528           </row>
 529         </tbody>
 530       </tgroup>
 531     </table>
 532
 533     <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-fmt-ivtv-magic">
 534       <title>Magic Constants for &v4l2-mpeg-vbi-fmt-ivtv;
 535         <structfield>magic</structfield> field</title>
 536       <tgroup cols="3">
 537         &cs-def;
 538         <thead>
 539           <row>
 540             <entry align="left">Defined Symbol</entry>
 541             <entry align="left">Value</entry>
 542             <entry align="left">Description</entry>
 543           </row>
 544         </thead>
 545         <tbody valign="top">
 546           <row>
 547             <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC0</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.</entry>
 552           </row>
 553           <row>
 554             <entry><constant>V4L2_MPEG_VBI_IVTV_MAGIC1</constant>
 555             </entry>
 556             <entry>"ITV0"</entry>
 557             <entry>Indicates the <structfield>ITV0</structfield>
 558 member of the union in &v4l2-mpeg-vbi-fmt-ivtv; is valid and
 559 that 36 lines of sliced VBI data are present.</entry>
 560           </row>
 561         </tbody>
 562       </tgroup>
 563     </table>
 564
 565     <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0">
 566       <title>struct <structname>v4l2_mpeg_vbi_itv0</structname>
 567       </title>
 568       <tgroup cols="3">
 569         &cs-str;
 570         <tbody valign="top">
 571           <row>
 572             <entry>__le32</entry>
 573             <entry><structfield>linemask</structfield>[2]</entry>
 574             <entry><para>Bitmasks indicating the VBI service lines
 575 present.  These <structfield>linemask</structfield> values are stored
 576 in little endian byte order in the MPEG stream.  Some reference
 577 <structfield>linemask</structfield> bit positions with their
 578 corresponding VBI line number and video field are given below.
 579 b<subscript>0</subscript> indicates the least significant bit of a
 580 <structfield>linemask</structfield> value:<screen>
 581 <structfield>linemask</structfield>[0] b<subscript>0</subscript>:               line  6         first field
 582 <structfield>linemask</structfield>[0] b<subscript>17</subscript>:              line 23         first field
 583 <structfield>linemask</structfield>[0] b<subscript>18</subscript>:              line  6         second field
 584 <structfield>linemask</structfield>[0] b<subscript>31</subscript>:              line 19         second field
 585 <structfield>linemask</structfield>[1] b<subscript>0</subscript>:               line 20         second field
 586 <structfield>linemask</structfield>[1] b<subscript>3</subscript>:               line 23         second field
 587 <structfield>linemask</structfield>[1] b<subscript>4</subscript>-b<subscript>31</subscript>:    unused and set to 0</screen></para></entry>
 588           </row>
 589           <row>
 590             <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
 591               <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
 592             </entry>
 593             <entry><structfield>line</structfield>[35]</entry>
 594             <entry>This is a variable length array that holds from 1
 595 to 35 lines of sliced VBI data.  The sliced VBI data lines present
 596 correspond to the bits set in the <structfield>linemask</structfield>
 597 array, starting from b<subscript>0</subscript> of <structfield>
 598 linemask</structfield>[0] up through b<subscript>31</subscript> of
 599 <structfield>linemask</structfield>[0], and from b<subscript>0
 600 </subscript> of <structfield>linemask</structfield>[1] up through b
 601 <subscript>3</subscript> of <structfield>linemask</structfield>[1].
 602 <structfield>line</structfield>[0] corresponds to the first bit
 603 found set in the <structfield>linemask</structfield> array,
 604 <structfield>line</structfield>[1] corresponds to the second bit
 605 found set in the <structfield>linemask</structfield> array, etc.
 606 If no <structfield>linemask</structfield> array bits are set, then
 607 <structfield>line</structfield>[0] may contain one line of
 608 unspecified data that should be ignored by applications.</entry>
 609           </row>
 610         </tbody>
 611       </tgroup>
 612     </table>
 613
 614     <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-1">
 615       <title>struct <structname>v4l2_mpeg_vbi_ITV0</structname>
 616       </title>
 617       <tgroup cols="3">
 618         &cs-str;
 619         <tbody valign="top">
 620           <row>
 621             <entry>struct <link linkend="v4l2-mpeg-vbi-itv0-line">
 622               <structname>v4l2_mpeg_vbi_itv0_line</structname></link>
 623             </entry>
 624             <entry><structfield>line</structfield>[36]</entry>
 625             <entry>A fixed length array of 36 lines of sliced VBI
 626 data.  <structfield>line</structfield>[0] through <structfield>line
 627 </structfield>[17] correspond to lines 6 through 23 of the
 628 first field.  <structfield>line</structfield>[18] through
 629 <structfield>line</structfield>[35] corresponds to lines 6
 630 through 23 of the second field.</entry>
 631           </row>
 632         </tbody>
 633       </tgroup>
 634     </table>
 635
 636     <table frame="none" pgwide="1" id="v4l2-mpeg-vbi-itv0-line">
 637       <title>struct <structname>v4l2_mpeg_vbi_itv0_line</structname>
 638       </title>
 639       <tgroup cols="3">
 640         &cs-str;
 641         <tbody valign="top">
 642           <row>
 643             <entry>__u8</entry>
 644             <entry><structfield>id</structfield></entry>
 645             <entry>A line identifier value from
 646 <xref linkend="ITV0-Line-Identifier-Constants" /> that indicates
 647 the type of sliced VBI data stored on this line.</entry>
 648           </row>
 649           <row>
 650             <entry>__u8</entry>
 651             <entry><structfield>data</structfield>[42]</entry>
 652             <entry>The sliced VBI data for the line.</entry>
 653           </row>
 654         </tbody>
 655       </tgroup>
 656     </table>
 657
 658     <table frame="none" pgwide="1" id="ITV0-Line-Identifier-Constants">
 659       <title>Line Identifiers for struct <link
 660       linkend="v4l2-mpeg-vbi-itv0-line"><structname>
 661 v4l2_mpeg_vbi_itv0_line</structname></link> <structfield>id
 662 </structfield> field</title>
 663       <tgroup cols="3">
 664         &cs-def;
 665         <thead>
 666           <row>
 667             <entry align="left">Defined Symbol</entry>
 668             <entry align="left">Value</entry>
 669             <entry align="left">Description</entry>
 670           </row>
 671         </thead>
 672         <tbody valign="top">
 673           <row>
 674             <entry><constant>V4L2_MPEG_VBI_IVTV_TELETEXT_B</constant>
 675             </entry>
 676             <entry>1</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_CAPTION_525</constant>
 682             </entry>
 683             <entry>4</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_WSS_625</constant>
 689             </entry>
 690             <entry>5</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           <row>
 695             <entry><constant>V4L2_MPEG_VBI_IVTV_VPS</constant>
 696             </entry>
 697             <entry>7</entry>
 698             <entry>Refer to <link linkend="vbi-services2">
 699 Sliced VBI services</link> for a description of the line payload.</entry>
 700           </row>
 701         </tbody>
 702       </tgroup>
 703     </table>
 704
 705   </section>
 706   </section>