summaryrefslogtreecommitdiffstats
path: root/Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst
blob: 42cdb0a9f786066a2d4b8ebc2c72a9318dabebf5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _sliced:

*************************
Sliced VBI Data Interface
*************************

VBI stands for Vertical Blanking Interval, a gap in the sequence of
lines of an analog video signal. During VBI no picture information is
transmitted, allowing some time while the electron beam of a cathode ray
tube TV returns to the top of the screen.

Sliced VBI devices use hardware to demodulate data transmitted in the
VBI. V4L2 drivers shall *not* do this by software, see also the
:ref:`raw VBI interface <raw-vbi>`. The data is passed as short
packets of fixed size, covering one scan line each. The number of
packets per video frame is variable.

Sliced VBI capture and output devices are accessed through the same
character special files as raw VBI devices. When a driver supports both
interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI
capturing or output, and the sliced VBI function is only available after
calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as defined
below. Likewise a ``/dev/video`` device may support the sliced VBI API,
however the default function here is video capturing or output.
Different file descriptors must be used to pass raw and sliced VBI data
simultaneously, if this is supported by the driver.

Querying Capabilities
=====================

Devices supporting the sliced VBI capturing or output API set the
``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag
respectively, in the ``capabilities`` field of struct
:c:type:`v4l2_capability` returned by the
:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
read/write or streaming :ref:`I/O methods <io>` must be
supported. Sliced VBI devices may have a tuner or modulator.

Supplemental Functions
======================

Sliced VBI devices shall support :ref:`video input or output <video>`
and :ref:`tuner or modulator <tuner>` ioctls if they have these
capabilities, and they may support :ref:`control` ioctls.
The :ref:`video standard <standard>` ioctls provide information vital
to program a sliced VBI device, therefore must be supported.

.. _sliced-vbi-format-negotitation:

Sliced VBI Format Negotiation
=============================

To find out which data services are supported by the hardware
applications can call the
:ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl.
All drivers implementing the sliced VBI interface must support this
ioctl. The results may differ from those of the
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl when the number of VBI
lines the hardware can capture or output per frame, or the number of
services it can identify on a given line are limited. For example on PAL
line 16 the hardware may be able to look for a VPS or Teletext signal,
but not both at the same time.

To determine the currently selected services applications set the
``type`` field of struct :c:type:`v4l2_format` to
``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl fills the ``fmt.sliced``
member, a struct
:c:type:`v4l2_sliced_vbi_format`.

Applications can request different parameters by initializing or
modifying the ``fmt.sliced`` member and calling the
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with a pointer to the
struct :c:type:`v4l2_format` structure.

The sliced VBI API is more complicated than the raw VBI API because the
hardware must be told which VBI service to expect on each scan line. Not
all services may be supported by the hardware on all lines (this is
especially true for VBI output where Teletext is often unsupported and
other services can only be inserted in one specific line). In many
cases, however, it is sufficient to just set the ``service_set`` field
to the required services and let the driver fill the ``service_lines``
array according to hardware capabilities. Only if more precise control
is needed should the programmer set the ``service_lines`` array
explicitly.

The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl modifies the parameters
according to hardware capabilities. When the driver allocates resources
at this point, it may return an ``EBUSY`` error code if the required
resources are temporarily unavailable. Other resource allocation points
which may return ``EBUSY`` can be the
:ref:`VIDIOC_STREAMON` ioctl and the first
:c:func:`read()`, :c:func:`write()` and
:c:func:`select()` call.

.. c:type:: v4l2_sliced_vbi_format

struct v4l2_sliced_vbi_format
-----------------------------

.. raw:: latex

    \begingroup
    \scriptsize
    \setlength{\tabcolsep}{2pt}

.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.45cm}|p{4.45cm}|p{4.45cm}|

