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