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 **Figure 4.1. Line synchronization**
225
226 .. _vbi-525:
227
228 .. kernel-figure:: vbi_525.svg
229 :alt: vbi_525.svg
230 :align: center
231
232 **Figure 4.2. 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 **Figure 4.3. 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`.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.