Sliced VBI 데이터 인터페이스

Sliced VBI 모델과 capability

VBI는 Vertical Blanking Interval로, 아날로그 video signal의 line sequence 사이에서 CRT electron beam이 화면 위로 복귀하는 동안 영상 정보가 없는 구간입니다.

Sliced VBI 장치는 VBI에 실린 data를 hardware로 demodulate합니다. V4L2 드라이버가 software로 demodulation해서는 안 됩니다. Raw VBI가 sample image를 전달하는 것과 달리 sliced VBI는 scan line 하나를 나타내는 고정 크기의 짧은 packet을 전달하며, video frame마다 packet 수는 달라질 수 있습니다.

Raw VBI와 sliced VBI는 같은 `/dev/vbi` character device를 사용합니다. 둘 다 지원하면 기본 기능은 raw VBI이고 `VIDIOC_S_FMT`를 호출한 뒤 sliced 기능을 사용합니다. `/dev/video`에서도 sliced VBI를 제공할 수 있지만 기본 기능은 video capture/output입니다.

드라이버가 raw와 sliced VBI 동시 전달을 지원한다면 서로 다른 file descriptor를 사용해야 합니다. Capture는 `V4L2_CAP_SLICED_VBI_CAPTURE`, output은 `V4L2_CAP_SLICED_VBI_OUTPUT`을 `VIDIOC_QUERYCAP` 결과에 설정하며 read/write 또는 streaming I/O 중 적어도 하나를 지원해야 합니다.

장치에 해당 기능이 있다면 video input/output과 tuner/modulator ioctl을 지원하고 control ioctl도 지원할 수 있습니다. Sliced VBI program에 필수인 video standard ioctl은 반드시 지원해야 합니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: V4L

.. _sliced:

*************************
Sliced VBI Data Interface
*************************

VBI stands for Vertical Blanking Interval, a gap in the sequence of
lines of an analog video signal. During VBI no picture information is
transmitted, allowing some time while the electron beam of a cathode ray
tube TV returns to the top of the screen.

Sliced VBI devices use hardware to demodulate data transmitted in the
VBI. V4L2 drivers shall *not* do this by software, see also the
:ref:`raw VBI interface <raw-vbi>`. The data is passed as short
packets of fixed size, covering one scan line each. The number of
packets per video frame is variable.

Sliced VBI capture and output devices are accessed through the same
character special files as raw VBI devices. When a driver supports both
interfaces, the default function of a ``/dev/vbi`` device is *raw* VBI
capturing or output, and the sliced VBI function is only available after
calling the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as defined
below. Likewise a ``/dev/video`` device may support the sliced VBI API,
however the default function here is video capturing or output.
Different file descriptors must be used to pass raw and sliced VBI data
simultaneously, if this is supported by the driver.

Querying Capabilities
=====================

Devices supporting the sliced VBI capturing or output API set the
``V4L2_CAP_SLICED_VBI_CAPTURE`` or ``V4L2_CAP_SLICED_VBI_OUTPUT`` flag
respectively, in the ``capabilities`` field of struct
:c:type:`v4l2_capability` returned by the
:ref:`VIDIOC_QUERYCAP` ioctl. At least one of the
read/write or streaming :ref:`I/O methods <io>` must be
supported. Sliced VBI devices may have a tuner or modulator.

Supplemental Functions
======================

Sliced VBI devices shall support :ref:`video input or output <video>`
and :ref:`tuner or modulator <tuner>` ioctls if they have these
capabilities, and they may support :ref:`control` ioctls.
The :ref:`video standard <standard>` ioctls provide information vital
to program a sliced VBI device, therefore must be supported.

.. _sliced-vbi-format-negotiation:

Service capability와 format 협상

Hardware가 지원하는 data service는 모든 sliced VBI 드라이버가 구현해야 하는 `VIDIOC_G_SLICED_VBI_CAP`으로 조회합니다. 이 결과는 실제 `VIDIOC_S_FMT` 결과와 다를 수 있습니다. Frame당 처리 가능한 VBI line 수나 한 line에서 식별할 수 있는 service 수가 제한되기 때문입니다. 예를 들어 PAL line 16에서 VPS와 Teletext를 각각 찾을 수 있어도 동시에 찾지는 못할 수 있습니다.

현재 선택된 service를 조회하려면 `struct v4l2_format.type`을 `V4L2_BUF_TYPE_SLICED_VBI_CAPTURE` 또는 `V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`으로 설정하고 `VIDIOC_G_FMT`를 호출합니다. 결과는 `fmt.sliced`의 `struct v4l2_sliced_vbi_format`에 들어갑니다.

다른 매개변수는 `fmt.sliced`를 초기화하거나 현재 결과를 수정한 뒤 `VIDIOC_S_FMT`로 요청합니다. 일반적인 경우에는 필요한 service를 `service_set`에 넣고 드라이버가 hardware capability에 따라 `service_lines`를 채우게 하면 됩니다. Scan line별 service를 정밀하게 통제할 때만 배열을 직접 설정합니다.

