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 aspec
7 driver-specific ioctls and implementation note
8
9 Questions and remarks can be sent to the Linux
10 linux-media@vger.kernel.org.
11
12
13 Extension Unit (XU) support
14 ---------------------------
15
16 Introduction
17 ~~~~~~~~~~~~
18
19 The UVC specification allows for vendor-specif
20 units (XUs). The Linux UVC driver supports ext
21 through two separate mechanisms:
22
23 - through mappings of XU controls to V4L2 co
24 - through a driver-specific ioctl interface
25
26 The first one allows generic V4L2 applications
27 certain XU controls onto V4L2 controls, which
28 control enumeration.
29
30 The second mechanism requires uvcvideo-specifi
31 access XU controls but exposes the entire UVC
32 maximum flexibility.
33
34 Both mechanisms complement each other and are
35
36
37 Control mappings
38 ~~~~~~~~~~~~~~~~
39
40 The UVC driver provides an API for user space
41 control mappings at runtime. These allow for i
42 ranges thereof to be mapped to new V4L2 contro
43 function exactly like normal V4L2 controls (i.
44 brightness, contrast, etc.). However, reading
45 triggers a read or write of the associated XU
46
47 The ioctl used to create these control mapping
48 Previous driver versions (before 0.2.0) requir
49 beforehand (UVCIOC_CTRL_ADD) to pass XU contro
50 This is no longer necessary as newer uvcvideo
51 directly from the device.
52
53 For details on the UVCIOC_CTRL_MAP ioctl pleas
54 "IOCTL reference" below.
55
56
57 3. Driver specific XU control interface
58
59 For applications that need to access XU contro
60 purposes, firmware upload, or accessing binary
61 access XU controls is provided in the form of
62 UVCIOC_CTRL_QUERY.
63
64 A call to this ioctl allows applications to se
65 directly map to the low-level UVC control requ
66
67 In order to make such a request the UVC unit I
68 and the control selector need to be known. Thi
69 hardcoded in the application or queried using
70 UVC descriptor or, if available, using the med
71 device's entities.
72
73 Unless the control size is already known it is
74 UVC_GET_LEN requests in order to be able to al
75 and set the buffer size to the correct value.
76 UVC_GET_CUR or UVC_SET_CUR are valid requests
77 UVC_GET_INFO request should be made. The bits
78 supported) of the resulting byte indicate whic
79
80 With the addition of the UVCIOC_CTRL_QUERY ioc
81 UVCIOC_CTRL_SET ioctls have become obsolete si
82 subset of the former ioctl. For the time being
83 application developers are encouraged to use U
84
85 For details on the UVCIOC_CTRL_QUERY ioctl ple
86 "IOCTL reference" below.
87
88
89 Security
90 ~~~~~~~~
91
92 The API doesn't currently provide a fine-grain
93 UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls req
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 contr
102 recommended to enable the UVC_TRACE_CONTROL bi
103 This causes extra output to be written into th
104
105
106 IOCTL reference
107 ~~~~~~~~~~~~~~~
108
109 UVCIOC_CTRL_MAP - Map a UVC control to a V4L2
110 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
111
112 Argument: struct uvc_xu_control_mapping
113
114 **Description**:
115
116 This ioctl creates a mapping between a
117 control and a V4L2 control. Once mappi
118 applications can access vendor-defined
119 control API.
120
121 To create a mapping, applications fill
122 structure with information about an ex
123 UVCIOC_CTRL_ADD and a new V4L2 control
124
125 A UVC control can be mapped to several
126 a UVC pan/tilt control could be mapped
127 controls. The UVC control is divided i
128 the 'size' and 'offset' fields and are
129 V4L2 control.
130
131 For signed integer V4L2 controls the d
132 UVC_CTRL_DATA_TYPE_SIGNED. Other value
133
134 **Return value**:
135
136 On success 0 is returned. On error -1
137 appropriately.
138
139 ENOMEM
140 Not enough memory to perform t
141 EPERM
142 Insufficient privileges (super
143 EINVAL
144 No such UVC control.
145 EOVERFLOW
146 The requested offset and size
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 i
157 __u8 name[32] V4L2 control n
158 __u8 entity[16] UVC extension
159 __u8 selector UVC control se
160 __u8 size V4L2 control s
161 __u8 offset V4L2 control o
162 enum v4l2_ctrl_type
163 v4l2_type V4L2 control t
164 enum uvc_control_data_type
165 data_type UVC control da
166 struct uvc_menu_info
167 *menu_info Array of menu
168 __u32 menu_count Number of menu
169
170 * struct uvc_menu_info
171
172 __u32 value Menu entry val
173 __u8 name[32] Menu entry nam
174
175
176 * enum uvc_control_data_type
177
178 UVC_CTRL_DATA_TYPE_RAW Raw co
179 UVC_CTRL_DATA_TYPE_SIGNED Signed
180 UVC_CTRL_DATA_TYPE_UNSIGNED Unsign
181 UVC_CTRL_DATA_TYPE_BOOLEAN Boolea
182 UVC_CTRL_DATA_TYPE_ENUM Enumer
183 UVC_CTRL_DATA_TYPE_BITMASK Bitmas
184
185
186 UVCIOC_CTRL_QUERY - Query a UVC XU control
187 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
188 Argument: struct uvc_xu_control_query
189
190 **Description**:
191
192 This ioctl queries a UVC XU control id
193 and control selector.
194
195 There are a number of different querie
196 correspond to the low-level control re
197 specification. These requests are:
198
199 UVC_GET_CUR
200 Obtain the current value of th
201 UVC_GET_MIN
202 Obtain the minimum value of th
203 UVC_GET_MAX
204 Obtain the maximum value of th
205 UVC_GET_DEF
206 Obtain the default value of th
207 UVC_GET_RES
208 Query the resolution of the co
209 allowed control values.
210 UVC_GET_LEN
211 Query the size of the control
212 UVC_GET_INFO
213 Query the control information
214 get/set requests are supported
215 UVC_SET_CUR
216 Update the value of the contro
217
218 Applications must set the 'size' field
219 control. Exceptions are the UVC_GET_LE
220 which the size must be set to 2 and 1,
221 must point to a valid writable buffer
222 number of data bytes.
223
224 Data is copied directly from the devic
225 processing. Applications are responsib
226 including little-endian/big-endian con
227 important for the result of the UVC_GE
228 returned as a little-endian 16-bit int
229
230 **Return value**:
231
232 On success 0 is returned. On error -1
233 appropriately.
234
235 ENOENT
236 The device does not support th
237 extension unit could not be fo
238 ENOBUFS
239 The specified buffer size is i
240 EINVAL
241 An invalid request code was pa
242 EBADRQC
243 The given request is not suppo
244 EFAULT
245 The data pointer references an
246
247 **Data types**:
248
249 .. code-block:: none
250
251 * struct uvc_xu_control_query
252
253 __u8 unit Extension unit
254 __u8 selector Control select
255 __u8 query Request code t
256 __u16 size Control data s
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.