Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst

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