Output 장치는 Teletext를 지원하지 않거나 특정 service를 정확히 한 line에만 삽입할 수 있는 경우가 흔합니다. `VIDIOC_S_FMT`는 이런 제약에 맞춰 값을 수정합니다. 이 호출과 `VIDIOC_STREAMON`, 첫 `read()`, `write()`, `select()`는 자원 할당 지점이라 자원이 없으면 `EBUSY`를 반환할 수 있습니다.

Sliced VBI Format Negotiation
=============================

To find out which data services are supported by the hardware
applications can call the
:ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl.
All drivers implementing the sliced VBI interface must support this
ioctl. The results may differ from those of the
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl when the number of VBI
lines the hardware can capture or output per frame, or the number of
services it can identify on a given line are limited. For example on PAL
line 16 the hardware may be able to look for a VPS or Teletext signal,
but not both at the same time.

To determine the currently selected services applications set the
``type`` field of struct :c:type:`v4l2_format` to
``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``, and the
:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl fills the ``fmt.sliced``
member, a struct
:c:type:`v4l2_sliced_vbi_format`.

Applications can request different parameters by initializing or
modifying the ``fmt.sliced`` member and calling the
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl with a pointer to the
struct :c:type:`v4l2_format` structure.

The sliced VBI API is more complicated than the raw VBI API because the
hardware must be told which VBI service to expect on each scan line. Not
all services may be supported by the hardware on all lines (this is
especially true for VBI output where Teletext is often unsupported and
other services can only be inserted in one specific line). In many
cases, however, it is sufficient to just set the ``service_set`` field
to the required services and let the driver fill the ``service_lines``
array according to hardware capabilities. Only if more precise control
is needed should the programmer set the ``service_lines`` array
explicitly.

The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl modifies the parameters
according to hardware capabilities. When the driver allocates resources
at this point, it may return an ``EBUSY`` error code if the required
resources are temporarily unavailable. Other resource allocation points
which may return ``EBUSY`` can be the
:ref:`VIDIOC_STREAMON` ioctl and the first
:c:func:`read()`, :c:func:`write()` and
:c:func:`select()` call.

v4l2_sliced_vbi_format 필드

`service_set`이 `VIDIOC_S_FMT` 또는 `VIDIOC_TRY_FMT` 입력에서 0이 아니면 드라이버는 이 bitmask가 요청한 service를 기준으로 `service_lines`를 채웁니다. 예를 들어 `V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625`를 cx25840 decoder에 요청하면 두 field의 line 7-22에 Teletext B, 첫 field의 line 23에 WSS 625를 설정할 수 있습니다.

입력 `service_set`이 0이면 애플리케이션이 채운 `service_lines`를 사용합니다. 반환할 때 드라이버는 실제 `service_lines` 모든 원소의 union을 `service_set`에 넣습니다. 동시에 여러 service를 처리할 수 없다면 요청보다 적은 subset, 하나의 service, 또는 지원 항목이 없을 때 0을 반환할 수 있습니다.

`service_lines[2][24]`는 각 scan line에서 찾거나 삽입할 service set입니다. Hardware가 같은 line의 여러 service를 처리할 수 없으면 그중 하나를 선택하며 애플리케이션은 무엇이 선택될지 가정해서는 안 됩니다.

배열 index는 ITU-R line number에 대응합니다. `[0][1]`과 `[0][23]`은 두 체계 모두 첫 field line 1과 23입니다. `[1][1]`은 525-line에서 264, 625-line에서 314이고 `[1][23]`은 각각 286과 336입니다. `[0][0]`과 `[1][0]`은 반드시 0이며 ITU line numbering은 0이 아니라 1에서 시작합니다.

`io_size`는 한 `read()`/`write()`의 최대 byte 수이자 `VIDIOC_QBUF`/`VIDIOC_DQBUF` buffer 크기입니다. 드라이버는 `sizeof(struct v4l2_sliced_vbi_data)`에 반환된 `service_lines`의 non-zero 원소 수를 곱해 계산합니다. `reserved[2]`는 양쪽 모두 0으로 설정합니다.

.. c:type:: v4l2_sliced_vbi_format

struct v4l2_sliced_vbi_format
-----------------------------

.. raw:: latex

    \begingroup
    \scriptsize
    \setlength{\tabcolsep}{2pt}

.. tabularcolumns:: |p{.85cm}|p{3.3cm}|p{4.45cm}|p{4.45cm}|p{4.45cm}|

