4.7. Sliced VBI Data Interface¶
VBI stands for Vertical Blanking Interval, a gap in the sequence of lines of an analog video signal. During VBI no picture information is transmitted, allowing some time while the electron beam of a cathode ray tube TV returns to the top of the screen.
Sliced VBI devices use hardware to demodulate data transmitted in the VBI. V4L2 drivers shall not do this by software, see also the raw VBI interface. The data is passed as short packets of fixed size, covering one scan line each. The number of packets per video frame is variable.
Sliced VBI capture and output devices are accessed through the same
character special files as raw VBI devices. When a driver supports both
interfaces, the default function of a /dev/vbi
device is raw VBI
capturing or output, and the sliced VBI function is only available after
calling the VIDIOC_S_FMT ioctl as defined
below. Likewise a /dev/video
device may support the sliced VBI API,
however the default function here is video capturing or output.
Different file descriptors must be used to pass raw and sliced VBI data
simultaneously, if this is supported by the driver.
4.7.1. Querying Capabilities¶
Devices supporting the sliced VBI capturing or output API set the
V4L2_CAP_SLICED_VBI_CAPTURE
or V4L2_CAP_SLICED_VBI_OUTPUT
flag
respectively, in the capabilities
field of struct
v4l2_capability
returned by the
ioctl VIDIOC_QUERYCAP ioctl. At least one of the
read/write, streaming or asynchronous I/O methods must be
supported. Sliced VBI devices may have a tuner or modulator.
4.7.2. Supplemental Functions¶
Sliced VBI devices shall support video input or output and tuner or modulator ioctls if they have these capabilities, and they may support User Controls ioctls. The video standard ioctls provide information vital to program a sliced VBI device, therefore must be supported.
4.7.3. Sliced VBI Format Negotiation¶
To find out which data services are supported by the hardware applications can call the VIDIOC_G_SLICED_VBI_CAP ioctl. All drivers implementing the sliced VBI interface must support this ioctl. The results may differ from those of the VIDIOC_S_FMT ioctl when the number of VBI lines the hardware can capture or output per frame, or the number of services it can identify on a given line are limited. For example on PAL line 16 the hardware may be able to look for a VPS or Teletext signal, but not both at the same time.
To determine the currently selected services applications set the
type
field of struct v4l2_format
to
V4L2_BUF_TYPE_SLICED_VBI_CAPTURE
or
V4L2_BUF_TYPE_SLICED_VBI_OUTPUT
, and the
VIDIOC_G_FMT ioctl fills the fmt.sliced
member, a struct
v4l2_sliced_vbi_format
.
Applications can request different parameters by initializing or
modifying the fmt.sliced
member and calling the
VIDIOC_S_FMT ioctl with a pointer to the
struct v4l2_format
structure.
The sliced VBI API is more complicated than the raw VBI API because the
hardware must be told which VBI service to expect on each scan line. Not
all services may be supported by the hardware on all lines (this is
especially true for VBI output where Teletext is often unsupported and
other services can only be inserted in one specific line). In many
cases, however, it is sufficient to just set the service_set
field
to the required services and let the driver fill the service_lines
array according to hardware capabilities. Only if more precise control
is needed should the programmer set the service_lines
array
explicitly.
The VIDIOC_S_FMT ioctl modifies the parameters
according to hardware capabilities. When the driver allocates resources
at this point, it may return an EBUSY
error code if the required
resources are temporarily unavailable. Other resource allocation points
which may return EBUSY
can be the
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF ioctl and the first
read(), write() and
select() call.
-
v4l2_sliced_vbi_format
¶
4.7.3.1. struct v4l2_sliced_vbi_format¶
__u32 | service_set |
If On return the driver sets this field to the union of all elements
of the returned |
||
__u16 | service_lines [2][24] |
Applications initialize this array with sets of data services the driver shall look for or insert on the respective scan line. Subject to hardware capabilities drivers return the requested set, a subset, which may be just a single service, or an empty set. When the hardware cannot handle multiple services on the same line the driver shall choose one. No assumptions can be made on which service the driver chooses. Data services are defined in Sliced VBI services. Array indices map to ITU-R line numbers[2] as follows: |
||
Element | 525 line systems | 625 line systems | ||
service_lines [0][1] |
1 | 1 | ||
service_lines [0][23] |
23 | 23 | ||
service_lines [1][1] |
264 | 314 | ||
service_lines [1][23] |
286 | 336 | ||
Drivers must set service_lines [0][0] and
service_lines [1][0] to zero. The
V4L2_VBI_ITU_525_F1_START , V4L2_VBI_ITU_525_F2_START ,
V4L2_VBI_ITU_625_F1_START and V4L2_VBI_ITU_625_F2_START
defines give the start line numbers for each field for each 525 or
625 line format as a convenience. Don't forget that ITU line
numbering starts at 1, not 0. |
||||
__u32 | io_size |
Maximum number of bytes passed by one
read() or write() call,
and the buffer size in bytes for the
ioctl VIDIOC_QBUF, VIDIOC_DQBUF and
VIDIOC_DQBUF ioctl. Drivers set this field
to the size of struct
v4l2_sliced_vbi_data times the
number of non-zero elements in the returned service_lines
array (that is the number of lines potentially carrying data). |
||
__u32 | reserved [2] |
This array is reserved for future extensions. Applications and drivers must set it to zero. |
4.7.3.2. Sliced VBI services¶
Symbol | Value | Reference | Lines, usually | Payload |
---|---|---|---|---|
V4L2_SLICED_TELETEXT_B (Teletext System B) |
0x0001 | PAL/SECAM line 7-22, 320-335 (second field 7-22) | Last 42 of the 45 byte Teletext packet, that is without clock run-in and framing code, lsb first transmitted. | |
V4L2_SLICED_VPS |
0x0400 | ETS 300 231 | PAL line 16 | Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb first transmitted. |
V4L2_SLICED_CAPTION_525 |
0x1000 | CEA 608-E | NTSC line 21, 284 (second field 21) | Two bytes in transmission order, including parity bit, lsb first transmitted. |
V4L2_SLICED_WSS_625 |
0x4000 | PAL/SECAM line 23 | Byte 0 1
msb lsb msb lsb
Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9
|
|
V4L2_SLICED_VBI_525 |
0x1000 | Set of services applicable to 525 line systems. | ||
V4L2_SLICED_VBI_625 |
0x4401 | Set of services applicable to 625 line systems. |
Drivers may return an EINVAL
error code when applications attempt to
read or write data without prior format negotiation, after switching the
video standard (which may invalidate the negotiated VBI parameters) and
after switching the video input (which may change the video standard as
a side effect). The VIDIOC_S_FMT ioctl may
return an EBUSY
error code when applications attempt to change the
format while i/o is in progress (between a
ioctl VIDIOC_STREAMON, VIDIOC_STREAMOFF and
VIDIOC_STREAMOFF call, and after the first
read() or write() call).
4.7.4. Reading and writing sliced VBI data¶
A single read() or write()
call must pass all data belonging to one video frame. That is an array
of struct v4l2_sliced_vbi_data
structures with one or
more elements and a total size not exceeding io_size
bytes. Likewise
in streaming I/O mode one buffer of io_size
bytes must contain data
of one video frame. The id
of unused
struct v4l2_sliced_vbi_data
elements must be zero.
-
v4l2_sliced_vbi_data
¶
4.7.4.1. struct v4l2_sliced_vbi_data¶
__u32 | id |
A flag from Sliced VBI services identifying the type of data in
this packet. Only a single bit must be set. When the id of a
captured packet is zero, the packet is empty and the contents of
other fields are undefined. Applications shall ignore empty
packets. When the id of a packet for output is zero the
contents of the data field are undefined and the driver must
no longer insert data on the requested field and line . |
__u32 | field |
The video field number this data has been captured from, or shall
be inserted at. 0 for the first field, 1 for the second
field. |
__u32 | line |
The field (as opposed to frame) line number this data has been
captured from, or shall be inserted at. See Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL) and
Figure 4.3. ITU-R 625 line numbering for valid values. Sliced VBI capture devices can
set the line number of all packets to 0 if the hardware cannot
reliably identify scan lines. The field number must always be
valid. |
__u32 | reserved |
This field is reserved for future extensions. Applications and drivers must set it to zero. |
__u8 | data [48] |
The packet payload. See Sliced VBI services for the contents and number of bytes passed for each data type. The contents of padding bytes at the end of this array are undefined, drivers and applications shall ignore them. |
Packets are always passed in ascending line number order, without
duplicate line numbers. The write() function and
the ioctl VIDIOC_QBUF, VIDIOC_DQBUF ioctl must return an EINVAL
error code when applications violate this rule. They must also return an
EINVAL error code when applications pass an incorrect field or line
number, or a combination of field
, line
and id
which has not
been negotiated with the VIDIOC_G_FMT or
VIDIOC_S_FMT ioctl. When the line numbers are
unknown the driver must pass the packets in transmitted order. The
driver can insert empty packets with id
set to zero anywhere in the
packet array.
To assure synchronization and to distinguish from frame dropping, when a captured frame does not carry any of the requested data services drivers must pass one or more empty packets. When an application fails to pass VBI data in time for output, the driver must output the last VPS and WSS packet again, and disable the output of Closed Caption and Teletext data, or output data which is ignored by Closed Caption and Teletext decoders.
A sliced VBI device may support read/write and/or streaming (memory mapping and/or user pointer) I/O. The latter bears the possibility of synchronizing video and VBI data by using buffer timestamps.
4.7.5. Sliced VBI Data in MPEG Streams¶
If a device can produce an MPEG output stream, it may be capable of providing negotiated sliced VBI services as data embedded in the MPEG stream. Users or applications control this sliced VBI data insertion with the V4L2_CID_MPEG_STREAM_VBI_FMT control.
If the driver does not provide the V4L2_CID_MPEG_STREAM_VBI_FMT control, or only allows that control to be set to V4L2_MPEG_STREAM_VBI_FMT_NONE, then the device cannot embed sliced VBI data in the MPEG stream.
The V4L2_CID_MPEG_STREAM_VBI_FMT control does not implicitly set the device driver to capture nor cease capturing sliced VBI data. The control only indicates to embed sliced VBI data in the MPEG stream, if an application has negotiated sliced VBI service be captured.
It may also be the case that a device can embed sliced VBI data in only certain types of MPEG streams: for example in an MPEG-2 PS but not an MPEG-2 TS. In this situation, if sliced VBI data insertion is requested, the sliced VBI data will be embedded in MPEG stream types when supported, and silently omitted from MPEG stream types where sliced VBI data insertion is not supported by the device.
The following subsections specify the format of the embedded sliced VBI data.
4.7.5.1. MPEG Stream Embedded, Sliced VBI Data Format: NONE¶
The V4L2_MPEG_STREAM_VBI_FMT_NONE embedded sliced VBI format shall be interpreted by drivers as a control to cease embedding sliced VBI data in MPEG streams. Neither the device nor driver shall insert "empty" embedded sliced VBI data packets in the MPEG stream when this format is set. No MPEG stream data structures are specified for this format.
4.7.5.2. MPEG Stream Embedded, Sliced VBI Data Format: IVTV¶
The V4L2_MPEG_STREAM_VBI_FMT_IVTV embedded sliced VBI format, when supported, indicates to the driver to embed up to 36 lines of sliced VBI data per frame in an MPEG-2 Private Stream 1 PES packet encapsulated in an MPEG-2 Program Pack in the MPEG stream.
Historical context: This format specification originates from a
custom, embedded, sliced VBI data format used by the ivtv
driver.
This format has already been informally specified in the kernel sources
in the file Documentation/media/v4l-drivers/cx2341x.rst
. The
maximum size of the payload and other aspects of this format are driven
by the CX23415 MPEG decoder's capabilities and limitations with respect
to extracting, decoding, and displaying sliced VBI data embedded within
an MPEG stream.
This format's use is not exclusive to the ivtv
driver nor
exclusive to CX2341x devices, as the sliced VBI data packet insertion
into the MPEG stream is implemented in driver software. At least the
cx18
driver provides sliced VBI data insertion into an MPEG-2 PS in
this format as well.
The following definitions specify the payload of the MPEG-2 Private Stream 1 PES packets that contain sliced VBI data when V4L2_MPEG_STREAM_VBI_FMT_IVTV is set. (The MPEG-2 Private Stream 1 PES packet header and encapsulating MPEG-2 Program Pack header are not detailed here. Please refer to the MPEG-2 specifications for details on those packet headers.)
The payload of the MPEG-2 Private Stream 1 PES packets that contain
sliced VBI data is specified by struct
v4l2_mpeg_vbi_fmt_ivtv
. The
payload is variable length, depending on the actual number of lines of
sliced VBI data present in a video frame. The payload may be padded at
the end with unspecified fill bytes to align the end of the payload to a
4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
with 18 lines/field with 43 bytes of data/line and a 4 byte magic
number).
-
v4l2_mpeg_vbi_fmt_ivtv
¶
4.7.5.3. struct v4l2_mpeg_vbi_fmt_ivtv¶
__u8 | magic [4] |
A "magic" constant from Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field that
indicates this is a valid sliced VBI data payload and also
indicates which member of the anonymous union, itv0 or
ITV0 , to use for the payload data. |
union { | (anonymous) | |
struct v4l2_mpeg_vbi_itv0 |
itv0 |
The primary form of the sliced VBI data payload that contains anywhere from 1 to 35 lines of sliced VBI data. Line masks are provided in this form of the payload indicating which VBI lines are provided. |
struct v4l2_mpeg_vbi_ITV0 | ITV0 |
An alternate form of the sliced VBI data payload used when 36 lines of sliced VBI data are present. No line masks are provided in this form of the payload; all valid line mask bits are implcitly set. |
} |
4.7.5.4. Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field¶
Defined Symbol | Value | Description |
---|---|---|
V4L2_MPEG_VBI_IVTV_MAGIC0 |
"itv0" | Indicates the itv0 member of the union in struct
v4l2_mpeg_vbi_fmt_ivtv is
valid. |
V4L2_MPEG_VBI_IVTV_MAGIC1 |
"ITV0" | Indicates the ITV0 member of the union in struct
v4l2_mpeg_vbi_fmt_ivtv is
valid and that 36 lines of sliced VBI data are present. |
-
v4l2_mpeg_vbi_itv0
¶
-
v4l2_mpeg_vbi_ITV0
¶
4.7.5.5. structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0¶
__le32 | linemask [2] |
Bitmasks indicating the VBI service lines present. These
linemask[0] b0: line 6 first field
linemask[0] b17: line 23 first field
linemask[0] b18: line 6 second field
linemask[0] b31: line 19 second field
linemask[1] b0: line 20 second field
linemask[1] b3: line 23 second field
linemask[1] b4-b31: unused and set to 0
|
struct
v4l2_mpeg_vbi_itv0_line |
line [35] |
This is a variable length array that holds from 1 to 35 lines of
sliced VBI data. The sliced VBI data lines present correspond to
the bits set in the linemask array, starting from b0
of linemask [0] up through b31 of linemask [0],
and from b0 of linemask [1] up through b3 of
linemask [1]. line [0] corresponds to the first bit
found set in the linemask array, line [1] corresponds to
the second bit found set in the linemask array, etc. If no
linemask array bits are set, then line [0] may contain
one line of unspecified data that should be ignored by
applications. |
4.7.5.6. struct v4l2_mpeg_vbi_ITV0¶
struct
v4l2_mpeg_vbi_itv0_line |
line [36] |
A fixed length array of 36 lines of sliced VBI data. line [0]
through line [17] correspond to lines 6 through 23 of the
first field. line [18] through line [35] corresponds to
lines 6 through 23 of the second field. |
-
v4l2_mpeg_vbi_itv0_line
¶
4.7.5.7. struct v4l2_mpeg_vbi_itv0_line¶
__u8 | id |
A line identifier value from Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field that indicates the type of sliced VBI data stored on this line. |
__u8 | data [42] |
The sliced VBI data for the line. |
4.7.5.8. Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field¶
Defined Symbol | Value | Description |
---|---|---|
V4L2_MPEG_VBI_IVTV_TELETEXT_B |
1 | Refer to Sliced VBI services for a description of the line payload. |
V4L2_MPEG_VBI_IVTV_CAPTION_525 |
4 | Refer to Sliced VBI services for a description of the line payload. |
V4L2_MPEG_VBI_IVTV_WSS_625 |
5 | Refer to Sliced VBI services for a description of the line payload. |
V4L2_MPEG_VBI_IVTV_VPS |
7 | Refer to Sliced VBI services for a description of the line payload. |
[1] | According to ETS 300 706 lines 6-22 of the first field and lines 5-22 of the second field may carry Teletext data. |
[2] | See also Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL) and Figure 4.3. ITU-R 625 line numbering. |