VIDIOC_G_EXT_CTRLS·VIDIOC_S_EXT_CTRLS·VIDIOC_TRY_EXT_CTRLS ioctl

목적, 호출 형식과 공통 초기화

`VIDIOC_G_EXT_CTRLS`, `VIDIOC_S_EXT_CTRLS`, `VIDIOC_TRY_EXT_CTRLS`는 여러 V4L2 제어값을 한 번에 조회·설정하거나 설정 가능성을 시험합니다. 세 명령은 모두 `struct v4l2_ext_controls *argp`를 받고, `fd`는 `open()`이 반환한 파일 디스크립터입니다.

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

.. _VIDIOC_G_EXT_CTRLS:

******************************************************************
ioctl VIDIOC_G_EXT_CTRLS, VIDIOC_S_EXT_CTRLS, VIDIOC_TRY_EXT_CTRLS
******************************************************************

Name
====

VIDIOC_G_EXT_CTRLS - VIDIOC_S_EXT_CTRLS - VIDIOC_TRY_EXT_CTRLS - Get or set the value of several controls, try control values

Synopsis
========

.. c:macro:: VIDIOC_G_EXT_CTRLS

``int ioctl(int fd, VIDIOC_G_EXT_CTRLS, struct v4l2_ext_controls *argp)``

.. c:macro:: VIDIOC_S_EXT_CTRLS

``int ioctl(int fd, VIDIOC_S_EXT_CTRLS, struct v4l2_ext_controls *argp)``

.. c:macro:: VIDIOC_TRY_EXT_CTRLS

``int ioctl(int fd, VIDIOC_TRY_EXT_CTRLS, struct v4l2_ext_controls *argp)``

Arguments
=========

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

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

원자적 조회, payload 크기와 배열

이 ioctl들은 여러 제어를 원자적으로 다룹니다. 제어 ID는 control class로 묶이며, `controls` 배열의 모든 제어는 같은 클래스에 속해야 합니다.

애플리케이션은 항상 `v4l2_ext_controls`의 `count`, `which`, `controls`, `reserved`를 채우고, `controls`가 가리키는 `v4l2_ext_control` 배열도 초기화해야 합니다.

현재 값을 읽을 때는 각 원소의 `id`, `size`, `reserved2`를 초기화한 뒤 `VIDIOC_G_EXT_CTRLS`를 호출합니다. 문자열 제어는 `string`, `V4L2_CTRL_FLAG_HAS_PAYLOAD`가 설정된 compound 제어는 `ptr`도 지정해야 합니다.

문자열 같은 포인터형 제어에서 결과를 담기엔 `size`가 작으면 드라이버가 필요한 유효 크기를 `size`에 기록하고 `ENOSPC`를 반환합니다. 그 크기로 메모리를 다시 할당한 뒤 재시도해야 하며, 문자열이 사이에 늘면 다시 `ENOSPC`가 날 수 있습니다.

문자열은 먼저 `VIDIOC_QUERYCTRL`을 호출해 얻은 `maximum + 1`을 `size`로 쓰는 방식이 권장됩니다. 이 크기는 결과 문자열을 담기에 충분하다고 보장됩니다.

N차원 배열은 행 단위 순서로 전달되지만 일부 원소만 조회·설정할 수는 없습니다. 모든 원소를 한 번에 처리하며 총 payload 크기는 `elems * elem_size`입니다. 두 값은 `VIDIOC_QUERY_EXT_CTRL`로 얻습니다.

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

These ioctls allow the caller to get or set multiple controls
atomically. Control IDs are grouped into control classes (see
:ref:`ctrl-class`) and all controls in the control array must belong
to the same control class.

Applications must always fill in the ``count``, ``which``, ``controls``
and ``reserved`` fields of struct
:c:type:`v4l2_ext_controls`, and initialize the
struct :c:type:`v4l2_ext_control` array pointed to
by the ``controls`` fields.

