1.. SPDX-License-Identifier: GPL-2.0 2 3The Linux USB Video Class (UVC) driver 4====================================== 5 6This file documents some driver-specific aspects of the UVC driver, such as 7driver-specific ioctls and implementation notes. 8 9Questions and remarks can be sent to the Linux UVC development mailing list at 10linux-media@vger.kernel.org. 11 12 13Extension Unit (XU) support 14--------------------------- 15 16Introduction 17~~~~~~~~~~~~ 18 19The UVC specification allows for vendor-specific extensions through extension 20units (XUs). The Linux UVC driver supports extension unit controls (XU controls) 21through two separate mechanisms: 22 23 - through mappings of XU controls to V4L2 controls 24 - through a driver-specific ioctl interface 25 26The first one allows generic V4L2 applications to use XU controls by mapping 27certain XU controls onto V4L2 controls, which then show up during ordinary 28control enumeration. 29 30The second mechanism requires uvcvideo-specific knowledge for the application to 31access XU controls but exposes the entire UVC XU concept to user space for 32maximum flexibility. 33 34Both mechanisms complement each other and are described in more detail below. 35 36 37Control mappings 38~~~~~~~~~~~~~~~~ 39 40The UVC driver provides an API for user space applications to define so-called 41control mappings at runtime. These allow for individual XU controls or byte 42ranges thereof to be mapped to new V4L2 controls. Such controls appear and 43function exactly like normal V4L2 controls (i.e. the stock controls, such as 44brightness, contrast, etc.). However, reading or writing of such a V4L2 controls 45triggers 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 used 49beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver. 50This is no longer necessary as newer uvcvideo versions query the information 51directly from the device. 52 53For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled 54"IOCTL reference" below. 55 56 573. Driver specific XU control interface 58 59For applications that need to access XU controls directly, e.g. for testing 60purposes, firmware upload, or accessing binary controls, a second mechanism to 61access XU controls is provided in the form of a driver-specific ioctl, namely 62UVCIOC_CTRL_QUERY. 63 64A call to this ioctl allows applications to send queries to the UVC driver that 65directly 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 unit 68and the control selector need to be known. This information either needs to be 69hardcoded in the application or queried using other ways such as by parsing the 70UVC descriptor or, if available, using the media controller API to enumerate a 71device's entities. 72 73Unless the control size is already known it is necessary to first make a 74UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer 75and set the buffer size to the correct value. Similarly, to find out whether 76UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a 77UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET 78supported) of the resulting byte indicate which requests are valid. 79 80With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and 81UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a 82subset of the former ioctl. For the time being they are still supported but 83application developers are encouraged to use UVCIOC_CTRL_QUERY instead. 84 85For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled 86"IOCTL reference" below. 87 88 89Security 90~~~~~~~~ 91 92The API doesn't currently provide a fine-grained access control facility. The 93UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions. 94 95Suggestions on how to improve this are welcome. 96 97 98Debugging 99~~~~~~~~~ 100 101In order to debug problems related to XU controls or controls in general it is 102recommended 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 reference 107~~~~~~~~~~~~~~~ 108 109UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control 110^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 111 112**This IOCTL is deprecated and will be eventually removed** 113 114Argument: struct uvc_xu_control_mapping 115 116**Description**: 117 118 This ioctl creates a mapping between a UVC control or part of a UVC 119 control and a V4L2 control. Once mappings are defined, userspace 120 applications can access vendor-defined UVC control through the V4L2 121 control API. 122 123 To create a mapping, applications fill the uvc_xu_control_mapping 124 structure with information about an existing UVC control defined with 125 UVCIOC_CTRL_ADD and a new V4L2 control. 126 127 A UVC control can be mapped to several V4L2 controls. For instance, 128 a UVC pan/tilt control could be mapped to separate pan and tilt V4L2 129 controls. The UVC control is divided into non overlapping fields using 130 the 'size' and 'offset' fields and are then independently mapped to 131 V4L2 control. 132 133 For signed integer V4L2 controls the data_type field should be set to 134 UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored. 135 136**Return value**: 137 138 On success 0 is returned. On error -1 is returned and errno is set 139 appropriately. 140 141 ENOMEM 142 Not enough memory to perform the operation. 143 EPERM 144 Insufficient privileges (super user privileges are required). 145 EINVAL 146 No such UVC control. 147 EOVERFLOW 148 The requested offset and size would overflow the UVC control. 149 EEXIST 150 Mapping already exists. 151 152**Data types**: 153 154.. code-block:: none 155 156 * struct uvc_xu_control_mapping 157 158 __u32 id V4L2 control identifier 159 __u8 name[32] V4L2 control name 160 __u8 entity[16] UVC extension unit GUID 161 __u8 selector UVC control selector 162 __u8 size V4L2 control size (in bits) 163 __u8 offset V4L2 control offset (in bits) 164 enum v4l2_ctrl_type 165 v4l2_type V4L2 control type 166 enum uvc_control_data_type 167 data_type UVC control data type 168 struct uvc_menu_info 169 *menu_info Array of menu entries (for menu controls only) 170 __u32 menu_count Number of menu entries (for menu controls only) 171 172 * struct uvc_menu_info 173 174 __u32 value Menu entry value used by the device 175 __u8 name[32] Menu entry name 176 177 178 * enum uvc_control_data_type 179 180 UVC_CTRL_DATA_TYPE_RAW Raw control (byte array) 181 UVC_CTRL_DATA_TYPE_SIGNED Signed integer 182 UVC_CTRL_DATA_TYPE_UNSIGNED Unsigned integer 183 UVC_CTRL_DATA_TYPE_BOOLEAN Boolean 184 UVC_CTRL_DATA_TYPE_ENUM Enumeration 185 UVC_CTRL_DATA_TYPE_BITMASK Bitmask 186 UVC_CTRL_DATA_TYPE_RECT Rectangular area 187 188 189UVCIOC_CTRL_QUERY - Query a UVC XU control 190^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 191Argument: struct uvc_xu_control_query 192 193**Description**: 194 195 This ioctl queries a UVC XU control identified by its extension unit ID 196 and control selector. 197 198 There are a number of different queries available that closely 199 correspond to the low-level control requests described in the UVC 200 specification. These requests are: 201 202 UVC_GET_CUR 203 Obtain the current value of the control. 204 UVC_GET_MIN 205 Obtain the minimum value of the control. 206 UVC_GET_MAX 207 Obtain the maximum value of the control. 208 UVC_GET_DEF 209 Obtain the default value of the control. 210 UVC_GET_RES 211 Query the resolution of the control, i.e. the step size of the 212 allowed control values. 213 UVC_GET_LEN 214 Query the size of the control in bytes. 215 UVC_GET_INFO 216 Query the control information bitmap, which indicates whether 217 get/set requests are supported. 218 UVC_SET_CUR 219 Update the value of the control. 220 221 Applications must set the 'size' field to the correct length for the 222 control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for 223 which the size must be set to 2 and 1, respectively. The 'data' field 224 must point to a valid writable buffer big enough to hold the indicated 225 number of data bytes. 226 227 Data is copied directly from the device without any driver-side 228 processing. Applications are responsible for data buffer formatting, 229 including little-endian/big-endian conversion. This is particularly 230 important for the result of the UVC_GET_LEN requests, which is always 231 returned as a little-endian 16-bit integer by the device. 232 233**Return value**: 234 235 On success 0 is returned. On error -1 is returned and errno is set 236 appropriately. 237 238 ENOENT 239 The device does not support the given control or the specified 240 extension unit could not be found. 241 ENOBUFS 242 The specified buffer size is incorrect (too big or too small). 243 EINVAL 244 An invalid request code was passed. 245 EBADRQC 246 The given request is not supported by the given control. 247 EFAULT 248 The data pointer references an inaccessible memory area. 249 250**Data types**: 251 252.. code-block:: none 253 254 * struct uvc_xu_control_query 255 256 __u8 unit Extension unit ID 257 __u8 selector Control selector 258 __u8 query Request code to send to the device 259 __u16 size Control data size (in bytes) 260 __u8 *data Control value 261 262 263Driver-specific V4L2 controls 264----------------------------- 265 266The uvcvideo driver implements the following UVC-specific controls: 267 268``V4L2_CID_UVC_REGION_OF_INTEREST_RECT (struct)`` 269 This control determines the region of interest (ROI). ROI is a 270 rectangular area represented by a struct :c:type:`v4l2_rect`. The 271 rectangle is in global sensor coordinates using pixel units. It is 272 independent of the field of view, not impacted by any cropping or 273 scaling. 274 275 Use ``V4L2_CTRL_WHICH_MIN_VAL`` and ``V4L2_CTRL_WHICH_MAX_VAL`` to query 276 the range of rectangle sizes. 277 278 Setting a ROI allows the camera to optimize the capture for the region. 279 The value of ``V4L2_CID_REGION_OF_INTEREST_AUTO`` control determines 280 the detailed behavior. 281 282 An example of use of this control, can be found in the: 283 `Chrome OS USB camera HAL. 284 <https://chromium.googlesource.com/chromiumos/platform2/+/refs/heads/release-R121-15699.B/camera/hal/usb/>` 285 286 287``V4L2_CID_UVC_REGION_OF_INTEREST_AUTO (bitmask)`` 288 This determines which, if any, on-board features should track to the 289 Region of Interest specified by the current value of 290 ``V4L2_CID_UVD__REGION_OF_INTEREST_RECT``. 291 292 Max value is a mask indicating all supported Auto Controls. 293 294.. flat-table:: 295 :header-rows: 0 296 :stub-columns: 0 297 298 * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_EXPOSURE`` 299 - Setting this bit causes automatic exposure to track the region of 300 interest instead of the whole image. 301 * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IRIS`` 302 - Setting this bit causes automatic iris to track the region of interest 303 instead of the whole image. 304 * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_WHITE_BALANCE`` 305 - Setting this bit causes automatic white balance to track the region 306 of interest instead of the whole image. 307 * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FOCUS`` 308 - Setting this bit causes automatic focus adjustment to track the region 309 of interest instead of the whole image. 310 * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_FACE_DETECT`` 311 - Setting this bit causes automatic face detection to track the region of 312 interest instead of the whole image. 313 * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_DETECT_AND_TRACK`` 314 - Setting this bit enables automatic face detection and tracking. The 315 current value of ``V4L2_CID_REGION_OF_INTEREST_RECT`` may be updated by 316 the driver. 317 * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_IMAGE_STABILIZATION`` 318 - Setting this bit enables automatic image stabilization. The 319 current value of ``V4L2_CID_REGION_OF_INTEREST_RECT`` may be updated by 320 the driver. 321 * - ``V4L2_UVC_REGION_OF_INTEREST_AUTO_HIGHER_QUALITY`` 322 - Setting this bit enables automatically capture the specified region 323 with higher quality if possible. 324