Video for Linux Two - Data Services Interface Specification

Michael Schimek - July 25, 2002

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

The abbreviation VBI stands for "Vertical Blanking Interval", a gap in the line sequence of analog video signals used to transmit data services like "Closed Caption" or "Teletext". Subject of this device type is raw vbi data, as sampled off a baseband video signal, or to be encoded with a signal for output. The data format is similar to uncompressed video images, a number of lines times a number of samples per line, called a VBI image in this document.

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:

struct v4l2_format
__u32 type     V4L2_BUF_TYPE_VBI
union {
  struct v4l2_pix_format pix
  struct v4l2_vbi_format  vbi
  __u8 raw_data[200]
fmt

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
Line synchronization diagram


__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)
ITU-R PAL/SECAM line numbering scheme
(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)
ITU-R NTSC line numbering scheme
(1) For the purpose of this specification field 2 starts in line 264 and not 263.5 because half line capturing is not supported.


Flags for the struct v4l2_vbi_format flags field
V4L2_VBI_UNSYNC This flag indicates hardware which does not properly distinguish between fields. Normally the first field in memory is the first field transmitted, the odd a. k. a. top field. If this flag is set, the driver will process the frames in correct order but it remains unknown if the top or bottom field is stored first in memory.
V4L2_VBI_INTERLACED By default, the two field images will be passed sequentially. All lines of the first field followed by all lines of the second field. If this flag is set, the two fields are interlaced. The first line of the first field followed by the first line of the second field, then the two second lines, and so on. Such a layout may be necessary when the hardware has been programmed to capture interlaced video images and cannot separate the fields for VBI at the same time. Setting this flag implies that both count values are equal and non-zero.

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

Proposal. This is not currently implemented in v4l2.

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:

struct v4l2_format
__u32 type     V4L2_BUF_TYPE_SLICED_VBI
union {
  struct v4l2_pix_format pix
  struct v4l2_vbi_format vbi
  struct v4l2_sliced_vbi_format  sliced
  __u8 raw_data[200]
fmt

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...".)

struct v4l2_sliced_vbi_format
__u32 services Set of V4L2_SLICED_... flags defining the types of data packets passed. See Sliced VBI data formats for details.
__u32 packet_size

The size of each type of packet is fixed, however when different types of packets are exchanged between driver and application their size can vary. This value defines the size of largest packet (struct v4l2_sliced_data) that will be passed, smaller packets must be padded accordingly. When the architecture requires special alignment of __u32 quantities the driver shall round up packet_size as necessary.

(TBD: One could permit variable length packets when packet_size is zero, if this serves some useful purpose. OTOH KISS: drivers may just use a hardcoded size like 64 covering any known type.)

__u32 io_size Maximum number of bytes passed by one read() or write() call, buffer size in bytes for the VIDIOC_QBUF or VIDIOC_DQBUF ioctl. Usually this will be packet_size times the number of scan lines potentially containing the data in question. On input, applications should set this to zero and accept the value proposed by the driver.
__u32 reserved Applications and drivers must set this field to zero.


struct v4l2_sliced_data
__u32 id One of the V4L2_SLICED_... flags defining the type of data in this packet. See Sliced VBI data formats for details. A value of zero indicates an empty packet with no payload, in this case line and data are undefined.
__s32 line The scanning system line number this data has been captured from. See Figure 1.2 - PAL/SECAM line numbering and Figure 1.3 - NTSC line numbering for valid values. Sliced VBI input drivers can set the line number of all packets to -1 if the hardware cannot reliable identify scan lines.
__u8 data[] The packet payload. See Sliced VBI data formats for the contents and number of bytes passed for each data type. The contents of padding bytes following up to packet_size is undefined.
Sliced VBI data formats
Format Reference Lines, usually Payload
V4L2_SLICED_TELETEXT_B (Teletext System B) ETS 300 706 "Enhanced Teletext specification" PAL line 6 - 22, 318 - 335 Last 42 of the 45 byte Teletext packet, that is without clock run-in and framing code, lsb first transmitted.
V4L2_SLICED_VPS ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)" PAL line 16 Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb first transmitted.
V4L2_SLICED_CAPTION_625 EIA 608 "Recommended Practice for Line 21 Data Service" PAL line 22 First and second byte including parity, lsb first transmitted.
V4L2_SLICED_WSS_625 ITU-R BT.1119, EN 300 294 "625-line television Wide Screen" Signalling (WSS)" PAL 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 8
	
V4L2_SLICED_CAPTION_525 EIA 608 "Recommended Practice for Line 21 Data Service" NTSC line 21, 284 First and second byte including parity, lsb first transmitted.
V4L2_SLICED_RESERVED (This and higher numbers reserved for custom formats) - undefined undefined

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

The rules for raw VBI devices apply. See section 1.2.

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

Date Description
14 Jan 1999 First version.
23 Dec 1999 In struct v4l2_vbi_format, field 'reserved1' became 'offset'. 'reserved1' was required to always read zero. Compatibility: Old drivers may return zero.
18 Sep 2000 Added V4L2_BUF_TYPE_VBI, not documented in this file. Compatibility: VIDIOC_G_FMT and VIDIOC_S_FMT may fail if field 'type' is not V4L2_BUF_TYPE_VBI.
18 Sep 2000 Changed the ambiguous phrase 'rising edge' to 'leading edge' in the definition of field 'offset'.
17 Nov 2000 Added figure 1.1 to clarify definition of 'offset'.
23 Nov 2000 Added figure 1.2 and 1.3, line numbering scheme. The description of 'start[0]' and 'start[1]' as base 0 offset has been dropped. Rationale: a) The previous definition was unclear. b) The 'start[]' values are not an offset into anything, as a means of identifying scanning lines it can only be counterproductive to deviate from common numbering conventions. Compatibility: Add one to the 'start' values. Applications depending on the previous semantics of 'start' values may not function correctly.
23 Nov 2000 Restored description of the driver option to return negative 'start' values. Existed in the initial revision of this document, not traceable why it disappeared in later versions. Compatibility: Applications depending on the returned 'start' values being positive may not function correctly.
23 Nov 2000 Clarification on the use of EBUSY and EINVAL in VIDIOC_S_FMT ioctl. Added EBUSY paragraph to section 1.3.
23 Nov 2000 The restriction 'count[0] > 0 and count[1] > 0' in section 1.1.2 has been relaxed to '(count[0] + count[1]) > 0'. Rationale: Drivers allocating resources at scanning line granularity and first field only data services. The comment that both 'count' values will usually be equal is misleading and pointless and has been removed. Compatibility: Drivers may return EINVAL, applications depending on the previous restriction may not function correctly.
23 Nov 2000 Added description of 'reserved2', previously mentioned only in videodev.h.
23 Nov 2000 Added V4L2_TYPE_VBI_INPUT and V4L2_TYPE_VBI_OUTPUT here and in videodev.h. The first is an alias for the older V4L2_TYPE_VBI, the latter was missing in videodev.h.
25 Jul 2002 Added sliced VBI interface proposal, s/transmit/pass where it refers to i/o, updated contact address.
   

Please send comments, suggestions and errata for public discussion to the V4L mailing list, or to the maintainer of this page.

Copyright © 1999-2002 Michael H. Schimek < mailto:mschimek@users.sourceforge.net>