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