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