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
112Argument: 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
185
186UVCIOC_CTRL_QUERY - Query a UVC XU control
187^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
188Argument: struct uvc_xu_control_query
189
190**Description**:
191
192	This ioctl queries a UVC XU control identified by its extension unit ID
193	and control selector.
194
195	There are a number of different queries available that closely
196	correspond to the low-level control requests described in the UVC
197	specification. These requests are:
198
199	UVC_GET_CUR
200		Obtain the current value of the control.
201	UVC_GET_MIN
202		Obtain the minimum value of the control.
203	UVC_GET_MAX
204		Obtain the maximum value of the control.
205	UVC_GET_DEF
206		Obtain the default value of the control.
207	UVC_GET_RES
208		Query the resolution of the control, i.e. the step size of the
209		allowed control values.
210	UVC_GET_LEN
211		Query the size of the control in bytes.
212	UVC_GET_INFO
213		Query the control information bitmap, which indicates whether
214		get/set requests are supported.
215	UVC_SET_CUR
216		Update the value of the control.
217
218	Applications must set the 'size' field to the correct length for the
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, respectively. The 'data' field
221	must point to a valid writable buffer big enough to hold the indicated
222	number of data bytes.
223
224	Data is copied directly from the device without any driver-side
225	processing. Applications are responsible for data buffer formatting,
226	including little-endian/big-endian conversion. This is particularly
227	important for the result of the UVC_GET_LEN requests, which is always
228	returned as a little-endian 16-bit integer by the device.
229
230**Return value**:
231
232	On success 0 is returned. On error -1 is returned and errno is set
233	appropriately.
234
235	ENOENT
236		The device does not support the given control or the specified
237		extension unit could not be found.
238	ENOBUFS
239		The specified buffer size is incorrect (too big or too small).
240	EINVAL
241		An invalid request code was passed.
242	EBADRQC
243		The given request is not supported by the given control.
244	EFAULT
245		The data pointer references an inaccessible memory area.
246
247**Data types**:
248
249.. code-block:: none
250
251	* struct uvc_xu_control_query
252
253	__u8	unit		Extension unit ID
254	__u8	selector	Control selector
255	__u8	query		Request code to send to the device
256	__u16	size		Control data size (in bytes)
257	__u8	*data		Control value
258