Raw VBI 데이터 인터페이스

VBI 신호, 장치 노드와 capability

VBI는 Vertical Blanking Interval의 약자로 아날로그 video signal의 line sequence 사이에 있는 공백 구간입니다. CRT TV의 electron beam이 화면 위로 돌아가는 동안 영상 정보는 전송되지 않으며, 이 구간에는 vertical synchronization pulse와 video signal에 ASK로 변조된 짧은 data packet이 들어갈 수 있습니다. Teletext와 Closed Caption이 대표적인 서비스입니다.

이 인터페이스는 video signal에서 sampling한 raw VBI data를 capture하거나 출력 신호에 추가합니다. 형식은 압축하지 않은 영상과 비슷하게 여러 line에 각 line의 sample 배열을 두며, 이를 VBI image라고 부릅니다.

전용 노드는 major 81, minor 224부터 255의 `/dev/vbi`, `/dev/vbi0`부터 `/dev/vbi31`입니다. `/dev/vbi`는 보통 선호 장치의 symbolic link이고, 이 이름 규칙은 input과 output 모두에 적용됩니다.

관련 video와 VBI 장치를 찾기 어려운 문제를 줄이기 위해 raw VBI capture/output 기능을 `/dev/video`에서도 제공할 수 있습니다. `/dev/video`에서 사용할 때는 `VIDIOC_S_FMT`로 기능을 선택해야 하지만 `/dev/vbi`에서는 raw VBI가 기본 기능입니다.

Capture 장치는 `V4L2_CAP_VBI_CAPTURE`, output 장치는 `V4L2_CAP_VBI_OUTPUT`을 `VIDIOC_QUERYCAP` 결과에 설정합니다. Read/write 또는 streaming I/O 중 적어도 하나를 지원해야 하며 tuner나 modulator 유무는 선택 사항입니다. 필요한 video input/output, tuner/modulator, control ioctl과 중요한 video standard ioctl을 지원해야 합니다.

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

.. _raw-vbi:

**********************
Raw VBI Data Interface
**********************

