| blob | e0d54caa831edae4a9f98148d58cead3ac9c2d41 |
1 .\" $NetBSD: ugen.4,v 1.29 2009/12/23 01:04:45 pooka Exp $
2 .\"
3 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Lennart Augustsson.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd December 23, 2009
31 .Dt UGEN 4
32 .Os
33 .Sh NAME
34 .Nm ugen
35 .Nd USB generic device support
36 .Sh SYNOPSIS
37 .Cd "ugen* at uhub? flags N"
38 .Sh DESCRIPTION
39 The
40 .Nm
41 driver provides support for all USB devices that do not have
42 a special driver.
43 It supports access to all parts of the device,
44 but not in a way that is as convenient as a special purpose driver.
45 .Pp
46 Normally the
47 .Nm
48 driver is used when no other driver attaches to a device.
49 If
50 .Dq flags 1
51 is specified, the
52 .Nm
53 will instead attach with a very high priority and always be used.
54 Together with the
55 .Cd vendor
56 and
57 .Cd product
58 locators this can be used to force the
59 .Nm
60 driver to be used for a certain
61 device.
62 .Pp
63 There can be up to 127 USB devices connected to a USB bus.
64 Each USB device can have up to 16 endpoints.
65 Each of these endpoints will communicate in one of four different
66 modes: control, isochronous, bulk, or interrupt.
67 Each of the endpoints will have a different device node.
68 The four least significant bits in the minor device
69 number determines which endpoint the device accesses and the rest
70 of the bits determines which USB device.
71 .Pp
72 If an endpoint address is used both for input and output the device
73 can be opened for both read or write.
74 .Pp
75 To find out what endpoints exist there are a series of
76 .Xr ioctl 2
77 operations on the control endpoint that return the USB descriptors
78 of the device, configurations, interfaces, and endpoints.
79 .Pp
80 The control transfer mode can only happen on the control endpoint
81 which is always endpoint 0.
82 The control endpoint accepts requests
83 and may respond with an answer to such requests.
84 Control requests are issued by
85 .Xr ioctl 2
86 calls.
87 .\" .Pp
88 .\" The isochronous transfer mode can be in or out depending on the
89 .\" endpoint.
90 .\" To perform IO on an isochronous endpoint
91 .\" .Xr read 2
92 .\" and
93 .\" .Xr write 2
94 .\" should be used.
95 .\" Before any IO operations can take place the transfer rate in
96 .\" bytes/second has to be set.
97 .\" This is done with
98 .\" .Xr ioctl 2
99 .\" .Dv USB_SET_ISO_RATE .
100 .\" Performing this call sets up a buffer corresponding to
101 .\" about 1 second of data.
102 .Pp
103 The bulk transfer mode can be in or out depending on the
104 endpoint.
105 To perform IO on a bulk endpoint
106 .Xr read 2
107 and
108 .Xr write 2
109 should be used.
110 All IO operations on a bulk endpoint are normally unbuffered.
111 The
112 .Dv USB_SET_BULK_RA
113 and
114 .Dv USB_SET_BULK_WB
115 .Xr ioctl 2
116 calls enable read-ahead and write-behind buffering, respectively.
117 This buffering supports fixed-sized USB transfers and is intended for
118 devices with regular and continuing data transfers.
119 When read-ahead or write-behind are enabled, the file descriptor
120 may be set to use non-blocking IO.
121 .Pp
122 When in a read-ahead/writeback mode,
123 .Xr select 2
124 for read and write operates normally, returning true if there is data
125 in the read buffer and space in the write buffer, respectively.
126 When not,
127 .Xr select 2
128 always returns true, because there is no way to predict how the device
129 will respond to a read or write request.
130 .Pp
131 The interrupt transfer mode can be in or out depending on the
132 endpoint.
133 To perform IO on an interrupt endpoint
134 .Xr read 2
135 and
136 .Xr write 2
137 should be used.
138 A moderate amount of buffering is done
139 by the driver.
140 .Pp
141 All endpoints handle the following
142 .Xr ioctl 2
143 calls:
144 .Pp
145 .Bl -tag -width indent -compact
146 .It Dv USB_SET_SHORT_XFER (int)
147 Allow short read transfer.
148 Normally a transfer from the device which is shorter than the
149 request specified is reported as an error.
150 .It Dv USB_SET_TIMEOUT (int)
151 Set the timeout on the device operations, the time is specified
152 in milliseconds.
153 The value 0 is used to indicate that there is no timeout.
154 .El
155 .Pp
156 The control endpoint (endpoint 0) handles the following
157 .Xr ioctl 2
158 calls:
159 .Pp
160 .Bl -tag -width indent -compact
161 .It Dv USB_GET_CONFIG (int)
162 Get the device configuration number.
163 .It Dv USB_SET_CONFIG (int)
164 Set the device into the given configuration number.
165 .Pp
166 This operation can only be performed when the control endpoint
167 is the sole open endpoint.
168 .It Dv USB_GET_ALTINTERFACE (struct usb_alt_interface)
169 Get the alternative setting number for the interface with the given
170 index.
171 The
172 .Dv config_index
173 is ignored in this call.
174 .Bd -literal
175 struct usb_alt_interface {
176 int uai_config_index;
177 int uai_interface_index;
178 int uai_alt_no;
179 };
180 .Ed
181 .It Dv USB_SET_ALTINTERFACE (struct usb_alt_interface)
182 Set the alternative setting to the given number in the interface with the
183 given index.
184 The
185 .Dv uai_config_index
186 is ignored in this call.
187 .Pp
188 This operation can only be performed when no endpoints for the interface
189 are open.
190 .It Dv USB_GET_NO_ALT (struct usb_alt_interface)
191 Return the number of different alternate settings in the
192 .Dv aui_alt_no
193 field.
194 .It Dv USB_GET_DEVICE_DESC (usb_device_descriptor_t)
195 Return the device descriptor.
196 .It Dv USB_GET_CONFIG_DESC (struct usb_config_desc)
197 Return the descriptor for the configuration with the given index.
198 For convenience the current configuration can be specified by
199 .Dv USB_CURRENT_CONFIG_INDEX .
200 .Bd -literal
201 struct usb_config_desc {
202 int ucd_config_index;
203 usb_config_descriptor_t ucd_desc;
204 };
205 .Ed
206 .It Dv USB_GET_INTERFACE_DESC (struct usb_interface_desc)
207 Return the interface descriptor for an interface specified by its
208 configuration index, interface index, and alternative index.
209 For convenience the current alternative can be specified by
210 .Dv USB_CURRENT_ALT_INDEX .
211 .Bd -literal
212 struct usb_interface_desc {
213 int uid_config_index;
214 int uid_interface_index;
215 int uid_alt_index;
216 usb_interface_descriptor_t uid_desc;
217 };
218 .Ed
219 .It Dv USB_GET_ENDPOINT_DESC (struct usb_endpoint_desc)
220 Return the endpoint descriptor for the endpoint specified by its
221 configuration index, interface index, alternative index, and
222 endpoint index.
223 .Bd -literal
224 struct usb_endpoint_desc {
225 int ued_config_index;
226 int ued_interface_index;
227 int ued_alt_index;
228 int ued_endpoint_index;
229 usb_endpoint_descriptor_t ued_desc;
230 };
231 .Ed
232 .It Dv USB_GET_FULL_DESC (struct usb_full_desc)
233 Return all the descriptors for the given configuration.
234 .Bd -literal
235 struct usb_full_desc {
236 int ufd_config_index;
237 u_int ufd_size;
238 u_char *ufd_data;
239 };
240 .Ed
241 The
242 .Dv ufd_data
243 field should point to a memory area of the size given in the
244 .Dv ufd_size
245 field.
246 The proper size can be determined by first issuing a
247 .Dv USB_GET_CONFIG_DESC
248 and inspecting the
249 .Dv wTotalLength
250 field.
251 .It Dv USB_GET_STRING_DESC (struct usb_string_desc)
252 Get a string descriptor for the given language id and
253 string index.
254 .Bd -literal
255 struct usb_string_desc {
256 int usd_string_index;
257 int usd_language_id;
258 usb_string_descriptor_t usd_desc;
259 };
260 .Ed
261 .It Dv USB_DO_REQUEST
262 Send a USB request to the device on the control endpoint.
263 Any data sent to/from the device is located at
264 .Dv data .
265 The size of the transferred data is determined from the
266 .Dv request .
267 The
268 .Dv ucr_addr
269 field is ignored in this call.
270 The
271 .Dv ucr_flags
272 field can be used to flag that the request is allowed to
273 be shorter than the requested size, and the
274 .Dv ucr_actlen
275 field will contain the actual size on completion.
276 .Bd -literal
277 struct usb_ctl_request {
278 int ucr_addr;
279 usb_device_request_t ucr_request;
280 void *ucr_data;
281 int ucr_flags;
282 #define USBD_SHORT_XFER_OK 0x04 /* allow short reads */
283 int ucr_actlen; /* actual length transferred */
284 };
285 .Ed
286 This is a dangerous operation in that it can perform arbitrary operations
287 on the device.
288 Some of the most dangerous (e.g., changing the device
289 address) are not allowed.
290 .It Dv USB_GET_DEVICEINFO (struct usb_device_info)
291 Get an information summary for the device.
292 This call will not issue any USB transactions.
293 .El
294 .Pp
295 Bulk endpoints handle the following
296 .Xr ioctl 2
297 calls:
298 .Pp
299 .Bl -tag -width indent -compact
300 .It Dv USB_SET_BULK_RA (int)
301 Enable or disable bulk read-ahead.
302 When enabled, the driver will begin to read data from the device into
303 a buffer, and will perform reads from the device whenever there is
304 room in the buffer.
305 The
306 .Xr read 2
307 call will read data from this buffer, blocking if necessary until
308 there is enough data to read the length of data requested.
309 The buffer size and the read request length can be set by the
310 .Dv USB_SET_BULK_RA_OPT
311 .Xr ioctl 2
312 call.
313 .It Dv USB_SET_BULK_WB (int)
314 Enable or disable bulk write-behind.
315 When enabled, the driver will buffer data from the
316 .Xr write 2
317 call before writing it to the device, enabling the
318 .Xr write 2
319 call to return immediately.
320 .Xr write 2
321 will block if there is not enough room in the buffer for all
322 the data.
323 The buffer size and the write request length can be set by the
324 .Dv USB_SET_BULK_WB_OPT
325 .Xr ioctl 2
326 call.
327 .It Dv USB_SET_BULK_RA_OPT (struct usb_bulk_ra_wb_opt)
328 Set the size of the buffer and the length of the read requests used by
329 the driver when bulk read-ahead is enabled.
330 The changes do not take
331 effect until the next time bulk read-ahead is enabled.
332 Read requests
333 are made for the length specified, and the host controller driver
334 (i.e.,
335 .Xr ehci 4 ,
336 .Xr ohci 4 ,
337 and
338 .Xr uhci 4 )
339 will perform as many bus transfers as required.
340 If transfers from the device should be smaller than the maximum length,
341 .Dv ra_wb_request_size
342 must be set to the required length.
343 .Bd -literal
344 struct usb_bulk_ra_wb_opt {
345 u_int ra_wb_buffer_size;
346 u_int ra_wb_request_size;
347 };
348 .Ed
349 .It Dv USB_SET_BULK_WB_OPT (struct usb_bulk_ra_wb_opt)
350 Set the size of the buffer and the length of the write requests used
351 by the driver when bulk write-behind is enabled.
352 The changes do not
353 take effect until the next time bulk write-behind is enabled.
354 .El
355 .Pp
356 Note that there are two different ways of addressing configurations, interfaces,
357 alternatives, and endpoints: by index or by number.
358 The index is the ordinal number (starting from 0) of the descriptor
359 as presented by the device.
360 The number is the respective number of
361 the entity as found in its descriptor.
362 Enumeration of descriptors
363 use the index, getting and setting typically uses numbers.
364 .Pp
365 Example:
366 All endpoints (except the control endpoint) for the current configuration
367 can be found by iterating the
368 .Dv interface_index
369 from 0 to
370 .Dv config_desc-\*[Gt]bNumInterface-1
371 and for each of these iterating the
372 .Dv endpoint_index
373 from 0 to
374 .Dv interface_desc-\*[Gt]bNumEndpoints .
375 The
376 .Dv config_index
377 should set to
378 .Dv USB_CURRENT_CONFIG_INDEX
379 and
380 .Dv alt_index
381 should be set to
382 .Dv USB_CURRENT_ALT_INDEX .
383 .Sh FILES
384 .Bl -tag -width Pa
385 .It Pa /dev/ugenN.EE
386 Endpoint
387 .Pa EE
388 of device
389 .Pa N .
390 .El
391 .Sh SEE ALSO
392 .Xr usb 4
393 .Sh HISTORY
394 The
395 .Nm
396 driver
397 appeared in
398 .Nx 1.4 .
399 .\" .Sh BUGS
400 .\" The driver is not yet finished; there is no access to isochronous endpoints.