.. cssclass:: longtable

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 3 2 2 2

    * - __u16
      - ``service_set``
      - :cspan:`2`

	If ``service_set`` is non-zero when passed with
	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
	:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines``
	array will be filled by the driver according to the services
	specified in this field. For example, if ``service_set`` is
	initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``,
	a driver for the cx25840 video decoder sets lines 7-22 of both
	fields [#f1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first
	field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to
	zero, then the values of ``service_lines`` will be used instead.

	On return the driver sets this field to the union of all elements
	of the returned ``service_lines`` array. It may contain less
	services than requested, perhaps just one, if the hardware cannot
	handle more services simultaneously. It may be empty (zero) if
	none of the requested services are supported by the hardware.
    * - __u16
      - ``service_lines``\ [2][24]
      - :cspan:`2`

	Applications initialize this array with sets of data services the
	driver shall look for or insert on the respective scan line.
	Subject to hardware capabilities drivers return the requested set,
	a subset, which may be just a single service, or an empty set.
	When the hardware cannot handle multiple services on the same line
	the driver shall choose one. No assumptions can be made on which
	service the driver chooses.

	Data services are defined in :ref:`vbi-services2`. Array indices
	map to ITU-R line numbers\ [#f2]_ as follows:
    * -
      -
      - Element
      - 525 line systems
      - 625 line systems
    * -
      -
      - ``service_lines``\ [0][1]
      - 1
      - 1
    * -
      -
      - ``service_lines``\ [0][23]
      - 23
      - 23
    * -
      -
      - ``service_lines``\ [1][1]
      - 264
      - 314
    * -
      -
      - ``service_lines``\ [1][23]
      - 286
      - 336
    * -
      -
      - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
	``service_lines``\ [1][0] to zero. The
	``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``,
	``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START``
	defines give the start line numbers for each field for each 525 or
	625 line format as a convenience. Don't forget that ITU line
	numbering starts at 1, not 0.
    * - __u32
      - ``io_size``
      - :cspan:`2` Maximum number of bytes passed by one
	:c:func:`read()` or :c:func:`write()` call,
	and the buffer size in bytes for the
	:ref:`VIDIOC_QBUF` and
	:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field
	to the size of struct
	:c:type:`v4l2_sliced_vbi_data` times the
	number of non-zero elements in the returned ``service_lines``
	array (that is the number of lines potentially carrying data).
    * - __u32
      - ``reserved``\ [2]
      - :cspan:`2` This array is reserved for future extensions.

	Applications and drivers must set it to zero.

.. raw:: latex

    \endgroup

.. _vbi-services2:

Sliced VBI services
-------------------

.. raw:: latex

    \footnotesize

.. tabularcolumns:: |p{4.2cm}|p{1.1cm}|p{2.1cm}|p{2.0cm}|p{6.5cm}|

.. flat-table::
    :header-rows:  1
    :stub-columns: 0
    :widths:       2 1 1 2 2

    * - Symbol
      - Value
      - Reference
      - Lines, usually
      - Payload
    * - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
      - 0x0001
      - :ref:`ets300706`,

	:ref:`itu653`
      - PAL/SECAM line 7-22, 320-335 (second field 7-22)
      - Last 42 of the 45 byte Teletext packet, that is without clock
	run-in and framing code, lsb first transmitted.
    * - ``V4L2_SLICED_VPS``
      - 0x0400
      - :ref:`ets300231`
      - PAL line 16
      - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
	first transmitted.
    * - ``V4L2_SLICED_CAPTION_525``
      - 0x1000
      - :ref:`cea608`
      - NTSC line 21, 284 (second field 21)
      - Two bytes in transmission order, including parity bit, lsb first
	transmitted.
    * - ``V4L2_SLICED_WSS_625``
      - 0x4000
      - :ref:`itu1119`,

	:ref:`en300294`
      - PAL/SECAM line 23
      -  See :ref:`v4l2-sliced-wss-625-payload` below.
    * - ``V4L2_SLICED_VBI_525``
      - 0x1000
      - :cspan:`2` Set of services applicable to 525 line systems.
    * - ``V4L2_SLICED_VBI_625``
      - 0x4401
      - :cspan:`2` Set of services applicable to 625 line systems.

.. raw:: latex

    \normalsize

Drivers may return an ``EINVAL`` error code when applications attempt to
read or write data without prior format negotiation, after switching the
video standard (which may invalidate the negotiated VBI parameters) and
after switching the video input (which may change the video standard as
a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may
return an ``EBUSY`` error code when applications attempt to change the
format while i/o is in progress (between a
:ref:`VIDIOC_STREAMON` and
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first
:c:func:`read()` or :c:func:`write()` call).

.. _v4l2-sliced-wss-625-payload:

V4L2_SLICED_WSS_625 payload
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The payload for ``V4L2_SLICED_WSS_625`` is:

           +-----+------------------+-----------------------+
	   |Byte |        0         |           1           |
           +-----+--------+---------+-----------+-----------+
	   |     | msb    | lsb     | msb       | lsb       |
           |     +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+
	   | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 |
           +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+

Reading and writing sliced VBI data
===================================

A single :c:func:`read()` or :c:func:`write()`
call must pass all data belonging to one video frame. That is an array
of struct :c:type:`v4l2_sliced_vbi_data` structures with one or
more elements and a total size not exceeding ``io_size`` bytes. Likewise
in streaming I/O mode one buffer of ``io_size`` bytes must contain data
of one video frame. The ``id`` of unused
struct :c:type:`v4l2_sliced_vbi_data` elements must be zero.

.. c:type:: v4l2_sliced_vbi_data

struct v4l2_sliced_vbi_data
---------------------------

.. tabularcolumns:: |p{1.2cm}|p{2.2cm}|p{13.9cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - __u32
      - ``id``
      - A flag from :ref:`vbi-services` identifying the type of data in
	this packet. Only a single bit must be set. When the ``id`` of a
	captured packet is zero, the packet is empty and the contents of
	other fields are undefined. Applications shall ignore empty
	packets. When the ``id`` of a packet for output is zero the
	contents of the ``data`` field are undefined and the driver must
	no longer insert data on the requested ``field`` and ``line``.
    * - __u32
      - ``field``
      - The video field number this data has been captured from, or shall
	be inserted at. ``0`` for the first field, ``1`` for the second
	field.
    * - __u32
      - ``line``
      - The field (as opposed to frame) line number this data has been
	captured from, or shall be inserted at. See :ref:`vbi-525` and
	:ref:`vbi-625` for valid values. Sliced VBI capture devices can
	set the line number of all packets to ``0`` if the hardware cannot
	reliably identify scan lines. The field number must always be
	valid.
    * - __u32
      - ``reserved``
      - This field is reserved for future extensions. Applications and
	drivers must set it to zero.
    * - __u8
      - ``data``\ [48]
      - The packet payload. See :ref:`vbi-services` for the contents and
	number of bytes passed for each data type. The contents of padding
	bytes at the end of this array are undefined, drivers and
	applications shall ignore them.

Packets are always passed in ascending line number order, without
duplicate line numbers. The :c:func:`write()` function and
the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL``
error code when applications violate this rule. They must also return an
EINVAL error code when applications pass an incorrect field or line
number, or a combination of ``field``, ``line`` and ``id`` which has not
been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are
unknown the driver must pass the packets in transmitted order. The
driver can insert empty packets with ``id`` set to zero anywhere in the
packet array.

To assure synchronization and to distinguish from frame dropping, when a
captured frame does not carry any of the requested data services drivers
must pass one or more empty packets. When an application fails to pass
VBI data in time for output, the driver must output the last VPS and WSS
packet again, and disable the output of Closed Caption and Teletext
data, or output data which is ignored by Closed Caption and Teletext
decoders.

A sliced VBI device may support :ref:`read/write <rw>` and/or
streaming (:ref:`memory mapping <mmap>` and/or
:ref:`user pointer <userp>`) I/O. The latter bears the possibility of
synchronizing video and VBI data by using buffer timestamps.

Sliced VBI Data in MPEG Streams
===============================

If a device can produce an MPEG output stream, it may be capable of
providing
:ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>`
as data embedded in the MPEG stream. Users or applications control this
sliced VBI data insertion with the
:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
control.

If the driver does not provide the
:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
control, or only allows that control to be set to
:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`,
then the device cannot embed sliced VBI data in the MPEG stream.

The
:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
control does not implicitly set the device driver to capture nor cease
capturing sliced VBI data. The control only indicates to embed sliced
VBI data in the MPEG stream, if an application has negotiated sliced VBI
service be captured.

It may also be the case that a device can embed sliced VBI data in only
certain types of MPEG streams: for example in an MPEG-2 PS but not an
MPEG-2 TS. In this situation, if sliced VBI data insertion is requested,
the sliced VBI data will be embedded in MPEG stream types when
supported, and silently omitted from MPEG stream types where sliced VBI
data insertion is not supported by the device.

The following subsections specify the format of the embedded sliced VBI
data.

MPEG Stream Embedded, Sliced VBI Data Format: NONE
--------------------------------------------------

The
:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`
embedded sliced VBI format shall be interpreted by drivers as a control
to cease embedding sliced VBI data in MPEG streams. Neither the device
nor driver shall insert "empty" embedded sliced VBI data packets in the
MPEG stream when this format is set. No MPEG stream data structures are
specified for this format.

MPEG Stream Embedded, Sliced VBI Data Format: IVTV
--------------------------------------------------

The
:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
embedded sliced VBI format, when supported, indicates to the driver to
embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private
Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the
MPEG stream.

*Historical context*: This format specification originates from a
custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
This format has already been informally specified in the kernel sources
in the file ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst`` . The
maximum size of the payload and other aspects of this format are driven
by the CX23415 MPEG decoder's capabilities and limitations with respect
to extracting, decoding, and displaying sliced VBI data embedded within
an MPEG stream.

This format's use is *not* exclusive to the ``ivtv`` driver *nor*
exclusive to CX2341x devices, as the sliced VBI data packet insertion
into the MPEG stream is implemented in driver software. At least the
``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in
this format as well.

The following definitions specify the payload of the MPEG-2 *Private
Stream 1 PES* packets that contain sliced VBI data when
:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
is set. (The MPEG-2 *Private Stream 1 PES* packet header and
encapsulating MPEG-2 *Program Pack* header are not detailed here. Please
refer to the MPEG-2 specifications for details on those packet headers.)

The payload of the MPEG-2 *Private Stream 1 PES* packets that contain
sliced VBI data is specified by struct
:c:type:`v4l2_mpeg_vbi_fmt_ivtv`. The
payload is variable length, depending on the actual number of lines of
sliced VBI data present in a video frame. The payload may be padded at
the end with unspecified fill bytes to align the end of the payload to a
4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
with 18 lines/field with 43 bytes of data/line and a 4 byte magic
number).

.. c:type:: v4l2_mpeg_vbi_fmt_ivtv

struct v4l2_mpeg_vbi_fmt_ivtv
-----------------------------

.. tabularcolumns:: |p{4.2cm}|p{2.0cm}|p{11.1cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u8
      - ``magic``\ [4]
      - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that
	indicates this is a valid sliced VBI data payload and also
	indicates which member of the anonymous union, ``itv0`` or
	``ITV0``, to use for the payload data.
    * - union {
      - (anonymous)
    * - struct :c:type:`v4l2_mpeg_vbi_itv0`
      - ``itv0``
      - The primary form of the sliced VBI data payload that contains
	anywhere from 1 to 35 lines of sliced VBI data. Line masks are
	provided in this form of the payload indicating which VBI lines
	are provided.
    * - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>`
      - ``ITV0``
      - An alternate form of the sliced VBI data payload used when 36
	lines of sliced VBI data are present. No line masks are provided
	in this form of the payload; all valid line mask bits are
	implicitly set.
    * - }
      -

.. _v4l2-mpeg-vbi-fmt-ivtv-magic:

Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
-------------------------------------------------------------

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. flat-table::
    :header-rows:  1
    :stub-columns: 0
    :widths:       3 1 4

    * - Defined Symbol
      - Value
      - Description
    * - ``V4L2_MPEG_VBI_IVTV_MAGIC0``
      - "itv0"
      - Indicates the ``itv0`` member of the union in struct
	:c:type:`v4l2_mpeg_vbi_fmt_ivtv` is
	valid.
    * - ``V4L2_MPEG_VBI_IVTV_MAGIC1``
      - "ITV0"
      - Indicates the ``ITV0`` member of the union in struct
	:c:type:`v4l2_mpeg_vbi_fmt_ivtv` is
	valid and that 36 lines of sliced VBI data are present.


.. c:type:: v4l2_mpeg_vbi_itv0

.. c:type:: v4l2_mpeg_vbi_ITV0

structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0
-------------------------------------------------

.. raw:: latex

   \footnotesize

.. tabularcolumns:: |p{4.6cm}|p{2.0cm}|p{10.7cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __le32
      - ``linemask``\ [2]
      - Bitmasks indicating the VBI service lines present. These
	``linemask`` values are stored in little endian byte order in the
	MPEG stream. Some reference ``linemask`` bit positions with their
	corresponding VBI line number and video field are given below.
	b\ :sub:`0` indicates the least significant bit of a ``linemask``
	value:


	::

	    linemask[0] b0:     line  6  first field
	    linemask[0] b17:    line 23  first field
	    linemask[0] b18:    line  6  second field
	    linemask[0] b31:    line 19  second field
	    linemask[1] b0:     line 20  second field
	    linemask[1] b3:     line 23  second field
	    linemask[1] b4-b31: unused and set to 0
    * - struct
	:c:type:`v4l2_mpeg_vbi_itv0_line`
      - ``line``\ [35]
      - This is a variable length array that holds from 1 to 35 lines of
	sliced VBI data. The sliced VBI data lines present correspond to
	the bits set in the ``linemask`` array, starting from b\ :sub:`0`
	of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0],
	and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of
	``linemask``\ [1]. ``line``\ [0] corresponds to the first bit
	found set in the ``linemask`` array, ``line``\ [1] corresponds to
	the second bit found set in the ``linemask`` array, etc. If no
	``linemask`` array bits are set, then ``line``\ [0] may contain
	one line of unspecified data that should be ignored by
	applications.

.. raw:: latex

   \normalsize

.. _v4l2-mpeg-vbi-itv0-1:

struct v4l2_mpeg_vbi_ITV0
-------------------------

.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.7cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - struct
	:c:type:`v4l2_mpeg_vbi_itv0_line`
      - ``line``\ [36]
      - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0]
	through ``line``\ [17] correspond to lines 6 through 23 of the
	first field. ``line``\ [18] through ``line``\ [35] corresponds to
	lines 6 through 23 of the second field.


.. c:type:: v4l2_mpeg_vbi_itv0_line

struct v4l2_mpeg_vbi_itv0_line
------------------------------

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u8
      - ``id``
      - A line identifier value from
	:ref:`ITV0-Line-Identifier-Constants` that indicates the type of
	sliced VBI data stored on this line.
    * - __u8
      - ``data``\ [42]
      - The sliced VBI data for the line.


.. _ITV0-Line-Identifier-Constants:

Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
------------------------------------------------------------

.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.5cm}|

.. flat-table::
    :header-rows:  1
    :stub-columns: 0
    :widths:       3 1 4

    * - Defined Symbol
      - Value
      - Description
    * - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B``
      - 1
      - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
	description of the line payload.
    * - ``V4L2_MPEG_VBI_IVTV_CAPTION_525``
      - 4
      - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
	description of the line payload.
    * - ``V4L2_MPEG_VBI_IVTV_WSS_625``
      - 5
      - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
	description of the line payload.
    * - ``V4L2_MPEG_VBI_IVTV_VPS``
      - 7
      - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
	description of the line payload.


.. [#f1]
   According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first
   field and lines 5-22 of the second field may carry Teletext data.

.. [#f2]
   See also :ref:`vbi-525` and :ref:`vbi-625`.