1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
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 In
11 sequence of lines of an analog video signal. D
12 information is transmitted, allowing some time
13 of a cathode ray tube TV returns to the top of
14 oscilloscope you will find here the vertical s
15 short data packages ASK modulated [#f1]_ onto
16 transmissions of services such as Teletext or
17
18 Subject of this interface type is raw VBI data
19 signal, or to be added to a signal for output.
20 similar to uncompressed video images, a number
21 of samples per line, we call this a VBI image.
22
23 Conventionally V4L2 VBI devices are accessed t
24 special files named ``/dev/vbi`` and ``/dev/vb
25 with major number 81 and minor numbers 224 to
26 typically a symbolic link to the preferred VBI
27 applies to both input and output devices.
28
29 To address the problems of finding related vid
30 capturing and output is also available as devi
31 ``/dev/video``. To capture or output raw VBI d
32 applications must call the :ref:`VIDIOC_S_FMT
33 Accessed as ``/dev/vbi``, raw VBI capturing or
34 device function.
35
36 Querying Capabilities
37 =====================
38
39 Devices supporting the raw VBI capturing or ou
40 ``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUT
41 in the ``capabilities`` field of struct
42 :c:type:`v4l2_capability` returned by the
43 :ref:`VIDIOC_QUERYCAP` ioctl. At least one of
44 read/write or streaming I/O methods must be su
45 devices may or may not have a tuner or modulat
46
47 Supplemental Functions
48 ======================
49
50 VBI devices shall support :ref:`video input or
51 :ref:`tuner or modulator <tuner>`, and :ref:`c
52 ioctls as needed. The :ref:`video standard <st
53 information vital to program a VBI device, the
54
55 Raw VBI Format Negotiation
56 ==========================
57
58 Raw VBI sampling abilities can vary, in partic
59 frequency. To properly interpret the data V4L2
60 query the sampling parameters. Moreover, to al
61 applications can also suggest different parame
62
63 As usual these parameters are *not* reset at :
64 time to permit Unix tool chains, programming a
65 from it as if it was a plain file. Well writte
66 always ensure they really get what they want,
67 parameters and then checking if the actual par
68
69 To query the current raw VBI capture parameter
70 ``type`` field of a struct :c:type:`v4l2_forma
71 ``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TY
72 the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl w
73 structure. Drivers fill the struct
74 :c:type:`v4l2_vbi_format` ``vbi`` member of th
75 ``fmt`` union.
76
77 To request different parameters applications s
78 struct :c:type:`v4l2_format` as above and init
79 fields of the struct :c:type:`v4l2_vbi_format`
80 ``vbi`` member of the ``fmt`` union, or better
81 of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and cal
82 ioctl with a pointer to this structure. Driver
83 code only when the given parameters are ambigu
84 the parameters according to the hardware capab
85 actual parameters. When the driver allocates r
86 may return an ``EBUSY`` error code to indicate
87 valid but the required resources are currently
88 happen for instance when the video and VBI are
89 overlap, or when the driver supports multiple
90 already requested VBI capturing or output. Any
91 expect other resource allocation points which
92 :ref:`VIDIOC_STREAMON` ioctl and the first :c:
93 , :c:func:`write()` and :c:func:`select()` cal
94
95 VBI devices must implement both the :ref:`VIDI
96 :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even
97 and always returns default parameters as :ref:
98 :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is option
99
100 .. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.5c
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, re
117 of the line synchronization pulse and
118 first sample in the VBI image will be
119 ``sampling_rate`` seconds following th
120 :ref:`vbi-hsync`.
121 * - __u32
122 - ``samples_per_line``
123 -
124 * - __u32
125 - ``sample_format``
126 - Defines the sample format as in :ref:`
127 four-character-code. [#f2]_ Usually th
128 i. e. each sample consists of 8 bits w
129 towards the black level. Do not assume
130 values with the signal level. For exam
131 necessarily indicate if the signal is
132 may not be the mean value of the signa
133 the sample format by software.
134 * - __u32
135 - ``start``\ [#f2]_
136 - This is the scanning system line numbe
137 line of the VBI image, of the first an
138 respectively. See :ref:`vbi-525` and :
139 values. The ``V4L2_VBI_ITU_525_F1_STAR
140 ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_
141 ``V4L2_VBI_ITU_625_F2_START`` defines
142 for each field for each 525 or 625 lin
143 Don't forget that ITU line numbering s
144 drivers can return start values 0 if t
145 identify scanning lines, VBI acquisiti
146 information.
147 * - __u32
148 - ``count``\ [#f2]_
149 - The number of lines in the first and s
150 respectively.
151 * - :cspan:`2`
152
153 Drivers should be as flexibility as po
154 be possible to extend or move the VBI
155 picture area, implementing a 'full fie
156 service transmissions embedded in the
157
158 An application can set the first or se
159 if no data is required from the respec
160 if the scanning system is progressive,
161 corresponding start value shall be ign
162 driver. Anyway, drivers may not suppor
163 return both count values non-zero.
164
165 Both ``count`` values set to zero, or
166 bounds depicted\ [#f4]_, or a field im
167 fields, are invalid and shall not be r
168
169 To initialize the ``start`` and ``coun
170 must first determine the current video
171 :ref:`v4l2_std_id <v4l2-std-id>` or th
172 of struct :c:type:`v4l2_standard` can
173 for this purpose.
174 * - __u32
175 - ``flags``
176 - See :ref:`vbifmt-flags` below. Current
177 applications must set this field to ze
178 * - __u32
179 - ``reserved``\ [#f2]_
180 - This array is reserved for future exte
181 applications must set it to zero.
182
183 .. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.4c
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 doe
195 between fields. Normally the VBI image
196 (lower scanning line numbers) first in
197 or bottom field depending on the video
198 set the first or second field may be s
199 fields are still in correct temporal o
200 first in memory. [#f3]_
201 * - ``V4L2_VBI_INTERLACED``
202 - 0x0002
203 - By default the two field images will b
204 lines of the first field followed by a
205 (compare :ref:`field-order` ``V4L2_FIE
206 ``V4L2_FIELD_SEQ_BT``, whether the top
207 memory depends on the video standard).
208 two fields are interlaced (cf. ``V4L2_
209 first line of the first field followed
210 second field, then the two second line
211 may be necessary when the hardware has
212 or output interlaced video images and
213 fields for VBI capturing at the same t
214 this flag implies that both ``count``
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/
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 s
243 therefore the application must choose a new st
244 current standard first. Attempts to read or wr
245 negotiation, or after switching the video stan
246 the negotiated VBI parameters, should be refus
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 numbe
253 implementation, the smallest unit of data pass
254 consisting of two fields of VBI images immedia
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 *
261
262 The sample size is most likely always one byte
263 the ``sample_format`` field though, to functio
264 drivers.
265
266 A VBI device may support :ref:`read/write <rw>
267 (:ref:`memory mapping <mmap>` or :ref:`user po
268 The latter bears the possibility of synchroniz
269 using buffer timestamps.
270
271 Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STR
272 first :c:func:`read()`, :c:func:`write()` and
273 :c:func:`select()` call can be resource alloca
274 points returning an ``EBUSY`` error code if th
275 are temporarily unavailable, for example the d
276 another process.
277
278 .. [#f1]
279 ASK: Amplitude-Shift Keying. A high signal
280 bit, a low level a '0' bit.
281
282 .. [#f2]
283 A few devices may be unable to sample VBI d
284 the video capture window to the VBI region.
285
286 .. [#f3]
287 Most VBI services transmit on both fields,
288 semantics depending on the field number. Th
289 decoded or encoded when ``V4L2_VBI_UNSYNC``
290
291 .. [#f4]
292 The valid values ar shown at :ref:`vbi-525`
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.