The Linux USB Video Class (UVC) driver

문서 범위와 연락처

이 문서는 GPL-2.0 라이선스를 따르며 Linux USB Video Class(UVC) 드라이버의 전용 IOCTL과 구현 참고 사항을 설명합니다.

질문과 의견은 Linux UVC 개발 메일링 리스트 `linux-media@vger.kernel.org`로 보낼 수 있습니다.

.. SPDX-License-Identifier: GPL-2.0

The Linux USB Video Class (UVC) driver
======================================

This file documents some driver-specific aspects of the UVC driver, such as
driver-specific ioctls and implementation notes.

Questions and remarks can be sent to the Linux UVC development mailing list at
linux-media@vger.kernel.org.

Extension Unit(XU) 지원

UVC 규격은 Extension Unit(XU)을 통한 벤더별 확장을 허용합니다. Linux UVC 드라이버는 XU 컨트롤을 두 가지 별도 방식으로 지원합니다.

첫 번째 방식은 특정 XU 컨트롤을 V4L2 컨트롤에 매핑합니다. 그러면 해당 컨트롤이 일반 컨트롤 열거 과정에 나타나므로 범용 V4L2 애플리케이션에서도 사용할 수 있습니다.

두 번째 방식은 애플리케이션이 uvcvideo 전용 인터페이스를 알아야 하지만, 최대한의 유연성을 위해 UVC XU 전체를 사용자 공간에 노출합니다. 두 방식은 서로 보완적입니다.

Extension Unit (XU) support
---------------------------

Introduction
~~~~~~~~~~~~

The UVC specification allows for vendor-specific extensions through extension
units (XUs). The Linux UVC driver supports extension unit controls (XU controls)
through two separate mechanisms:

  - through mappings of XU controls to V4L2 controls
  - through a driver-specific ioctl interface

The first one allows generic V4L2 applications to use XU controls by mapping
certain XU controls onto V4L2 controls, which then show up during ordinary
control enumeration.

The second mechanism requires uvcvideo-specific knowledge for the application to
access XU controls but exposes the entire UVC XU concept to user space for
maximum flexibility.

Both mechanisms complement each other and are described in more detail below.

런타임 컨트롤 매핑

UVC 드라이버는 사용자 공간 애플리케이션이 런타임에 컨트롤 매핑을 정의하는 API를 제공합니다. 개별 XU 컨트롤이나 그 일부 바이트 범위를 새 V4L2 컨트롤에 매핑할 수 있습니다.

매핑된 컨트롤은 밝기나 대비 같은 기본 컨트롤과 똑같이 일반 V4L2 컨트롤로 표시되고 동작합니다. 다만 그 V4L2 컨트롤을 읽거나 쓰면 연결된 XU 컨트롤 읽기 또는 쓰기가 실행됩니다.

컨트롤 매핑을 만드는 IOCTL은 `UVCIOC_CTRL_MAP`입니다. 0.2.0 이전 드라이버에서는 먼저 `UVCIOC_CTRL_ADD`로 XU 컨트롤 정보를 전달해야 했지만, 최신 uvcvideo는 장치에서 직접 정보를 질의하므로 더 이상 필요하지 않습니다.

`UVCIOC_CTRL_MAP`의 세부 사항은 아래의 IOCTL 참조 절에서 설명합니다.

Control mappings
~~~~~~~~~~~~~~~~

The UVC driver provides an API for user space applications to define so-called
control mappings at runtime. These allow for individual XU controls or byte
ranges thereof to be mapped to new V4L2 controls. Such controls appear and
function exactly like normal V4L2 controls (i.e. the stock controls, such as
brightness, contrast, etc.). However, reading or writing of such a V4L2 controls
triggers a read or write of the associated XU control.

The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.
Previous driver versions (before 0.2.0) required another ioctl to be used
beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.
This is no longer necessary as newer uvcvideo versions query the information
directly from the device.

For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled
"IOCTL reference" below.

드라이버 전용 XU 컨트롤 인터페이스

테스트, 펌웨어 업로드, 바이너리 컨트롤처럼 XU 컨트롤에 직접 접근해야 하는 애플리케이션을 위해 `UVCIOC_CTRL_QUERY` 드라이버 전용 IOCTL이 제공됩니다. 이 호출은 저수준 UVC 컨트롤 요청과 직접 대응하는 질의를 UVC 드라이버에 보냅니다.

요청하려면 컨트롤이 속한 Extension Unit의 UVC unit ID와 control selector를 알아야 합니다. 애플리케이션에 값을 하드코딩하거나, UVC descriptor를 파싱하거나, 가능하면 Media Controller API로 장치 entity를 열거해 얻을 수 있습니다.

