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