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 | |
42 | :ref:`v4l2_capability <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 | |
72 | ``type`` field of a struct :ref:`v4l2_format <v4l2-format>` to | |
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 MH |
75 | structure. Drivers fill the struct |
76 | :ref:`v4l2_vbi_format <v4l2-vbi-format>` ``vbi`` member of the | |
77 | ``fmt`` union. | |
78 | ||
79 | To request different parameters applications set the ``type`` field of a | |
80 | struct :ref:`v4l2_format <v4l2-format>` as above and initialize all | |
81 | fields of the struct :ref:`v4l2_vbi_format <v4l2-vbi-format>` | |
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 MH |
101 | |
102 | ||
103 | .. _v4l2-vbi-format: | |
104 | ||
105 | .. flat-table:: struct v4l2_vbi_format | |
106 | :header-rows: 0 | |
107 | :stub-columns: 0 | |
108 | :widths: 1 1 2 | |
109 | ||
110 | ||
111 | - .. row 1 | |
112 | ||
113 | - __u32 | |
114 | ||
115 | - ``sampling_rate`` | |
116 | ||
117 | - Samples per second, i. e. unit 1 Hz. | |
118 | ||
119 | - .. row 2 | |
120 | ||
121 | - __u32 | |
122 | ||
123 | - ``offset`` | |
124 | ||
125 | - Horizontal offset of the VBI image, relative to the leading edge | |
0579e6e3 MCC |
126 | of the line synchronization pulse and counted in samples: The |
127 | first sample in the VBI image will be located ``offset`` / | |
128 | ``sampling_rate`` seconds following the leading edge. See also | |
129 | :ref:`vbi-hsync`. | |
5377d91f MH |
130 | |
131 | - .. row 3 | |
132 | ||
133 | - __u32 | |
134 | ||
135 | - ``samples_per_line`` | |
136 | ||
0579e6e3 | 137 | - |
5377d91f MH |
138 | |
139 | - .. row 4 | |
140 | ||
141 | - __u32 | |
142 | ||
143 | - ``sample_format`` | |
144 | ||
145 | - Defines the sample format as in :ref:`pixfmt`, a | |
4855307b | 146 | four-character-code. [#f2]_ Usually this is ``V4L2_PIX_FMT_GREY``, |
0579e6e3 MCC |
147 | i. e. each sample consists of 8 bits with lower values oriented |
148 | towards the black level. Do not assume any other correlation of | |
149 | values with the signal level. For example, the MSB does not | |
150 | necessarily indicate if the signal is 'high' or 'low' because 128 | |
151 | may not be the mean value of the signal. Drivers shall not convert | |
152 | the sample format by software. | |
5377d91f MH |
153 | |
154 | - .. row 5 | |
155 | ||
156 | - __u32 | |
157 | ||
4855307b | 158 | - ``start``\ [#f2]_ |
5377d91f MH |
159 | |
160 | - This is the scanning system line number associated with the first | |
0579e6e3 MCC |
161 | line of the VBI image, of the first and the second field |
162 | respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid | |
163 | values. The ``V4L2_VBI_ITU_525_F1_START``, | |
164 | ``V4L2_VBI_ITU_525_F2_START``, ``V4L2_VBI_ITU_625_F1_START`` and | |
165 | ``V4L2_VBI_ITU_625_F2_START`` defines give the start line numbers | |
166 | for each field for each 525 or 625 line format as a convenience. | |
167 | Don't forget that ITU line numbering starts at 1, not 0. VBI input | |
168 | drivers can return start values 0 if the hardware cannot reliable | |
169 | identify scanning lines, VBI acquisition may not require this | |
170 | information. | |
5377d91f MH |
171 | |
172 | - .. row 6 | |
173 | ||
174 | - __u32 | |
175 | ||
4855307b | 176 | - ``count``\ [#f2]_ |
5377d91f MH |
177 | |
178 | - The number of lines in the first and second field image, | |
0579e6e3 | 179 | respectively. |
5377d91f MH |
180 | |
181 | - .. row 7 | |
182 | ||
183 | - :cspan:`2` | |
184 | ||
0579e6e3 MCC |
185 | Drivers should be as flexibility as possible. For example, it may |
186 | be possible to extend or move the VBI capture window down to the | |
187 | picture area, implementing a 'full field mode' to capture data | |
188 | service transmissions embedded in the picture. | |
189 | ||
190 | An application can set the first or second ``count`` value to zero | |
8968da9b | 191 | if no data is required from the respective field; ``count``\ [1] |
0579e6e3 MCC |
192 | if the scanning system is progressive, i. e. not interlaced. The |
193 | corresponding start value shall be ignored by the application and | |
194 | driver. Anyway, drivers may not support single field capturing and | |
195 | return both count values non-zero. | |
196 | ||
197 | Both ``count`` values set to zero, or line numbers outside the | |
198 | bounds depicted in :ref:`vbi-525` and :ref:`vbi-625`, or a | |
199 | field image covering lines of two fields, are invalid and shall | |
200 | not be returned by the driver. | |
201 | ||
202 | To initialize the ``start`` and ``count`` fields, applications | |
203 | must first determine the current video standard selection. The | |
204 | :ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field | |
205 | of struct :ref:`v4l2_standard <v4l2-standard>` can be evaluated | |
206 | for this purpose. | |
5377d91f MH |
207 | |
208 | - .. row 8 | |
209 | ||
210 | - __u32 | |
211 | ||
212 | - ``flags`` | |
213 | ||
214 | - See :ref:`vbifmt-flags` below. Currently only drivers set flags, | |
0579e6e3 | 215 | applications must set this field to zero. |
5377d91f MH |
216 | |
217 | - .. row 9 | |
218 | ||
219 | - __u32 | |
220 | ||
4855307b | 221 | - ``reserved``\ [#f2]_ |
5377d91f MH |
222 | |
223 | - This array is reserved for future extensions. Drivers and | |
0579e6e3 | 224 | applications must set it to zero. |
5377d91f MH |
225 | |
226 | ||
227 | ||
228 | .. _vbifmt-flags: | |
229 | ||
230 | .. flat-table:: Raw VBI Format Flags | |
231 | :header-rows: 0 | |
232 | :stub-columns: 0 | |
233 | :widths: 3 1 4 | |
234 | ||
235 | ||
236 | - .. row 1 | |
237 | ||
238 | - ``V4L2_VBI_UNSYNC`` | |
239 | ||
240 | - 0x0001 | |
241 | ||
242 | - This flag indicates hardware which does not properly distinguish | |
0579e6e3 MCC |
243 | between fields. Normally the VBI image stores the first field |
244 | (lower scanning line numbers) first in memory. This may be a top | |
245 | or bottom field depending on the video standard. When this flag is | |
246 | set the first or second field may be stored first, however the | |
247 | fields are still in correct temporal order with the older field | |
4855307b | 248 | first in memory. [#f3]_ |
5377d91f MH |
249 | |
250 | - .. row 2 | |
251 | ||
252 | - ``V4L2_VBI_INTERLACED`` | |
253 | ||
254 | - 0x0002 | |
255 | ||
256 | - By default the two field images will be passed sequentially; all | |
0579e6e3 MCC |
257 | lines of the first field followed by all lines of the second field |
258 | (compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and | |
259 | ``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in | |
260 | memory depends on the video standard). When this flag is set, the | |
261 | two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The | |
262 | first line of the first field followed by the first line of the | |
263 | second field, then the two second lines, and so on. Such a layout | |
264 | may be necessary when the hardware has been programmed to capture | |
265 | or output interlaced video images and is unable to separate the | |
266 | fields for VBI capturing at the same time. For simplicity setting | |
267 | this flag implies that both ``count`` values are equal and | |
268 | non-zero. | |
5377d91f MH |
269 | |
270 | ||
271 | ||
272 | .. _vbi-hsync: | |
273 | ||
274 | .. figure:: dev-raw-vbi_files/vbi_hsync.* | |
275 | :alt: vbi_hsync.pdf / vbi_hsync.gif | |
276 | :align: center | |
277 | ||
ca023c3d | 278 | **Figure 4.1. Line synchronization** |
5377d91f MH |
279 | |
280 | ||
281 | .. _vbi-525: | |
282 | ||
283 | .. figure:: dev-raw-vbi_files/vbi_525.* | |
284 | :alt: vbi_525.pdf / vbi_525.gif | |
285 | :align: center | |
286 | ||
ca023c3d | 287 | **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)** |
5377d91f MH |
288 | |
289 | ||
290 | ||
291 | .. _vbi-625: | |
292 | ||
293 | .. figure:: dev-raw-vbi_files/vbi_625.* | |
294 | :alt: vbi_625.pdf / vbi_625.gif | |
295 | :align: center | |
296 | ||
ca023c3d | 297 | **Figure 4.3. ITU-R 625 line numbering** |
5377d91f MH |
298 | |
299 | ||
300 | ||
301 | Remember the VBI image format depends on the selected video standard, | |
302 | therefore the application must choose a new standard or query the | |
303 | current standard first. Attempts to read or write data ahead of format | |
304 | negotiation, or after switching the video standard which may invalidate | |
305 | the negotiated VBI parameters, should be refused by the driver. A format | |
306 | change during active I/O is not permitted. | |
307 | ||
308 | ||
309 | Reading and writing VBI images | |
310 | ============================== | |
311 | ||
312 | To assure synchronization with the field number and easier | |
313 | implementation, the smallest unit of data passed at a time is one frame, | |
314 | consisting of two fields of VBI images immediately following in memory. | |
315 | ||
316 | The total size of a frame computes as follows: | |
317 | ||
318 | ||
319 | .. code-block:: c | |
320 | ||
8968da9b | 321 | (count[0] + count[1]) * samples_per_line * sample size in bytes |
5377d91f MH |
322 | |
323 | The sample size is most likely always one byte, applications must check | |
324 | the ``sample_format`` field though, to function properly with other | |
325 | drivers. | |
326 | ||
327 | A VBI device may support :ref:`read/write <rw>` and/or streaming | |
328 | (:ref:`memory mapping <mmap>` or :ref:`user pointer <userp>`) I/O. | |
329 | The latter bears the possibility of synchronizing video and VBI data by | |
330 | using buffer timestamps. | |
331 | ||
ca023c3d MCC |
332 | Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the |
333 | first :ref:`read() <func-read>`, :ref:`write() <func-write>` and | |
334 | :ref:`select() <func-select>` call can be resource allocation | |
cdb4af0f | 335 | points returning an ``EBUSY`` error code if the required hardware resources |
5377d91f MH |
336 | are temporarily unavailable, for example the device is already in use by |
337 | another process. | |
338 | ||
4855307b | 339 | .. [#f1] |
5377d91f MH |
340 | ASK: Amplitude-Shift Keying. A high signal level represents a '1' |
341 | bit, a low level a '0' bit. | |
342 | ||
4855307b | 343 | .. [#f2] |
5377d91f MH |
344 | A few devices may be unable to sample VBI data at all but can extend |
345 | the video capture window to the VBI region. | |
346 | ||
4855307b | 347 | .. [#f3] |
5377d91f MH |
348 | Most VBI services transmit on both fields, but some have different |
349 | semantics depending on the field number. These cannot be reliable | |
350 | decoded or encoded when ``V4L2_VBI_UNSYNC`` is set. |