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