About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / video4linux / uvcvideo.txt


Based on kernel version 4.7.2. Page generated on 2016-08-22 22:48 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog