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