컨트롤 크기를 모르면 충분한 버퍼를 할당하고 정확한 크기를 설정하기 위해 먼저 `UVC_GET_LEN`을 요청해야 합니다. 특정 컨트롤에서 `UVC_GET_CUR` 또는 `UVC_SET_CUR`이 유효한지 확인하려면 `UVC_GET_INFO`를 요청합니다.

`UVC_GET_INFO` 결과 바이트의 bit 0은 GET 지원, bit 1은 SET 지원을 나타냅니다.

`UVCIOC_CTRL_QUERY`가 추가되면서 `UVCIOC_CTRL_GET`과 `UVCIOC_CTRL_SET`은 기능이 QUERY의 부분집합이므로 폐기 예정이 되었습니다. 당분간은 지원되지만 새 애플리케이션은 `UVCIOC_CTRL_QUERY`를 사용하는 것이 권장됩니다.

3. Driver specific XU control interface

For applications that need to access XU controls directly, e.g. for testing
purposes, firmware upload, or accessing binary controls, a second mechanism to
access XU controls is provided in the form of a driver-specific ioctl, namely
UVCIOC_CTRL_QUERY.

A call to this ioctl allows applications to send queries to the UVC driver that
directly map to the low-level UVC control requests.

In order to make such a request the UVC unit ID of the control's extension unit
and the control selector need to be known. This information either needs to be
hardcoded in the application or queried using other ways such as by parsing the
UVC descriptor or, if available, using the media controller API to enumerate a
device's entities.

Unless the control size is already known it is necessary to first make a
UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer
and set the buffer size to the correct value. Similarly, to find out whether
UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a
UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET
supported) of the resulting byte indicate which requests are valid.

With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and
UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a
subset of the former ioctl. For the time being they are still supported but
application developers are encouraged to use UVCIOC_CTRL_QUERY instead.

For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled
"IOCTL reference" below.

보안과 디버깅

현재 API는 세밀한 접근 제어 기능을 제공하지 않습니다. `UVCIOC_CTRL_ADD`와 `UVCIOC_CTRL_MAP` IOCTL을 사용하려면 super user 권한이 필요합니다. 이 부분을 개선할 제안을 환영합니다.

XU 컨트롤이나 일반 컨트롤 문제를 디버깅할 때는 모듈 매개변수 `trace`에서 `UVC_TRACE_CONTROL` 비트를 활성화하는 것이 권장됩니다. 그러면 추가 진단 출력이 시스템 로그에 기록됩니다.

Security
~~~~~~~~

The API doesn't currently provide a fine-grained access control facility. The
UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.

Suggestions on how to improve this are welcome.


Debugging
~~~~~~~~~

In order to debug problems related to XU controls or controls in general it is
recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.
This causes extra output to be written into the system log.

UVCIOC_CTRL_MAP

`UVCIOC_CTRL_MAP`은 UVC 컨트롤 또는 그 일부를 V4L2 컨트롤에 매핑합니다. 인자는 `struct uvc_xu_control_mapping`입니다. 매핑을 정의하면 사용자 공간은 V4L2 컨트롤 API로 벤더 정의 UVC 컨트롤에 접근할 수 있습니다.

애플리케이션은 기존 UVC 컨트롤 정보와 새 V4L2 컨트롤 정보를 `uvc_xu_control_mapping` 구조체에 채웁니다. 원문은 기존 컨트롤이 `UVCIOC_CTRL_ADD`로 정의된다고 설명합니다.

하나의 UVC 컨트롤을 여러 V4L2 컨트롤에 매핑할 수 있습니다. 예를 들어 UVC pan/tilt 컨트롤을 별도의 pan과 tilt V4L2 컨트롤로 나눌 수 있습니다. `size`와 `offset`으로 UVC 컨트롤을 겹치지 않는 필드로 나눈 뒤 각각 독립적으로 매핑합니다.

부호 있는 정수 V4L2 컨트롤은 `data_type`을 `UVC_CTRL_DATA_TYPE_SIGNED`로 설정해야 합니다. 현재 다른 값은 무시됩니다.

성공하면 0을 반환합니다. 오류이면 -1을 반환하고 `errno`를 알맞게 설정합니다.

IOCTL reference
~~~~~~~~~~~~~~~

UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Argument: struct uvc_xu_control_mapping

**Description**:

	This ioctl creates a mapping between a UVC control or part of a UVC
	control and a V4L2 control. Once mappings are defined, userspace
	applications can access vendor-defined UVC control through the V4L2
	control API.

	To create a mapping, applications fill the uvc_xu_control_mapping
	structure with information about an existing UVC control defined with
	UVCIOC_CTRL_ADD and a new V4L2 control.

	A UVC control can be mapped to several V4L2 controls. For instance,
	a UVC pan/tilt control could be mapped to separate pan and tilt V4L2
	controls. The UVC control is divided into non overlapping fields using
	the 'size' and 'offset' fields and are then independently mapped to
	V4L2 control.

	For signed integer V4L2 controls the data_type field should be set to
	UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored.