To get the current value of a set of controls applications initialize
the ``id``, ``size`` and ``reserved2`` fields of each struct
:c:type:`v4l2_ext_control` and call the
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. String controls must also set the
``string`` field. Controls of compound types
(``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set) must set the ``ptr`` field.

If the ``size`` is too small to receive the control result (only
relevant for pointer-type controls like strings), then the driver will
set ``size`` to a valid value and return an ``ENOSPC`` error code. You
should re-allocate the memory to this new size and try again. For the
string type it is possible that the same issue occurs again if the
string has grown in the meantime. It is recommended to call
:ref:`VIDIOC_QUERYCTRL` first and use
``maximum``\ +1 as the new ``size`` value. It is guaranteed that that is
sufficient memory.

N-dimensional arrays are set and retrieved row-by-row. You cannot set a
partial array, all elements have to be set or retrieved. The total size
is calculated as ``elems`` * ``elem_size``. These values can be obtained
by calling :ref:`VIDIOC_QUERY_EXT_CTRL <VIDIOC_QUERYCTRL>`.

설정·시험, request와 원자성

값을 바꾸려면 각 `v4l2_ext_control`의 `id`, `size`, `reserved2`와 형식에 맞는 `value`, `value64`, `string` 또는 `ptr`를 초기화한 뒤 `VIDIOC_S_EXT_CTRLS`를 호출합니다. 모든 값이 유효할 때만 제어 집합이 설정됩니다.

값의 유효성만 확인하려면 같은 필드를 채워 `VIDIOC_TRY_EXT_CTRLS`를 호출합니다. 잘못된 값을 가장 가까운 유효값으로 자동 조정할지 오류를 반환할지는 드라이버가 결정합니다.

`id` 또는 `which`가 잘못되면 `EINVAL`입니다. 범위를 벗어난 값은 가장 가까운 값으로 조정되어 구조체에 돌아오거나 `ERANGE`가 될 수 있습니다. 지원하지 않는 메뉴 인덱스처럼 값 자체가 부적절하면 `EINVAL`입니다.

아직 큐에 넣지 않은 media request의 파일 디스크립터를 `request_fd`에 넣고 `which = V4L2_CTRL_WHICH_REQUEST_VAL`로 설정하면, `VIDIOC_S_EXT_CTRLS`의 값은 즉시 적용되지 않고 같은 request의 버퍼에 대해 드라이버가 적용합니다.

장치가 request를 지원하지 않으면 `EACCES`, request 지원 장치에 잘못된 파일 디스크립터를 주면 `EINVAL`, 이미 큐에 넣은 request에 설정을 시도하면 `EBUSY`입니다.

request 값에 `VIDIOC_G_EXT_CTRLS`를 사용하면 request 완료 시점의 제어값을 반환합니다. request가 아직 완료되지 않았으면 `EACCES`입니다.

드라이버는 모든 값이 올바를 때만 제어 집합 전체를 조회·설정해 일부만 처리되는 상태를 막습니다. 다만 실패한 I2C 명령 같은 저수준 하드웨어 오류는 일부 제어만 처리된 상태를 여전히 만들 수 있습니다.

To change the value of a set of controls applications initialize the
``id``, ``size``, ``reserved2`` and ``value/value64/string/ptr`` fields
of each struct :c:type:`v4l2_ext_control` and call
the :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. The controls will only be set if *all*
control values are valid.

To check if a set of controls have correct values applications
initialize the ``id``, ``size``, ``reserved2`` and
``value/value64/string/ptr`` fields of each struct
:c:type:`v4l2_ext_control` and call the
:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctl. It is up to the driver whether wrong
values are automatically adjusted to a valid value or if an error is
returned.

When the ``id`` or ``which`` is invalid drivers return an ``EINVAL`` error
code. When the value is out of bounds drivers can choose to take the
closest valid value or return an ``ERANGE`` error code, whatever seems more
appropriate. In the first case the new value is set in struct
:c:type:`v4l2_ext_control`. If the new control value
is inappropriate (e.g. the given menu index is not supported by the menu
control), then this will also result in an ``EINVAL`` error code error.

