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
- Raw VBI Data Interface
- 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
 |
|
|
__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. |
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>