Video for Linux Two - Data Services Interface Specification

Video for Linux Two is a set of APIs and standards for handling video devices on Linux. Video for Linux Two is a replacement for the Video for Linux API that comes with the kernel.

This document is the specification of the interface to access data services broadcasted alongside television and radio programs, such as "Closed Caption", "Teletext", or "Radio Data System".

Contents

1. Raw VBI Data Interface
2. Sliced VBI Data Interface (proposal)

1. Raw VBI Data Interface

Traditionally, v4l VBI drivers are accessible through character special files named /dev/vbi. Note this naming convention applies to both, input and output devices. Except for video hardware dedicated to VBI operations only, it may be useful to identify the VBI device associated with another v4l2 capture or output device. See the Device document for details.

1.1 Raw VBI Functions

1.1.1 Query Capabilities - VIDIOC_QUERYCAP

Raw VBI devices identify themselves as either V4L2_TYPE_VBI_INPUT or V4L2_TYPE_VBI_OUTPUT. The older V4L2_TYPE_VBI is an alias for V4L2_TYPE_VBI_INPUT. The other fields of the struct v4l2_capability must be set in accordance to the capture or output device specification. See Device document, Video Capture API Specification, Video Output Device API Specification.

1.1.2 Raw VBI Format Negotiation - VIDIOC_G_FMT, VIDIOC_S_FMT

Prior to exchange data the driver and application have to negotiate the VBI image format.

On a VBI device the VIDIOC_G_FMT ioctl fills the vbi entry of struct v4l2_format with the current VBI capture parameters:

Applications can request different parameters by initializing or modifying struct v4l2_vbi_format and passing its address with the VIDIOC_S_FMT ioctl. All fields of struct v4l2_vbi_format must be initialized. The driver shall return EINVAL only if the given parameters are ambiguous, otherwise modify the parameters according to hardware limitations. When the driver allocates hardware resources for the application at this point, it may return an EBUSY error code to indicate the returned parameters are valid but the required resources are currently not available. That may happen for instance when capture windows would overlap.

Expect other resource allocation points which may return EBUSY, for example at the VIDIOC_STREAMON ioctl and the first read(), write() and select() call.

struct v4l2_vbi_format

__u32 sampling_rate	Samples per second, i. e. unit 1 Hz.
__u32 offset	Horizontal offset of the VBI image, relative to the leading edge of the line synchronization pulse and counted in samples: The first sample in the VBI image will be located offset / sampling_rate seconds following the leading edge. Figure 1.1. Line synchronization
__u32 samples_per_line
__u32 sample_format	Currently only one sample format is specified, V4L2_VBI_SF_UBYTE. This is, each sample consists of 8 bits (an unsigned integer), with lower values oriented towards the black level. Do not assume any other correlation of values with the signal level. For example, the MSB does not necessarily indicate if the signal is 'high' or 'low' because 128 may not be the mean value of the signal. In the future other formats may be offered. "YUYV" for instance, if the hardware is unable to sample VBI data at all but can extend the video capture window to the VBI region. (TBD: Actually we should probably just use the PIX_FMT_ codes here.)
__s32 start[2]	This is the scanning system line number associated with the first line of the VBI image, of the first and the second field in time respectively. See Figure 1.2 - PAL/SECAM line numbering and Figure 1.3 - NTSC line numbering for valid values. VBI input drivers can return start values of -1 if the hardware cannot reliable identify scanning lines.
__u32 count[2]	The number of lines in the first and second field image, respectively. Drivers should be as flexibility as possible. For example, it may be possible to extend or move the VBI capture window down to the picture area, implementing a 'full field mode' to capture data service transmissions embedded in the picture. An application can set the first or second count value to zero if no data is required from the respective field; count[1] if the scanning system is progressive, i. e. the term 'field' does not apply. The corresponding start value shall be ignored by the application and driver. Anyway, drivers may not support single field capturing and return both count values non-zero. Both count values set to zero, or line numbers outside the bounds depicted in figure 1.2 and 1.3 below, or a field image covering lines of different fields, is invalid and shall not be returned by the driver. To initialize the start and count fields, applications must first determine the current video standard selection. The field framelines of struct v4l2_standard is the authoritative source of information. See Video Capture API Specification.
__u32 flags	See struct v4l2_vbi_format flags below.
__u32 reserved2	Applications and drivers must set this field to zero.

Figure 1.2. PAL/SECAM (625) line numbering (ITU-R)

(1) For the purpose of this specification field 2 starts in line 314 and not 313.5 because half line capturing is not supported.

Figure 1.3. NTSC (525) line numbering (ITU-R)

(1) For the purpose of this specification field 2 starts in line 264 and not 263.5 because half line capturing is not supported.

Note the VBI image format depends on the selected video standard, thus the application must choose a new standard or query the current standard first. Attempts to read or write data ahead of format negotiation (VIDIOC_G_FMT or VIDIOC_S_FMT), or after switching the video standard which may invalidate the negotiated VBI parameters, should be refused by the driver. As the capture and output specs state, a format change is illegal during active stream i/o.

1.2 Multiple Opens per Device

VBI drivers need not support multiple non-i/o opens on a device, but it is highly recommended. Support for multiple data streams on the same device is entirely optional. Simultaneous video and VBI operation is not guaranteed either. This may be a restriction of the hardware or depend on circumstances, for example if the capture windows overlap.

