Commit | Line | Data |
---|---|---|
5377d91f MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
3 | .. _sliced: | |
4 | ||
5 | ************************* | |
6 | Sliced VBI Data Interface | |
7 | ************************* | |
8 | ||
9 | VBI stands for Vertical Blanking Interval, a gap in the sequence of | |
10 | lines of an analog video signal. During VBI no picture information is | |
11 | transmitted, allowing some time while the electron beam of a cathode ray | |
12 | tube TV returns to the top of the screen. | |
13 | ||
14 | Sliced VBI devices use hardware to demodulate data transmitted in the | |
15 | VBI. V4L2 drivers shall *not* do this by software, see also the | |
16 | :ref:`raw VBI interface <raw-vbi>`. The data is passed as short | |
17 | packets of fixed size, covering one scan line each. The number of | |
18 | packets per video frame is variable. | |
19 | ||
20 | Sliced VBI capture and output devices are accessed through the same | |
21 | character special files as raw VBI devices. When a driver supports both | |
22 | interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI | |
23 | capturing or output, and the sliced VBI function is only available after | |
af4a4d0d | 24 | calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as defined |
5377d91f MH |
25 | below. Likewise a ``/dev/video`` device may support the sliced VBI API, |
26 | however the default function here is video capturing or output. | |
27 | Different file descriptors must be used to pass raw and sliced VBI data | |
28 | simultaneously, if this is supported by the driver. | |
29 | ||
30 | ||
31 | Querying Capabilities | |
32 | ===================== | |
33 | ||
34 | Devices supporting the sliced VBI capturing or output API set the | |
35 | ``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag | |
36 | respectively, in the ``capabilities`` field of struct | |
e8be7e97 | 37 | :c:type:`v4l2_capability` returned by the |
7347081e | 38 | :ref:`VIDIOC_QUERYCAP` ioctl. At least one of the |
5377d91f MH |
39 | read/write, streaming or asynchronous :ref:`I/O methods <io>` must be |
40 | supported. Sliced VBI devices may have a tuner or modulator. | |
41 | ||
42 | ||
43 | Supplemental Functions | |
44 | ====================== | |
45 | ||
46 | Sliced VBI devices shall support :ref:`video input or output <video>` | |
47 | and :ref:`tuner or modulator <tuner>` ioctls if they have these | |
7347081e | 48 | capabilities, and they may support :ref:`control` ioctls. |
5377d91f MH |
49 | The :ref:`video standard <standard>` ioctls provide information vital |
50 | to program a sliced VBI device, therefore must be supported. | |
51 | ||
52 | ||
53 | .. _sliced-vbi-format-negotitation: | |
54 | ||
55 | Sliced VBI Format Negotiation | |
56 | ============================= | |
57 | ||
58 | To find out which data services are supported by the hardware | |
59 | applications can call the | |
4e03cb76 | 60 | :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. |
5377d91f MH |
61 | All drivers implementing the sliced VBI interface must support this |
62 | ioctl. The results may differ from those of the | |
af4a4d0d | 63 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl when the number of VBI |
5377d91f MH |
64 | lines the hardware can capture or output per frame, or the number of |
65 | services it can identify on a given line are limited. For example on PAL | |
66 | line 16 the hardware may be able to look for a VPS or Teletext signal, | |
67 | but not both at the same time. | |
68 | ||
69 | To determine the currently selected services applications set the | |
e8be7e97 | 70 | ``type`` field of struct :c:type:`v4l2_format` to |
5377d91f MH |
71 | ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or |
72 | ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the | |
4e03cb76 | 73 | :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl fills the ``fmt.sliced`` |
5377d91f | 74 | member, a struct |
e8be7e97 | 75 | :c:type:`v4l2_sliced_vbi_format`. |
5377d91f MH |
76 | |
77 | Applications can request different parameters by initializing or | |
78 | modifying the ``fmt.sliced`` member and calling the | |
af4a4d0d | 79 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with a pointer to the |
fc78c7c7 | 80 | struct :c:type:`v4l2_format` structure. |
5377d91f MH |
81 | |
82 | The sliced VBI API is more complicated than the raw VBI API because the | |
83 | hardware must be told which VBI service to expect on each scan line. Not | |
84 | all services may be supported by the hardware on all lines (this is | |
85 | especially true for VBI output where Teletext is often unsupported and | |
86 | other services can only be inserted in one specific line). In many | |
87 | cases, however, it is sufficient to just set the ``service_set`` field | |
88 | to the required services and let the driver fill the ``service_lines`` | |
89 | array according to hardware capabilities. Only if more precise control | |
90 | is needed should the programmer set the ``service_lines`` array | |
91 | explicitly. | |
92 | ||
af4a4d0d | 93 | The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl modifies the parameters |
5377d91f | 94 | according to hardware capabilities. When the driver allocates resources |
cdb4af0f | 95 | at this point, it may return an ``EBUSY`` error code if the required |
5377d91f | 96 | resources are temporarily unavailable. Other resource allocation points |
cdb4af0f | 97 | which may return ``EBUSY`` can be the |
7347081e | 98 | :ref:`VIDIOC_STREAMON` ioctl and the first |
5377d91f MH |
99 | :ref:`read() <func-read>`, :ref:`write() <func-write>` and |
100 | :ref:`select() <func-select>` call. | |
101 | ||
102 | ||
e8be7e97 | 103 | .. c:type:: v4l2_sliced_vbi_format |
5377d91f | 104 | |
41dbe0c1 MCC |
105 | struct v4l2_sliced_vbi_format |
106 | ----------------------------- | |
107 | ||
0101036c MCC |
108 | .. tabularcolumns:: |p{1.0cm}|p{4.5cm}|p{4.0cm}|p{4.0cm}|p{4.0cm}| |
109 | ||
110 | .. cssclass:: longtable | |
5bd4bb78 | 111 | |
41dbe0c1 | 112 | .. flat-table:: |
5377d91f MH |
113 | :header-rows: 0 |
114 | :stub-columns: 0 | |
115 | :widths: 3 3 2 2 2 | |
116 | ||
117 | ||
118 | - .. row 1 | |
119 | ||
120 | - __u32 | |
121 | ||
122 | - ``service_set`` | |
123 | ||
124 | - :cspan:`2` | |
125 | ||
0579e6e3 MCC |
126 | If ``service_set`` is non-zero when passed with |
127 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or | |
128 | :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines`` | |
129 | array will be filled by the driver according to the services | |
130 | specified in this field. For example, if ``service_set`` is | |
131 | initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``, | |
132 | a driver for the cx25840 video decoder sets lines 7-22 of both | |
4855307b | 133 | fields [#f1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first |
0579e6e3 MCC |
134 | field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to |
135 | zero, then the values of ``service_lines`` will be used instead. | |
136 | ||
137 | On return the driver sets this field to the union of all elements | |
138 | of the returned ``service_lines`` array. It may contain less | |
139 | services than requested, perhaps just one, if the hardware cannot | |
140 | handle more services simultaneously. It may be empty (zero) if | |
141 | none of the requested services are supported by the hardware. | |
5377d91f MH |
142 | |
143 | - .. row 2 | |
144 | ||
145 | - __u16 | |
146 | ||
8968da9b | 147 | - ``service_lines``\ [2][24] |
5377d91f MH |
148 | |
149 | - :cspan:`2` | |
150 | ||
0579e6e3 MCC |
151 | Applications initialize this array with sets of data services the |
152 | driver shall look for or insert on the respective scan line. | |
153 | Subject to hardware capabilities drivers return the requested set, | |
154 | a subset, which may be just a single service, or an empty set. | |
155 | When the hardware cannot handle multiple services on the same line | |
156 | the driver shall choose one. No assumptions can be made on which | |
157 | service the driver chooses. | |
5377d91f | 158 | |
0579e6e3 | 159 | Data services are defined in :ref:`vbi-services2`. Array indices |
23c751f0 | 160 | map to ITU-R line numbers\ [#f2]_ as follows: |
5377d91f MH |
161 | |
162 | - .. row 3 | |
163 | ||
0579e6e3 MCC |
164 | - |
165 | - | |
5377d91f MH |
166 | - Element |
167 | ||
168 | - 525 line systems | |
169 | ||
170 | - 625 line systems | |
171 | ||
172 | - .. row 4 | |
173 | ||
0579e6e3 MCC |
174 | - |
175 | - | |
8968da9b | 176 | - ``service_lines``\ [0][1] |
5377d91f MH |
177 | |
178 | - 1 | |
179 | ||
180 | - 1 | |
181 | ||
182 | - .. row 5 | |
183 | ||
0579e6e3 MCC |
184 | - |
185 | - | |
8968da9b | 186 | - ``service_lines``\ [0][23] |
5377d91f MH |
187 | |
188 | - 23 | |
189 | ||
190 | - 23 | |
191 | ||
192 | - .. row 6 | |
193 | ||
0579e6e3 MCC |
194 | - |
195 | - | |
8968da9b | 196 | - ``service_lines``\ [1][1] |
5377d91f MH |
197 | |
198 | - 264 | |
199 | ||
200 | - 314 | |
201 | ||
202 | - .. row 7 | |
203 | ||
0579e6e3 MCC |
204 | - |
205 | - | |
8968da9b | 206 | - ``service_lines``\ [1][23] |
5377d91f MH |
207 | |
208 | - 286 | |
209 | ||
210 | - 336 | |
211 | ||
212 | - .. row 8 | |
213 | ||
0579e6e3 MCC |
214 | - |
215 | - | |
8968da9b MCC |
216 | - :cspan:`2` Drivers must set ``service_lines`` [0][0] and |
217 | ``service_lines``\ [1][0] to zero. The | |
0579e6e3 MCC |
218 | ``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``, |
219 | ``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START`` | |
220 | defines give the start line numbers for each field for each 525 or | |
221 | 625 line format as a convenience. Don't forget that ITU line | |
222 | numbering starts at 1, not 0. | |
5377d91f MH |
223 | |
224 | - .. row 9 | |
225 | ||
226 | - __u32 | |
227 | ||
228 | - ``io_size`` | |
229 | ||
230 | - :cspan:`2` Maximum number of bytes passed by one | |
0579e6e3 MCC |
231 | :ref:`read() <func-read>` or :ref:`write() <func-write>` call, |
232 | and the buffer size in bytes for the | |
233 | :ref:`VIDIOC_QBUF` and | |
234 | :ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field | |
235 | to the size of struct | |
e8be7e97 | 236 | :c:type:`v4l2_sliced_vbi_data` times the |
0579e6e3 MCC |
237 | number of non-zero elements in the returned ``service_lines`` |
238 | array (that is the number of lines potentially carrying data). | |
5377d91f MH |
239 | |
240 | - .. row 10 | |
241 | ||
242 | - __u32 | |
243 | ||
8968da9b | 244 | - ``reserved``\ [2] |
5377d91f MH |
245 | |
246 | - :cspan:`2` This array is reserved for future extensions. | |
5377d91f | 247 | |
0101036c | 248 | Applications and drivers must set it to zero. |
5377d91f MH |
249 | |
250 | ||
251 | .. _vbi-services2: | |
252 | ||
41dbe0c1 MCC |
253 | Sliced VBI services |
254 | ------------------- | |
255 | ||
0101036c MCC |
256 | .. raw:: latex |
257 | ||
8c978c08 | 258 | \begin{adjustbox}{width=\columnwidth} |
0101036c MCC |
259 | |
260 | .. tabularcolumns:: |p{5.0cm}|p{1.4cm}|p{3.0cm}|p{2.5cm}|p{9.0cm}| | |
5bd4bb78 | 261 | |
41dbe0c1 | 262 | .. flat-table:: |
5377d91f MH |
263 | :header-rows: 1 |
264 | :stub-columns: 0 | |
265 | :widths: 2 1 1 2 2 | |
266 | ||
267 | ||
268 | - .. row 1 | |
269 | ||
270 | - Symbol | |
271 | ||
272 | - Value | |
273 | ||
274 | - Reference | |
275 | ||
276 | - Lines, usually | |
277 | ||
278 | - Payload | |
279 | ||
280 | - .. row 2 | |
281 | ||
282 | - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B) | |
283 | ||
284 | - 0x0001 | |
285 | ||
0101036c MCC |
286 | - :ref:`ets300706`, |
287 | ||
288 | :ref:`itu653` | |
5377d91f MH |
289 | |
290 | - PAL/SECAM line 7-22, 320-335 (second field 7-22) | |
291 | ||
292 | - Last 42 of the 45 byte Teletext packet, that is without clock | |
0579e6e3 | 293 | run-in and framing code, lsb first transmitted. |
5377d91f MH |
294 | |
295 | - .. row 3 | |
296 | ||
297 | - ``V4L2_SLICED_VPS`` | |
298 | ||
299 | - 0x0400 | |
300 | ||
301 | - :ref:`ets300231` | |
302 | ||
303 | - PAL line 16 | |
304 | ||
305 | - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb | |
0579e6e3 | 306 | first transmitted. |
5377d91f MH |
307 | |
308 | - .. row 4 | |
309 | ||
310 | - ``V4L2_SLICED_CAPTION_525`` | |
311 | ||
312 | - 0x1000 | |
313 | ||
314 | - :ref:`cea608` | |
315 | ||
316 | - NTSC line 21, 284 (second field 21) | |
317 | ||
318 | - Two bytes in transmission order, including parity bit, lsb first | |
0579e6e3 | 319 | transmitted. |
5377d91f MH |
320 | |
321 | - .. row 5 | |
322 | ||
323 | - ``V4L2_SLICED_WSS_625`` | |
324 | ||
325 | - 0x4000 | |
326 | ||
0101036c MCC |
327 | - :ref:`itu1119`, |
328 | ||
329 | :ref:`en300294` | |
5377d91f MH |
330 | |
331 | - PAL/SECAM line 23 | |
332 | ||
0579e6e3 | 333 | - |
5377d91f | 334 | |
0579e6e3 | 335 | :: |
5377d91f | 336 | |
0579e6e3 MCC |
337 | Byte 0 1 |
338 | msb lsb msb lsb | |
339 | Bit 7 6 5 4 3 2 1 0 x x 13 12 11 10 9 | |
5377d91f MH |
340 | |
341 | - .. row 6 | |
342 | ||
343 | - ``V4L2_SLICED_VBI_525`` | |
344 | ||
345 | - 0x1000 | |
346 | ||
347 | - :cspan:`2` Set of services applicable to 525 line systems. | |
348 | ||
349 | - .. row 7 | |
350 | ||
351 | - ``V4L2_SLICED_VBI_625`` | |
352 | ||
353 | - 0x4401 | |
354 | ||
355 | - :cspan:`2` Set of services applicable to 625 line systems. | |
356 | ||
0101036c MCC |
357 | .. raw:: latex |
358 | ||
359 | \end{adjustbox}\newline\newline | |
360 | ||
5377d91f | 361 | |
cdb4af0f | 362 | Drivers may return an ``EINVAL`` error code when applications attempt to |
5377d91f MH |
363 | read or write data without prior format negotiation, after switching the |
364 | video standard (which may invalidate the negotiated VBI parameters) and | |
365 | after switching the video input (which may change the video standard as | |
af4a4d0d | 366 | a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may |
cdb4af0f | 367 | return an ``EBUSY`` error code when applications attempt to change the |
5377d91f | 368 | format while i/o is in progress (between a |
7347081e | 369 | :ref:`VIDIOC_STREAMON` and |
af4a4d0d | 370 | :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first |
5377d91f MH |
371 | :ref:`read() <func-read>` or :ref:`write() <func-write>` call). |
372 | ||
373 | ||
374 | Reading and writing sliced VBI data | |
375 | =================================== | |
376 | ||
377 | A single :ref:`read() <func-read>` or :ref:`write() <func-write>` | |
378 | call must pass all data belonging to one video frame. That is an array | |
fc78c7c7 | 379 | of struct :c:type:`v4l2_sliced_vbi_data` structures with one or |
5377d91f MH |
380 | more elements and a total size not exceeding ``io_size`` bytes. Likewise |
381 | in streaming I/O mode one buffer of ``io_size`` bytes must contain data | |
382 | of one video frame. The ``id`` of unused | |
fc78c7c7 | 383 | struct :c:type:`v4l2_sliced_vbi_data` elements must be zero. |
5377d91f MH |
384 | |
385 | ||
e8be7e97 | 386 | .. c:type:: v4l2_sliced_vbi_data |
5377d91f | 387 | |
41dbe0c1 MCC |
388 | struct v4l2_sliced_vbi_data |
389 | --------------------------- | |
390 | ||
5bd4bb78 MCC |
391 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
392 | ||
41dbe0c1 | 393 | .. flat-table:: |
5377d91f MH |
394 | :header-rows: 0 |
395 | :stub-columns: 0 | |
396 | :widths: 3 1 4 | |
397 | ||
398 | ||
399 | - .. row 1 | |
400 | ||
401 | - __u32 | |
402 | ||
403 | - ``id`` | |
404 | ||
405 | - A flag from :ref:`vbi-services` identifying the type of data in | |
0579e6e3 MCC |
406 | this packet. Only a single bit must be set. When the ``id`` of a |
407 | captured packet is zero, the packet is empty and the contents of | |
408 | other fields are undefined. Applications shall ignore empty | |
409 | packets. When the ``id`` of a packet for output is zero the | |
410 | contents of the ``data`` field are undefined and the driver must | |
411 | no longer insert data on the requested ``field`` and ``line``. | |
5377d91f MH |
412 | |
413 | - .. row 2 | |
414 | ||
415 | - __u32 | |
416 | ||
417 | - ``field`` | |
418 | ||
419 | - The video field number this data has been captured from, or shall | |
0579e6e3 MCC |
420 | be inserted at. ``0`` for the first field, ``1`` for the second |
421 | field. | |
5377d91f MH |
422 | |
423 | - .. row 3 | |
424 | ||
425 | - __u32 | |
426 | ||
427 | - ``line`` | |
428 | ||
429 | - The field (as opposed to frame) line number this data has been | |
0579e6e3 MCC |
430 | captured from, or shall be inserted at. See :ref:`vbi-525` and |
431 | :ref:`vbi-625` for valid values. Sliced VBI capture devices can | |
432 | set the line number of all packets to ``0`` if the hardware cannot | |
433 | reliably identify scan lines. The field number must always be | |
434 | valid. | |
5377d91f MH |
435 | |
436 | - .. row 4 | |
437 | ||
438 | - __u32 | |
439 | ||
440 | - ``reserved`` | |
441 | ||
442 | - This field is reserved for future extensions. Applications and | |
0579e6e3 | 443 | drivers must set it to zero. |
5377d91f MH |
444 | |
445 | - .. row 5 | |
446 | ||
447 | - __u8 | |
448 | ||
8968da9b | 449 | - ``data``\ [48] |
5377d91f MH |
450 | |
451 | - The packet payload. See :ref:`vbi-services` for the contents and | |
0579e6e3 MCC |
452 | number of bytes passed for each data type. The contents of padding |
453 | bytes at the end of this array are undefined, drivers and | |
454 | applications shall ignore them. | |
5377d91f MH |
455 | |
456 | ||
457 | Packets are always passed in ascending line number order, without | |
458 | duplicate line numbers. The :ref:`write() <func-write>` function and | |
cdb4af0f | 459 | the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL`` |
5377d91f MH |
460 | error code when applications violate this rule. They must also return an |
461 | EINVAL error code when applications pass an incorrect field or line | |
462 | number, or a combination of ``field``, ``line`` and ``id`` which has not | |
4e03cb76 | 463 | been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or |
af4a4d0d | 464 | :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are |
5377d91f MH |
465 | unknown the driver must pass the packets in transmitted order. The |
466 | driver can insert empty packets with ``id`` set to zero anywhere in the | |
467 | packet array. | |
468 | ||
469 | To assure synchronization and to distinguish from frame dropping, when a | |
470 | captured frame does not carry any of the requested data services drivers | |
471 | must pass one or more empty packets. When an application fails to pass | |
472 | VBI data in time for output, the driver must output the last VPS and WSS | |
473 | packet again, and disable the output of Closed Caption and Teletext | |
474 | data, or output data which is ignored by Closed Caption and Teletext | |
475 | decoders. | |
476 | ||
477 | A sliced VBI device may support :ref:`read/write <rw>` and/or | |
478 | streaming (:ref:`memory mapping <mmap>` and/or | |
479 | :ref:`user pointer <userp>`) I/O. The latter bears the possibility of | |
480 | synchronizing video and VBI data by using buffer timestamps. | |
481 | ||
482 | ||
483 | Sliced VBI Data in MPEG Streams | |
484 | =============================== | |
485 | ||
486 | If a device can produce an MPEG output stream, it may be capable of | |
487 | providing | |
488 | :ref:`negotiated sliced VBI services <sliced-vbi-format-negotitation>` | |
489 | as data embedded in the MPEG stream. Users or applications control this | |
490 | sliced VBI data insertion with the | |
491 | :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>` | |
492 | control. | |
493 | ||
494 | If the driver does not provide the | |
495 | :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>` | |
496 | control, or only allows that control to be set to | |
497 | :ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`, | |
498 | then the device cannot embed sliced VBI data in the MPEG stream. | |
499 | ||
500 | The | |
501 | :ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>` | |
502 | control does not implicitly set the device driver to capture nor cease | |
503 | capturing sliced VBI data. The control only indicates to embed sliced | |
504 | VBI data in the MPEG stream, if an application has negotiated sliced VBI | |
505 | service be captured. | |
506 | ||
507 | It may also be the case that a device can embed sliced VBI data in only | |
508 | certain types of MPEG streams: for example in an MPEG-2 PS but not an | |
509 | MPEG-2 TS. In this situation, if sliced VBI data insertion is requested, | |
510 | the sliced VBI data will be embedded in MPEG stream types when | |
511 | supported, and silently omitted from MPEG stream types where sliced VBI | |
512 | data insertion is not supported by the device. | |
513 | ||
514 | The following subsections specify the format of the embedded sliced VBI | |
515 | data. | |
516 | ||
517 | ||
518 | MPEG Stream Embedded, Sliced VBI Data Format: NONE | |
519 | -------------------------------------------------- | |
520 | ||
521 | The | |
522 | :ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>` | |
523 | embedded sliced VBI format shall be interpreted by drivers as a control | |
524 | to cease embedding sliced VBI data in MPEG streams. Neither the device | |
525 | nor driver shall insert "empty" embedded sliced VBI data packets in the | |
526 | MPEG stream when this format is set. No MPEG stream data structures are | |
527 | specified for this format. | |
528 | ||
529 | ||
530 | MPEG Stream Embedded, Sliced VBI Data Format: IVTV | |
531 | -------------------------------------------------- | |
532 | ||
533 | The | |
534 | :ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>` | |
535 | embedded sliced VBI format, when supported, indicates to the driver to | |
536 | embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private | |
537 | Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the | |
538 | MPEG stream. | |
539 | ||
540 | *Historical context*: This format specification originates from a | |
541 | custom, embedded, sliced VBI data format used by the ``ivtv`` driver. | |
542 | This format has already been informally specified in the kernel sources | |
543 | in the file ``Documentation/video4linux/cx2341x/README.vbi`` . The | |
544 | maximum size of the payload and other aspects of this format are driven | |
545 | by the CX23415 MPEG decoder's capabilities and limitations with respect | |
546 | to extracting, decoding, and displaying sliced VBI data embedded within | |
547 | an MPEG stream. | |
548 | ||
549 | This format's use is *not* exclusive to the ``ivtv`` driver *nor* | |
550 | exclusive to CX2341x devices, as the sliced VBI data packet insertion | |
551 | into the MPEG stream is implemented in driver software. At least the | |
552 | ``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in | |
553 | this format as well. | |
554 | ||
555 | The following definitions specify the payload of the MPEG-2 *Private | |
556 | Stream 1 PES* packets that contain sliced VBI data when | |
557 | :ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>` | |
558 | is set. (The MPEG-2 *Private Stream 1 PES* packet header and | |
559 | encapsulating MPEG-2 *Program Pack* header are not detailed here. Please | |
560 | refer to the MPEG-2 specifications for details on those packet headers.) | |
561 | ||
562 | The payload of the MPEG-2 *Private Stream 1 PES* packets that contain | |
563 | sliced VBI data is specified by struct | |
e8be7e97 | 564 | :c:type:`v4l2_mpeg_vbi_fmt_ivtv`. The |
5377d91f MH |
565 | payload is variable length, depending on the actual number of lines of |
566 | sliced VBI data present in a video frame. The payload may be padded at | |
567 | the end with unspecified fill bytes to align the end of the payload to a | |
568 | 4-byte boundary. The payload shall never exceed 1552 bytes (2 fields | |
569 | with 18 lines/field with 43 bytes of data/line and a 4 byte magic | |
570 | number). | |
571 | ||
572 | ||
e8be7e97 | 573 | .. c:type:: v4l2_mpeg_vbi_fmt_ivtv |
5377d91f | 574 | |
41dbe0c1 MCC |
575 | struct v4l2_mpeg_vbi_fmt_ivtv |
576 | ----------------------------- | |
577 | ||
0101036c | 578 | .. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{1.0cm}|p{11.5cm}| |
5bd4bb78 | 579 | |
41dbe0c1 | 580 | .. flat-table:: |
5377d91f MH |
581 | :header-rows: 0 |
582 | :stub-columns: 0 | |
583 | :widths: 1 1 1 2 | |
584 | ||
585 | ||
586 | - .. row 1 | |
587 | ||
588 | - __u8 | |
589 | ||
8968da9b | 590 | - ``magic``\ [4] |
5377d91f | 591 | |
0579e6e3 | 592 | - |
5377d91f | 593 | - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that |
0579e6e3 MCC |
594 | indicates this is a valid sliced VBI data payload and also |
595 | indicates which member of the anonymous union, ``itv0`` or | |
596 | ``ITV0``, to use for the payload data. | |
5377d91f MH |
597 | |
598 | - .. row 2 | |
599 | ||
600 | - union | |
601 | ||
602 | - (anonymous) | |
603 | ||
604 | - .. row 3 | |
605 | ||
0579e6e3 | 606 | - |
e8be7e97 | 607 | - struct :c:type:`v4l2_mpeg_vbi_itv0` |
5377d91f MH |
608 | |
609 | - ``itv0`` | |
610 | ||
611 | - The primary form of the sliced VBI data payload that contains | |
0579e6e3 MCC |
612 | anywhere from 1 to 35 lines of sliced VBI data. Line masks are |
613 | provided in this form of the payload indicating which VBI lines | |
614 | are provided. | |
5377d91f MH |
615 | |
616 | - .. row 4 | |
617 | ||
0579e6e3 | 618 | - |
5377d91f MH |
619 | - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>` |
620 | ||
621 | - ``ITV0`` | |
622 | ||
623 | - An alternate form of the sliced VBI data payload used when 36 | |
0579e6e3 MCC |
624 | lines of sliced VBI data are present. No line masks are provided |
625 | in this form of the payload; all valid line mask bits are | |
626 | implcitly set. | |
5377d91f MH |
627 | |
628 | ||
629 | ||
630 | .. _v4l2-mpeg-vbi-fmt-ivtv-magic: | |
631 | ||
41dbe0c1 MCC |
632 | Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field |
633 | ------------------------------------------------------------- | |
634 | ||
5bd4bb78 MCC |
635 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
636 | ||
41dbe0c1 | 637 | .. flat-table:: |
5377d91f MH |
638 | :header-rows: 1 |
639 | :stub-columns: 0 | |
640 | :widths: 3 1 4 | |
641 | ||
642 | ||
643 | - .. row 1 | |
644 | ||
645 | - Defined Symbol | |
646 | ||
647 | - Value | |
648 | ||
649 | - Description | |
650 | ||
651 | - .. row 2 | |
652 | ||
653 | - ``V4L2_MPEG_VBI_IVTV_MAGIC0`` | |
654 | ||
655 | - "itv0" | |
656 | ||
657 | - Indicates the ``itv0`` member of the union in struct | |
e8be7e97 | 658 | :c:type:`v4l2_mpeg_vbi_fmt_ivtv` is |
0579e6e3 | 659 | valid. |
5377d91f MH |
660 | |
661 | - .. row 3 | |
662 | ||
663 | - ``V4L2_MPEG_VBI_IVTV_MAGIC1`` | |
664 | ||
665 | - "ITV0" | |
666 | ||
667 | - Indicates the ``ITV0`` member of the union in struct | |
e8be7e97 | 668 | :c:type:`v4l2_mpeg_vbi_fmt_ivtv` is |
0579e6e3 | 669 | valid and that 36 lines of sliced VBI data are present. |
5377d91f MH |
670 | |
671 | ||
672 | ||
e8be7e97 | 673 | .. c:type:: v4l2_mpeg_vbi_itv0 |
5377d91f | 674 | |
8b98db6b MCC |
675 | .. c:type:: v4l2_mpeg_vbi_ITV0 |
676 | ||
677 | structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0 | |
678 | ------------------------------------------------- | |
41dbe0c1 | 679 | |
0101036c | 680 | .. tabularcolumns:: |p{4.4cm}|p{2.4cm}|p{10.7cm}| |
5bd4bb78 | 681 | |
41dbe0c1 | 682 | .. flat-table:: |
5377d91f MH |
683 | :header-rows: 0 |
684 | :stub-columns: 0 | |
685 | :widths: 1 1 2 | |
686 | ||
687 | ||
688 | - .. row 1 | |
689 | ||
690 | - __le32 | |
691 | ||
8968da9b | 692 | - ``linemask``\ [2] |
5377d91f MH |
693 | |
694 | - Bitmasks indicating the VBI service lines present. These | |
0579e6e3 MCC |
695 | ``linemask`` values are stored in little endian byte order in the |
696 | MPEG stream. Some reference ``linemask`` bit positions with their | |
697 | corresponding VBI line number and video field are given below. | |
698 | b\ :sub:`0` indicates the least significant bit of a ``linemask`` | |
699 | value: | |
5377d91f MH |
700 | |
701 | ||
702 | ||
0579e6e3 | 703 | :: |
5377d91f | 704 | |
8968da9b | 705 | linemask[0] b0: line 6 first field |
0101036c MCC |
706 | linemask[0] b17: line 23 first field |
707 | linemask[0] b18: line 6 second field | |
708 | linemask[0] b31: line 19 second field | |
8968da9b MCC |
709 | linemask[1] b0: line 20 second field |
710 | linemask[1] b3: line 23 second field | |
711 | linemask[1] b4-b31: unused and set to 0 | |
5377d91f MH |
712 | |
713 | - .. row 2 | |
714 | ||
715 | - struct | |
e8be7e97 | 716 | :c:type:`v4l2_mpeg_vbi_itv0_line` |
5377d91f | 717 | |
8968da9b | 718 | - ``line``\ [35] |
5377d91f MH |
719 | |
720 | - This is a variable length array that holds from 1 to 35 lines of | |
0579e6e3 MCC |
721 | sliced VBI data. The sliced VBI data lines present correspond to |
722 | the bits set in the ``linemask`` array, starting from b\ :sub:`0` | |
8968da9b MCC |
723 | of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0], |
724 | and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of | |
725 | ``linemask``\ [1]. ``line``\ [0] corresponds to the first bit | |
726 | found set in the ``linemask`` array, ``line``\ [1] corresponds to | |
0579e6e3 | 727 | the second bit found set in the ``linemask`` array, etc. If no |
8968da9b | 728 | ``linemask`` array bits are set, then ``line``\ [0] may contain |
0579e6e3 MCC |
729 | one line of unspecified data that should be ignored by |
730 | applications. | |
5377d91f MH |
731 | |
732 | ||
733 | ||
734 | .. _v4l2-mpeg-vbi-itv0-1: | |
735 | ||
41dbe0c1 MCC |
736 | struct v4l2_mpeg_vbi_ITV0 |
737 | ------------------------- | |
738 | ||
5bd4bb78 MCC |
739 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
740 | ||
41dbe0c1 | 741 | .. flat-table:: |
5377d91f MH |
742 | :header-rows: 0 |
743 | :stub-columns: 0 | |
744 | :widths: 1 1 2 | |
745 | ||
746 | ||
747 | - .. row 1 | |
748 | ||
749 | - struct | |
e8be7e97 | 750 | :c:type:`v4l2_mpeg_vbi_itv0_line` |
5377d91f | 751 | |
8968da9b | 752 | - ``line``\ [36] |
5377d91f | 753 | |
8968da9b MCC |
754 | - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0] |
755 | through ``line``\ [17] correspond to lines 6 through 23 of the | |
756 | first field. ``line``\ [18] through ``line``\ [35] corresponds to | |
0579e6e3 | 757 | lines 6 through 23 of the second field. |
5377d91f MH |
758 | |
759 | ||
760 | ||
e8be7e97 | 761 | .. c:type:: v4l2_mpeg_vbi_itv0_line |
5377d91f | 762 | |
41dbe0c1 MCC |
763 | struct v4l2_mpeg_vbi_itv0_line |
764 | ------------------------------ | |
765 | ||
5bd4bb78 MCC |
766 | .. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| |
767 | ||
41dbe0c1 | 768 | .. flat-table:: |
5377d91f MH |
769 | :header-rows: 0 |
770 | :stub-columns: 0 | |
771 | :widths: 1 1 2 | |
772 | ||
773 | ||
774 | - .. row 1 | |
775 | ||
776 | - __u8 | |
777 | ||
778 | - ``id`` | |
779 | ||
780 | - A line identifier value from | |
0579e6e3 MCC |
781 | :ref:`ITV0-Line-Identifier-Constants` that indicates the type of |
782 | sliced VBI data stored on this line. | |
5377d91f MH |
783 | |
784 | - .. row 2 | |
785 | ||
786 | - __u8 | |
787 | ||
8968da9b | 788 | - ``data``\ [42] |
5377d91f MH |
789 | |
790 | - The sliced VBI data for the line. | |
791 | ||
792 | ||
793 | ||
794 | .. _ITV0-Line-Identifier-Constants: | |
795 | ||
41dbe0c1 MCC |
796 | Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field |
797 | ------------------------------------------------------------ | |
798 | ||
5bd4bb78 MCC |
799 | .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| |
800 | ||
41dbe0c1 | 801 | .. flat-table:: |
5377d91f MH |
802 | :header-rows: 1 |
803 | :stub-columns: 0 | |
804 | :widths: 3 1 4 | |
805 | ||
806 | ||
807 | - .. row 1 | |
808 | ||
809 | - Defined Symbol | |
810 | ||
811 | - Value | |
812 | ||
813 | - Description | |
814 | ||
815 | - .. row 2 | |
816 | ||
817 | - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B`` | |
818 | ||
819 | - 1 | |
820 | ||
821 | - Refer to :ref:`Sliced VBI services <vbi-services2>` for a | |
0579e6e3 | 822 | description of the line payload. |
5377d91f MH |
823 | |
824 | - .. row 3 | |
825 | ||
826 | - ``V4L2_MPEG_VBI_IVTV_CAPTION_525`` | |
827 | ||
828 | - 4 | |
829 | ||
830 | - Refer to :ref:`Sliced VBI services <vbi-services2>` for a | |
0579e6e3 | 831 | description of the line payload. |
5377d91f MH |
832 | |
833 | - .. row 4 | |
834 | ||
835 | - ``V4L2_MPEG_VBI_IVTV_WSS_625`` | |
836 | ||
837 | - 5 | |
838 | ||
839 | - Refer to :ref:`Sliced VBI services <vbi-services2>` for a | |
0579e6e3 | 840 | description of the line payload. |
5377d91f MH |
841 | |
842 | - .. row 5 | |
843 | ||
844 | - ``V4L2_MPEG_VBI_IVTV_VPS`` | |
845 | ||
846 | - 7 | |
847 | ||
848 | - Refer to :ref:`Sliced VBI services <vbi-services2>` for a | |
0579e6e3 | 849 | description of the line payload. |
5377d91f MH |
850 | |
851 | ||
852 | ||
4855307b | 853 | .. [#f1] |
5377d91f MH |
854 | According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first |
855 | field and lines 5-22 of the second field may carry Teletext data. | |
23c751f0 MCC |
856 | |
857 | .. [#f2] | |
858 | See also :ref:`vbi-525` and :ref:`vbi-625`. |