Merge branch 'x86-urgent-for-linus' of git://git.kernel.org/pub/scm/linux/kernel...
[linux-3.10.git] / Documentation / video4linux / uvcvideo.txt
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