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