翻译内核uvcvideo.txt

翻译源：linux-3.4.20Documentationvideo4linuxuvcvideo.txt

译文：

Linux USB视频类（UVC）驱动程序
==================================
此文件记录了UVC驱动程序的某些驱动程序特定方面，例如
驱动程序特定的ioctls和实现说明。


问题和评论可以发送到Linux UVC开发邮件列表中
linux-uvc-devel@lists.berlios.de。

扩展单元（XU）的支持
---------------------------

1.介绍

UVC规范允许通过扩展单元（XU）进行供应商特定的扩展。
Linux UVC驱动程序通过两个单独的机制支持扩展单元控制（XU控制）：


   - 通过将XU控件映射到V4L2控件
   - 通过驱动程序特定的ioctl界面


第一个允许通用V4L2应用程序通过将某些XU控件映射到V4L2控件上来使用XU控件，
然后在普通的控件枚举中显示这些控件。

第二种机制需要uvcvideo特定的知识来使应用程序访问XU控件，
但将整个UVC XU概念暴露给用户空间以获得最大的灵活性。


两种机制相辅相成，下面将更详细地介绍。

2.控制映射

UVC驱动程序为用户空间应用程序提供了一个API，以在运行时定义所谓的控制映射。 这些允许单独的XU控件或其字节范围映射到新的V4L2控件。 这些控件的出现和功能与正常的V4L2控件（即库存控件，如亮度，对比度等）完全一样。 但是，读取或写入这样的V4L2控件会触发读取或写入相关的XU控件。


用于创建这些控件映射的ioctl称为UVCIOC_CTRL_MAP。 以前的驱动程序版本（在0.2.0之前）需要预先使用另一个ioctl（UVCIOC_CTRL_ADD）将XU控制信息传递给UVC驱动程序。 这不再是必要的，因为更新的uvcvideo版本直接从设备查询信息。


有关UVCIOC_CTRL_MAP ioctl的详细信息，请参阅下面标题为“IOCTL参考”的部分。

3.驱动程序特定的XU控制界面

对于需要直接访问XU控件的应用程序，例如出于测试目的，固件上载或访问二进制控制，访问XU控制的第二种机制以驱动器特定的ioctl的形式提供，即UVCIOC_CTRL_QUERY。


对此ioctl的调用允许应用程序将查询发送到直接映射到低级别UVC控制请求的UVC驱动程序。


为了做出这样的要求，需要知道控制器的扩展单元和控制选择器的UVC单元ID。这些信息需要在应用程序中进行硬编码，或者使用其他方法查询，例如解析UVC描述符，或者使用媒体控制器API枚举设备的实体（如果可用）。


除非已知控件大小，否则必须首先进行UVC_GET_LEN请求，以便能够分配足够大的缓冲区并将缓冲区大小设置为正确的值。同样，要找出UVC_GET_CUR或UVC_SET_CUR是否是给定控件的有效请求，应该发出UVC_GET_INFO请求。结果字节的位0（GET支持）和1（支持SET）指示哪些请求有效。


随着UVCIOC_CTRL_QUERY ioctl的添加，UVCIOC_CTRL_GET和UVCIOC_CTRL_SET ioctl已经过时，因为它们的功能是前ioctl的子集。目前它们仍然受到支持，但鼓励应用程序开发人员使用UVCIOC_CTRL_QUERY。


有关UVCIOC_CTRL_QUERY ioctl的详细信息，请参阅下面标题为“IOCTL参考”的部分。

4.安全

该API目前不提供细粒度的访问控制设施。 UVCIOC_CTRL_ADD和UVCIOC_CTRL_MAP ioctls需要超级用户权限。

如何改善这一点的建议值得欢迎。

5.调试

为了调试与XU控件或控件相关的问题，建议在模块参数“trace”中启用UVC_TRACE_CONTROL位。这会导致额外的输出写入系统日志。

6. IOCTL参考

---- UVCIOC_CTRL_MAP - 将UVC控件映射到V4L2控件----

参数：struct uvc_xu_control_mapping


描述：
这个ioctl创建UVC控制或UVC控制的一部分和V4L2控制之间的映射。 一旦定义了映射，用户空间应用程序就可以通过V4L2控制API访问供应商定义的UVC控制。

