翻译内核uvcvideo.txt

翻译源：linux-3.4.20\Documentation\video4linux\uvcvideo.txt

译文：

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


问题和评论可以发送到Linux UVC开发邮件列表中
[e-mail]。

扩展单元（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 asdriver-specific ioctls and implementation notes.Questions and remarks can be sent to the Linux UVC development mailing list [e-mail] Unit (XU) support---------------------------1. IntroductionThe UVC specification allows for vendor-specific extensions through extensionunits (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 interfaceThe first one allows generic V4L2 applications to use XU controls by mappingcertain XU controls onto V4L2 controls, which then show up during ordinarycontrol enumeration.The second mechanism requires uvcvideo-specific knowledge for the application toaccess XU controls but exposes the entire UVC XU concept to user space formaximum flexibility.Both mechanisms complement each other and are described in more detail below.2. Control mappingsThe UVC driver provides an API for user space applications to define so-calledcontrol mappings at runtime. These allow for individual XU controls or byteranges thereof to be mapped to new V4L2 controls. Such controls appear andfunction exactly like normal V4L2 controls (i.e. the stock controls, such asbrightness, contrast, etc.). However, reading or writing of such a V4L2 controlstriggers 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 usedbeforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.This is no longer necessary as newer uvcvideo versions query the informationdirectly 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 interfaceFor applications that need to access XU controls directly, e.g. for testingpurposes, firmware upload, or accessing binary controls, a second mechanism toaccess XU controls is provided in the form of a driver-specific ioctl, namelyUVCIOC_CTRL_QUERY.A call to this ioctl allows applications to send queries to the UVC driver thatdirectly map to the low-level UVC control requests.In order to make such a request the UVC unit ID of the control's extension unitand the control selector need to be known. This information either needs to behardcoded in the application or queried using other ways such as by parsing theUVC descriptor or, if available, using the media controller API to enumerate adevice's entities.Unless the control size is already known it is necessary to first make aUVC_GET_LEN requests in order to be able to allocate a sufficiently large bufferand set the buffer size to the correct value. Similarly, to find out whetherUVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, aUVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SETsupported) of the resulting byte indicate which requests are valid.With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET andUVCIOC_CTRL_SET ioctls have become obsolete since their functionality is asubset of the former ioctl. For the time being they are still supported butapplication 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. SecurityThe API doesn't currently provide a fine-grained access control facility. TheUVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.Suggestions on how to improve this are welcome.5. DebuggingIn order to debug problems related to XU controls or controls in general it isrecommended 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_mappingDescription:This ioctl creates a mapping between a UVC control or part of a UVCcontrol and a V4L2 control. Once mappings are defined, userspaceapplications can access vendor-defined UVC control through the V4L2control API.To create a mapping, applications fill the uvc_xu_control_mappingstructure with information about an existing UVC control defined withUVCIOC_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 V4L2controls. The UVC control is divided into non overlapping fields usingthe 'size' and 'offset' fields and are then independently mapped toV4L2 control.For signed integer V4L2 controls the data_type field should be set toUVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored.Return value:On success 0 is returned. On error -1 is returned and errno is setappropriately.ENOMEMNot enough memory to perform the operation.EPERMInsufficient privileges (super user privileges are required).EINVALNo such UVC control.EOVERFLOWThe requested offset and size would overflow the UVC control.EEXISTMapping already exists.Data types:* struct uvc_xu_control_mapping__u32idV4L2 control identifier__u8name[32]V4L2 control name__u8entity[16]UVC extension unit GUID__u8selectorUVC control selector__u8sizeV4L2 control size (in bits)__u8offsetV4L2 control offset (in bits)enum v4l2_ctrl_typev4l2_typeV4L2 control typeenum uvc_control_data_typedata_typeUVC control data typestruct uvc_menu_info*menu_infoArray of menu entries (for menu controls only)__u32menu_countNumber of menu entries (for menu controls only)* struct uvc_menu_info__u32valueMenu entry value used by the device__u8name[32]Menu entry name* enum uvc_control_data_typeUVC_CTRL_DATA_TYPE_RAWRaw control (byte array)UVC_CTRL_DATA_TYPE_SIGNEDSigned integerUVC_CTRL_DATA_TYPE_UNSIGNEDUnsigned integerUVC_CTRL_DATA_TYPE_BOOLEANBooleanUVC_CTRL_DATA_TYPE_ENUMEnumerationUVC_CTRL_DATA_TYPE_BITMASKBitmask---- UVCIOC_CTRL_QUERY - Query a UVC XU control ----Argument: struct uvc_xu_control_queryDescription:This ioctl queries a UVC XU control identified by its extension unit IDand control selector.There are a number of different queries available that closelycorrespond to the low-level control requests described in the UVCspecification. These requests are:UVC_GET_CURObtain the current value of the control.UVC_GET_MINObtain the minimum value of the control.UVC_GET_MAXObtain the maximum value of the control.UVC_GET_DEFObtain the default value of the control.UVC_GET_RESQuery the resolution of the control, i.e. the step size of theallowed control values.UVC_GET_LENQuery the size of the control in bytes.UVC_GET_INFOQuery the control information bitmap, which indicates whetherget/set requests are supported.UVC_SET_CURUpdate the value of the control.Applications must set the 'size' field to the correct length for thecontrol. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, forwhich the size must be set to 2 and 1, respectively. The 'data' fieldmust point to a valid writable buffer big enough to hold the indicatednumber of data bytes.Data is copied directly from the device without any driver-sideprocessing. Applications are responsible for data buffer formatting,including little-endian/big-endian conversion. This is particularlyimportant for the result of the UVC_GET_LEN requests, which is alwaysreturned 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 setappropriately.ENOENTThe device does not support the given control or the specifiedextension unit could not be found.ENOBUFSThe specified buffer size is incorrect (too big or too small).EINVALAn invalid request code was passed.EBADRQCThe given request is not supported by the given control.EFAULTThe data pointer references an inaccessible memory area.Data types:* struct uvc_xu_control_query__u8unitExtension unit ID__u8selectorControl selector__u8queryRequest code to send to the device__u16sizeControl data size (in bytes)__u8*dataControl value