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