**Return value**:

	On success 0 is returned. On error -1 is returned and errno is set
	appropriately.

	ENOMEM
		Not enough memory to perform the operation.
	EPERM
		Insufficient privileges (super user privileges are required).
	EINVAL
		No such UVC control.
	EOVERFLOW
		The requested offset and size would overflow the UVC control.
	EEXIST
		Mapping already exists.

매핑 구조체와 데이터 형식

**Data types**:

.. code-block:: none

	* struct uvc_xu_control_mapping

	__u32	id		V4L2 control identifier
	__u8	name[32]	V4L2 control name
	__u8	entity[16]	UVC extension unit GUID
	__u8	selector	UVC control selector
	__u8	size		V4L2 control size (in bits)
	__u8	offset		V4L2 control offset (in bits)
	enum v4l2_ctrl_type
		v4l2_type	V4L2 control type
	enum uvc_control_data_type
		data_type	UVC control data type
	struct uvc_menu_info
		*menu_info	Array of menu entries (for menu controls only)
	__u32	menu_count	Number of menu entries (for menu controls only)

	* struct uvc_menu_info

	__u32	value		Menu entry value used by the device
	__u8	name[32]	Menu entry name


	* enum uvc_control_data_type

	UVC_CTRL_DATA_TYPE_RAW		Raw control (byte array)
	UVC_CTRL_DATA_TYPE_SIGNED	Signed integer
	UVC_CTRL_DATA_TYPE_UNSIGNED	Unsigned integer
	UVC_CTRL_DATA_TYPE_BOOLEAN	Boolean
	UVC_CTRL_DATA_TYPE_ENUM		Enumeration
	UVC_CTRL_DATA_TYPE_BITMASK	Bitmask
	UVC_CTRL_DATA_TYPE_RECT		Rectangular area

UVCIOC_CTRL_QUERY 요청

`UVCIOC_CTRL_QUERY`는 Extension Unit ID와 control selector로 식별한 UVC XU 컨트롤을 질의합니다. 인자는 `struct uvc_xu_control_query`입니다.

사용 가능한 질의는 UVC 규격의 저수준 컨트롤 요청과 밀접하게 대응합니다.

애플리케이션은 `size` 필드를 컨트롤의 정확한 길이로 설정해야 합니다. 예외적으로 `UVC_GET_LEN`은 2, `UVC_GET_INFO`는 1로 설정해야 합니다. `data`는 지정한 byte 수를 담을 만큼 큰 유효한 쓰기 가능 버퍼를 가리켜야 합니다.

데이터는 드라이버 측 처리 없이 장치에서 그대로 복사됩니다. little-endian과 big-endian 변환을 포함한 버퍼 형식 처리는 애플리케이션 책임입니다. 특히 `UVC_GET_LEN` 결과는 장치가 항상 little-endian 16-bit 정수로 반환합니다.

UVCIOC_CTRL_QUERY - Query a UVC XU control
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Argument: struct uvc_xu_control_query

**Description**:

	This ioctl queries a UVC XU control identified by its extension unit ID
	and control selector.

	There are a number of different queries available that closely
	correspond to the low-level control requests described in the UVC
	specification. These requests are:

	UVC_GET_CUR
		Obtain the current value of the control.
	UVC_GET_MIN
		Obtain the minimum value of the control.
	UVC_GET_MAX
		Obtain the maximum value of the control.
	UVC_GET_DEF
		Obtain the default value of the control.
	UVC_GET_RES
		Query the resolution of the control, i.e. the step size of the
		allowed control values.
	UVC_GET_LEN
		Query the size of the control in bytes.
	UVC_GET_INFO
		Query the control information bitmap, which indicates whether
		get/set requests are supported.
	UVC_SET_CUR
		Update the value of the control.

	Applications must set the 'size' field to the correct length for the
	control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for
	which the size must be set to 2 and 1, respectively. The 'data' field
	must point to a valid writable buffer big enough to hold the indicated
	number of data bytes.

	Data is copied directly from the device without any driver-side
	processing. Applications are responsible for data buffer formatting,
	including little-endian/big-endian conversion. This is particularly
	important for the result of the UVC_GET_LEN requests, which is always
	returned as a little-endian 16-bit integer by the device.

QUERY 반환값과 구조체

