1The Linux USB Video Class (UVC) driver 2====================================== 3 4This file documents some driver-specific aspects of the UVC driver, such as 5driver-specific ioctls and implementation notes. 6 7Questions and remarks can be sent to the Linux UVC development mailing list at 8linux-uvc-devel@lists.berlios.de. 9 10 11Extension Unit (XU) support 12--------------------------- 13 14Introduction 15~~~~~~~~~~~~ 16 17The UVC specification allows for vendor-specific extensions through extension 18units (XUs). The Linux UVC driver supports extension unit controls (XU controls) 19through two separate mechanisms: 20 21 - through mappings of XU controls to V4L2 controls 22 - through a driver-specific ioctl interface 23 24The first one allows generic V4L2 applications to use XU controls by mapping 25certain XU controls onto V4L2 controls, which then show up during ordinary 26control enumeration. 27 28The second mechanism requires uvcvideo-specific knowledge for the application to 29access XU controls but exposes the entire UVC XU concept to user space for 30maximum flexibility. 31 32Both mechanisms complement each other and are described in more detail below. 33 34 35Control mappings 36~~~~~~~~~~~~~~~~ 37 38The UVC driver provides an API for user space applications to define so-called 39control mappings at runtime. These allow for individual XU controls or byte 40ranges thereof to be mapped to new V4L2 controls. Such controls appear and 41function exactly like normal V4L2 controls (i.e. the stock controls, such as 42brightness, contrast, etc.). However, reading or writing of such a V4L2 controls 43triggers a read or write of the associated XU control. 44 45The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP. 46Previous driver versions (before 0.2.0) required another ioctl to be used 47beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver. 48This is no longer necessary as newer uvcvideo versions query the information 49directly from the device. 50 51For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled 52"IOCTL reference" below. 53 54 553. Driver specific XU control interface 56 57For applications that need to access XU controls directly, e.g. for testing 58purposes, firmware upload, or accessing binary controls, a second mechanism to 59access XU controls is provided in the form of a driver-specific ioctl, namely 60UVCIOC_CTRL_QUERY. 61 62A call to this ioctl allows applications to send queries to the UVC driver that 63directly map to the low-level UVC control requests. 64 65In order to make such a request the UVC unit ID of the control's extension unit 66and the control selector need to be known. This information either needs to be 67hardcoded in the application or queried using other ways such as by parsing the 68UVC descriptor or, if available, using the media controller API to enumerate a 69device's entities. 70 71Unless the control size is already known it is necessary to first make a 72UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer 73and set the buffer size to the correct value. Similarly, to find out whether 74UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a 75UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET 76supported) of the resulting byte indicate which requests are valid. 77 78With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and 79UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a 80subset of the former ioctl. For the time being they are still supported but 81application developers are encouraged to use UVCIOC_CTRL_QUERY instead. 82 83For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled 84"IOCTL reference" below. 85 86 87Security 88~~~~~~~~ 89 90The API doesn't currently provide a fine-grained access control facility. The 91UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions. 92 93Suggestions on how to improve this are welcome. 94 95 96Debugging 97~~~~~~~~~ 98 99In order to debug problems related to XU controls or controls in general it is 100recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'. 101This causes extra output to be written into the system log. 102 103 104IOCTL reference 105~~~~~~~~~~~~~~~ 106 107UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control 108^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 109 110Argument: struct uvc_xu_control_mapping 111 112**Description**: 113 114 This ioctl creates a mapping between a UVC control or part of a UVC 115 control and a V4L2 control. Once mappings are defined, userspace 116 applications can access vendor-defined UVC control through the V4L2 117 control API. 118 119 To create a mapping, applications fill the uvc_xu_control_mapping 120 structure with information about an existing UVC control defined with 121 UVCIOC_CTRL_ADD and a new V4L2 control. 122 123 A UVC control can be mapped to several V4L2 controls. For instance, 124 a UVC pan/tilt control could be mapped to separate pan and tilt V4L2 125 controls. The UVC control is divided into non overlapping fields using 126 the 'size' and 'offset' fields and are then independently mapped to 127 V4L2 control. 128 129 For signed integer V4L2 controls the data_type field should be set to 130 UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored. 131 132**Return value**: 133 134 On success 0 is returned. On error -1 is returned and errno is set 135 appropriately. 136 137 ENOMEM 138 Not enough memory to perform the operation. 139 EPERM 140 Insufficient privileges (super user privileges are required). 141 EINVAL 142 No such UVC control. 143 EOVERFLOW 144 The requested offset and size would overflow the UVC control. 145 EEXIST 146 Mapping already exists. 147 148**Data types**: 149 150.. code-block:: none 151 152 * struct uvc_xu_control_mapping 153 154 __u32 id V4L2 control identifier 155 __u8 name[32] V4L2 control name 156 __u8 entity[16] UVC extension unit GUID 157 __u8 selector UVC control selector 158 __u8 size V4L2 control size (in bits) 159 __u8 offset V4L2 control offset (in bits) 160 enum v4l2_ctrl_type 161 v4l2_type V4L2 control type 162 enum uvc_control_data_type 163 data_type UVC control data type 164 struct uvc_menu_info 165 *menu_info Array of menu entries (for menu controls only) 166 __u32 menu_count Number of menu entries (for menu controls only) 167 168 * struct uvc_menu_info 169 170 __u32 value Menu entry value used by the device 171 __u8 name[32] Menu entry name 172 173 174 * enum uvc_control_data_type 175 176 UVC_CTRL_DATA_TYPE_RAW Raw control (byte array) 177 UVC_CTRL_DATA_TYPE_SIGNED Signed integer 178 UVC_CTRL_DATA_TYPE_UNSIGNED Unsigned integer 179 UVC_CTRL_DATA_TYPE_BOOLEAN Boolean 180 UVC_CTRL_DATA_TYPE_ENUM Enumeration 181 UVC_CTRL_DATA_TYPE_BITMASK Bitmask 182 183 184UVCIOC_CTRL_QUERY - Query a UVC XU control 185^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 186Argument: struct uvc_xu_control_query 187 188**Description**: 189 190 This ioctl queries a UVC XU control identified by its extension unit ID 191 and control selector. 192 193 There are a number of different queries available that closely 194 correspond to the low-level control requests described in the UVC 195 specification. These requests are: 196 197 UVC_GET_CUR 198 Obtain the current value of the control. 199 UVC_GET_MIN 200 Obtain the minimum value of the control. 201 UVC_GET_MAX 202 Obtain the maximum value of the control. 203 UVC_GET_DEF 204 Obtain the default value of the control. 205 UVC_GET_RES 206 Query the resolution of the control, i.e. the step size of the 207 allowed control values. 208 UVC_GET_LEN 209 Query the size of the control in bytes. 210 UVC_GET_INFO 211 Query the control information bitmap, which indicates whether 212 get/set requests are supported. 213 UVC_SET_CUR 214 Update the value of the control. 215 216 Applications must set the 'size' field to the correct length for the 217 control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for 218 which the size must be set to 2 and 1, respectively. The 'data' field 219 must point to a valid writable buffer big enough to hold the indicated 220 number of data bytes. 221 222 Data is copied directly from the device without any driver-side 223 processing. Applications are responsible for data buffer formatting, 224 including little-endian/big-endian conversion. This is particularly 225 important for the result of the UVC_GET_LEN requests, which is always 226 returned as a little-endian 16-bit integer by the device. 227 228**Return value**: 229 230 On success 0 is returned. On error -1 is returned and errno is set 231 appropriately. 232 233 ENOENT 234 The device does not support the given control or the specified 235 extension unit could not be found. 236 ENOBUFS 237 The specified buffer size is incorrect (too big or too small). 238 EINVAL 239 An invalid request code was passed. 240 EBADRQC 241 The given request is not supported by the given control. 242 EFAULT 243 The data pointer references an inaccessible memory area. 244 245**Data types**: 246 247.. code-block:: none 248 249 * struct uvc_xu_control_query 250 251 __u8 unit Extension unit ID 252 __u8 selector Control selector 253 __u8 query Request code to send to the device 254 __u16 size Control data size (in bytes) 255 __u8 *data Control value 256