| 1 |
.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later |
| 2 |
.. c:namespace:: V4L |
| 3 |
|
| 4 |
.. _raw-vbi: |
| 5 |
|
| 6 |
********************** |
| 7 |
Raw VBI Data Interface |
| 8 |
********************** |
| 9 |
|
| 10 |
VBI is an abbreviation of Vertical Blanking Interval, a gap in the |
| 11 |
sequence of lines of an analog video signal. During VBI no picture |
| 12 |
information is transmitted, allowing some time while the electron beam |
| 13 |
of a cathode ray tube TV returns to the top of the screen. Using an |
| 14 |
oscilloscope you will find here the vertical synchronization pulses and |
| 15 |
short data packages ASK modulated [#f1]_ onto the video signal. These are |
| 16 |
transmissions of services such as Teletext or Closed Caption. |
| 17 |
|
| 18 |
Subject of this interface type is raw VBI data, as sampled off a video |
| 19 |
signal, or to be added to a signal for output. The data format is |
| 20 |
similar to uncompressed video images, a number of lines times a number |
| 21 |
of samples per line, we call this a VBI image. |
| 22 |
|
| 23 |
Conventionally V4L2 VBI devices are accessed through character device |
| 24 |
special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31`` |
| 25 |
with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is |
| 26 |
typically a symbolic link to the preferred VBI device. This convention |
| 27 |
applies to both input and output devices. |
| 28 |
|
| 29 |
To address the problems of finding related video and VBI devices VBI |
| 30 |
capturing and output is also available as device function under |
| 31 |
``/dev/video``. To capture or output raw VBI data with these devices |
| 32 |
applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. |
| 33 |
Accessed as ``/dev/vbi``, raw VBI capturing or output is the default |
| 34 |
device function. |
| 35 |
|
| 36 |
Querying Capabilities |
| 37 |
===================== |
| 38 |
|
| 39 |
Devices supporting the raw VBI capturing or output API set the |
| 40 |
``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, respectively, |
| 41 |
in the ``capabilities`` field of struct |
| 42 |
:c:type:`v4l2_capability` returned by the |
| 43 |
:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the |
| 44 |
read/write or streaming I/O methods must be supported. VBI |
| 45 |
devices may or may not have a tuner or modulator. |
| 46 |
|
| 47 |
Supplemental Functions |
| 48 |
====================== |
| 49 |
|
| 50 |
VBI devices shall support :ref:`video input or output <video>`, |
| 51 |
:ref:`tuner or modulator <tuner>`, and :ref:`controls <control>` |
| 52 |
ioctls as needed. The :ref:`video standard <standard>` ioctls provide |
| 53 |
information vital to program a VBI device, therefore must be supported. |
| 54 |
|
| 55 |
Raw VBI Format Negotiation |
| 56 |
========================== |
| 57 |
|
| 58 |
Raw VBI sampling abilities can vary, in particular the sampling |
| 59 |
frequency. To properly interpret the data V4L2 specifies an ioctl to |
| 60 |
query the sampling parameters. Moreover, to allow for some flexibility |
| 61 |
applications can also suggest different parameters. |
| 62 |
|
| 63 |
As usual these parameters are *not* reset at :c:func:`open()` |
| 64 |
time to permit Unix tool chains, programming a device and then reading |
| 65 |
from it as if it was a plain file. Well written V4L2 applications should |
| 66 |
always ensure they really get what they want, requesting reasonable |
| 67 |
parameters and then checking if the actual parameters are suitable. |
| 68 |
|
| 69 |
To query the current raw VBI capture parameters applications set the |
| 70 |
``type`` field of a struct :c:type:`v4l2_format` to |
| 71 |
``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call |
| 72 |
the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this |
| 73 |
structure. Drivers fill the struct |
| 74 |
:c:type:`v4l2_vbi_format` ``vbi`` member of the |
| 75 |
``fmt`` union. |
| 76 |
|
| 77 |
To request different parameters applications set the ``type`` field of a |
| 78 |
struct :c:type:`v4l2_format` as above and initialize all |
| 79 |
fields of the struct :c:type:`v4l2_vbi_format` |
| 80 |
``vbi`` member of the ``fmt`` union, or better just modify the results |
| 81 |
of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` |
| 82 |
ioctl with a pointer to this structure. Drivers return an ``EINVAL`` error |
| 83 |
code only when the given parameters are ambiguous, otherwise they modify |
| 84 |
the parameters according to the hardware capabilities and return the |
| 85 |
actual parameters. When the driver allocates resources at this point, it |
| 86 |
may return an ``EBUSY`` error code to indicate the returned parameters are |
| 87 |
valid but the required resources are currently not available. That may |
| 88 |
happen for instance when the video and VBI areas to capture would |
| 89 |
overlap, or when the driver supports multiple opens and another process |
| 90 |
already requested VBI capturing or output. Anyway, applications must |
| 91 |
expect other resource allocation points which may return ``EBUSY``, at the |
| 92 |
:ref:`VIDIOC_STREAMON` ioctl and the first :c:func:`read()` |
| 93 |
, :c:func:`write()` and :c:func:`select()` calls. |
| 94 |
|
| 95 |
VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and |
| 96 |
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests |
| 97 |
and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. |
| 98 |
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. |
| 99 |
|
| 100 |
.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.5cm}| |
| 101 |
|
| 102 |
.. c:type:: v4l2_vbi_format |
| 103 |
|
| 104 |
.. cssclass:: longtable |
| 105 |
|
| 106 |
.. flat-table:: struct v4l2_vbi_format |
| 107 |
:header-rows: 0 |
| 108 |
:stub-columns: 0 |
| 109 |
:widths: 1 1 2 |
| 110 |
|
| 111 |
* - __u32 |
| 112 |
- ``sampling_rate`` |
| 113 |
- Samples per second, i. e. unit 1 Hz. |
| 114 |
* - __u32 |
| 115 |
- ``offset`` |
| 116 |
- Horizontal offset of the VBI image, relative to the leading edge |
| 117 |
of the line synchronization pulse and counted in samples: The |
| 118 |
first sample in the VBI image will be located ``offset`` / |
| 119 |
``sampling_rate`` seconds following the leading edge. See also |
| 120 |
:ref:`vbi-hsync`. |
| 121 |
* - __u32 |
| 122 |
- ``samples_per_line`` |
| 123 |
- |
| 124 |
* - __u32 |
| 125 |
- ``sample_format`` |
| 126 |
- Defines the sample format as in :ref:`pixfmt`, a |
| 127 |
four-character-code. [#f2]_ Usually this is ``V4L2_PIX_FMT_GREY``, |
| 128 |
i. e. each sample consists of 8 bits with lower values oriented |
| 129 |
towards the black level. Do not assume any other correlation of |
| 130 |
values with the signal level. For example, the MSB does not |
| 131 |
necessarily indicate if the signal is 'high' or 'low' because 128 |
| 132 |
may not be the mean value of the signal. Drivers shall not convert |
| 133 |
the sample format by software. |
| 134 |
* - __u32 |
| 135 |
- ``start``\ [#f2]_ |
| 136 |
- This is the scanning system line number associated with the first |
| 137 |
line of the VBI image, of the first and the second field |
| 138 |
respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid |
| 139 |
values. The ``V4L2_VBI_ITU_525_F1_START``, |
| 140 |
``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and |
| 141 |
``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers |
| 142 |
for each field for each 525 or 625 line format as a convenience. |
| 143 |
Don't forget that ITU line numbering starts at 1, not 0. VBI input |
| 144 |
drivers can return start values 0 if the hardware cannot reliable |
| 145 |
identify scanning lines, VBI acquisition may not require this |
| 146 |
information. |
| 147 |
* - __u32 |
| 148 |
- ``count``\ [#f2]_ |
| 149 |
- The number of lines in the first and second field image, |
| 150 |
respectively. |
| 151 |
* - :cspan:`2` |
| 152 |
|
| 153 |
Drivers should be as flexibility as possible. For example, it may |
| 154 |
be possible to extend or move the VBI capture window down to the |
| 155 |
picture area, implementing a 'full field mode' to capture data |
| 156 |
service transmissions embedded in the picture. |
| 157 |
|
| 158 |
An application can set the first or second ``count`` value to zero |
| 159 |
if no data is required from the respective field; ``count``\ [1] |
| 160 |
if the scanning system is progressive, i. e. not interlaced. The |
| 161 |
corresponding start value shall be ignored by the application and |
| 162 |
driver. Anyway, drivers may not support single field capturing and |
| 163 |
return both count values non-zero. |
| 164 |
|
| 165 |
Both ``count`` values set to zero, or line numbers are outside the |
| 166 |
bounds depicted\ [#f4]_, or a field image covering lines of two |
| 167 |
fields, are invalid and shall not be returned by the driver. |
| 168 |
|
| 169 |
To initialize the ``start`` and ``count`` fields, applications |
| 170 |
must first determine the current video standard selection. The |
| 171 |
:ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field |
| 172 |
of struct :c:type:`v4l2_standard` can be evaluated |
| 173 |
for this purpose. |
| 174 |
* - __u32 |
| 175 |
- ``flags`` |
| 176 |
- See :ref:`vbifmt-flags` below. Currently only drivers set flags, |
| 177 |
applications must set this field to zero. |
| 178 |
* - __u32 |
| 179 |
- ``reserved``\ [#f2]_ |
| 180 |
- This array is reserved for future extensions. Drivers and |
| 181 |
applications must set it to zero. |
| 182 |
|
| 183 |
.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.4cm}| |
| 184 |
|
| 185 |
.. _vbifmt-flags: |
| 186 |
|
| 187 |
.. flat-table:: Raw VBI Format Flags |
| 188 |
:header-rows: 0 |
| 189 |
:stub-columns: 0 |
| 190 |
:widths: 3 1 4 |
| 191 |
|
| 192 |
* - ``V4L2_VBI_UNSYNC`` |
| 193 |
- 0x0001 |
| 194 |
- This flag indicates hardware which does not properly distinguish |
| 195 |
between fields. Normally the VBI image stores the first field |
| 196 |
(lower scanning line numbers) first in memory. This may be a top |
| 197 |
or bottom field depending on the video standard. When this flag is |
| 198 |
set the first or second field may be stored first, however the |
| 199 |
fields are still in correct temporal order with the older field |
| 200 |
first in memory. [#f3]_ |
| 201 |
* - ``V4L2_VBI_INTERLACED`` |
| 202 |
- 0x0002 |
| 203 |
- By default the two field images will be passed sequentially; all |
| 204 |
lines of the first field followed by all lines of the second field |
| 205 |
(compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and |
| 206 |
``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in |
| 207 |
memory depends on the video standard). When this flag is set, the |
| 208 |
two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The |
| 209 |
first line of the first field followed by the first line of the |
| 210 |
second field, then the two second lines, and so on. Such a layout |
| 211 |
may be necessary when the hardware has been programmed to capture |
| 212 |
or output interlaced video images and is unable to separate the |
| 213 |
fields for VBI capturing at the same time. For simplicity setting |
| 214 |
this flag implies that both ``count`` values are equal and |
| 215 |
non-zero. |
| 216 |
|
| 217 |
|
| 218 |
.. _vbi-hsync: |
| 219 |
|
| 220 |
.. kernel-figure:: vbi_hsync.svg |
| 221 |
:alt: vbi_hsync.svg |
| 222 |
:align: center |
| 223 |
|
| 224 |
Line synchronization |
| 225 |
|
| 226 |
.. _vbi-525: |
| 227 |
|
| 228 |
.. kernel-figure:: vbi_525.svg |
| 229 |
:alt: vbi_525.svg |
| 230 |
:align: center |
| 231 |
|
| 232 |
ITU-R 525 line numbering (M/NTSC and M/PAL) |
| 233 |
|
| 234 |
.. _vbi-625: |
| 235 |
|
| 236 |
.. kernel-figure:: vbi_625.svg |
| 237 |
:alt: vbi_625.svg |
| 238 |
:align: center |
| 239 |
|
| 240 |
ITU-R 625 line numbering |
| 241 |
|
| 242 |
Remember the VBI image format depends on the selected video standard, |
| 243 |
therefore the application must choose a new standard or query the |
| 244 |
current standard first. Attempts to read or write data ahead of format |
| 245 |
negotiation, or after switching the video standard which may invalidate |
| 246 |
the negotiated VBI parameters, should be refused by the driver. A format |
| 247 |
change during active I/O is not permitted. |
| 248 |
|
| 249 |
Reading and writing VBI images |
| 250 |
============================== |
| 251 |
|
| 252 |
To assure synchronization with the field number and easier |
| 253 |
implementation, the smallest unit of data passed at a time is one frame, |
| 254 |
consisting of two fields of VBI images immediately following in memory. |
| 255 |
|
| 256 |
The total size of a frame computes as follows: |
| 257 |
|
| 258 |
.. code-block:: c |
| 259 |
|
| 260 |
(count[0] + count[1]) * samples_per_line * sample size in bytes |
| 261 |
|
| 262 |
The sample size is most likely always one byte, applications must check |
| 263 |
the ``sample_format`` field though, to function properly with other |
| 264 |
drivers. |
| 265 |
|
| 266 |
A VBI device may support :ref:`read/write <rw>` and/or streaming |
| 267 |
(:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O. |
| 268 |
The latter bears the possibility of synchronizing video and VBI data by |
| 269 |
using buffer timestamps. |
| 270 |
|
| 271 |
Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the |
| 272 |
first :c:func:`read()`, :c:func:`write()` and |
| 273 |
:c:func:`select()` call can be resource allocation |
| 274 |
points returning an ``EBUSY`` error code if the required hardware resources |
| 275 |
are temporarily unavailable, for example the device is already in use by |
| 276 |
another process. |
| 277 |
|
| 278 |
.. [#f1] |
| 279 |
ASK: Amplitude-Shift Keying. A high signal level represents a '1' |
| 280 |
bit, a low level a '0' bit. |
| 281 |
|
| 282 |
.. [#f2] |
| 283 |
A few devices may be unable to sample VBI data at all but can extend |
| 284 |
the video capture window to the VBI region. |
| 285 |
|
| 286 |
.. [#f3] |
| 287 |
Most VBI services transmit on both fields, but some have different |
| 288 |
semantics depending on the field number. These cannot be reliable |
| 289 |
decoded or encoded when ``V4L2_VBI_UNSYNC`` is set. |
| 290 |
|
| 291 |
.. [#f4] |
| 292 |
The valid values ar shown at :ref:`vbi-525` and :ref:`vbi-625`. |