VIDIOC_G_DV_TIMINGS·VIDIOC_S_DV_TIMINGS ioctl

목적, 네 호출 형식과 인자

`VIDIOC_G_DV_TIMINGS`와 `VIDIOC_S_DV_TIMINGS`는 input 또는 output의 DV timing을 조회·설정합니다. sub-device에는 대응하는 `VIDIOC_SUBDEV_G_DV_TIMINGS`와 `VIDIOC_SUBDEV_S_DV_TIMINGS`를 사용합니다.

네 ioctl 모두 `struct v4l2_dv_timings *argp`를 받습니다. `fd`는 `open()`이 반환한 파일 디스크립터이고, 구조체에는 timing type과 BT.656/1120 상세값이 담깁니다.

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

.. _VIDIOC_G_DV_TIMINGS:

**********************************************
ioctl VIDIOC_G_DV_TIMINGS, VIDIOC_S_DV_TIMINGS
**********************************************

Name
====

VIDIOC_G_DV_TIMINGS - VIDIOC_S_DV_TIMINGS - VIDIOC_SUBDEV_G_DV_TIMINGS - VIDIOC_SUBDEV_S_DV_TIMINGS - Get or set DV timings for input or output

Synopsis
========

.. c:macro:: VIDIOC_G_DV_TIMINGS

``int ioctl(int fd, VIDIOC_G_DV_TIMINGS, struct v4l2_dv_timings *argp)``

.. c:macro:: VIDIOC_S_DV_TIMINGS

``int ioctl(int fd, VIDIOC_S_DV_TIMINGS, struct v4l2_dv_timings *argp)``

.. c:macro:: VIDIOC_SUBDEV_G_DV_TIMINGS

``int ioctl(int fd, VIDIOC_SUBDEV_G_DV_TIMINGS, struct v4l2_dv_timings *argp)``

.. c:macro:: VIDIOC_SUBDEV_S_DV_TIMINGS

``int ioctl(int fd, VIDIOC_SUBDEV_S_DV_TIMINGS, struct v4l2_dv_timings *argp)``

Arguments
=========

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

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

DV timing 조회·설정과 지원 판별

input 또는 output timing을 설정할 때는 `VIDIOC_S_DV_TIMINGS`, 현재 timing을 얻을 때는 `VIDIOC_G_DV_TIMINGS`를 사용합니다. 상세 timing 정보는 `v4l2_dv_timings`에 채웁니다.

ioctl 자체를 지원하지 않거나 설정 timing 값이 올바르지 않으면 `EINVAL`입니다. device가 busy라 timing을 바꿀 수 없으면 `EBUSY`입니다.

read-only mode로 등록된 subdev node에서 `VIDIOC_SUBDEV_S_DV_TIMINGS`를 호출할 수 없습니다. 원문 본문은 errno가 `-EPERM`으로 설정된다고 쓰고 Return Value 절은 `EPERM` 항목으로 설명합니다.

`linux/v4l2-dv-timings.h`는 CEA-861 및 VESA DMT 표준 format의 timing을 구하는 데 사용할 수 있습니다. 현재 input/output이 DV timing capability를 제공하지 않으면, 예를 들어 `VIDIOC_ENUMINPUT`의 `V4L2_IN_CAP_DV_TIMINGS`가 없으면 `ENODATA`입니다.

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

To set DV timings for the input or output, applications use the
:ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl and to get the current timings,
applications use the :ref:`VIDIOC_G_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>` ioctl. The detailed timing
information is filled in using the structure struct
:c:type:`v4l2_dv_timings`. These ioctls take a
pointer to the struct :c:type:`v4l2_dv_timings`
structure as argument. If the ioctl is not supported or the timing
values are not correct, the driver returns ``EINVAL`` error code.

Calling ``VIDIOC_SUBDEV_S_DV_TIMINGS`` on a subdev device node that has been
registered in read-only mode is not allowed. An error is returned and the errno
variable is set to ``-EPERM``.

The ``linux/v4l2-dv-timings.h`` header can be used to get the timings of
the formats in the :ref:`cea861` and :ref:`vesadmt` standards. If
the current input or output does not support DV timings (e.g. if
:ref:`VIDIOC_ENUMINPUT` does not set the
``V4L2_IN_CAP_DV_TIMINGS`` flag), then ``ENODATA`` error code is returned.