If ``request_fd`` is set to a not-yet-queued :ref:`request <media-request-api>`
file descriptor and ``which`` is set to ``V4L2_CTRL_WHICH_REQUEST_VAL``,
then the controls are not applied immediately when calling
:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, but instead are applied by
the driver for the buffer associated with the same request.
If the device does not support requests, then ``EACCES`` will be returned.
If requests are supported but an invalid request file descriptor is given,
then ``EINVAL`` will be returned.

An attempt to call :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` for a
request that has already been queued will result in an ``EBUSY`` error.

If ``request_fd`` is specified and ``which`` is set to
``V4L2_CTRL_WHICH_REQUEST_VAL`` during a call to
:ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then it will return the
values of the controls at the time of request completion.
If the request is not yet completed, then this will result in an
``EACCES`` error.

The driver will only set/get these controls if all control values are
correct. This prevents the situation where only some of the controls
were set/get. Only low-level errors (e. g. a failed i2c command) can
still cause this situation.

struct v4l2_ext_control 기본·행렬 필드

`v4l2_ext_control`은 제어 ID, payload 크기, 예약 필드와 값 union을 담습니다. `id`는 애플리케이션이 지정하고, `size`는 payload 메모리의 전체 바이트 크기입니다.

보통 `size`는 0이지만 포인터 제어에서는 payload를 담거나 받을 메모리 크기로 설정합니다. 조회 시 부족하면 드라이버가 충분한 크기로 고치고 `ENOSPC`를 반환합니다. 문자열에서 `size`는 문자열 길이가 아니라 문자열을 담은 메모리 크기입니다.

.. tabularcolumns:: |p{6.8cm}|p{4.0cm}|p{6.5cm}|

.. c:type:: v4l2_ext_control

.. raw:: latex

   \footnotesize

.. cssclass:: longtable

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

    * - __u32
      - ``id``
      - Identifies the control, set by the application.
    * - __u32
      - ``size``
      - The total size in bytes of the payload of this control.
    * - :cspan:`2` The ``size`` field is normally 0, but for pointer
	controls this should be set to the size of the memory that contains
	the payload or that will receive the payload.
	If :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` finds that this value
	is less than is required to store the payload result, then it is set
	to a value large enough to store the payload result and ``ENOSPC`` is
	returned.

	.. note::

	   For string controls, this ``size`` field should
	   not be confused with the length of the string. This field refers
	   to the size of the memory that contains the string. The actual
	   *length* of the string may well be much smaller.
    * - __u32
      - ``reserved2``\ [1]
      - Reserved for future extensions. Drivers and applications must set
	the array to zero.
    * - union {
      - (anonymous)
    * - __s32
      - ``value``
      - New value or current value. Valid if this control is not of type
	``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
	not set.
    * - __s64
      - ``value64``
      - New value or current value. Valid if this control is of type
	``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
	not set.
    * - char *
      - ``string``
      - A pointer to a string. Valid if this control is of type
	``V4L2_CTRL_TYPE_STRING``.
    * - __u8 *
      - ``p_u8``
      - A pointer to a matrix control of unsigned 8-bit values. Valid if
	this control is of type ``V4L2_CTRL_TYPE_U8``.
    * - __u16 *
      - ``p_u16``
      - A pointer to a matrix control of unsigned 16-bit values. Valid if
	this control is of type ``V4L2_CTRL_TYPE_U16``.
    * - __u32 *
      - ``p_u32``
      - A pointer to a matrix control of unsigned 32-bit values. Valid if
	this control is of type ``V4L2_CTRL_TYPE_U32``.
    * - __s32 *
      - ``p_s32``
      - A pointer to a matrix control of signed 32-bit values. Valid if
        this control is of type ``V4L2_CTRL_TYPE_INTEGER`` and
        ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set.
    * - __s64 *
      - ``p_s64``
      - A pointer to a matrix control of signed 64-bit values. Valid if
        this control is of type ``V4L2_CTRL_TYPE_INTEGER64`` and
        ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set.
    * - struct :c:type:`v4l2_area` *
      - ``p_area``
      - A pointer to a struct :c:type:`v4l2_area`. Valid if this control is

코덱·HDR compound payload 포인터

나머지 union 멤버는 사각형, stateless 코덱 매개변수, HDR10 메타데이터처럼 형식이 정해진 compound payload를 가리킵니다. 포인터 필드와 제어 형식은 정확히 대응해야 합니다.

범용 `ptr`는 N차원 배열일 수 있는 compound 형식 또는 제어 형식 값이 `V4L2_CTRL_COMPOUND_TYPES` 이상인 compound 형식을 가리킵니다. 해당 제어에 `V4L2_CTRL_FLAG_HAS_PAYLOAD`가 설정된 경우에만 유효합니다.

        of type ``V4L2_CTRL_TYPE_AREA``.
    * - struct :c:type:`v4l2_rect` *
      - ``p_rect``
      - A pointer to a struct :c:type:`v4l2_rect`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_RECT``.
    * - struct :c:type:`v4l2_ctrl_h264_sps` *
      - ``p_h264_sps``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_sps`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_SPS``.
    * - struct :c:type:`v4l2_ctrl_h264_pps` *
      - ``p_h264_pps``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_pps`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_PPS``.
    * - struct :c:type:`v4l2_ctrl_h264_scaling_matrix` *
      - ``p_h264_scaling_matrix``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_scaling_matrix`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_SCALING_MATRIX``.
    * - struct :c:type:`v4l2_ctrl_h264_pred_weights` *
      - ``p_h264_pred_weights``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_pred_weights`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_PRED_WEIGHTS``.
    * - struct :c:type:`v4l2_ctrl_h264_slice_params` *
      - ``p_h264_slice_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_slice_params`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_SLICE_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_h264_decode_params` *
      - ``p_h264_decode_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_h264_decode_params`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_H264_DECODE_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_fwht_params` *
      - ``p_fwht_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_fwht_params`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_FWHT_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_vp8_frame` *
      - ``p_vp8_frame``
      - A pointer to a struct :c:type:`v4l2_ctrl_vp8_frame`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_VP8_FRAME``.
    * - struct :c:type:`v4l2_ctrl_mpeg2_sequence` *
      - ``p_mpeg2_sequence``
      - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_sequence`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_MPEG2_SEQUENCE``.
    * - struct :c:type:`v4l2_ctrl_mpeg2_picture` *
      - ``p_mpeg2_picture``
      - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_picture`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_MPEG2_PICTURE``.
    * - struct :c:type:`v4l2_ctrl_mpeg2_quantisation` *
      - ``p_mpeg2_quantisation``
      - A pointer to a struct :c:type:`v4l2_ctrl_mpeg2_quantisation`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_MPEG2_QUANTISATION``.
    * - struct :c:type:`v4l2_ctrl_vp9_compressed_hdr` *
      - ``p_vp9_compressed_hdr_probs``
      - A pointer to a struct :c:type:`v4l2_ctrl_vp9_compressed_hdr`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_VP9_COMPRESSED_HDR``.
    * - struct :c:type:`v4l2_ctrl_vp9_frame` *
      - ``p_vp9_frame``
      - A pointer to a struct :c:type:`v4l2_ctrl_vp9_frame`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_VP9_FRAME``.
    * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` *
      - ``p_hdr10_cll``
      - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``.
    * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` *
      - ``p_hdr10_mastering``
      - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``.
    * - struct :c:type:`v4l2_ctrl_hevc_sps` *
      - ``p_hevc_sps``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_sps`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_SPS``.
    * - struct :c:type:`v4l2_ctrl_hevc_pps` *
      - ``p_hevc_pps``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_pps`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_PPS``.
    * - struct :c:type:`v4l2_ctrl_hevc_slice_params` *
      - ``p_hevc_slice_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_slice_params`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_hevc_scaling_matrix` *
      - ``p_hevc_scaling_matrix``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_scaling_matrix`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_SCALING_MATRIX``.
    * - struct :c:type:`v4l2_ctrl_hevc_decode_params` *
      - ``p_hevc_decode_params``
      - A pointer to a struct :c:type:`v4l2_ctrl_hevc_decode_params`. Valid if this
        control is of type ``V4L2_CTRL_TYPE_HEVC_DECODE_PARAMS``.
    * - struct :c:type:`v4l2_ctrl_av1_sequence` *
      - ``p_av1_sequence``
      - A pointer to a struct :c:type:`v4l2_ctrl_av1_sequence`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_AV1_SEQUENCE``.
    * - struct :c:type:`v4l2_ctrl_av1_tile_group_entry` *
      - ``p_av1_tile_group_entry``
      - A pointer to a struct :c:type:`v4l2_ctrl_av1_tile_group_entry`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_AV1_TILE_GROUP_ENTRY``.
    * - struct :c:type:`v4l2_ctrl_av1_frame` *
      - ``p_av1_frame``
      - A pointer to a struct :c:type:`v4l2_ctrl_av1_frame`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_AV1_FRAME``.
    * - struct :c:type:`v4l2_ctrl_av1_film_grain` *
      - ``p_av1_film_grain``
      - A pointer to a struct :c:type:`v4l2_ctrl_av1_film_grain`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_AV1_FILM_GRAIN``.
    * - struct :c:type:`v4l2_ctrl_hdr10_cll_info` *
      - ``p_hdr10_cll_info``
      - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_cll_info`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_HDR10_CLL_INFO``.
    * - struct :c:type:`v4l2_ctrl_hdr10_mastering_display` *
      - ``p_hdr10_mastering_display``
      - A pointer to a struct :c:type:`v4l2_ctrl_hdr10_mastering_display`. Valid if this control is
        of type ``V4L2_CTRL_TYPE_HDR10_MASTERING_DISPLAY``.
    * - void *
      - ``ptr``
      - A pointer to a compound type which can be an N-dimensional array
	and/or a compound type (the control's type is >=
	``V4L2_CTRL_COMPOUND_TYPES``). Valid if
	``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is set for this control.
    * - }
      -

