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