반환값과 오류

성공하면 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
    This ioctl is not supported, or the :ref:`VIDIOC_S_DV_TIMINGS <VIDIOC_G_DV_TIMINGS>`
    parameter was unsuitable.

ENODATA
    Digital video timings are not supported for this input or output.

EBUSY
    The device is busy and therefore can not change the timings.

EPERM
    ``VIDIOC_SUBDEV_S_DV_TIMINGS`` has been called on a read-only subdevice.

v4l2_bt_timings 구조체

horizontal timing은 active `width` 뒤의 `hfrontporch`, `hsync`, `hbackporch`로 구성됩니다. vertical timing도 odd field에서 `height`, `vfrontporch`, `vsync`, `vbackporch`를 사용합니다.

interlaced format의 even field timing은 `il_vfrontporch`, `il_vsync`, `il_vbackporch`에 따로 기록합니다. progressive format에서는 이 세 필드가 모두 0이어야 합니다.

`polarities`는 vertical·horizontal sync의 positive polarity를 각각 bit 0과 bit 1로 나타냅니다. 비트가 clear이면 해당 sync는 negative polarity입니다.

`standards`는 driver output이므로 응용 프로그램이 설정할 때 0이어야 합니다. `reserved[46]`도 양쪽 모두 0으로 유지해야 합니다.

`picture_aspect`, `cea861_vic`, `hdmi_vic`는 대응하는 `HAS_*` flag가 있을 때만 읽어야 합니다. flag가 없다면 값의 의미를 가정해서는 안 됩니다.

.. c:type:: v4l2_bt_timings

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

.. cssclass:: longtable

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

    * - __u32
      - ``width``
      - Width of the active video in pixels.
    * - __u32
      - ``height``
      - Height of the active video frame in lines. So for interlaced
	formats the height of the active video in each field is
	``height``/2.
    * - __u32
      - ``interlaced``
      - Progressive (``V4L2_DV_PROGRESSIVE``) or interlaced (``V4L2_DV_INTERLACED``).
    * - __u32
      - ``polarities``
      - This is a bit mask that defines polarities of sync signals. bit 0
	(``V4L2_DV_VSYNC_POS_POL``) is for vertical sync polarity and bit
	1 (``V4L2_DV_HSYNC_POS_POL``) is for horizontal sync polarity. If
	the bit is set (1) it is positive polarity and if is cleared (0),
	it is negative polarity.
    * - __u64
      - ``pixelclock``
      - Pixel clock in Hz. Ex. 74.25MHz->74250000
    * - __u32
      - ``hfrontporch``
      - Horizontal front porch in pixels
    * - __u32
      - ``hsync``
      - Horizontal sync length in pixels
    * - __u32
      - ``hbackporch``
      - Horizontal back porch in pixels
    * - __u32
      - ``vfrontporch``
      - Vertical front porch in lines. For interlaced formats this refers
	to the odd field (aka field 1).
    * - __u32
      - ``vsync``
      - Vertical sync length in lines. For interlaced formats this refers
	to the odd field (aka field 1).
    * - __u32
      - ``vbackporch``
      - Vertical back porch in lines. For interlaced formats this refers
	to the odd field (aka field 1).
    * - __u32
      - ``il_vfrontporch``
      - Vertical front porch in lines for the even field (aka field 2) of
	interlaced field formats. Must be 0 for progressive formats.
    * - __u32
      - ``il_vsync``
      - Vertical sync length in lines for the even field (aka field 2) of
	interlaced field formats. Must be 0 for progressive formats.
    * - __u32
      - ``il_vbackporch``
      - Vertical back porch in lines for the even field (aka field 2) of
	interlaced field formats. Must be 0 for progressive formats.
    * - __u32
      - ``standards``
      - The video standard(s) this format belongs to. This will be filled
	in by the driver. Applications must set this to 0. See
	:ref:`dv-bt-standards` for a list of standards.
    * - __u32
      - ``flags``
      - Several flags giving more information about the format. See
	:ref:`dv-bt-flags` for a description of the flags.
    * - struct :c:type:`v4l2_fract`
      - ``picture_aspect``
      - The picture aspect if the pixels are not square. Only valid if the
        ``V4L2_DV_FL_HAS_PICTURE_ASPECT`` flag is set.
    * - __u8
      - ``cea861_vic``
      - The Video Identification Code according to the CEA-861 standard.
        Only valid if the ``V4L2_DV_FL_HAS_CEA861_VIC`` flag is set.
    * - __u8
      - ``hdmi_vic``
      - The Video Identification Code according to the HDMI standard.
        Only valid if the ``V4L2_DV_FL_HAS_HDMI_VIC`` flag is set.
    * - __u8
      - ``reserved[46]``
      - Reserved for future extensions. Drivers and applications must set
	the array to zero.