struct v4l2_ext_controls와 which

`v4l2_ext_controls`는 어떤 종류의 값을 처리할지, 제어 배열 개수와 오류 위치, request 파일 디스크립터 및 배열 포인터를 담습니다. 익명 union의 `ctrl_class`는 호환성용 옛 이름이며 새 코드는 `which`를 사용해야 합니다.

기본값·최솟값·최댓값 선택자는 값을 가져올 수만 있고 설정하거나 시험할 수 없습니다. request 값을 선택했는데 장치가 request를 지원하지 않으면 `EACCES`입니다.

최솟값·최댓값 조회 지원 여부는 `V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX`로 확인합니다. 대부분의 비-compound 제어가 지원하며 compound 제어의 min/max 의미는 각 제어 문서가 정의합니다. 의미가 문서화되지 않은 compound 제어를 조회하면 `-EINVAL`입니다.

하위 호환성을 위해 `which`에 control class를 넣을 수도 있지만 폐기 예정 방식입니다. 이때 모든 제어가 같은 클래스여야 합니다. 새 코드는 `V4L2_CTRL_WHICH_CUR_VAL`을 사용합니다.

아주 오래된 드라이버의 지원 여부는 `which = V4L2_CTRL_WHICH_CUR_VAL`, `count = 0`으로 `VIDIOC_TRY_EXT_CTRLS`를 호출해 시험합니다. 실패하면 해당 드라이버는 현재값 선택자를 지원하지 않으므로 control class 방식이 필요합니다.