.. cssclass:: longtable

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 3 2 2 2

    * - __u16
      - ``service_set``
      - :cspan:`2`

	If ``service_set`` is non-zero when passed with
	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` or
	:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>`, the ``service_lines``
	array will be filled by the driver according to the services
	specified in this field. For example, if ``service_set`` is
	initialized with ``V4L2_SLICED_TELETEXT_B | V4L2_SLICED_WSS_625``,
	a driver for the cx25840 video decoder sets lines 7-22 of both
	fields [#f1]_ to ``V4L2_SLICED_TELETEXT_B`` and line 23 of the first
	field to ``V4L2_SLICED_WSS_625``. If ``service_set`` is set to
	zero, then the values of ``service_lines`` will be used instead.

	On return the driver sets this field to the union of all elements
	of the returned ``service_lines`` array. It may contain less
	services than requested, perhaps just one, if the hardware cannot
	handle more services simultaneously. It may be empty (zero) if
	none of the requested services are supported by the hardware.
    * - __u16
      - ``service_lines``\ [2][24]
      - :cspan:`2`

	Applications initialize this array with sets of data services the
	driver shall look for or insert on the respective scan line.
	Subject to hardware capabilities drivers return the requested set,
	a subset, which may be just a single service, or an empty set.
	When the hardware cannot handle multiple services on the same line
	the driver shall choose one. No assumptions can be made on which
	service the driver chooses.

	Data services are defined in :ref:`vbi-services2`. Array indices
	map to ITU-R line numbers\ [#f2]_ as follows:
    * -
      -
      - Element
      - 525 line systems
      - 625 line systems
    * -
      -
      - ``service_lines``\ [0][1]
      - 1
      - 1
    * -
      -
      - ``service_lines``\ [0][23]
      - 23
      - 23
    * -
      -
      - ``service_lines``\ [1][1]
      - 264
      - 314
    * -
      -
      - ``service_lines``\ [1][23]
      - 286
      - 336
    * -
      -
      - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
	``service_lines``\ [1][0] to zero. The
	``V4L2_VBI_ITU_525_F1_START``, ``V4L2_VBI_ITU_525_F2_START``,
	``V4L2_VBI_ITU_625_F1_START`` and ``V4L2_VBI_ITU_625_F2_START``
	defines give the start line numbers for each field for each 525 or
	625 line format as a convenience. Don't forget that ITU line
	numbering starts at 1, not 0.
    * - __u32
      - ``io_size``
      - :cspan:`2` Maximum number of bytes passed by one
	:c:func:`read()` or :c:func:`write()` call,
	and the buffer size in bytes for the
	:ref:`VIDIOC_QBUF` and
	:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>` ioctl. Drivers set this field
	to the size of struct
	:c:type:`v4l2_sliced_vbi_data` times the
	number of non-zero elements in the returned ``service_lines``
	array (that is the number of lines potentially carrying data).
    * - __u32
      - ``reserved``\ [2]
      - :cspan:`2` This array is reserved for future extensions.

	Applications and drivers must set it to zero.

.. raw:: latex

    \endgroup

.. _vbi-services2:

Sliced VBI service와 상태 전환 오류

`V4L2_SLICED_TELETEXT_B` 값은 `0x0001`이며 PAL/SECAM의 첫 field line 7-22와 두 번째 field의 대응 line 320-335에서 사용합니다. Payload는 45-byte Teletext packet에서 clock run-in과 framing code를 뺀 마지막 42 byte이고 lsb가 먼저 전송됩니다.

`V4L2_SLICED_VPS`는 `0x0400`, 일반적으로 PAL line 16이며 ETS 300 231 Figure 9의 byte 3-15를 lsb first로 전달합니다. `V4L2_SLICED_CAPTION_525`는 `0x1000`, NTSC line 21과 두 번째 field line 284에서 parity bit를 포함한 두 byte를 전송 순서대로 전달합니다.

`V4L2_SLICED_WSS_625`는 `0x4000`이고 PAL/SECAM line 23을 사용합니다. 525-line service 집합 `V4L2_SLICED_VBI_525`는 `0x1000`, 625-line 집합 `V4L2_SLICED_VBI_625`는 `0x4401`입니다.

Format 협상 전에 I/O하거나, video standard 또는 input을 바꿔 기존 VBI 매개변수가 무효가 된 뒤 read/write하면 드라이버는 `EINVAL`을 반환할 수 있습니다. `VIDIOC_STREAMON`과 `VIDIOC_STREAMOFF` 사이 또는 첫 read/write 뒤 I/O 진행 중에 `VIDIOC_S_FMT`로 format을 바꾸면 `EBUSY`가 가능합니다.

Sliced VBI services
-------------------

.. raw:: latex

    \footnotesize

.. tabularcolumns:: |p{4.2cm}|p{1.1cm}|p{2.1cm}|p{2.0cm}|p{6.5cm}|

.. flat-table::
    :header-rows:  1
    :stub-columns: 0
    :widths:       2 1 1 2 2

    * - Symbol
      - Value
      - Reference
      - Lines, usually
      - Payload
    * - ``V4L2_SLICED_TELETEXT_B`` (Teletext System B)
      - 0x0001
      - :ref:`ets300706`,

	:ref:`itu653`
      - PAL/SECAM line 7-22, 320-335 (second field 7-22)
      - Last 42 of the 45 byte Teletext packet, that is without clock
	run-in and framing code, lsb first transmitted.
    * - ``V4L2_SLICED_VPS``
      - 0x0400
      - :ref:`ets300231`
      - PAL line 16
      - Byte number 3 to 15 according to Figure 9 of ETS 300 231, lsb
	first transmitted.
    * - ``V4L2_SLICED_CAPTION_525``
      - 0x1000
      - :ref:`cea608`
      - NTSC line 21, 284 (second field 21)
      - Two bytes in transmission order, including parity bit, lsb first
	transmitted.
    * - ``V4L2_SLICED_WSS_625``
      - 0x4000
      - :ref:`itu1119`,

	:ref:`en300294`
      - PAL/SECAM line 23
      -  See :ref:`v4l2-sliced-wss-625-payload` below.
    * - ``V4L2_SLICED_VBI_525``
      - 0x1000
      - :cspan:`2` Set of services applicable to 525 line systems.
    * - ``V4L2_SLICED_VBI_625``
      - 0x4401
      - :cspan:`2` Set of services applicable to 625 line systems.

.. raw:: latex

    \normalsize

Drivers may return an ``EINVAL`` error code when applications attempt to
read or write data without prior format negotiation, after switching the
video standard (which may invalidate the negotiated VBI parameters) and
after switching the video input (which may change the video standard as
a side effect). The :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl may
return an ``EBUSY`` error code when applications attempt to change the
format while i/o is in progress (between a
:ref:`VIDIOC_STREAMON` and
:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` call, and after the first
:c:func:`read()` or :c:func:`write()` call).

.. _v4l2-sliced-wss-625-payload:

V4L2_SLICED_WSS_625 payload

WSS 625 payload는 14 bit를 두 byte에 배치합니다. Byte 0의 bit 7부터 0에는 WSS bit 7부터 0이 그대로 들어갑니다. Byte 1의 상위 두 bit는 사용하지 않고, bit 5부터 0에 WSS bit 13부터 8을 넣습니다.

V4L2_SLICED_WSS_625 payload
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The payload for ``V4L2_SLICED_WSS_625`` is:

           +-----+------------------+-----------------------+
	   |Byte |        0         |           1           |
           +-----+--------+---------+-----------+-----------+
	   |     | msb    | lsb     | msb       | lsb       |
           |     +-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+
	   | Bit |7|6|5|4 | 3|2|1|0 | x|x|13|12 | 11|10|9|8 |
           +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+

Frame I/O와 v4l2_sliced_vbi_data

한 `read()` 또는 `write()`는 video frame 하나에 속한 모든 data를 전달해야 합니다. 하나 이상의 `struct v4l2_sliced_vbi_data` 배열이며 총 크기는 `io_size`를 넘을 수 없습니다. Streaming에서도 `io_size` byte buffer 하나가 frame 하나를 담고, 사용하지 않는 원소의 `id`는 0이어야 합니다.

`id`는 packet의 service type을 나타내며 정확히 한 bit만 설정해야 합니다. Capture packet의 id가 0이면 빈 packet이므로 다른 필드는 정의되지 않고 애플리케이션이 무시합니다. Output packet의 id가 0이면 data가 정의되지 않으며 드라이버는 지정 field/line에 더 이상 data를 삽입하지 않습니다.

`field`는 첫 field에서 0, 두 번째 field에서 1입니다. `line`은 frame 번호가 아니라 field 안의 line number입니다. Capture hardware가 scan line을 식별하지 못하면 모든 line을 0으로 둘 수 있지만 field는 항상 유효해야 합니다. `reserved`는 0이고 `data[48]`에는 service별 payload가 들어가며 끝 padding byte는 정의되지 않아 무시합니다.

Packet은 중복 line 없이 line number 오름차순으로 전달해야 합니다. Output `write()`와 `VIDIOC_QBUF`는 순서·중복 규칙, field/line 유효성, 협상되지 않은 field/line/id 조합을 위반하면 `EINVAL`을 반환해야 합니다. Line number를 모르면 전송 순서로 전달하고 빈 packet은 배열 어디에나 둘 수 있습니다.

요청 service가 없는 capture frame도 frame drop과 구분하고 동기화를 유지하도록 하나 이상의 빈 packet을 전달해야 합니다. 애플리케이션이 output VBI data를 제때 주지 못하면 드라이버는 마지막 VPS와 WSS를 반복하고 Closed Caption과 Teletext output을 끄거나 decoder가 무시할 data를 내보내야 합니다.

장치는 read/write와 mmap 또는 user pointer streaming을 지원할 수 있습니다. Streaming buffer timestamp를 이용하면 video와 sliced VBI data를 동기화할 수 있습니다.

Reading and writing sliced VBI data
===================================

A single :c:func:`read()` or :c:func:`write()`
call must pass all data belonging to one video frame. That is an array
of struct :c:type:`v4l2_sliced_vbi_data` structures with one or
more elements and a total size not exceeding ``io_size`` bytes. Likewise
in streaming I/O mode one buffer of ``io_size`` bytes must contain data
of one video frame. The ``id`` of unused
struct :c:type:`v4l2_sliced_vbi_data` elements must be zero.

.. c:type:: v4l2_sliced_vbi_data

struct v4l2_sliced_vbi_data
---------------------------

.. tabularcolumns:: |p{1.2cm}|p{2.2cm}|p{13.9cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - __u32
      - ``id``
      - A flag from :ref:`vbi-services` identifying the type of data in
	this packet. Only a single bit must be set. When the ``id`` of a
	captured packet is zero, the packet is empty and the contents of
	other fields are undefined. Applications shall ignore empty
	packets. When the ``id`` of a packet for output is zero the
	contents of the ``data`` field are undefined and the driver must
	no longer insert data on the requested ``field`` and ``line``.
    * - __u32
      - ``field``
      - The video field number this data has been captured from, or shall
	be inserted at. ``0`` for the first field, ``1`` for the second
	field.
    * - __u32
      - ``line``
      - The field (as opposed to frame) line number this data has been
	captured from, or shall be inserted at. See :ref:`vbi-525` and
	:ref:`vbi-625` for valid values. Sliced VBI capture devices can
	set the line number of all packets to ``0`` if the hardware cannot
	reliably identify scan lines. The field number must always be
	valid.
    * - __u32
      - ``reserved``
      - This field is reserved for future extensions. Applications and
	drivers must set it to zero.
    * - __u8
      - ``data``\ [48]
      - The packet payload. See :ref:`vbi-services` for the contents and
	number of bytes passed for each data type. The contents of padding
	bytes at the end of this array are undefined, drivers and
	applications shall ignore them.

Packets are always passed in ascending line number order, without
duplicate line numbers. The :c:func:`write()` function and
the :ref:`VIDIOC_QBUF` ioctl must return an ``EINVAL``
error code when applications violate this rule. They must also return an
EINVAL error code when applications pass an incorrect field or line
number, or a combination of ``field``, ``line`` and ``id`` which has not
been negotiated with the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` or
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. When the line numbers are
unknown the driver must pass the packets in transmitted order. The
driver can insert empty packets with ``id`` set to zero anywhere in the
packet array.

To assure synchronization and to distinguish from frame dropping, when a
captured frame does not carry any of the requested data services drivers
must pass one or more empty packets. When an application fails to pass
VBI data in time for output, the driver must output the last VPS and WSS
packet again, and disable the output of Closed Caption and Teletext
data, or output data which is ignored by Closed Caption and Teletext
decoders.

A sliced VBI device may support :ref:`read/write <rw>` and/or
streaming (:ref:`memory mapping <mmap>` and/or
:ref:`user pointer <userp>`) I/O. The latter bears the possibility of
synchronizing video and VBI data by using buffer timestamps.

MPEG stream 삽입과 NONE 형식

MPEG output stream을 만드는 장치는 협상된 sliced VBI service를 MPEG stream에 embedded data로 넣을 수 있습니다. 사용자는 `V4L2_CID_MPEG_STREAM_VBI_FMT` control로 삽입 형식을 선택합니다.

이 control이 없거나 `V4L2_MPEG_STREAM_VBI_FMT_NONE`만 허용하면 MPEG stream에 sliced VBI를 넣을 수 없습니다. Control 설정은 sliced VBI capture를 시작하거나 중지하지 않으며, 애플리케이션이 별도로 capture service를 협상한 경우 그 data를 MPEG에 embed하라는 지시만 합니다.

장치가 MPEG-2 PS에는 삽입하지만 MPEG-2 TS에는 삽입하지 못하는 것처럼 stream type별 지원이 다를 수 있습니다. 이때 지원하는 stream type에는 넣고 지원하지 않는 type에서는 경고 없이 생략합니다.

`V4L2_MPEG_STREAM_VBI_FMT_NONE`은 embedded sliced VBI 삽입 중지를 뜻합니다. Device와 driver는 빈 embedded packet조차 MPEG stream에 넣어서는 안 되며 이 형식에는 MPEG data structure가 정의되지 않습니다.

Sliced VBI Data in MPEG Streams
===============================

If a device can produce an MPEG output stream, it may be capable of
providing
:ref:`negotiated sliced VBI services <sliced-vbi-format-negotiation>`
as data embedded in the MPEG stream. Users or applications control this
sliced VBI data insertion with the
:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
control.

If the driver does not provide the
:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
control, or only allows that control to be set to
:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`,
then the device cannot embed sliced VBI data in the MPEG stream.

The
:ref:`V4L2_CID_MPEG_STREAM_VBI_FMT <v4l2-mpeg-stream-vbi-fmt>`
control does not implicitly set the device driver to capture nor cease
capturing sliced VBI data. The control only indicates to embed sliced
VBI data in the MPEG stream, if an application has negotiated sliced VBI
service be captured.

It may also be the case that a device can embed sliced VBI data in only
certain types of MPEG streams: for example in an MPEG-2 PS but not an
MPEG-2 TS. In this situation, if sliced VBI data insertion is requested,
the sliced VBI data will be embedded in MPEG stream types when
supported, and silently omitted from MPEG stream types where sliced VBI
data insertion is not supported by the device.

The following subsections specify the format of the embedded sliced VBI
data.

MPEG Stream Embedded, Sliced VBI Data Format: NONE
--------------------------------------------------

The
:ref:`V4L2_MPEG_STREAM_VBI_FMT_NONE <v4l2-mpeg-stream-vbi-fmt>`
embedded sliced VBI format shall be interpreted by drivers as a control
to cease embedding sliced VBI data in MPEG streams. Neither the device
nor driver shall insert "empty" embedded sliced VBI data packets in the
MPEG stream when this format is set. No MPEG stream data structures are
specified for this format.

IVTV embedded 형식과 크기 제한

`V4L2_MPEG_STREAM_VBI_FMT_IVTV`는 frame당 최대 36 line의 sliced VBI data를 MPEG-2 Program Pack 안의 MPEG-2 Private Stream 1 PES packet으로 삽입합니다.

이 형식은 `ivtv` 드라이버의 custom embedded format에서 시작했고 CX23415 MPEG decoder의 추출·decode·표시 능력과 제한이 payload 크기를 결정했습니다. 그러나 software가 packet을 삽입하므로 ivtv나 CX2341x에만 한정되지 않으며 `cx18`도 MPEG-2 PS에 같은 형식으로 넣습니다.

여기서는 Private Stream 1 PES payload만 정의하고 PES header와 이를 감싸는 Program Pack header는 MPEG-2 규격을 따릅니다. Payload는 frame에 실제로 있는 VBI line 수에 따라 가변 길이이고, 끝을 4-byte boundary에 맞추기 위해 정의되지 않은 fill byte를 붙일 수 있습니다.

Payload는 절대 1552 byte를 넘지 않습니다. 이는 field당 18 line, 두 field의 36 line에 line당 43 byte와 4-byte magic을 더한 최대 크기입니다.

MPEG Stream Embedded, Sliced VBI Data Format: IVTV
--------------------------------------------------

The
:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
embedded sliced VBI format, when supported, indicates to the driver to
embed up to 36 lines of sliced VBI data per frame in an MPEG-2 *Private
Stream 1 PES* packet encapsulated in an MPEG-2 *Program Pack* in the
MPEG stream.

*Historical context*: This format specification originates from a
custom, embedded, sliced VBI data format used by the ``ivtv`` driver.
This format has already been informally specified in the kernel sources
in the file ``Documentation/userspace-api/media/drivers/cx2341x-uapi.rst`` . The
maximum size of the payload and other aspects of this format are driven
by the CX23415 MPEG decoder's capabilities and limitations with respect
to extracting, decoding, and displaying sliced VBI data embedded within
an MPEG stream.

This format's use is *not* exclusive to the ``ivtv`` driver *nor*
exclusive to CX2341x devices, as the sliced VBI data packet insertion
into the MPEG stream is implemented in driver software. At least the
``cx18`` driver provides sliced VBI data insertion into an MPEG-2 PS in
this format as well.

The following definitions specify the payload of the MPEG-2 *Private
Stream 1 PES* packets that contain sliced VBI data when
:ref:`V4L2_MPEG_STREAM_VBI_FMT_IVTV <v4l2-mpeg-stream-vbi-fmt>`
is set. (The MPEG-2 *Private Stream 1 PES* packet header and
encapsulating MPEG-2 *Program Pack* header are not detailed here. Please
refer to the MPEG-2 specifications for details on those packet headers.)

The payload of the MPEG-2 *Private Stream 1 PES* packets that contain
sliced VBI data is specified by struct
:c:type:`v4l2_mpeg_vbi_fmt_ivtv`. The
payload is variable length, depending on the actual number of lines of
sliced VBI data present in a video frame. The payload may be padded at
the end with unspecified fill bytes to align the end of the payload to a
4-byte boundary. The payload shall never exceed 1552 bytes (2 fields
with 18 lines/field with 43 bytes of data/line and a 4 byte magic
number).

.. c:type:: v4l2_mpeg_vbi_fmt_ivtv

v4l2_mpeg_vbi_fmt_ivtv와 magic

`struct v4l2_mpeg_vbi_fmt_ivtv.magic[4]`은 payload가 유효한 sliced VBI data인지 확인하고 anonymous union의 `itv0` 또는 `ITV0` 중 어느 멤버를 해석할지 결정합니다.

Primary `struct v4l2_mpeg_vbi_itv0 itv0` 형식은 1~35 line을 담고 `linemask`로 포함된 VBI line을 표시합니다. Alternate `struct v4l2_mpeg_vbi_ITV0 ITV0` 형식은 정확히 36 line일 때 쓰며 line mask 없이 모든 유효 mask bit가 설정된 것으로 간주합니다.

`V4L2_MPEG_VBI_IVTV_MAGIC0` 값 `itv0`은 소문자 union 멤버가 유효함을 뜻합니다. `V4L2_MPEG_VBI_IVTV_MAGIC1` 값 `ITV0`은 대문자 멤버가 유효하고 36 line이 모두 존재함을 뜻합니다.

struct v4l2_mpeg_vbi_fmt_ivtv
-----------------------------

.. tabularcolumns:: |p{4.2cm}|p{2.0cm}|p{11.1cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u8
      - ``magic``\ [4]
      - A "magic" constant from :ref:`v4l2-mpeg-vbi-fmt-ivtv-magic` that
	indicates this is a valid sliced VBI data payload and also
	indicates which member of the anonymous union, ``itv0`` or
	``ITV0``, to use for the payload data.
    * - union {
      - (anonymous)
    * - struct :c:type:`v4l2_mpeg_vbi_itv0`
      - ``itv0``
      - The primary form of the sliced VBI data payload that contains
	anywhere from 1 to 35 lines of sliced VBI data. Line masks are
	provided in this form of the payload indicating which VBI lines
	are provided.
    * - struct :ref:`v4l2_mpeg_vbi_ITV0 <v4l2-mpeg-vbi-itv0-1>`
      - ``ITV0``
      - An alternate form of the sliced VBI data payload used when 36
	lines of sliced VBI data are present. No line masks are provided
	in this form of the payload; all valid line mask bits are
	implicitly set.
    * - }
      -

.. _v4l2-mpeg-vbi-fmt-ivtv-magic:

Magic Constants for struct v4l2_mpeg_vbi_fmt_ivtv magic field
-------------------------------------------------------------

.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|

.. flat-table::
    :header-rows:  1
    :stub-columns: 0
    :widths:       3 1 4

    * - Defined Symbol
      - Value
      - Description
    * - ``V4L2_MPEG_VBI_IVTV_MAGIC0``
      - "itv0"
      - Indicates the ``itv0`` member of the union in struct
	:c:type:`v4l2_mpeg_vbi_fmt_ivtv` is
	valid.
    * - ``V4L2_MPEG_VBI_IVTV_MAGIC1``
      - "ITV0"
      - Indicates the ``ITV0`` member of the union in struct
	:c:type:`v4l2_mpeg_vbi_fmt_ivtv` is
	valid and that 36 lines of sliced VBI data are present.


.. c:type:: v4l2_mpeg_vbi_itv0

.. c:type:: v4l2_mpeg_vbi_ITV0

itv0 linemask와 variable line 배열

`struct v4l2_mpeg_vbi_itv0.linemask[2]`는 MPEG stream에 little-endian byte order로 저장되는 VBI service line bitmask입니다. `linemask[0]` bit 0과 17은 첫 field line 6과 23, bit 18과 31은 두 번째 field line 6과 19입니다. `linemask[1]` bit 0과 3은 두 번째 field line 20과 23이고 bits 4-31은 사용하지 않으며 0입니다.

`line[35]`는 실제로 1~35 원소만 사용하는 variable-length 배열입니다. Data line은 `linemask[0]` bit 0부터 31, 이어서 `linemask[1]` bit 0부터 3까지 set bit 순서에 대응합니다. `line[0]`은 첫 set bit, `line[1]`은 두 번째 set bit의 VBI line입니다.

Mask bit가 하나도 없으면 `line[0]`에 지정되지 않은 data 한 line이 있을 수 있으며 애플리케이션은 이를 무시해야 합니다.

structs v4l2_mpeg_vbi_itv0 and v4l2_mpeg_vbi_ITV0
-------------------------------------------------

.. raw:: latex

   \footnotesize

.. tabularcolumns:: |p{4.6cm}|p{2.0cm}|p{10.7cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __le32
      - ``linemask``\ [2]
      - Bitmasks indicating the VBI service lines present. These
	``linemask`` values are stored in little endian byte order in the
	MPEG stream. Some reference ``linemask`` bit positions with their
	corresponding VBI line number and video field are given below.
	b\ :sub:`0` indicates the least significant bit of a ``linemask``
	value:


	::

	    linemask[0] b0:     line  6  first field
	    linemask[0] b17:    line 23  first field
	    linemask[0] b18:    line  6  second field
	    linemask[0] b31:    line 19  second field
	    linemask[1] b0:     line 20  second field
	    linemask[1] b3:     line 23  second field
	    linemask[1] b4-b31: unused and set to 0
    * - struct
	:c:type:`v4l2_mpeg_vbi_itv0_line`
      - ``line``\ [35]
      - This is a variable length array that holds from 1 to 35 lines of
	sliced VBI data. The sliced VBI data lines present correspond to
	the bits set in the ``linemask`` array, starting from b\ :sub:`0`
	of ``linemask``\ [0] up through b\ :sub:`31` of ``linemask``\ [0],
	and from b\ :sub:`0` of ``linemask``\ [1] up through b\ :sub:`3` of
	``linemask``\ [1]. ``line``\ [0] corresponds to the first bit
	found set in the ``linemask`` array, ``line``\ [1] corresponds to
	the second bit found set in the ``linemask`` array, etc. If no
	``linemask`` array bits are set, then ``line``\ [0] may contain
	one line of unspecified data that should be ignored by
	applications.

.. raw:: latex

   \normalsize

.. _v4l2-mpeg-vbi-itv0-1:

ITV0 fixed 배열과 line payload

`struct v4l2_mpeg_vbi_ITV0.line[36]`은 정확히 36 line을 담는 fixed-length 배열입니다. `line[0]`부터 `line[17]`은 첫 field line 6부터 23, `line[18]`부터 `line[35]`는 두 번째 field line 6부터 23에 대응합니다.

각 `struct v4l2_mpeg_vbi_itv0_line`은 1-byte `id`와 42-byte `data`로 구성됩니다. `id`는 line에 저장된 sliced VBI service type이고 `data[42]`는 해당 line payload입니다.

struct v4l2_mpeg_vbi_ITV0
-------------------------

.. tabularcolumns:: |p{5.2cm}|p{2.4cm}|p{9.7cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - struct
	:c:type:`v4l2_mpeg_vbi_itv0_line`
      - ``line``\ [36]
      - A fixed length array of 36 lines of sliced VBI data. ``line``\ [0]
	through ``line``\ [17] correspond to lines 6 through 23 of the
	first field. ``line``\ [18] through ``line``\ [35] corresponds to
	lines 6 through 23 of the second field.


.. c:type:: v4l2_mpeg_vbi_itv0_line

struct v4l2_mpeg_vbi_itv0_line
------------------------------

.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}|

.. flat-table::
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 2

    * - __u8
      - ``id``
      - A line identifier value from
	:ref:`ITV0-Line-Identifier-Constants` that indicates the type of
	sliced VBI data stored on this line.
    * - __u8
      - ``data``\ [42]
      - The sliced VBI data for the line.


.. _ITV0-Line-Identifier-Constants:

IVTV line identifier와 Teletext 각주

IVTV line record의 `id`는 `V4L2_MPEG_VBI_IVTV_TELETEXT_B` 값 1, `V4L2_MPEG_VBI_IVTV_CAPTION_525` 값 4, `V4L2_MPEG_VBI_IVTV_WSS_625` 값 5, `V4L2_MPEG_VBI_IVTV_VPS` 값 7 중 하나입니다. 각 line payload의 의미는 일반 sliced VBI service 정의를 따릅니다.

ETS 300 706에 따르면 Teletext data는 첫 field line 6-22와 두 번째 field line 5-22에 실릴 수 있습니다. 일반 service 표에 적힌 통상 line과 hardware별 실제 지원 line을 구분하고, 최종적으로 협상된 `service_lines`를 기준으로 처리해야 합니다.

Line Identifiers for struct v4l2_mpeg_vbi_itv0_line id field
------------------------------------------------------------

.. tabularcolumns:: |p{7.0cm}|p{1.8cm}|p{8.5cm}|

.. flat-table::
    :header-rows:  1
    :stub-columns: 0
    :widths:       3 1 4

    * - Defined Symbol
      - Value
      - Description
    * - ``V4L2_MPEG_VBI_IVTV_TELETEXT_B``
      - 1
      - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
	description of the line payload.
    * - ``V4L2_MPEG_VBI_IVTV_CAPTION_525``
      - 4
      - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
	description of the line payload.
    * - ``V4L2_MPEG_VBI_IVTV_WSS_625``
      - 5
      - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
	description of the line payload.
    * - ``V4L2_MPEG_VBI_IVTV_VPS``
      - 7
      - Refer to :ref:`Sliced VBI services <vbi-services2>` for a
	description of the line payload.


.. [#f1]
   According to :ref:`ETS 300 706 <ets300706>` lines 6-22 of the first
   field and lines 5-22 of the second field may carry Teletext data.

.. [#f2]
   See also :ref:`vbi-525` and :ref:`vbi-625`.