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