.. raw:: latex

   \normalsize

.. tabularcolumns:: |p{4.0cm}|p{2.5cm}|p{10.8cm}|

.. c:type:: v4l2_ext_controls

.. cssclass:: longtable

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

    * - union {
      - (anonymous)
    * - __u32
      - ``which``
      - Which value of the control to get/set/try.
    * - :cspan:`2` ``V4L2_CTRL_WHICH_CUR_VAL`` will return the current value of
	the control, ``V4L2_CTRL_WHICH_DEF_VAL`` will return the default
	value of the control, ``V4L2_CTRL_WHICH_MIN_VAL`` will return the minimum
	value of the control, and ``V4L2_CTRL_WHICH_MAX_VAL`` will return the maximum
	value of the control. ``V4L2_CTRL_WHICH_REQUEST_VAL`` indicates that
	the control value has to be retrieved from a request or tried/set for
	a request. In that case the ``request_fd`` field contains the
	file descriptor of the request that should be used. If the device
	does not support requests, then ``EACCES`` will be returned.

	When using ``V4L2_CTRL_WHICH_DEF_VAL``, ``V4L2_CTRL_WHICH_MIN_VAL``
	or ``V4L2_CTRL_WHICH_MAX_VAL`` be aware that you can only get the
	default/minimum/maximum value of the control, you cannot set or try it.

	Whether a control supports querying the minimum and maximum values using
	``V4L2_CTRL_WHICH_MIN_VAL`` and ``V4L2_CTRL_WHICH_MAX_VAL`` is indicated
	by the ``V4L2_CTRL_FLAG_HAS_WHICH_MIN_MAX`` flag. Most non-compound
	control types support this. For controls with compound types, the
	definition of minimum/maximum values are provided by
	the control documentation. If a compound control does not document the
	meaning of minimum/maximum value, then querying the minimum or maximum
	value will result in the error code -EINVAL.

	For backwards compatibility you can also use a control class here
	(see :ref:`ctrl-class`). In that case all controls have to
	belong to that control class. This usage is deprecated, instead
	just use ``V4L2_CTRL_WHICH_CUR_VAL``. There are some very old
	drivers that do not yet support ``V4L2_CTRL_WHICH_CUR_VAL`` and
	that require a control class here. You can test for such drivers
	by setting ``which`` to ``V4L2_CTRL_WHICH_CUR_VAL`` and calling
	:ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` with a count of 0.
	If that fails, then the driver does not support ``V4L2_CTRL_WHICH_CUR_VAL``.
    * - __u32
      - ``ctrl_class``
      - Deprecated name kept for backwards compatibility. Use ``which`` instead.
    * - }
      -

count, error_idx와 request_fd

특정 제어와 연결된 오류이면 `error_idx`는 그 제어의 배열 인덱스입니다. 특정 제어와 무관하거나 하드웨어 접근 전 검증 단계가 실패하면 `error_idx = count`입니다. ioctl이 성공한 경우 `error_idx`는 정의되지 않습니다.

사전 검증은 모든 ID의 유효성, 읽기 전용 제어 쓰기, 쓰기 전용 제어 읽기 등 하드웨어 없이 확인 가능한 조건을 검사합니다. 정확한 범위는 드라이버에 따라 다르지만 가능한 검사를 최대한 먼저 수행해야 합니다.

검증 단계는 피할 수 있는 문제로 하드웨어가 불일치 상태가 되는 일을 줄입니다. 다만 `error_idx = count`만으로는 어떤 제어가 검증에 실패했는지 알 수 없다는 단점이 있습니다.

검증은 통과했지만 실제 하드웨어 접근에서 실패하면 `error_idx < count`입니다. 이때 `error_idx - 1`까지의 제어만 올바르게 읽거나 썼고, 실패 위치 이후 제어의 상태는 정의되지 않습니다.

`VIDIOC_TRY_EXT_CTRLS`는 하드웨어를 접근하지 않으므로 검증 실패 제어를 `error_idx`로 직접 알려 줍니다. `VIDIOC_S_EXT_CTRLS`가 `error_idx = count`로 실패하면 TRY를 호출해 실제 실패 제어를 찾을 수 있지만, `VIDIOC_G_EXT_CTRLS`에는 대응하는 TRY 조회가 없습니다.

`request_fd`는 `which = V4L2_CTRL_WHICH_REQUEST_VAL`일 때만 유효합니다. request 미지원은 `EACCES`, 잘못된 request 파일 디스크립터는 `EINVAL`입니다.

    * - __u32
      - ``count``
      - The number of controls in the controls array. May also be zero.
    * - __u32
      - ``error_idx``
      - Index of the failing control. Set by the driver in case of an error.
    * - :cspan:`2` If the error is associated
	with a particular control, then ``error_idx`` is set to the index
	of that control. If the error is not related to a specific
	control, or the validation step failed (see below), then
	``error_idx`` is set to ``count``. The value is undefined if the
	ioctl returned 0 (success).

	Before controls are read from/written to hardware a validation
	step takes place: this checks if all controls in the list are
	valid controls, if no attempt is made to write to a read-only
	control or read from a write-only control, and any other up-front
	checks that can be done without accessing the hardware. The exact
	validations done during this step are driver dependent since some
	checks might require hardware access for some devices, thus making
	it impossible to do those checks up-front. However, drivers should
	make a best-effort to do as many up-front checks as possible.

	This check is done to avoid leaving the hardware in an
	inconsistent state due to easy-to-avoid problems. But it leads to
	another problem: the application needs to know whether an error
	came from the validation step (meaning that the hardware was not
	touched) or from an error during the actual reading from/writing
	to hardware.

	The, in hindsight quite poor, solution for that is to set
	``error_idx`` to ``count`` if the validation failed. This has the
	unfortunate side-effect that it is not possible to see which
	control failed the validation. If the validation was successful
	and the error happened while accessing the hardware, then
	``error_idx`` is less than ``count`` and only the controls up to
	``error_idx-1`` were read or written correctly, and the state of
	the remaining controls is undefined.

	Since :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` does not access hardware there is
	also no need to handle the validation step in this special way, so
	``error_idx`` will just be set to the control that failed the
	validation step instead of to ``count``. This means that if
	:ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` fails with ``error_idx`` set to ``count``,
	then you can call :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` to try to discover the
	actual control that failed the validation step. Unfortunately,
	there is no ``TRY`` equivalent for :ref:`VIDIOC_G_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`.
    * - __s32
      - ``request_fd``
      - File descriptor of the request to be used by this operation. Only
	valid if ``which`` is set to ``V4L2_CTRL_WHICH_REQUEST_VAL``.
	If the device does not support requests, then ``EACCES`` will be returned.
	If requests are supported but an invalid request file descriptor is
	given, then ``EINVAL`` will be returned.
    * - __u32
      - ``reserved``\ [1]
      - Reserved for future extensions.

	Drivers and applications must set the array to zero.
    * - struct :c:type:`v4l2_ext_control` *
      - ``controls``
      - Pointer to an array of ``count`` v4l2_ext_control structures.

	Ignored if ``count`` equals zero.

Control classes

`V4L2_CTRL_CLASS_USER`에는 단일 제어 ioctl인 `VIDIOC_S_CTRL`과 `VIDIOC_G_CTRL`로 설정·조회할 수 있는 모든 제어가 속합니다. 나머지 클래스의 세부 제어는 각각 codec, camera, FM, flash, JPEG, image source·processing, tuner, detect, colorimetry 문서에 정의됩니다.

.. tabularcolumns:: |p{7.3cm}|p{2.0cm}|p{8.0cm}|

.. cssclass:: longtable

.. _ctrl-class:

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

    * - ``V4L2_CTRL_CLASS_USER``
      - 0x980000
      - The class containing user controls. These controls are described
	in :ref:`control`. All controls that can be set using the
	:ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` and
	:ref:`VIDIOC_G_CTRL <VIDIOC_G_CTRL>` ioctl belong to this
	class.
    * - ``V4L2_CTRL_CLASS_CODEC``
      - 0x990000
      - The class containing stateful codec controls. These controls are
	described in :ref:`codec-controls`.
    * - ``V4L2_CTRL_CLASS_CAMERA``
      - 0x9a0000
      - The class containing camera controls. These controls are described
	in :ref:`camera-controls`.
    * - ``V4L2_CTRL_CLASS_FM_TX``
      - 0x9b0000
      - The class containing FM Transmitter (FM TX) controls. These
	controls are described in :ref:`fm-tx-controls`.
    * - ``V4L2_CTRL_CLASS_FLASH``
      - 0x9c0000
      - The class containing flash device controls. These controls are
	described in :ref:`flash-controls`.
    * - ``V4L2_CTRL_CLASS_JPEG``
      - 0x9d0000
      - The class containing JPEG compression controls. These controls are
	described in :ref:`jpeg-controls`.
    * - ``V4L2_CTRL_CLASS_IMAGE_SOURCE``
      - 0x9e0000
      - The class containing image source controls. These controls are
	described in :ref:`image-source-controls`.
    * - ``V4L2_CTRL_CLASS_IMAGE_PROC``
      - 0x9f0000
      - The class containing image processing controls. These controls are
	described in :ref:`image-process-controls`.
    * - ``V4L2_CTRL_CLASS_FM_RX``
      - 0xa10000
      - The class containing FM Receiver (FM RX) controls. These controls
	are described in :ref:`fm-rx-controls`.
    * - ``V4L2_CTRL_CLASS_RF_TUNER``
      - 0xa20000
      - The class containing RF tuner controls. These controls are
	described in :ref:`rf-tuner-controls`.
    * - ``V4L2_CTRL_CLASS_DETECT``
      - 0xa30000
      - The class containing motion or object detection controls. These controls
        are described in :ref:`detect-controls`.
    * - ``V4L2_CTRL_CLASS_CODEC_STATELESS``
      - 0xa40000
      - The class containing stateless codec controls. These controls are
	described in :ref:`codec-stateless-controls`.
    * - ``V4L2_CTRL_CLASS_COLORIMETRY``
      - 0xa50000
      - The class containing colorimetry controls. These controls are
	described in :ref:`colorimetry-controls`.

반환값과 오류

성공하면 0을 반환합니다. 오류가 발생하면 -1을 반환하고 `errno`를 설정하며, 아래 전용 오류 외에도 Generic Error Codes 장의 공통 오류가 적용됩니다.

`EINVAL`은 구조체 선택 오류뿐 아니라 여러 제어값 사이의 충돌도 나타낼 수 있습니다. `ENOSPC`에서는 반환된 `size`를 사용해 버퍼를 늘리고 전체 원자적 작업을 다시 시도해야 합니다.

`EACCES`는 Unix 파일 권한만 뜻하지 않습니다. 제어의 읽기·쓰기 방향 위반, request 완료 시점 위반, request 기능 부재, 비활성 제어값 캐시 불가를 모두 포함하므로 호출 문맥을 함께 확인해야 합니다.

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 struct :c:type:`v4l2_ext_control` ``id`` is
    invalid, or the struct :c:type:`v4l2_ext_controls`
    ``which`` is invalid, or the struct
    :c:type:`v4l2_ext_control` ``value`` was
    inappropriate (e.g. the given menu index is not supported by the
    driver), or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL``
    but the given ``request_fd`` was invalid or ``V4L2_CTRL_WHICH_REQUEST_VAL``
    is not supported by the kernel.
    This error code is also returned by the
    :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` and :ref:`VIDIOC_TRY_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>` ioctls if two or
    more control values are in conflict.

ERANGE
    The struct :c:type:`v4l2_ext_control` ``value``
    is out of bounds.

EBUSY
    The control is temporarily not changeable, possibly because another
    applications took over control of the device function this control
    belongs to, or (if the ``which`` field was set to
    ``V4L2_CTRL_WHICH_REQUEST_VAL``) the request was queued but not yet
    completed.

ENOSPC
    The space reserved for the control's payload is insufficient. The
    field ``size`` is set to a value that is enough to store the payload
    and this error code is returned.

EACCES
    Attempt to try or set a read-only control, or to get a write-only
    control, or to get a control from a request that has not yet been
    completed.

    Or the ``which`` field was set to ``V4L2_CTRL_WHICH_REQUEST_VAL`` but the
    device does not support requests.

    Or if there is an attempt to set an inactive control and the driver is
    not capable of caching the new value until the control is active again.