VIDIOC_DV_TIMINGS_CAP와 VIDIOC_SUBDEV_DV_TIMINGS_CAP ioctl

이름, 호출 형식과 인자

`VIDIOC_DV_TIMINGS_CAP`와 `VIDIOC_SUBDEV_DV_TIMINGS_CAP`는 디지털 비디오 수신기 또는 송신기가 지원하는 타이밍 범위를 조회합니다. 두 호출 모두 `struct v4l2_dv_timings_cap *argp`를 사용합니다.

`fd`는 `open()`이 반환한 비디오 또는 sub-device 노드의 파일 디스크립터이며 `argp`는 응용 프로그램이 pad와 예약 필드를 초기화하고 드라이버가 capability를 채우는 구조체입니다.

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

.. _VIDIOC_DV_TIMINGS_CAP:

*********************************************************
ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP
*********************************************************

Name
====

VIDIOC_DV_TIMINGS_CAP - VIDIOC_SUBDEV_DV_TIMINGS_CAP - The capabilities of the Digital Video receiver/transmitter

Synopsis
========

.. c:macro:: VIDIOC_DV_TIMINGS_CAP

``int ioctl(int fd, VIDIOC_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)``

.. c:macro:: VIDIOC_SUBDEV_DV_TIMINGS_CAP

``int ioctl(int fd, VIDIOC_SUBDEV_DV_TIMINGS_CAP, struct v4l2_dv_timings_cap *argp)``

Arguments
=========

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

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

비디오 노드와 sub-device 조회

비디오 노드에서 수신기·송신기 capability를 조회하려면 `pad`를 0으로 설정하고 `reserved` 배열을 0으로 지운 뒤 `VIDIOC_DV_TIMINGS_CAP`를 호출합니다. 입력이나 출력을 전환하면 드라이버가 다른 capability 값을 반환할 수 있습니다.

드라이버가 지원하면 sub-device 노드에 `VIDIOC_SUBDEV_DV_TIMINGS_CAP`를 직접 호출할 수 있습니다. DV 수신기는 입력 pad, 송신기는 출력 pad별로 capability가 다르므로 원하는 media controller pad 번호를 `pad`에 지정하고 `reserved`를 0으로 설정해야 합니다.

해당 capability를 지원하지 않는 pad를 조회하면 `EINVAL`을 반환합니다.

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

To query the capabilities of the DV receiver/transmitter applications
initialize the ``pad`` field to 0, zero the reserved array of struct
:c:type:`v4l2_dv_timings_cap` and call the
``VIDIOC_DV_TIMINGS_CAP`` ioctl on a video node and the driver will fill
in the structure.

.. note::

   Drivers may return different values after
   switching the video input or output.

When implemented by the driver DV capabilities of subdevices can be
queried by calling the ``VIDIOC_SUBDEV_DV_TIMINGS_CAP`` ioctl directly
on a subdevice node. The capabilities are specific to inputs (for DV
receivers) or outputs (for DV transmitters), applications must specify
the desired pad number in the struct
:c:type:`v4l2_dv_timings_cap` ``pad`` field and
zero the ``reserved`` array. Attempts to query capabilities on a pad
that doesn't support them will return an ``EINVAL`` error code.

v4l2_bt_timings_cap 범위

`v4l2_bt_timings_cap`은 하드웨어가 받아들이거나 생성할 수 있는 활성 영상 크기와 pixel clock의 최소·최대값, 지원 표준과 추가 capability 비트를 나타냅니다.

.. tabularcolumns:: |p{1.2cm}|p{3.2cm}|p{12.9cm}|

.. c:type:: v4l2_bt_timings_cap

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

    * - __u32
      - ``min_width``
      - Minimum width of the active video in pixels.
    * - __u32
      - ``max_width``
      - Maximum width of the active video in pixels.
    * - __u32
      - ``min_height``
      - Minimum height of the active video in lines.
    * - __u32
      - ``max_height``
      - Maximum height of the active video in lines.
    * - __u64
      - ``min_pixelclock``
      - Minimum pixelclock frequency in Hz.
    * - __u64
      - ``max_pixelclock``
      - Maximum pixelclock frequency in Hz.
    * - __u32
      - ``standards``
      - The video standard(s) supported by the hardware. See
	:ref:`dv-bt-standards` for a list of standards.
    * - __u32
      - ``capabilities``
      - Several flags giving more information about the capabilities. See
	:ref:`dv-bt-cap-capabilities` for a description of the flags.
    * - __u32
      - ``reserved``\ [16]
      - Reserved for future extensions.
	Drivers must set the array to zero.

v4l2_dv_timings_cap 구조체

외부 구조체의 `type`은 DV timing 유형, `pad`는 media controller가 보고한 pad 번호입니다. 비디오 노드에서는 `pad`를 반드시 0으로 두고 sub-device 노드에서만 실제 pad 번호를 사용합니다.

익명 union의 `bt`는 BT.656/1120 capability를 담고 `raw_data[32]`는 유형별 원시 공간입니다. `reserved[2]`는 드라이버와 응용 프로그램 양쪽이 모두 0으로 설정해야 합니다.

.. tabularcolumns:: |p{4.4cm}|p{3.6cm}|p{9.3cm}|

.. c:type:: v4l2_dv_timings_cap

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

    * - __u32
      - ``type``
      - Type of DV timings as listed in :ref:`dv-timing-types`.
    * - __u32
      - ``pad``
      - Pad number as reported by the media controller API. This field is
	only used when operating on a subdevice node. When operating on a
	video node applications must set this field to zero.
    * - __u32
      - ``reserved``\ [2]
      - Reserved for future extensions.

	Drivers and applications must set the array to zero.
    * - union {
      - (anonymous)
    * - struct :c:type:`v4l2_bt_timings_cap`
      - ``bt``
      - BT.656/1120 timings capabilities of the hardware.
    * - __u32
      - ``raw_data``\ [32]
    * - }
      -

DV BT Timing capability 비트

`standards`는 알려진 표준 집합을 나타내고 `V4L2_DV_BT_CAP_CUSTOM`은 그 밖의 timing도 다룰 수 있음을 별도로 표시합니다. 최소·최대 범위 안이라고 해서 모든 중간 조합이 자동으로 유효한 것은 아니므로 실제 timing 검증 API와 함께 사용해야 합니다.

.. tabularcolumns:: |p{7.2cm}|p{10.3cm}|

.. _dv-bt-cap-capabilities:

.. flat-table:: DV BT Timing capabilities
    :header-rows:  0
    :stub-columns: 0

    * - Flag
      - Description
    * -
      -
    * - ``V4L2_DV_BT_CAP_INTERLACED``
      - Interlaced formats are supported.
    * - ``V4L2_DV_BT_CAP_PROGRESSIVE``
      - Progressive formats are supported.
    * - ``V4L2_DV_BT_CAP_REDUCED_BLANKING``
      - CVT/GTF specific: the timings can make use of reduced blanking
	(CVT) or the 'Secondary GTF' curve (GTF).
    * - ``V4L2_DV_BT_CAP_CUSTOM``
      - Can support non-standard timings, i.e. timings not belonging to
	the standards set in the ``standards`` field.

반환값

성공하면 0을 반환하고 실패하면 -1과 적절한 `errno`를 반환합니다. 일반 오류 코드는 Generic Error Codes 절을 따르며, capability가 없는 pad에는 앞서 설명한 `EINVAL`이 적용됩니다.

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.