Documentation/userspace-api/media/v4l/dev-raw-vbi.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/media/v4l/dev-raw-vbi.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/media/v4l/dev-raw-vbi.rst
Extension
.rst
Size
12095 bytes
Lines
293
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _raw-vbi:

**********************
Raw VBI Data Interface
**********************

VBI is an abbreviation of 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. Using an
oscilloscope you will find here the vertical synchronization pulses and
short data packages ASK modulated [#f1]_ onto the video signal. These are
transmissions of services such as Teletext or Closed Caption.

Subject of this interface type is raw VBI data, as sampled off a video
signal, or to be added to a signal for output. The data format is
similar to uncompressed video images, a number of lines times a number
of samples per line, we call this a VBI image.

Conventionally V4L2 VBI devices are accessed through character device
special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31``
with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is
typically a symbolic link to the preferred VBI device. This convention
applies to both input and output devices.

To address the problems of finding related video and VBI devices VBI
capturing and output is also available as device function under
``/dev/video``. To capture or output raw VBI data with these devices
applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
Accessed as ``/dev/vbi``, raw VBI capturing or output is the default
device function.

Querying Capabilities
=====================

Devices supporting the raw VBI capturing or output API set the
``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively,
in the ``capabilities`` field of struct
:c:type:`v4l2_capability` returned by the
:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
read/write or streaming I/O methods must be supported. VBI
devices may or may not have a tuner or modulator.

Supplemental Functions
======================

VBI devices shall support :ref:`video input or output <video>`,
:ref:`tuner or modulator <tuner>`, and :ref:`controls <control>`
ioctls as needed. The :ref:`video standard <standard>` ioctls provide
information vital to program a VBI device, therefore must be supported.

Raw VBI Format Negotiation
==========================

Raw VBI sampling abilities can vary, in particular the sampling
frequency. To properly interpret the data V4L2 specifies an ioctl to
query the sampling parameters. Moreover, to allow for some flexibility
applications can also suggest different parameters.

As usual these parameters are *not* reset at :c:func:`open()`
time to permit Unix tool chains, programming a device and then reading
from it as if it was a plain file. Well written V4L2 applications should
always ensure they really get what they want, requesting reasonable
parameters and then checking if the actual parameters are suitable.

To query the current raw VBI capture parameters applications set the
``type`` field of a struct :c:type:`v4l2_format` to

Annotation

Implementation Notes