v4l2_dv_timings와 timing type

현재 문서가 정의하는 type은 값 0인 `V4L2_DV_BT_656_1120`이며, 상세값은 union의 `bt` 멤버에서 `v4l2_bt_timings`로 전달됩니다.

.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{7.0cm}|p{3.1cm}|

.. c:type:: v4l2_dv_timings

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

    * - __u32
      - ``type``
      - Type of DV timings as listed in :ref:`dv-timing-types`.
    * - union {
      - (anonymous)
    * - struct :c:type:`v4l2_bt_timings`
      - ``bt``
      - Timings defined by BT.656/1120 specifications
    * - __u32
      - ``reserved``\ [32]
      -
    * - }
      -

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

.. _dv-timing-types:

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

    * - Timing type
      - value
      - Description
    * -
      -
      -
    * - ``V4L2_DV_BT_656_1120``
      - 0
      - BT.656/1120 timings

DV BT timing 표준

CEA-861은 digital TV profile, DMT·CVT·GTF는 각각 VESA monitor timing 체계, SDI는 Serial Digital Interface timing을 나타냅니다.

SDI format에는 horizontal sync와 porch가 전혀 없습니다. 전체 blanking timing은 `hsync` 또는 `vsync` 필드에만 설정해야 합니다.

.. tabularcolumns:: |p{6.5cm}|p{11.0cm}|

.. cssclass:: longtable

.. _dv-bt-standards:

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

    * - Timing standard
      - Description
    * - ``V4L2_DV_BT_STD_CEA861``
      - The timings follow the CEA-861 Digital TV Profile standard
    * - ``V4L2_DV_BT_STD_DMT``
      - The timings follow the VESA Discrete Monitor Timings standard
    * - ``V4L2_DV_BT_STD_CVT``
      - The timings follow the VESA Coordinated Video Timings standard
    * - ``V4L2_DV_BT_STD_GTF``
      - The timings follow the VESA Generalized Timings Formula standard
    * - ``V4L2_DV_BT_STD_SDI``
      - The timings follow the SDI Timings standard.
	There are no horizontal syncs/porches at all in this format.
	Total blanking timings must be set in hsync or vsync fields only.

DV BT timing 플래그

`REDUCED_BLANKING`과 `CAN_REDUCE_FPS`는 read-only이므로 응용 프로그램이 설정해서는 안 됩니다. 후자는 transmitter가 필요한 frequency를 생성할 수 없는 경우 driver가 clear합니다.

CEA-861에서 framerate가 6의 배수인 format은 NTSC·PAL-M 계열과 호환되도록 1/1.001 속도를 선택할 수 있습니다. 예를 들어 30 fps는 29.97 fps가 됩니다.

transmitter에서 `REDUCED_FPS`를 설정하면 설정에 사용하는 pixelclock을 1.001로 나눕니다. 해당 frequency를 만들 수 없으면 flag는 clear됩니다.

receiver는 감소 framerate를 감지하면 `REDUCED_FPS`를 설정합니다. 이 flag는 `CAN_DETECT_REDUCED_FPS`와 `CAN_REDUCE_FPS` 조건을 만족하지 않으면 driver가 clear합니다.

`HALF_LINE`의 실제 감지·사용 가능 여부는 hardware에 달려 있습니다. `FIRST_FIELD_EXTRA_LINE`이 없으면 홀수 total height의 extra line은 second field에 있습니다.

