]>
Commit | Line | Data |
---|---|---|
fb08a5cd MR |
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 | |
40e47125 | 119 | the 'size' and 'offset' fields and are then independently mapped to |
fb08a5cd MR |
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 |