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 &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 &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 &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 modifies the parameters according to hardware capabilities. When the driver allocates resources at this point, it may return an &EBUSY; if the required resources are temporarily unavailable. Other resource allocation points which may return EBUSY can be the &VIDIOC-STREAMON; ioctl and the first &func-read;, &func-write; and &func-select; call. __u32 service_set If service_set is non-zero when passed with &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;, the service_lines array will be filled by the driver according to the services specified in this field. For example, if service_set is initialized with V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625, a driver for the cx25840 video decoder sets lines 7-22 of both fieldsAccording to ETS 300 706 lines 6-22 of the first field and lines 5-22 of the second field may carry Teletext data. to V4L2_SLICED_TELETEXT_B and line 23 of the first field to V4L2_SLICED_WSS_625. If service_set is set to zero, then the values of service_lines will be used instead. On return the driver sets this field to the union of all elements of the returned service_lines array. It may contain less services than requested, perhaps just one, if the hardware cannot handle more services simultaneously. It may be empty (zero) if none of the requested services are supported by the hardware. __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 . Array indices map to ITU-R line numbers (see also and ) 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 &func-read; or &func-write; call, and the buffer size in bytes for the &VIDIOC-QBUF; and &VIDIOC-DQBUF; ioctl. Drivers set this field to the size of &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. 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 PAL line 16 Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb first transmitted. V4L2_SLICED_CAPTION_525 0x1000 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; 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; 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 &func-read; or &func-write; call).

A single &func-read; or &func-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. &cs-def; __u32 id A flag from 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 and 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 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 &func-write; function and the &VIDIOC-QBUF; ioctl must return an &EINVAL; when applications violate this rule. They must also return an &EINVAL; 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.