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