Documentation/media/uapi/v4l/dev-sliced-vbi.rst

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