blob: 35ce19cddcf8070501e0d30f81c2fde2ac2a2456 [file] [log] [blame]
Martin Rublifb08a5c2010-09-01 04:11:22 -03001Linux USB Video Class (UVC) driver
2==================================
3
4This file documents some driver-specific aspects of the UVC driver, such as
5driver-specific ioctls and implementation notes.
6
7Questions and remarks can be sent to the Linux UVC development mailing list at
8linux-uvc-devel@lists.berlios.de.
9
10
11Extension Unit (XU) support
12---------------------------
13
141. Introduction
15
16The UVC specification allows for vendor-specific extensions through extension
17units (XUs). The Linux UVC driver supports extension unit controls (XU controls)
18through two separate mechanisms:
19
20 - through mappings of XU controls to V4L2 controls
21 - through a driver-specific ioctl interface
22
23The first one allows generic V4L2 applications to use XU controls by mapping
24certain XU controls onto V4L2 controls, which then show up during ordinary
25control enumeration.
26
27The second mechanism requires uvcvideo-specific knowledge for the application to
28access XU controls but exposes the entire UVC XU concept to user space for
29maximum flexibility.
30
31Both mechanisms complement each other and are described in more detail below.
32
33
342. Control mappings
35
36The UVC driver provides an API for user space applications to define so-called
37control mappings at runtime. These allow for individual XU controls or byte
38ranges thereof to be mapped to new V4L2 controls. Such controls appear and
39function exactly like normal V4L2 controls (i.e. the stock controls, such as
40brightness, contrast, etc.). However, reading or writing of such a V4L2 controls
41triggers a read or write of the associated XU control.
42
43The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP.
44Previous driver versions (before 0.2.0) required another ioctl to be used
45beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver.
46This is no longer necessary as newer uvcvideo versions query the information
47directly from the device.
48
49For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled
50"IOCTL reference" below.
51
52
533. Driver specific XU control interface
54
55For applications that need to access XU controls directly, e.g. for testing
56purposes, firmware upload, or accessing binary controls, a second mechanism to
57access XU controls is provided in the form of a driver-specific ioctl, namely
58UVCIOC_CTRL_QUERY.
59
60A call to this ioctl allows applications to send queries to the UVC driver that
61directly map to the low-level UVC control requests.
62
63In order to make such a request the UVC unit ID of the control's extension unit
64and the control selector need to be known. This information either needs to be
65hardcoded in the application or queried using other ways such as by parsing the
66UVC descriptor or, if available, using the media controller API to enumerate a
67device's entities.
68
69Unless the control size is already known it is necessary to first make a
70UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer
71and set the buffer size to the correct value. Similarly, to find out whether
72UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a
73UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET
74supported) of the resulting byte indicate which requests are valid.
75
76With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and
77UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a
78subset of the former ioctl. For the time being they are still supported but
79application developers are encouraged to use UVCIOC_CTRL_QUERY instead.
80
81For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled
82"IOCTL reference" below.
83
84
854. Security
86
87The API doesn't currently provide a fine-grained access control facility. The
88UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions.
89
90Suggestions on how to improve this are welcome.
91
92
935. Debugging
94
95In order to debug problems related to XU controls or controls in general it is
96recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'.
97This causes extra output to be written into the system log.
98
99
1006. IOCTL reference
101
102---- UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control ----
103
104Argument: struct uvc_xu_control_mapping
105
106Description:
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
Masanari Iida40e47122012-03-04 23:16:11 +0900119 the 'size' and 'offset' fields and are then independently mapped to
Martin Rublifb08a5c2010-09-01 04:11:22 -0300120 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
125Return 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
140Data 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
175Argument: struct uvc_xu_control_query
176
177Description:
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
216Return 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
232Data 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