VIDIOC_G_SLICED_VBI_CAP ioctl

목적, 호출 형식과 인자

`VIDIOC_G_SLICED_VBI_CAP`은 sliced VBI 캡처 또는 출력 장치가 지원하는 데이터 서비스를 조회합니다. 호출자는 `struct v4l2_sliced_vbi_cap`을 가리키는 `argp`를 전달합니다.

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

.. _VIDIOC_G_SLICED_VBI_CAP:

*****************************
ioctl VIDIOC_G_SLICED_VBI_CAP
*****************************

Name
====

VIDIOC_G_SLICED_VBI_CAP - Query sliced VBI capabilities

Synopsis
========

.. c:macro:: VIDIOC_G_SLICED_VBI_CAP

``int ioctl(int fd, VIDIOC_G_SLICED_VBI_CAP, struct v4l2_sliced_vbi_cap *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to struct :c:type:`v4l2_sliced_vbi_cap`.

Description
===========

조회 절차와 Linux 2.6.19 변경

애플리케이션은 `type`에 조회할 데이터 스트림 형식을 지정하고 `reserved` 배열을 0으로 지운 다음 ioctl을 호출합니다. 드라이버는 나머지 필드를 채우며, sliced VBI API를 지원하지 않거나 `type`이 잘못되면 `EINVAL`을 반환합니다.

`type` 필드는 Linux 2.6.19에서 추가되었습니다. 같은 시점에 이 ioctl의 방향도 읽기 전용에서 쓰기-읽기로 바뀌었으므로, 구조체의 입력 필드를 반드시 준비해야 합니다.

To find out which data services are supported by a sliced VBI capture or
output device, applications initialize the ``type`` field of a struct
:c:type:`v4l2_sliced_vbi_cap`, clear the
``reserved`` array and call the :ref:`VIDIOC_G_SLICED_VBI_CAP <VIDIOC_G_SLICED_VBI_CAP>` ioctl. The
driver fills in the remaining fields or returns an ``EINVAL`` error code if
the sliced VBI API is unsupported or ``type`` is invalid.

.. note::

   The ``type`` field was added, and the ioctl changed from read-only
   to write-read, in Linux 2.6.19.

.. c:type:: v4l2_sliced_vbi_cap

.. tabularcolumns:: |p{1.4cm}|p{4.4cm}|p{4.5cm}|p{3.6cm}|p{3.6cm}|

v4l2_sliced_vbi_cap 필드와 주사선 매핑

`service_lines[0][0]`과 `service_lines[1][0]`은 어떤 실제 주사선에도 대응하지 않으므로 드라이버가 반드시 0으로 설정합니다. 525줄·625줄 VBI 줄 번호에 관한 세부 사항은 원문의 `vbi-525`와 `vbi-625` 참조를 따릅니다.

하드웨어는 프레임당 캡처·출력할 VBI 줄 수나 한 줄에서 식별할 서비스 수에 제한이 있을 수 있습니다. 예를 들어 PAL 16번 줄에서 VPS와 Teletext를 각각 찾을 수 있어도 둘을 동시에 찾지는 못할 수 있습니다.

애플리케이션은 `VIDIOC_S_FMT`를 사용해 이러한 동시 처리 제한을 확인합니다. 단순히 `service_set`에 비트가 존재한다는 사실만으로 모든 서비스 조합이 동시에 가능하다고 가정하면 안 됩니다.

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

    * - __u16
      - ``service_set``
      - :cspan:`2` A set of all data services supported by the driver.

	Equal to the union of all elements of the ``service_lines`` array.
    * - __u16
      - ``service_lines``\ [2][24]
      - :cspan:`2` Each element of this array contains a set of data
	services the hardware can look for or insert into a particular
	scan line. Data services are defined in :ref:`vbi-services`.
	Array indices map to ITU-R line numbers\ [#f1]_ 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` 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 may be 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. Applications can learn about these limits using the
	:ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl as described in
	:ref:`sliced`.
    * -
    * -
      -
      - :cspan:`2` Drivers must set ``service_lines`` [0][0] and
	``service_lines``\ [1][0] to zero.
    * - __u32
      - ``type``
      - Type of the data stream, see :c:type:`v4l2_buf_type`. Should be
	``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` or
	``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT``.
    * - __u32
      - ``reserved``\ [3]
      - :cspan:`2` This array is reserved for future extensions.

	Applications and drivers must set it to zero.

Sliced VBI 서비스 표의 정의

다음 서비스 값은 `service_set`과 `service_lines`의 비트 집합에 사용됩니다. 각 서비스는 적용 방송 체계, 통상적인 주사선, 전달되는 payload 형식을 함께 정의합니다.

원문의 LaTeX 전용 크기 지시문은 출력 표의 조판만 바꾸며 API 의미에는 영향을 주지 않습니다.

.. [#f1]

   See also :ref:`vbi-525` and :ref:`vbi-625`.

.. raw:: latex

    \scriptsize

.. tabularcolumns:: |p{3.9cm}|p{1.0cm}|p{2.0cm}|p{3.0cm}|p{7.0cm}|

.. _vbi-services:

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

    * - Symbol
      - Value
      - Reference
      - Lines, usually
      - Payload

지원 서비스와 페이로드

Teletext System B는 ETS 300 706과 ITU 653을, VPS는 ETS 300 231을, 525-line caption은 CEA-608을, WSS 625는 EN 300 294와 ITU 1119를 참조합니다.

두 번째 field의 표기 320-335, 284는 괄호에 적힌 원래 field 내 줄 번호 7-22, 21에 대응합니다. 비트 값이 같은 `V4L2_SLICED_CAPTION_525`와 `V4L2_SLICED_VBI_525`는 각각 단일 서비스와 525줄 서비스 집합이라는 문맥으로 구분합니다.

    * - ``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:`en300294`,

	:ref:`itu1119`
      - PAL/SECAM line 23
      - See :ref:`v4l2-sliced-vbi-cap-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

WSS_625 페이로드 비트 배치

`V4L2_SLICED_WSS_625`의 payload는 2바이트입니다. 원문의 ASCII 그림을 같은 의미의 비트 표로 정리하면 다음과 같습니다.

두 바이트 모두 표의 왼쪽이 MSB, 오른쪽이 LSB입니다. 바이트 1의 상위 두 비트는 원문에서 `x`로 표시된 미사용 위치입니다.

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

V4L2_SLICED_VBI_CAP 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 |
	    +-----+-+-+-+--+--+-+-+--+--+-+--+---+---+--+-+--+

반환값과 오류

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 설정하며, 공통 오류는 Generic Error Codes 절을 따릅니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

EINVAL
    The value in the ``type`` field is wrong.