CE format은 IT format과 달리 RGB encoding의 기본 범위가 full 0~255가 아니라 limited 16~235입니다. CEA-861의 640x480p59.94를 제외한 모든 format이 CE format입니다.

`CAN_DETECT_REDUCED_FPS`는 receiver 전용이며 60/59.94 Hz, 30/29.97 Hz, 24/23.976 Hz의 차이를 hardware가 감지할 수 있음을 뜻합니다.

.. tabularcolumns:: |p{7.7cm}|p{9.8cm}|

.. cssclass:: longtable

.. _dv-bt-flags:

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

    * - Flag
      - Description
    * - ``V4L2_DV_FL_REDUCED_BLANKING``
      - CVT/GTF specific: the timings use reduced blanking (CVT) or the
	'Secondary GTF' curve (GTF). In both cases the horizontal and/or
	vertical blanking intervals are reduced, allowing a higher
	resolution over the same bandwidth. This is a read-only flag,
	applications must not set this.
    * - ``V4L2_DV_FL_CAN_REDUCE_FPS``
      - CEA-861 specific: set for CEA-861 formats with a framerate that is
	a multiple of six. These formats can be optionally played at 1 /
	1.001 speed to be compatible with 60 Hz based standards such as
	NTSC and PAL-M that use a framerate of 29.97 frames per second. If
	the transmitter can't generate such frequencies, then the flag
	will also be cleared. This is a read-only flag, applications must
	not set this.
    * - ``V4L2_DV_FL_REDUCED_FPS``
      - CEA-861 specific: only valid for video transmitters or video
        receivers that have the ``V4L2_DV_FL_CAN_DETECT_REDUCED_FPS``
	set. This flag is cleared otherwise. It is also only valid for
	formats with the ``V4L2_DV_FL_CAN_REDUCE_FPS`` flag set, for other
	formats the flag will be cleared by the driver.

	If the application sets this flag for a transmitter, then the
	pixelclock used to set up the transmitter is divided by 1.001 to
	make it compatible with NTSC framerates. If the transmitter can't
	generate such frequencies, then the flag will be cleared.

	If a video receiver detects that the format uses a reduced framerate,
	then it will set this flag to signal this to the application.
    * - ``V4L2_DV_FL_HALF_LINE``
      - Specific to interlaced formats: if set, then the vertical
	frontporch of field 1 (aka the odd field) is really one half-line
	longer and the vertical backporch of field 2 (aka the even field)
	is really one half-line shorter, so each field has exactly the
	same number of half-lines. Whether half-lines can be detected or
	used depends on the hardware.
    * - ``V4L2_DV_FL_IS_CE_VIDEO``
      - If set, then this is a Consumer Electronics (CE) video format.
	Such formats differ from other formats (commonly called IT
	formats) in that if R'G'B' encoding is used then by default the
	R'G'B' values use limited range (i.e. 16-235) as opposed to full
	range (i.e. 0-255). All formats defined in CEA-861 except for the
	640x480p59.94 format are CE formats.
    * - ``V4L2_DV_FL_FIRST_FIELD_EXTRA_LINE``
      - Some formats like SMPTE-125M have an interlaced signal with a odd
	total height. For these formats, if this flag is set, the first
	field has the extra line. Else, it is the second field.
    * - ``V4L2_DV_FL_HAS_PICTURE_ASPECT``
      - If set, then the picture_aspect field is valid. Otherwise assume that
        the pixels are square, so the picture aspect ratio is the same as the
	width to height ratio.
    * - ``V4L2_DV_FL_HAS_CEA861_VIC``
      - If set, then the cea861_vic field is valid and contains the Video
        Identification Code as per the CEA-861 standard.
    * - ``V4L2_DV_FL_HAS_HDMI_VIC``
      - If set, then the hdmi_vic field is valid and contains the Video
        Identification Code as per the HDMI standard (HDMI Vendor Specific
	InfoFrame).
    * - ``V4L2_DV_FL_CAN_DETECT_REDUCED_FPS``
      - CEA-861 specific: only valid for video receivers, the flag is
        cleared by transmitters.
        If set, then the hardware can detect the difference between
	regular framerates and framerates reduced by 1000/1001. E.g.:
	60 vs 59.94 Hz, 30 vs 29.97 Hz or 24 vs 23.976 Hz.