为了创建映射，应用程序使用UVCIOC_CTRL_ADD和新的V4L2控件定义的现有UVC控件的信息来填充uvc_xu_control_mapping结构。

UVC控件可以映射到几个V4L2控件。 例如，可以将UVC摇摄/倾斜控制映射到独立的摇摄和倾斜V4L2控制。 UVC控制使用“大小”和“偏移”字段分成不重叠的字段，然后独立映射到V4L2控制。

对于带符号的整数V4L2控件，data_type字段应设置为UVC_CTRL_DATA_TYPE_SIGNED。 其他值目前被忽略。

返回值：
成功时返回0。 出错-1返回，并适当地设置errno。


ENOMEM
没有足够的内存来执行操作。
EPERM
权限不足（需要超级用户权限）。
EINVAL
没有这样的UVC控制。
EOVERFLOW
所要求的偏移量和大小将溢出UVC控制。
EEXIST
映射已经存在。


数据类型：
* struct uvc_xu_control_mapping

__u32 id        V4L2控制标识符
__u8 name[32]   V4L2控制名称
__u8 entity[16] UVC扩展单元GUID
__u8 selector   UVC控制选择器
__u8 size       V4L2控制大小（以位为单位）
__u8 offset     V4L2控制偏移量（以位为单位）
enum v4l2_ctrl_type
v4l2_type V4L2控制类型
enum uvc_control_data_type
data_type UVC控制数据类型
struct uvc_menu_info
* menu_info菜单条目数组（仅适用于菜单控件）
__u32 menu_count菜单条目数（仅适用于菜单控件）


* struct uvc_menu_info

__u32 value      设备使用的菜单输入值
__u8  name[32]   菜单条目名称


* enum uvc_control_data_type

UVC_CTRL_DATA_TYPE_RAW       原始控制（字节数组）
UVC_CTRL_DATA_TYPE_SIGNED    带符号整数
UVC_CTRL_DATA_TYPE_UNSIGNED  无符号整数
UVC_CTRL_DATA_TYPE_BOOLEAN   布尔
UVC_CTRL_DATA_TYPE_ENUM      枚举
UVC_CTRL_DATA_TYPE_BITMASK   位掩码


---- UVCIOC_CTRL_QUERY - 查询UVC XU控制----


参数：struct uvc_xu_control_query


描述：
这个ioctl查询由其扩展单元ID和控制选择器标识的UVC XU控制。
有许多不同的查询可以与UVC规范中描述的底层控制请求密切对应。 这些要求是：


UVC_GET_CUR
获取控件的当前值。
UVC_GET_MIN
获得控制的最小值。
UVC_GET_MAX
获取控件的最大值。
UVC_GET_DEF
获取控件的默认值。
UVC_GET_RES
查询控件的分辨率，即。的步长
允许的控制值。
UVC_GET_LEN
以字节为单位查询控件的大小。
UVC_GET_INFO
查询控制信息位图，指示是否
获取/设置请求被支持。
UVC_SET_CUR
更新控件的值。


应用程序必须将“大小”字段设置为控件的正确长度。 例外是UVC_GET_LEN和UVC_GET_INFO查询，其大小必须分别设置为2和1。 “数据”字段必须指向一个有效的可写缓冲区，其大小足以容纳指定数量的数据字节。
数据直接从设备复制，不需要任何驱动程序处理。 应用程序负责数据缓冲区格式化，包括little-endian / big-endian转换。 这对于UVC_GET_LEN请求的结果尤其重要，它总是以设备的小尾数16位整数形式返回。


返回值：
成功时返回0。 出错-1返回，并适当地设置errno。


ENOENT
该设备不支持给定的控件或指定的扩展单元无法找到。
ENOBUFS
指定的缓冲区大小不正确（太大或太小）。
EINVAL
无效的请求代码已通过。
EBADRQC
给定的请求不被给定的控件支持。
EFAULT
数据指针引用一个不可访问的内存区域。




数据类型：
* struct uvc_xu_control_query




__u8 unit扩展单元ID
__u8 selector控制选择器
__u8 query请求代码发送到设备
__u16 size控制数据大小（以字节为单位）
__u8 *data控制值

原文：

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-uvc-devel@lists.berlios.de.


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

1. 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.


2. 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.


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.


4. 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.


5. 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.


6. 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:
	* 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


---- 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.

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:
	* 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