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.
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 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.
Sliced VBI devices shall support video input or output and tuner or modulator ioctls if they have these capabilities, and they may support control ioctls. The video standard ioctls provide information vital to program a sliced VBI device, therefore must be supported.
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
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 returns an EINVAL error code only when the
given parameters are ambiguous, otherwise it 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
VIDIOC_STREAMON ioctl and the first read(), write() and
select() call.
Table 4-6. 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 Table 4-7. Array indices map to ITU-R line numbers (see also Figure 4-2 and Figure 4-3) 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. | ||||
| __u32 | io_size | Maximum number of bytes passed by
one read() or write() call, and the buffer size in bytes for
the VIDIOC_QBUF 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. | ||
| Notes: a. According to ETS 300 706 lines 6-22 of the first field and lines 5-22 of the second field may carry Teletext data. | ||||
Table 4-7. Sliced VBI services
| Symbol | Value | Reference | Lines, usually | Payload |
|---|---|---|---|---|
V4L2_SLICED_TELETEXT_B
(Teletext System B) | 0x0001 | ETS 300 706, ITU BT.653 | 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 | EIA 608-B | NTSC line 21, 284 (second field 21) | Two bytes in transmission order, including parity bit, lsb first transmitted. |
V4L2_SLICED_WSS_625 | 0x4000 | ITU BT.1119, EN 300 294 | 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 VIDIOC_STREAMON and VIDIOC_STREAMOFF call,
and after the first read() or write() call).
A single read() or write() call must pass all data
belonging to one video frame. That is an array of
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 v4l2_sliced_vbi_data elements must be
zero.
Table 4-8. struct
v4l2_sliced_vbi_data
| __u32 | id | A flag from Table 2
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 and Figure 4-3 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 Table 2 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
VIDIOC_QBUF 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.