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