| blob | 474015f6c35748356b9b221277a945c5a2603074 |
1 .\" $NetBSD: usb.4,v 1.90 2009/05/04 20:42:34 wiz Exp $
2 .\"
3 .\" Copyright (c) 1999-2008 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 March 25, 2008
31 .Dt USB 4
32 .Os
33 .Sh NAME
34 .Nm usb
35 .Nd Universal Serial Bus driver
36 .Sh SYNOPSIS
37 .Cd "ehci* at cardbus? function ?"
38 .Cd "ehci* at pci? dev ? function ?"
39 .Cd "ohci* at cardbus? function ?"
40 .Cd "ohci* at pci? dev ? function ?"
41 .Cd "slhci* at isa? port ? irq ?"
42 .Cd "slhci* at pcmcia? function ?"
43 .Cd "uhci* at cardbus? function ?"
44 .Cd "uhci* at pci? dev ? function ?"
45 .Cd "usb* at ehci? flags X"
46 .Cd "usb* at ohci? flags X"
47 .Cd "usb* at uhci? flags X"
48 .Cd "usb* at slhci? flags X"
49 .Cd "uhub* at usb?"
50 .Cd "uhub* at uhub? port ? configuration ? interface ? vendor ? product ? release ?"
51 .Cd "XX* at uhub? port ? configuration ? interface ? vendor ? product ? release ?"
52 .Pp
53 .Cd options USBVERBOSE
54 .Pp
55 .In dev/usb/usb.h
56 .In dev/usb/usbhid.h
57 .Sh DESCRIPTION
58 .Nx
59 provides machine-independent bus support and drivers for
60 .Tn USB
61 devices.
62 .Pp
63 The
64 .Nx
65 .Nm
66 driver has three layers (like
67 .Xr scsi 4
68 and
69 .Xr pcmcia 4 ) :
70 the controller, the bus, and the device layer.
71 The controller attaches to a physical bus (like
72 .Xr pci 4 ) .
73 The
74 .Tn USB
75 bus attaches to the controller and the root hub attaches
76 to the bus.
77 Further devices, which may include further hubs,
78 attach to other hubs.
79 The attachment forms the same tree structure as the physical
80 .Tn USB
81 device tree.
82 For each
83 .Tn USB
84 device there may be additional drivers attached to it.
85 .Pp
86 The
87 .Cm uhub
88 device controls
89 .Tn USB
90 hubs and must always be present since there is at least a root hub in any
91 .Tn USB
92 system.
93 .Pp
94 The
95 .Va flags
96 argument to the
97 .Va usb
98 device affects the order in which the device detection happens
99 during cold boot.
100 Normally, only the USB host controller and the
101 .Va usb
102 device are detected during the autoconfiguration when the
103 machine is booted.
104 The rest of the devices are detected once
105 the system becomes functional and the kernel thread for the
106 .Va usb
107 device is started.
108 Sometimes it is desirable to have a device detected early in the
109 boot process, e.g., the console keyboard.
110 To achieve this use a
111 .Va flags
112 value of 1.
113 .Pp
114 .Nx
115 supports the following machine-independent
116 .Tn USB
117 drivers:
118 .Ss Storage devices
119 .Bl -tag -width 12n -offset ind -compact
120 .It Xr umass 4
121 .Tn USB
122 Mass Storage Devices, e.g., external disk drives
123 .El
124 .Ss Wired network interfaces
125 .Bl -tag -width 12n -offset ind -compact
126 .It Xr aue 4
127 ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device
128 .It Xr axe 4
129 ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device
130 .It Xr cdce 4
131 USB Communication Device Class Ethernet device
132 .It Xr cue 4
133 CATC USB-EL1201A USB Ethernet device
134 .It Xr kue 4
135 Kawasaki LSI KL5KUSB101B USB Ethernet device
136 .It Xr udav 4
137 Davicom DM9601 10/100 USB Ethernet device
138 .It Xr url 4
139 Realtek RTL8150L 10/100 USB Ethernet device
140 .El
141 .Ss Wireless network interfaces
142 .Bl -tag -width 12n -offset ind -compact
143 .It Xr atu 4
144 Atmel AT76C50x IEEE 802.11b wireless network device
145 .It Xr ral 4
146 Ralink Technology USB IEEE 802.11b/g wireless network device
147 .It Xr rum 4
148 Ralink Technology USB IEEE 802.11a/b/g wireless network device
149 .It Xr ubt 4
150 USB Bluetooth dongles
151 .It Xr zyd 4
152 ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device
153 .El
154 .Ss Serial and parallel interfaces
155 .Bl -tag -width 12n -offset ind -compact
156 .It Xr ubsa 4
157 Belkin USB serial adapter
158 .It Xr uchcom 4
159 WinChipHead CH341/340 based USB serial adapter
160 .It Xr ucom 4
161 USB tty support
162 .It Xr ucycom 4
163 Cypress microcontroller based USB serial adapter
164 .It Xr uftdi 4
165 FT8U100AX USB serial adapter
166 .It Xr ugensa 4
167 USB generic serial adapter
168 .It Xr uhmodem 4
169 USB Huawei 3G wireless modem device
170 .It Xr uipaq 4
171 iPAQ USB units
172 .It Xr ukyopon 4
173 USB Kyocera AIR-EDGE PHONE device
174 .It Xr ulpt 4
175 USB printer support
176 .It Xr umct 4
177 MCT USB-RS232 USB serial adapter
178 .It Xr umodem 4
179 USB modem support
180 .It Xr uplcom 4
181 Prolific PL-2303 USB serial adapter
182 .It Xr uslsa 4
183 Silicon Laboratories CP2101/CP2102 based USB serial adapter
184 .It Xr uvisor 4
185 USB Handspring Visor
186 .It Xr uvscom 4
187 SUNTAC Slipper U VS-10U USB serial adapter
188 .El
189 .Ss Audio devices
190 .Bl -tag -width 12n -offset ind -compact
191 .It Xr uaudio 4
192 USB audio devices
193 .It Xr umidi 4
194 USB MIDI devices
195 .It Xr urio 4
196 Diamond Multimedia Rio MP3 players
197 .El
198 .Ss Radio receiver devices
199 .Bl -tag -width 12n -offset ind -compact
200 .It Xr udsbr 4
201 D-Link DSB-R100 USB radio device
202 .El
203 .Ss Human Interface Devices
204 .Bl -tag -width 12n -offset ind -compact
205 .It Xr uhid 4
206 Generic driver for Human Interface Devices
207 .It Xr uhidev 4
208 Base driver for all Human Interface Devices
209 .It Xr ukbd 4
210 .Tn USB
211 keyboards that follow the boot protocol
212 .It Xr ums 4
213 .Tn USB
214 mouse devices
215 .El
216 .Ss Miscellaneous devices
217 .Bl -tag -width 12n -offset ind -compact
218 .It Xr stuirda 4
219 Sigmaltel 4116/4220 USB-IrDA bridge
220 .It Xr uep 4
221 USB eGalax touch-panel
222 .It Xr ugen 4
223 USB generic devices
224 .It Xr uirda 4
225 USB IrDA bridges
226 .It Xr upl 4
227 Prolific based host-to-host adapters
228 .It Xr uscanner 4
229 USB scanner support
230 .It Xr usscanner 4
231 SCSI-over-USB scanners
232 .It Xr ustir 4
233 SigmaTel STIr4200 USB IrDA bridges
234 .It Xr utoppy 4
235 Topfield TF5000PVR range of digital video recorders
236 .It Xr uyap 4
237 USB YAP phone firmware loader
238 .El
239 .Sh INTRODUCTION TO USB
240 The
241 .Tn USB
242 1.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices.
243 .Tn USB
244 2.x handles 480 Mb/s.
245 Each
246 .Tn USB
247 has a host controller that is the master of the bus;
248 all other devices on the bus only speak when spoken to.
249 .Pp
250 There can be up to 127 devices (apart from the host controller)
251 on a bus, each with its own address.
252 The addresses are assigned
253 dynamically by the host when each device is attached to the bus.
254 .Pp
255 Within each device there can be up to 16 endpoints.
256 Each endpoint
257 is individually addressed and the addresses are static.
258 Each of these endpoints will communicate in one of four different modes:
259 control, isochronous, bulk, or interrupt.
260 A device always has at least one endpoint.
261 This endpoint has address 0 and is a control
262 endpoint and is used to give commands to and extract basic data,
263 such as descriptors, from the device.
264 Each endpoint, except the control endpoint, is unidirectional.
265 .Pp
266 The endpoints in a device are grouped into interfaces.
267 An interface is a logical unit within a device; e.g.,
268 a compound device with both a keyboard and a trackball would present
269 one interface for each.
270 An interface can sometimes be set into different modes,
271 called alternate settings, which affects how it operates.
272 Different alternate settings can have different endpoints
273 within it.
274 .Pp
275 A device may operate in different configurations.
276 Depending on the
277 configuration the device may present different sets of endpoints
278 and interfaces.
279 .Pp
280 Each device located on a hub has several
281 .Xr config 1
282 locators:
283 .Bl -tag -compact -width xxxxxxxxx
284 .It Cd port
285 this is the number of the port on closest upstream hub.
286 .It Cd configuration
287 this is the configuration the device must be in for this driver to attach.
288 This locator does not set the configuration; it is iterated by the bus
289 enumeration.
290 .It Cd interface
291 this is the interface number within a device that an interface driver
292 attaches to.
293 .It Cd vendor
294 this is the 16 bit vendor id of the device.
295 .It Cd product
296 this is the 16 bit product id of the device.
297 .It Cd release
298 this is the 16 bit release (revision) number of the device.
299 .El
300 The first locator can be used to pin down a particular device
301 according to its physical position in the device tree.
302 The last three locators can be used to pin down a particular
303 device according to what device it actually is.
304 .Pp
305 The bus enumeration of the
306 .Tn USB
307 bus proceeds in several steps:
308 .Bl -enum
309 .It
310 Any device specific driver can attach to the device.
311 .It
312 If none is found, any device class specific driver can attach.
313 .It
314 If none is found, all configurations are iterated over.
315 For each configuration all the interface are iterated over and interface
316 drivers can attach.
317 If any interface driver attached in a certain
318 configuration the iteration over configurations is stopped.
319 .It
320 If still no drivers have been found, the generic
321 .Tn USB
322 driver can attach.
323 .El
324 .Sh USB CONTROLLER INTERFACE
325 Use the following to get access to the
326 .Tn USB
327 specific structures and defines.
328 .Bd -literal
329 #include \*[Lt]dev/usb/usb.h\*[Gt]
330 .Ed
331 .Pp
332 The
333 .Pa /dev/usbN
334 can be opened and a few operations can be performed on it.
335 The
336 .Xr poll 2
337 system call will say that I/O is possible on the controller device when a
338 .Tn USB
339 device has been connected or disconnected to the bus.
340 .Pp
341 The following
342 .Xr ioctl 2
343 commands are supported on the controller device:
344 .Bl -tag -width xxxxxx
345 .\" .It Dv USB_DISCOVER
346 .\" This command will cause a complete bus discovery to be initiated.
347 .\" If any devices attached or detached from the bus they will be
348 .\" processed during this command.
349 .\" This is the only way that new devices are found on the bus.
350 .It Dv USB_DEVICEINFO Fa "struct usb_device_info"
351 This command can be used to retrieve some information about a device
352 on the bus.
353 The
354 .Va addr
355 field should be filled before the call and the other fields will
356 be filled by information about the device on that address.
357 Should no such device exist an error is reported.
358 .Bd -literal
359 struct usb_device_info {
360 uint8_t udi_bus;
361 uint8_t udi_addr;
362 usb_event_cookie_t udi_cookie;
363 char udi_product[USB_MAX_ENCODED_STRING_LEN];
364 char udi_vendor[USB_MAX_ENCODED_STRING_LEN];
365 char udi_release[8];
366 char udi_serial[USB_MAX_ENCODED_STRING_LEN];
367 uint16_t udi_productNo;
368 uint16_t udi_vendorNo;
369 uint16_t udi_releaseNo;
370 uint8_t udi_class;
371 uint8_t udi_subclass;
372 uint8_t udi_protocol;
373 uint8_t udi_config;
374 uint8_t udi_speed;
375 #define USB_SPEED_LOW 1
376 #define USB_SPEED_FULL 2
377 #define USB_SPEED_HIGH 3
378 int udi_power;
379 int udi_nports;
380 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
381 uint8_t udi_ports[16];
382 #define USB_PORT_ENABLED 0xff
383 #define USB_PORT_SUSPENDED 0xfe
384 #define USB_PORT_POWERED 0xfd
385 #define USB_PORT_DISABLED 0xfc
386 };
387 .Ed
388 .Pp
389 The
390 .Va product ,
391 .Va vendor ,
392 .Va release ,
393 and
394 .Va serial
395 fields contain self-explanatory descriptions of the device.
396 .Pp
397 The
398 .Va class
399 field contains the device class.
400 .Pp
401 The
402 .Va config
403 field shows the current configuration of the device.
404 .Pp
405 The
406 .Va lowspeed
407 field
408 is set if the device is a
409 .Tn USB
410 low speed device.
411 .Pp
412 The
413 .Va power
414 field shows the power consumption in milli-amps drawn at 5 volts,
415 or zero if the device is self powered.
416 .Pp
417 If the device is a hub the
418 .Va nports
419 field is non-zero and the
420 .Va ports
421 field contains the addresses of the connected devices.
422 If no device is connected to a port one of the
423 .Va USB_PORT_*
424 values indicates its status.
425 .It Dv USB_DEVICESTATS Fa "struct usb_device_stats"
426 This command retrieves statistics about the controller.
427 .Bd -literal
428 struct usb_device_stats {
429 u_long uds_requests[4];
430 };
431 .Ed
432 .Pp
433 The
434 .Va requests
435 field is indexed by the transfer kind, i.e.
436 .Va UE_* ,
437 and indicates how many transfers of each kind have been completed
438 by the controller.
439 .It Dv USB_REQUEST Fa "struct usb_ctl_request"
440 This command can be used to execute arbitrary requests on the control pipe.
441 This is
442 .Em DANGEROUS
443 and should be used with great care since it
444 can destroy the bus integrity.
445 .El
446 .Pp
447 The include file
448 .Aq Pa dev/usb/usb.h
449 contains definitions for the types used by the various
450 .Xr ioctl 2
451 calls.
452 The naming convention of the fields for the various
453 .Tn USB
454 descriptors exactly follows the naming in the
455 .Tn USB
456 specification.
457 Byte sized fields can be accessed directly, but word (16 bit)
458 sized fields must be access by the
459 .Fn UGETW field
460 and
461 .Fn USETW field value
462 macros to handle byte order and alignment properly.
463 .Pp
464 The include file
465 .Aq Pa dev/usb/usbhid.h
466 similarly contains the definitions for
467 Human Interface Devices
468 .Pq Tn HID .
469 .Sh USB EVENT INTERFACE
470 All
471 .Tn USB
472 events are reported via the
473 .Pa /dev/usb
474 device.
475 This devices can be opened for reading and each
476 .Xr read 2
477 will yield an event record (if something has happened).
478 The
479 .Xr poll 2
480 system call can be used to determine if an event record is available
481 for reading.
482 .Pp
483 The event record has the following definition:
484 .Bd -literal
485 struct usb_event {
486 int ue_type;
487 #define USB_EVENT_CTRLR_ATTACH 1
488 #define USB_EVENT_CTRLR_DETACH 2
489 #define USB_EVENT_DEVICE_ATTACH 3
490 #define USB_EVENT_DEVICE_DETACH 4
491 #define USB_EVENT_DRIVER_ATTACH 5
492 #define USB_EVENT_DRIVER_DETACH 6
493 struct timespec ue_time;
494 union {
495 struct {
496 int ue_bus;
497 } ue_ctrlr;
498 struct usb_device_info ue_device;
499 struct {
500 usb_event_cookie_t ue_cookie;
501 char ue_devname[16];
502 } ue_driver;
503 } u;
504 };
505 .Ed
506 .Pp
507 The
508 .Va ue_type
509 field identifies the type of event that is described.
510 The possible events are attach/detach of a host controller,
511 a device, or a device driver.
512 The union contains information
513 pertinent to the different types of events.
514 .Pp
515 The
516 .Va ue_bus
517 contains the number of the
518 .Tn USB
519 bus for host controller events.
520 .Pp
521 The
522 .Va ue_device
523 record contains information about the device in a device event event.
524 .Pp
525 The
526 .Va ue_cookie
527 is an opaque value that uniquely determines which
528 device a device driver has been attached to (i.e., it equals
529 the cookie value in the device that the driver attached to).
530 The
531 .Va ue_devname
532 contains the name of the device (driver) as seen in, e.g.,
533 kernel messages.
534 .Pp
535 Note that there is a separation between device and device
536 driver events.
537 A device event is generated when a physical
538 USB device is attached or detached.
539 A single USB device may
540 have zero, one, or many device drivers associated with it.
541 .Sh KERNEL THREADS
542 For each USB bus, i.e., for each host controller, there is
543 a kernel thread that handles attach and detach of devices on
544 that bus.
545 The thread is named
546 .Va usbN
547 where
548 .Va N
549 is the bus number.
550 .Pp
551 In addition there is a kernel thread,
552 .Va usbtask ,
553 which handles various minor tasks that are initiated from
554 an interrupt context, but need to sleep, e.g., time-out
555 abort of transfers.
556 .Sh SEE ALSO
557 The
558 .Tn USB
559 specifications can be found at:
560 .D1 http://www.usb.org/developers/docs/
561 .Pp
562 .Xr usbhidaction 1 ,
563 .Xr usbhidctl 1 ,
564 .Xr cardbus 4 ,
565 .Xr ehci 4 ,
566 .Xr isa 4 ,
567 .Xr ohci 4 ,
568 .Xr pci 4 ,
569 .Xr pcmcia 4 ,
570 .Xr slhci 4 ,
571 .Xr uhci 4 ,
572 .Xr usbdevs 8
573 .Sh HISTORY
574 The
575 .Nm
576 driver
577 appeared in
578 .Nx 1.4 .
579 .Sh BUGS
580 There should be a serial number locator, but
581 .Nx
582 does not have string valued locators.