It is mandatory for VBI drivers to support the same basic non-i/o commands as specified for capture or output devices. For example changing the tuner frequency, video standard, input/output ports and VBI relevant controls. Why this requirement exists for dedicated VBI drivers should be evident, but also for combined drivers. Looking up and opening the corresponding video input or output device is just not acceptable for a VBI application. Drivers can usually share the routines between their devices with little effort. See Device document, Video Capture API Specification, Video Output Device API Specification.

1.3 Reading and writing VBI Images

To assure synchronization with the field number and for ease of implementation, the smallest unit of data passed at a time is one frame, consisting of two fields of VBI images immediately following in memory. Unless the V4L2_VBI_UNSYNC flag is set, the first field in memory is always the first in time.

The total size of a frame computes as follows:

  (count[0] + count[1]) * samples_per_line * sample size in bytes

The sample size is currently always one byte, applications must check the sample_format field though, or will likely cease to function properly in the future.

A VBI driver may support the select() command, the read() and write() calls, as well as streaming i/o using memory mapped buffers. The latter bears the possibility of synchronizing video and VBI data by timestamping buffers. Passing VBI data field by field is not allowed, all other specifications for capture or output devices apply accordingly.

Mind the VIDIOC_STREAMON ioctl and the first read(), write() and select() call can be resource allocation points returning EBUSY if the required hardware resources are temporarily unavailable.

2. Sliced VBI Data Interface

Sliced VBI data is VBI data after demodulation by hardware decoders. Kernel drivers shall not convert raw VBI data by software. The data is passed as short packets of fixed size covering one scan line each. The number of packets per frame is variable.

Sliced VBI input and output drivers are accessed through character special files named /dev/vbi. Except for video hardware dedicated to VBI operations only, it may be useful to identify the VBI device associated with another v4l2 capture or output device. See the Device document for details.

2.1 Sliced VBI Functions

2.1.1 Query Capabilities - VIDIOC_QUERYCAP

Sliced VBI devices identify themselves as either V4L2_TYPE_VBI_INPUT or V4L2_TYPE_VBI_OUTPUT. The other fields of the struct v4l2_capability must be set in accordance to the capture or output device specification. See Device document, Video Capture API Specification, Video Output Device API Specification.

2.1.2 Sliced VBI Format Negotiation - VIDIOC_G_FMT, VIDIOC_S_FMT

Prior to exchange data the driver and application have to negotiate the sliced VBI data format.

On a VBI device supporting the sliced VBI interface, when setting the type to V4L2_BUF_TYPE_SLICED_VBI the VIDIOC_G_FMT ioctl fills the sliced entry of struct v4l2_format with the current sliced VBI data parameters:

Applications can request different parameters by initializing or modifying struct v4l2_sliced_vbi_format and passing its address with the VIDIOC_S_FMT ioctl. All fields of struct v4l2_sliced_vbi_format must be initialized. The driver shall return EINVAL only when the sliced VBI interface is not supported, otherwise modify the parameters as necessary. When the driver allocates hardware resources for the application at this point, it may return an EBUSY error code to indicate the returned parameters are valid but the required resources currently not available. Using one file descriptor only raw or sliced VBI data can be passed. The driver may support the use of both interfaces using two or more file descriptors.

Expect other resource allocation points which may return EBUSY, for example at the VIDIOC_STREAMON ioctl and the first read(), write() and select() call. (TBD: This should be restricted to "only at...".)

Byte         0                  1
     msb         lsb  msb             lsb
Bit  7 6 5 4 3 2 1 0  x x 13 12 11 10 9 8
	

Note the set of valid sliced VBI data formats depends on the selected video standard, thus the application must choose a new standard or query the current standard first. Attempts to read or write data ahead of format negotiation (VIDIOC_G_FMT or VIDIOC_S_FMT), or after switching the video standard which may invalidate the negotiated VBI parameters, should be refused by the driver. As the capture and output specs state, a format change is illegal during active stream i/o.

2.2 Multiple Opens per Device

2.3 Reading and writing sliced VBI data

The smallest unit of data passed at a time is one sliced data packet. Within the bounds of io_size multiple packets can (and should) be passed, but no more than one frame at a time (to keep the processing time low, for example from reception to display of subtitles). Packets are always passed in ascending line number order, without duplicate line numbers. If the line numbers are unknown the driver must pass the packets in transmitted order. Empty packets with id set to zero can be inserted anywhere.

To assure synchronization and to distinguish from frame dropping, when one frame does not contain any data in question one or more empty packets must be passed. (TBD: One could also include a timestamp in the packet?) In streaming i/o mode one buffer of io_size shall coincide with one video frame. The id of unused packets must be zero. (TBD: One could include a packet counter?)

A sliced VBI driver may support the select() command, the read() and write() calls, as well as streaming i/o using memory mapped buffers. The latter bears the possibility of synchronizing video and VBI data by timestamping buffers. Specifications for capture and output devices apply accordingly.

Mind the VIDIOC_STREAMON ioctl and the first read(), write() and select() call can be resource allocation points returning EBUSY if the required hardware resources are temporarily unavailable.

Revision History