VBI is an abbreviation of 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. Using an
oscilloscope you will find here the vertical synchronization pulses and
short data packages ASK modulated [#f1]_ onto the video signal. These are
transmissions of services such as Teletext or Closed Caption.

Subject of this interface type is raw VBI data, as sampled off a video
signal, or to be added to a signal for output. The data format is
similar to uncompressed video images, a number of lines times a number
of samples per line, we call this a VBI image.

Conventionally V4L2 VBI devices are accessed through character device
special files named ``/dev/vbi`` and ``/dev/vbi0`` to ``/dev/vbi31``
with major number 81 and minor numbers 224 to 255. ``/dev/vbi`` is
typically a symbolic link to the preferred VBI device. This convention
applies to both input and output devices.

To address the problems of finding related video and VBI devices VBI
capturing and output is also available as device function under
``/dev/video``. To capture or output raw VBI data with these devices
applications must call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl.
Accessed as ``/dev/vbi``, raw VBI capturing or output is the default
device function.

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

Devices supporting the raw VBI capturing or output API set the
``V4L2_CAP_VBI_CAPTURE`` or ``V4L2_CAP_VBI_OUTPUT`` flags, 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 I/O methods must be supported. VBI
devices may or may not have a tuner or modulator.

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

VBI devices shall support :ref:`video input or output <video>`,
:ref:`tuner or modulator <tuner>`, and :ref:`controls <control>`
ioctls as needed. The :ref:`video standard <standard>` ioctls provide
information vital to program a VBI device, therefore must be supported.

Raw VBI format 협상과 오류

장치마다 sampling frequency를 비롯한 raw VBI sampling 능력이 다릅니다. 따라서 애플리케이션은 현재 sampling parameter를 조회하고, 필요하면 다른 값을 제안한 뒤 드라이버가 반환한 실제 값을 검사해야 합니다.

이 매개변수는 Unix tool chain에서 장치를 일반 파일처럼 이어서 사용할 수 있도록 `open()` 때 초기화되지 않습니다. 잘 작성된 애플리케이션은 이전 프로세스의 설정을 가정하지 않고 매번 합리적인 값을 요청한 다음 결과가 목적에 맞는지 확인합니다.

현재 값을 읽을 때 `struct v4l2_format.type`을 capture는 `V4L2_BUF_TYPE_VBI_CAPTURE`, output은 `V4L2_BUF_TYPE_VBI_OUTPUT`으로 두고 `VIDIOC_G_FMT`를 호출합니다. 드라이버는 `fmt` union의 `struct v4l2_vbi_format vbi`를 채웁니다.

다른 값을 요청할 때는 모든 `vbi` 필드를 초기화하거나 `VIDIOC_G_FMT` 결과에서 필요한 필드만 바꾼 뒤 `VIDIOC_S_FMT`를 호출합니다. 매개변수가 모호할 때만 `EINVAL`이며, 그 밖에는 하드웨어 능력에 맞게 조정한 실제 값을 반환합니다.

`VIDIOC_S_FMT`가 자원을 할당하는 드라이버는 반환 매개변수 자체는 유효하지만 필요한 자원이 당장 없을 때 `EBUSY`를 반환할 수 있습니다. Video와 VBI capture 영역이 겹치거나 다른 프로세스가 VBI 기능을 이미 사용한 경우가 예입니다. `VIDIOC_STREAMON`과 첫 `read()`, `write()`, `select()`도 자원 할당 지점이라 같은 오류가 날 수 있습니다.

모든 VBI 장치는 `VIDIOC_G_FMT`와 `VIDIOC_S_FMT`를 구현해야 합니다. 하드웨어가 요청을 반영하지 못하더라도 S_FMT는 요청을 무시하고 기본값을 반환하는 식으로 존재해야 하며, `VIDIOC_TRY_FMT`는 선택 사항입니다.

Raw VBI Format Negotiation
==========================

Raw VBI sampling abilities can vary, in particular the sampling
frequency. To properly interpret the data V4L2 specifies an ioctl to
query the sampling parameters. Moreover, to allow for some flexibility
applications can also suggest different parameters.

As usual these parameters are *not* reset at :c:func:`open()`
time to permit Unix tool chains, programming a device and then reading
from it as if it was a plain file. Well written V4L2 applications should
always ensure they really get what they want, requesting reasonable
parameters and then checking if the actual parameters are suitable.

To query the current raw VBI capture parameters applications set the
``type`` field of a struct :c:type:`v4l2_format` to
``V4L2_BUF_TYPE_VBI_CAPTURE`` or ``V4L2_BUF_TYPE_VBI_OUTPUT``, and call
the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` ioctl with a pointer to this
structure. Drivers fill the struct
:c:type:`v4l2_vbi_format` ``vbi`` member of the
``fmt`` union.

To request different parameters applications set the ``type`` field of a
struct :c:type:`v4l2_format` as above and initialize all
fields of the struct :c:type:`v4l2_vbi_format`
``vbi`` member of the ``fmt`` union, or better just modify the results
of :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, and call the :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`
ioctl with a pointer to this structure. Drivers return an ``EINVAL`` error
code only when the given parameters are ambiguous, otherwise they modify
the parameters according to the hardware capabilities and return the
actual parameters. When the driver allocates resources at this point, it
may return an ``EBUSY`` error code to indicate the returned parameters are
valid but the required resources are currently not available. That may
happen for instance when the video and VBI areas to capture would
overlap, or when the driver supports multiple opens and another process
already requested VBI capturing or output. Anyway, applications must
expect other resource allocation points which may return ``EBUSY``, at the
:ref:`VIDIOC_STREAMON` ioctl and the first :c:func:`read()`
, :c:func:`write()` and :c:func:`select()` calls.

VBI devices must implement both the :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and
:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ignores all requests
and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does.
:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional.

v4l2_vbi_format 필드와 line 범위

`sampling_rate`는 초당 sample 수이며 단위는 1 Hz입니다. `offset`은 line synchronization pulse의 leading edge에서 첫 VBI sample까지의 수평 offset을 sample 수로 나타냅니다. 첫 sample의 시간 위치는 `offset / sampling_rate`초입니다.

`samples_per_line`은 각 VBI line의 sample 수입니다. `sample_format`은 pixel format과 같은 FourCC이며 보통 sample당 8-bit인 `V4L2_PIX_FMT_GREY`입니다. 값이 낮을수록 black level 방향이라는 점 외에 signal level과 다른 상관관계를 가정하면 안 됩니다. 예를 들어 128이 평균이 아닐 수 있으므로 MSB만으로 high/low를 판단할 수 없고, 드라이버는 software로 sample format을 변환해서는 안 됩니다.

`start[0]`과 `start[1]`은 첫 번째와 두 번째 field의 VBI image가 시작하는 scanning-system line number입니다. 525/625-line 형식에는 `V4L2_VBI_ITU_525_F1_START`, `V4L2_VBI_ITU_525_F2_START`, `V4L2_VBI_ITU_625_F1_START`, `V4L2_VBI_ITU_625_F2_START` 상수가 있습니다. ITU line 번호는 0이 아니라 1부터 시작합니다.

Input 하드웨어가 scanning line을 신뢰성 있게 식별하지 못하면 start를 0으로 반환할 수 있습니다. VBI 획득 자체에 line number가 필요하지 않을 수도 있기 때문입니다. `count[0]`과 `count[1]`은 각 field image의 line 수입니다.

드라이버는 가능하면 VBI capture window를 picture area까지 이동하거나 확장하는 full field mode를 허용해야 합니다. 애플리케이션은 필요 없는 field의 count를 0으로 만들 수 있고 progressive scanning에서는 `count[1]`을 0으로 둡니다. 이때 대응 start는 양쪽에서 무시합니다. 다만 single-field capture를 지원하지 않는 드라이버는 두 count를 모두 0이 아닌 값으로 되돌릴 수 있습니다.

두 count가 모두 0이거나 line number가 유효 범위를 벗어나거나 한 field image가 두 field의 line을 가로지르는 형식은 유효하지 않으며 드라이버가 반환해서는 안 됩니다. Start와 count를 초기화하기 전에 현재 video standard의 `v4l2_std_id` 또는 `struct v4l2_standard.framelines`를 확인해야 합니다.

`flags`는 현재 드라이버만 설정하고 애플리케이션은 0으로 초기화합니다. `reserved` 배열도 향후 확장을 위한 공간이므로 드라이버와 애플리케이션 모두 0으로 설정해야 합니다.

.. tabularcolumns:: |p{1.6cm}|p{4.2cm}|p{11.5cm}|

.. c:type:: v4l2_vbi_format

.. cssclass:: longtable

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

    * - __u32
      - ``sampling_rate``
      - Samples per second, i. e. unit 1 Hz.
    * - __u32
      - ``offset``
      - Horizontal offset of the VBI image, relative to the leading edge
	of the line synchronization pulse and counted in samples: The
	first sample in the VBI image will be located ``offset`` /
	``sampling_rate`` seconds following the leading edge. See also
	:ref:`vbi-hsync`.
    * - __u32
      - ``samples_per_line``
      -
    * - __u32
      - ``sample_format``
      - Defines the sample format as in :ref:`pixfmt`, a
	four-character-code. [#f2]_ Usually this is ``V4L2_PIX_FMT_GREY``,
	i. e. each sample consists of 8 bits with lower values oriented
	towards the black level. Do not assume any other correlation of
	values with the signal level. For example, the MSB does not
	necessarily indicate if the signal is 'high' or 'low' because 128
	may not be the mean value of the signal. Drivers shall not convert
	the sample format by software.
    * - __u32
      - ``start``\ [#f2]_
      - This is the scanning system line number associated with the first
	line of the VBI image, of the first and the second field
	respectively. See :ref:`vbi-525` and :ref:`vbi-625` for valid
	values. 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. VBI input
	drivers can return start values 0 if the hardware cannot reliable
	identify scanning lines, VBI acquisition may not require this
	information.
    * - __u32
      - ``count``\ [#f2]_
      - The number of lines in the first and second field image,
	respectively.
    * - :cspan:`2`

	Drivers should be as flexibility as possible. For example, it may
	be possible to extend or move the VBI capture window down to the
	picture area, implementing a 'full field mode' to capture data
	service transmissions embedded in the picture.

	An application can set the first or second ``count`` value to zero
	if no data is required from the respective field; ``count``\ [1]
	if the scanning system is progressive, i. e. not interlaced. The
	corresponding start value shall be ignored by the application and
	driver. Anyway, drivers may not support single field capturing and
	return both count values non-zero.

	Both ``count`` values set to zero, or line numbers are outside the
	bounds depicted\ [#f4]_, or a field image covering lines of two
	fields, are invalid and shall not be returned by the driver.

	To initialize the ``start`` and ``count`` fields, applications
	must first determine the current video standard selection. The
	:ref:`v4l2_std_id <v4l2-std-id>` or the ``framelines`` field
	of struct :c:type:`v4l2_standard` can be evaluated
	for this purpose.
    * - __u32
      - ``flags``
      - See :ref:`vbifmt-flags` below. Currently only drivers set flags,
	applications must set this field to zero.
    * - __u32
      - ``reserved``\ [#f2]_
      - This array is reserved for future extensions. Drivers and
	applications must set it to zero.

Raw VBI format flag와 memory 배열

`V4L2_VBI_UNSYNC`(0x0001)는 하드웨어가 두 field를 올바르게 구별하지 못한다는 뜻입니다. 보통 낮은 scanning line number의 첫 field image가 memory에 먼저 오지만, flag가 있으면 첫 번째 또는 두 번째 field가 먼저 저장될 수 있습니다. 그래도 시간 순서는 유지되어 더 오래된 field가 memory 앞쪽에 있습니다.

`V4L2_VBI_INTERLACED`(0x0002)가 없으면 첫 field의 모든 line 다음에 두 번째 field의 모든 line이 오는 sequential layout입니다. Top/bottom 중 어느 field가 먼저인지는 video standard에 달려 있으며 `V4L2_FIELD_SEQ_TB` 또는 `V4L2_FIELD_SEQ_BT`와 비교할 수 있습니다.

`V4L2_VBI_INTERLACED`가 있으면 첫 field의 첫 line, 두 번째 field의 첫 line, 이어서 각 field의 두 번째 line 순으로 교차합니다. Video와 VBI를 동시에 interlaced로 처리하면서 field를 분리할 수 없는 하드웨어에 필요할 수 있습니다. 이 flag는 두 count가 서로 같고 0이 아님을 전제로 합니다.

.. tabularcolumns:: |p{4.4cm}|p{1.5cm}|p{11.4cm}|

.. _vbifmt-flags:

.. flat-table:: Raw VBI Format Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 4

    * - ``V4L2_VBI_UNSYNC``
      - 0x0001
      - This flag indicates hardware which does not properly distinguish
	between fields. Normally the VBI image stores the first field
	(lower scanning line numbers) first in memory. This may be a top
	or bottom field depending on the video standard. When this flag is
	set the first or second field may be stored first, however the
	fields are still in correct temporal order with the older field
	first in memory. [#f3]_
    * - ``V4L2_VBI_INTERLACED``
      - 0x0002
      - By default the two field images will be passed sequentially; all
	lines of the first field followed by all lines of the second field
	(compare :ref:`field-order` ``V4L2_FIELD_SEQ_TB`` and
	``V4L2_FIELD_SEQ_BT``, whether the top or bottom field is first in
	memory depends on the video standard). When this flag is set, the
	two fields are interlaced (cf. ``V4L2_FIELD_INTERLACED``). The
	first line of the first field followed by the first line of the
	second field, then the two second lines, and so on. Such a layout
	may be necessary when the hardware has been programmed to capture
	or output interlaced video images and is unable to separate the
	fields for VBI capturing at the same time. For simplicity setting
	this flag implies that both ``count`` values are equal and
	non-zero.

동기화 그림과 standard 변경 규칙

문서의 세 figure는 line synchronization에 대한 offset 기준, ITU-R 525-line(M/NTSC와 M/PAL) 번호, ITU-R 625-line 번호를 보여 줍니다. `start`와 `count`는 이 line-number 체계를 기준으로 검증해야 합니다.

VBI image format은 선택된 video standard에 종속됩니다. 애플리케이션은 먼저 새 standard를 선택하거나 현재 standard를 조회한 뒤 format을 협상해야 합니다. 협상 전에 data를 읽거나 쓰는 요청, 또는 기존 VBI 매개변수를 무효화할 수 있는 standard 전환 뒤의 I/O는 드라이버가 거부해야 합니다.

I/O가 활성 상태일 때 format을 변경하는 것은 허용되지 않습니다. Standard를 바꾸려면 stream을 중지하고 raw VBI format을 다시 협상한 뒤 I/O를 재개해야 합니다.

.. _vbi-hsync:

.. kernel-figure:: vbi_hsync.svg
    :alt:   vbi_hsync.svg
    :align: center

    **Figure 4.1. Line synchronization**

.. _vbi-525:

.. kernel-figure:: vbi_525.svg
    :alt:   vbi_525.svg
    :align: center

    **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**

.. _vbi-625:

.. kernel-figure:: vbi_625.svg
    :alt:   vbi_625.svg
    :align: center

    **Figure 4.3. ITU-R 625 line numbering**

Remember the VBI image format depends on the selected video standard,
therefore the application must choose a new standard or query the
current standard first. Attempts to read or write data ahead of format
negotiation, or after switching the video standard which may invalidate
the negotiated VBI parameters, should be refused by the driver. A format
change during active I/O is not permitted.

VBI frame 크기와 I/O

Field number 동기화를 보장하고 구현을 단순하게 하기 위해 한 번에 전달하는 최소 단위는 두 field의 VBI image가 memory에서 바로 이어지는 한 frame입니다.

Frame의 총 byte 수는 `(count[0] + count[1]) * samples_per_line * sample size in bytes`로 계산합니다. Sample size는 대개 1 byte지만 다른 드라이버와 올바르게 동작하려면 반드시 `sample_format`에서 확인해야 합니다.

장치는 read/write와 streaming I/O 중 하나 이상을 지원할 수 있습니다. Streaming에는 memory mapping과 user pointer 방식이 있고, buffer timestamp를 이용하면 video와 VBI data를 동기화할 수 있습니다.

`VIDIOC_STREAMON`과 첫 `read()`, `write()`, `select()`는 필요한 hardware resource를 할당하는 지점일 수 있으므로, 다른 프로세스가 장치를 사용 중이면 `EBUSY`를 반환할 수 있습니다.

ASK는 Amplitude-Shift Keying으로 high signal level이 1, low level이 0을 나타냅니다. 일부 장치는 VBI를 직접 sampling하지 못하고 video capture window를 VBI 영역으로 확장할 수만 있습니다. `V4L2_VBI_UNSYNC`에서는 field number에 따라 의미가 다른 서비스를 안정적으로 decode하거나 encode할 수 없습니다.

Reading and writing VBI images
==============================

To assure synchronization with the field number and easier
implementation, the smallest unit of data passed at a time is one frame,
consisting of two fields of VBI images immediately following in memory.

The total size of a frame computes as follows:

.. code-block:: c

    (count[0] + count[1]) * samples_per_line * sample size in bytes

The sample size is most likely always one byte, applications must check
the ``sample_format`` field though, to function properly with other
drivers.

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

Remember the :ref:`VIDIOC_STREAMON <VIDIOC_STREAMON>` ioctl and the
first :c:func:`read()`, :c:func:`write()` and
:c:func:`select()` call can be resource allocation
points returning an ``EBUSY`` error code if the required hardware resources
are temporarily unavailable, for example the device is already in use by
another process.

.. [#f1]
   ASK: Amplitude-Shift Keying. A high signal level represents a '1'
   bit, a low level a '0' bit.

.. [#f2]
   A few devices may be unable to sample VBI data at all but can extend
   the video capture window to the VBI region.

.. [#f3]
   Most VBI services transmit on both fields, but some have different
   semantics depending on the field number. These cannot be reliable
   decoded or encoded when ``V4L2_VBI_UNSYNC`` is set.

.. [#f4]
   The valid values ar shown at :ref:`vbi-525` and :ref:`vbi-625`.