258 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3The Linux USB Video Class (UVC) driver4======================================5 6This file documents some driver-specific aspects of the UVC driver, such as7driver-specific ioctls and implementation notes.8 9Questions and remarks can be sent to the Linux UVC development mailing list at10linux-media@vger.kernel.org.11 12 13Extension Unit (XU) support14---------------------------15 16Introduction17~~~~~~~~~~~~18 19The UVC specification allows for vendor-specific extensions through extension20units (XUs). The Linux UVC driver supports extension unit controls (XU controls)21through two separate mechanisms:22 23 - through mappings of XU controls to V4L2 controls24 - through a driver-specific ioctl interface25 26The first one allows generic V4L2 applications to use XU controls by mapping27certain XU controls onto V4L2 controls, which then show up during ordinary28control enumeration.29 30The second mechanism requires uvcvideo-specific knowledge for the application to31access XU controls but exposes the entire UVC XU concept to user space for32maximum flexibility.33 34Both mechanisms complement each other and are described in more detail below.35 36 37Control mappings38~~~~~~~~~~~~~~~~39 40The UVC driver provides an API for user space applications to define so-called41control mappings at runtime. These allow for individual XU controls or byte42ranges thereof to be mapped to new V4L2 controls. Such controls appear and43function exactly like normal V4L2 controls (i.e. the stock controls, such as44brightness, contrast, etc.). However, reading or writing of such a V4L2 controls45triggers a read or write of the associated XU control.46 47The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.48Previous driver versions (before 0.2.0) required another ioctl to be used49beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.50This is no longer necessary as newer uvcvideo versions query the information51directly from the device.52 53For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled54"IOCTL reference" below.55 56 573. Driver specific XU control interface58 59For applications that need to access XU controls directly, e.g. for testing60purposes, firmware upload, or accessing binary controls, a second mechanism to61access XU controls is provided in the form of a driver-specific ioctl, namely62UVCIOC_CTRL_QUERY.63 64A call to this ioctl allows applications to send queries to the UVC driver that65directly map to the low-level UVC control requests.66 67In order to make such a request the UVC unit ID of the control's extension unit68and the control selector need to be known. This information either needs to be69hardcoded in the application or queried using other ways such as by parsing the70UVC descriptor or, if available, using the media controller API to enumerate a71device's entities.72 73Unless the control size is already known it is necessary to first make a74UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer75and set the buffer size to the correct value. Similarly, to find out whether76UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a77UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET78supported) of the resulting byte indicate which requests are valid.79 80With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and81UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a82subset of the former ioctl. For the time being they are still supported but83application developers are encouraged to use UVCIOC_CTRL_QUERY instead.84 85For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled86"IOCTL reference" below.87 88 89Security90~~~~~~~~91 92The API doesn't currently provide a fine-grained access control facility. The93UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.94 95Suggestions on how to improve this are welcome.96 97 98Debugging99~~~~~~~~~100 101In order to debug problems related to XU controls or controls in general it is102recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.103This causes extra output to be written into the system log.104 105 106IOCTL reference107~~~~~~~~~~~~~~~108 109UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control110^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^111 112Argument: struct uvc_xu_control_mapping113 114**Description**:115 116 This ioctl creates a mapping between a UVC control or part of a UVC117 control and a V4L2 control. Once mappings are defined, userspace118 applications can access vendor-defined UVC control through the V4L2119 control API.120 121 To create a mapping, applications fill the uvc_xu_control_mapping122 structure with information about an existing UVC control defined with123 UVCIOC_CTRL_ADD and a new V4L2 control.124 125 A UVC control can be mapped to several V4L2 controls. For instance,126 a UVC pan/tilt control could be mapped to separate pan and tilt V4L2127 controls. The UVC control is divided into non overlapping fields using128 the 'size' and 'offset' fields and are then independently mapped to129 V4L2 control.130 131 For signed integer V4L2 controls the data_type field should be set to132 UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored.133 134**Return value**:135 136 On success 0 is returned. On error -1 is returned and errno is set137 appropriately.138 139 ENOMEM140 Not enough memory to perform the operation.141 EPERM142 Insufficient privileges (super user privileges are required).143 EINVAL144 No such UVC control.145 EOVERFLOW146 The requested offset and size would overflow the UVC control.147 EEXIST148 Mapping already exists.149 150**Data types**:151 152.. code-block:: none153 154 * struct uvc_xu_control_mapping155 156 __u32 id V4L2 control identifier157 __u8 name[32] V4L2 control name158 __u8 entity[16] UVC extension unit GUID159 __u8 selector UVC control selector160 __u8 size V4L2 control size (in bits)161 __u8 offset V4L2 control offset (in bits)162 enum v4l2_ctrl_type163 v4l2_type V4L2 control type164 enum uvc_control_data_type165 data_type UVC control data type166 struct uvc_menu_info167 *menu_info Array of menu entries (for menu controls only)168 __u32 menu_count Number of menu entries (for menu controls only)169 170 * struct uvc_menu_info171 172 __u32 value Menu entry value used by the device173 __u8 name[32] Menu entry name174 175 176 * enum uvc_control_data_type177 178 UVC_CTRL_DATA_TYPE_RAW Raw control (byte array)179 UVC_CTRL_DATA_TYPE_SIGNED Signed integer180 UVC_CTRL_DATA_TYPE_UNSIGNED Unsigned integer181 UVC_CTRL_DATA_TYPE_BOOLEAN Boolean182 UVC_CTRL_DATA_TYPE_ENUM Enumeration183 UVC_CTRL_DATA_TYPE_BITMASK Bitmask184 185 186UVCIOC_CTRL_QUERY - Query a UVC XU control187^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^188Argument: struct uvc_xu_control_query189 190**Description**:191 192 This ioctl queries a UVC XU control identified by its extension unit ID193 and control selector.194 195 There are a number of different queries available that closely196 correspond to the low-level control requests described in the UVC197 specification. These requests are:198 199 UVC_GET_CUR200 Obtain the current value of the control.201 UVC_GET_MIN202 Obtain the minimum value of the control.203 UVC_GET_MAX204 Obtain the maximum value of the control.205 UVC_GET_DEF206 Obtain the default value of the control.207 UVC_GET_RES208 Query the resolution of the control, i.e. the step size of the209 allowed control values.210 UVC_GET_LEN211 Query the size of the control in bytes.212 UVC_GET_INFO213 Query the control information bitmap, which indicates whether214 get/set requests are supported.215 UVC_SET_CUR216 Update the value of the control.217 218 Applications must set the 'size' field to the correct length for the219 control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for220 which the size must be set to 2 and 1, respectively. The 'data' field221 must point to a valid writable buffer big enough to hold the indicated222 number of data bytes.223 224 Data is copied directly from the device without any driver-side225 processing. Applications are responsible for data buffer formatting,226 including little-endian/big-endian conversion. This is particularly227 important for the result of the UVC_GET_LEN requests, which is always228 returned as a little-endian 16-bit integer by the device.229 230**Return value**:231 232 On success 0 is returned. On error -1 is returned and errno is set233 appropriately.234 235 ENOENT236 The device does not support the given control or the specified237 extension unit could not be found.238 ENOBUFS239 The specified buffer size is incorrect (too big or too small).240 EINVAL241 An invalid request code was passed.242 EBADRQC243 The given request is not supported by the given control.244 EFAULT245 The data pointer references an inaccessible memory area.246 247**Data types**:248 249.. code-block:: none250 251 * struct uvc_xu_control_query252 253 __u8 unit Extension unit ID254 __u8 selector Control selector255 __u8 query Request code to send to the device256 __u16 size Control data size (in bytes)257 __u8 *data Control value258