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