`UVCIOC_CTRL_QUERY`는 성공 시 0, 오류 시 -1을 반환하고 `errno`를 설정합니다.

**Return value**:

	On success 0 is returned. On error -1 is returned and errno is set
	appropriately.

	ENOENT
		The device does not support the given control or the specified
		extension unit could not be found.
	ENOBUFS
		The specified buffer size is incorrect (too big or too small).
	EINVAL
		An invalid request code was passed.
	EBADRQC
		The given request is not supported by the given control.
	EFAULT
		The data pointer references an inaccessible memory area.

**Data types**:

.. code-block:: none

	* struct uvc_xu_control_query

	__u8	unit		Extension unit ID
	__u8	selector	Control selector
	__u8	query		Request code to send to the device
	__u16	size		Control data size (in bytes)
	__u8	*data		Control value

V4L2_CID_UVC_REGION_OF_INTEREST_RECT

uvcvideo 드라이버는 UVC 전용 V4L2 컨트롤을 구현합니다. `V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)`는 Region of Interest(ROI)를 결정합니다.

ROI는 `struct v4l2_rect`로 나타내는 사각형입니다. 픽셀 단위의 전역 센서 좌표를 사용하며 field of view와 독립적이고 crop이나 scale의 영향을 받지 않습니다.

`V4L2_CTRL_WHICH_MIN_VAL`과 `V4L2_CTRL_WHICH_MAX_VAL`을 사용해 사각형 크기 범위를 질의할 수 있습니다.

ROI를 설정하면 카메라는 해당 영역에 맞춰 캡처를 최적화할 수 있습니다. 구체적인 동작은 `V4L2_CID_REGION_OF_INTEREST_AUTO` 컨트롤 값이 결정합니다.

이 컨트롤의 사용 예는 원문이 연결한 `Chrome OS USB camera HAL`에서 확인할 수 있습니다: `https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/release-R121-15699.B/camera/hal/usb/`.

Driver-specific V4L2 controls
-----------------------------

The uvcvideo driver implements the following UVC-specific controls:

``V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)``
	This control determines the region of interest (ROI). ROI is a
	rectangular area represented by a struct :c:type:`v4l2_rect`. The
	rectangle is in global sensor coordinates using pixel units. It is
	independent of the field of view, not impacted by any cropping or
	scaling.

	Use ``V4L2_CTRL_WHICH_MIN_VAL`` and ``V4L2_CTRL_WHICH_MAX_VAL`` to query
	the range of rectangle sizes.

	Setting a ROI allows the camera to optimize the capture for the region.
	The value of ``V4L2_CID_REGION_OF_INTEREST_AUTO`` control determines
	the detailed behavior.

	An example of use of this control, can be found in the:
	`Chrome OS USB camera HAL.
	<https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/release-R121-15699.B/camera/hal/usb/>`

V4L2_CID_UVC_REGION_OF_INTEREST_AUTO

`V4L2_CID_UVC_REGION_OF_INTEREST_AUTO (bitmask)`는 현재 ROI 사각형을 추적할 온보드 자동 기능을 결정합니다. 원문 288줄은 사각형 컨트롤을 `V4L2_CID_UVD__REGION_OF_INTEREST_RECT`로 표기하고 있습니다.

최댓값은 지원되는 모든 Auto Control을 나타내는 mask입니다.

``V4L2_CID_UVC_REGION_OF_INTEREST_AUTO (bitmask)``
	This determines which, if any, on-board features should track to the
	Region of Interest specified by the current value of
	``V4L2_CID_UVD__REGION_OF_INTEREST_RECT``.

	Max value is a mask indicating all supported Auto Controls.

.. flat-table::
    :header-rows:  0
    :stub-columns: 0

    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_EXPOSURE``
      - Setting this bit causes automatic exposure to track the region of
	interest instead of the whole image.
    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS``
      - Setting this bit causes automatic iris to track the region of interest
        instead of the whole image.
    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE``
      - Setting this bit causes automatic white balance to track the region
	of interest instead of the whole image.
    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS``
      - Setting this bit causes automatic focus adjustment to track the region
        of interest instead of the whole image.
    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FACE_DETECT``
      - Setting this bit causes automatic face detection to track the region of
        interest instead of the whole image.
    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_DETECT_AND_TRACK``
      - Setting this bit enables automatic face detection and tracking. The
	current value of ``V4L2_CID_REGION_OF_INTEREST_RECT`` may be updated by
	the driver.
    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IMAGE_STABILIZATION``
      - Setting this bit enables automatic image stabilization. The
	current value of ``V4L2_CID_REGION_OF_INTEREST_RECT`` may be updated by
	the driver.
    * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY``
      - Setting this bit enables automatically capture the specified region
        with higher quality if possible.