1 .. -*- coding: utf-8; mode: rst -*-
5 *************************
6 Sliced VBI Data Interface
7 *************************
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.
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.
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.
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.
43 Supplemental Functions
44 ======================
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.
53 .. _sliced-vbi-format-negotitation:
55 Sliced VBI Format Negotiation
56 =============================
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.
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``
75 :ref:`v4l2_sliced_vbi_format <v4l2-sliced-vbi-format>`.
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.
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
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.
103 .. _v4l2-sliced-vbi-format:
105 struct v4l2_sliced_vbi_format
106 -----------------------------
108 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{2.9cm}|p{2.9cm}|p{2.9cm}|
124 If ``service_set`` is non-zero when passed with
125 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
126 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines``
127 array will be filled by the driver according to the services
128 specified in this field. For example, if ``service_set`` is
129 initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``,
130 a driver for the cx25840 video decoder sets lines 7-22 of both
131 fields [#f1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first
132 field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to
133 zero, then the values of ``service_lines`` will be used instead.
135 On return the driver sets this field to the union of all elements
136 of the returned ``service_lines`` array. It may contain less
137 services than requested, perhaps just one, if the hardware cannot
138 handle more services simultaneously. It may be empty (zero) if
139 none of the requested services are supported by the hardware.
145 - ``service_lines``\ [2][24]
149 Applications initialize this array with sets of data services the
150 driver shall look for or insert on the respective scan line.
151 Subject to hardware capabilities drivers return the requested set,
152 a subset, which may be just a single service, or an empty set.
153 When the hardware cannot handle multiple services on the same line
154 the driver shall choose one. No assumptions can be made on which
155 service the driver chooses.
157 Data services are defined in :ref:`vbi-services2`. Array indices
158 map to ITU-R line numbers\ [#f2]_ as follows:
174 - ``service_lines``\ [0][1]
184 - ``service_lines``\ [0][23]
194 - ``service_lines``\ [1][1]
204 - ``service_lines``\ [1][23]
214 - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
215 ``service_lines``\ [1][0] to zero. The
216 ``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``,
217 ``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START``
218 defines give the start line numbers for each field for each 525 or
219 625 line format as a convenience. Don't forget that ITU line
220 numbering starts at 1, not 0.
228 - :cspan:`2` Maximum number of bytes passed by one
229 :ref:`read() <func-read>` or :ref:`write() <func-write>` call,
230 and the buffer size in bytes for the
231 :ref:`VIDIOC_QBUF` and
232 :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field
233 to the size of struct
234 :ref:`v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` times the
235 number of non-zero elements in the returned ``service_lines``
236 array (that is the number of lines potentially carrying data).
244 - :cspan:`2` This array is reserved for future extensions.
245 Applications and drivers must set it to zero.
254 .. tabularcolumns:: |p{4.4cm}|p{2.2cm}|p{2.2cm}|p{4.4cm}|p{4.3cm}|
276 - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
280 - :ref:`ets300706`, :ref:`itu653`
282 - PAL/SECAM line 7-22, 320-335 (second field 7-22)
284 - Last 42 of the 45 byte Teletext packet, that is without clock
285 run-in and framing code, lsb first transmitted.
289 - ``V4L2_SLICED_VPS``
297 - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
302 - ``V4L2_SLICED_CAPTION_525``
308 - NTSC line 21, 284 (second field 21)
310 - Two bytes in transmission order, including parity bit, lsb first
315 - ``V4L2_SLICED_WSS_625``
319 - :ref:`itu1119`, :ref:`en300294`
329 Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
333 - ``V4L2_SLICED_VBI_525``
337 - :cspan:`2` Set of services applicable to 525 line systems.
341 - ``V4L2_SLICED_VBI_625``
345 - :cspan:`2` Set of services applicable to 625 line systems.
348 Drivers may return an ``EINVAL`` error code when applications attempt to
349 read or write data without prior format negotiation, after switching the
350 video standard (which may invalidate the negotiated VBI parameters) and
351 after switching the video input (which may change the video standard as
352 a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may
353 return an ``EBUSY`` error code when applications attempt to change the
354 format while i/o is in progress (between a
355 :ref:`VIDIOC_STREAMON` and
356 :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first
357 :ref:`read() <func-read>` or :ref:`write() <func-write>` call).
360 Reading and writing sliced VBI data
361 ===================================
363 A single :ref:`read() <func-read>` or :ref:`write() <func-write>`
364 call must pass all data belonging to one video frame. That is an array
365 of :ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` structures with one or
366 more elements and a total size not exceeding ``io_size`` bytes. Likewise
367 in streaming I/O mode one buffer of ``io_size`` bytes must contain data
368 of one video frame. The ``id`` of unused
369 :ref:`struct v4l2_sliced_vbi_data <v4l2-sliced-vbi-data>` elements must be zero.
372 .. _v4l2-sliced-vbi-data:
374 struct v4l2_sliced_vbi_data
375 ---------------------------
377 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
391 - A flag from :ref:`vbi-services` identifying the type of data in
392 this packet. Only a single bit must be set. When the ``id`` of a
393 captured packet is zero, the packet is empty and the contents of
394 other fields are undefined. Applications shall ignore empty
395 packets. When the ``id`` of a packet for output is zero the
396 contents of the ``data`` field are undefined and the driver must
397 no longer insert data on the requested ``field`` and ``line``.
405 - The video field number this data has been captured from, or shall
406 be inserted at. ``0`` for the first field, ``1`` for the second
415 - The field (as opposed to frame) line number this data has been
416 captured from, or shall be inserted at. See :ref:`vbi-525` and
417 :ref:`vbi-625` for valid values. Sliced VBI capture devices can
418 set the line number of all packets to ``0`` if the hardware cannot
419 reliably identify scan lines. The field number must always be
428 - This field is reserved for future extensions. Applications and
429 drivers must set it to zero.
437 - The packet payload. See :ref:`vbi-services` for the contents and
438 number of bytes passed for each data type. The contents of padding
439 bytes at the end of this array are undefined, drivers and
440 applications shall ignore them.
443 Packets are always passed in ascending line number order, without
444 duplicate line numbers. The :ref:`write() <func-write>` function and
445 the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL``
446 error code when applications violate this rule. They must also return an
447 EINVAL error code when applications pass an incorrect field or line
448 number, or a combination of ``field``, ``line`` and ``id`` which has not
449 been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or
450 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are
451 unknown the driver must pass the packets in transmitted order. The
452 driver can insert empty packets with ``id`` set to zero anywhere in the
455 To assure synchronization and to distinguish from frame dropping, when a
456 captured frame does not carry any of the requested data services drivers
457 must pass one or more empty packets. When an application fails to pass
458 VBI data in time for output, the driver must output the last VPS and WSS
459 packet again, and disable the output of Closed Caption and Teletext
460 data, or output data which is ignored by Closed Caption and Teletext
463 A sliced VBI device may support :ref:`read/write <rw>` and/or
464 streaming (:ref:`memory mapping <mmap>` and/or
465 :ref:`user pointer <userp>`) I/O. The latter bears the possibility of
466 synchronizing video and VBI data by using buffer timestamps.
469 Sliced VBI Data in MPEG Streams
470 ===============================
472 If a device can produce an MPEG output stream, it may be capable of
474 :ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>`
475 as data embedded in the MPEG stream. Users or applications control this
476 sliced VBI data insertion with the
477 :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
480 If the driver does not provide the
481 :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
482 control, or only allows that control to be set to
483 :ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`,
484 then the device cannot embed sliced VBI data in the MPEG stream.
487 :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
488 control does not implicitly set the device driver to capture nor cease
489 capturing sliced VBI data. The control only indicates to embed sliced
490 VBI data in the MPEG stream, if an application has negotiated sliced VBI
493 It may also be the case that a device can embed sliced VBI data in only
494 certain types of MPEG streams: for example in an MPEG-2 PS but not an
495 MPEG-2 TS. In this situation, if sliced VBI data insertion is requested,
496 the sliced VBI data will be embedded in MPEG stream types when
497 supported, and silently omitted from MPEG stream types where sliced VBI
498 data insertion is not supported by the device.
500 The following subsections specify the format of the embedded sliced VBI
504 MPEG Stream Embedded, Sliced VBI Data Format: NONE
505 --------------------------------------------------
508 :ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`
509 embedded sliced VBI format shall be interpreted by drivers as a control
510 to cease embedding sliced VBI data in MPEG streams. Neither the device
511 nor driver shall insert "empty" embedded sliced VBI data packets in the
512 MPEG stream when this format is set. No MPEG stream data structures are
513 specified for this format.
516 MPEG Stream Embedded, Sliced VBI Data Format: IVTV
517 --------------------------------------------------
520 :ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
521 embedded sliced VBI format, when supported, indicates to the driver to
522 embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private
523 Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the
526 *Historical context*: This format specification originates from a
527 custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
528 This format has already been informally specified in the kernel sources
529 in the file ``Documentation/video4linux/cx2341x/README.vbi`` . The
530 maximum size of the payload and other aspects of this format are driven
531 by the CX23415 MPEG decoder's capabilities and limitations with respect
532 to extracting, decoding, and displaying sliced VBI data embedded within
535 This format's use is *not* exclusive to the ``ivtv`` driver *nor*
536 exclusive to CX2341x devices, as the sliced VBI data packet insertion
537 into the MPEG stream is implemented in driver software. At least the
538 ``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in
541 The following definitions specify the payload of the MPEG-2 *Private
542 Stream 1 PES* packets that contain sliced VBI data when
543 :ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
544 is set. (The MPEG-2 *Private Stream 1 PES* packet header and
545 encapsulating MPEG-2 *Program Pack* header are not detailed here. Please
546 refer to the MPEG-2 specifications for details on those packet headers.)
548 The payload of the MPEG-2 *Private Stream 1 PES* packets that contain
549 sliced VBI data is specified by struct
550 :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>`. The
551 payload is variable length, depending on the actual number of lines of
552 sliced VBI data present in a video frame. The payload may be padded at
553 the end with unspecified fill bytes to align the end of the payload to a
554 4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
555 with 18 lines/field with 43 bytes of data/line and a 4 byte magic
559 .. _v4l2-mpeg-vbi-fmt-ivtv:
561 struct v4l2_mpeg_vbi_fmt_ivtv
562 -----------------------------
564 .. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}|
579 - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that
580 indicates this is a valid sliced VBI data payload and also
581 indicates which member of the anonymous union, ``itv0`` or
582 ``ITV0``, to use for the payload data.
593 - struct :ref:`v4l2_mpeg_vbi_itv0 <v4l2-mpeg-vbi-itv0>`
597 - The primary form of the sliced VBI data payload that contains
598 anywhere from 1 to 35 lines of sliced VBI data. Line masks are
599 provided in this form of the payload indicating which VBI lines
605 - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>`
609 - An alternate form of the sliced VBI data payload used when 36
610 lines of sliced VBI data are present. No line masks are provided
611 in this form of the payload; all valid line mask bits are
616 .. _v4l2-mpeg-vbi-fmt-ivtv-magic:
618 Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
619 -------------------------------------------------------------
621 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
639 - ``V4L2_MPEG_VBI_IVTV_MAGIC0``
643 - Indicates the ``itv0`` member of the union in struct
644 :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
649 - ``V4L2_MPEG_VBI_IVTV_MAGIC1``
653 - Indicates the ``ITV0`` member of the union in struct
654 :ref:`v4l2_mpeg_vbi_fmt_ivtv <v4l2-mpeg-vbi-fmt-ivtv>` is
655 valid and that 36 lines of sliced VBI data are present.
659 .. _v4l2-mpeg-vbi-itv0:
661 struct v4l2_mpeg_vbi_itv0
662 -------------------------
664 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
678 - Bitmasks indicating the VBI service lines present. These
679 ``linemask`` values are stored in little endian byte order in the
680 MPEG stream. Some reference ``linemask`` bit positions with their
681 corresponding VBI line number and video field are given below.
682 b\ :sub:`0` indicates the least significant bit of a ``linemask``
689 linemask[0] b0: line 6 first field
690 linemask[0] b17: line 23 first field
691 linemask[0] b18: line 6 second field
692 linemask[0] b31: line 19 second field
693 linemask[1] b0: line 20 second field
694 linemask[1] b3: line 23 second field
695 linemask[1] b4-b31: unused and set to 0
700 :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
704 - This is a variable length array that holds from 1 to 35 lines of
705 sliced VBI data. The sliced VBI data lines present correspond to
706 the bits set in the ``linemask`` array, starting from b\ :sub:`0`
707 of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0],
708 and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of
709 ``linemask``\ [1]. ``line``\ [0] corresponds to the first bit
710 found set in the ``linemask`` array, ``line``\ [1] corresponds to
711 the second bit found set in the ``linemask`` array, etc. If no
712 ``linemask`` array bits are set, then ``line``\ [0] may contain
713 one line of unspecified data that should be ignored by
718 .. _v4l2-mpeg-vbi-itv0-1:
720 struct v4l2_mpeg_vbi_ITV0
721 -------------------------
723 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
734 :ref:`v4l2_mpeg_vbi_itv0_line <v4l2-mpeg-vbi-itv0-line>`
738 - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0]
739 through ``line``\ [17] correspond to lines 6 through 23 of the
740 first field. ``line``\ [18] through ``line``\ [35] corresponds to
741 lines 6 through 23 of the second field.
745 .. _v4l2-mpeg-vbi-itv0-line:
747 struct v4l2_mpeg_vbi_itv0_line
748 ------------------------------
750 .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
764 - A line identifier value from
765 :ref:`ITV0-Line-Identifier-Constants` that indicates the type of
766 sliced VBI data stored on this line.
774 - The sliced VBI data for the line.
778 .. _ITV0-Line-Identifier-Constants:
780 Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
781 ------------------------------------------------------------
783 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
801 - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B``
805 - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
806 description of the line payload.
810 - ``V4L2_MPEG_VBI_IVTV_CAPTION_525``
814 - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
815 description of the line payload.
819 - ``V4L2_MPEG_VBI_IVTV_WSS_625``
823 - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
824 description of the line payload.
828 - ``V4L2_MPEG_VBI_IVTV_VPS``
832 - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
833 description of the line payload.
838 According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first
839 field and lines 5-22 of the second field may carry Teletext data.
842 See also :ref:`vbi-525` and :ref:`vbi-625`.
projects / cascardo / linux.git / blob