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