40ba00533dfc9ffaff28c6ee05630e6ed9b84a05
[dragonfly.git] / share / man / man4 / usb.4
1 .\" Copyright (c) 1997, 1998
2 .\"     Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\"    notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\"    notice, this list of conditions and the following disclaimer in the
11 .\"    documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the author nor the names of any co-contributors
13 .\"    may be used to endorse or promote products derived from this software
14 .\"   without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD
20 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
26 .\" THE POSSIBILITY OF SUCH DAMAGE.
27 .\"
28 .\" $FreeBSD: src/share/man/man4/usb.4,v 1.32 2005/04/20 07:33:09 simon Exp $
29 .\"
30 .Dd September 2, 2011
31 .Dt USB 4
32 .Os
33 .Sh NAME
34 .Nm usb
35 .Nd Universal Serial Bus
36 .Sh SYNOPSIS
37 .Cd "device usb"
38 .Pp
39 .In bus/usb/usb.h
40 .In bus/usb/usbhid.h
41 .Sh DESCRIPTION
42 .Dx
43 provides machine-independent bus support and drivers for
44 .Tn USB
45 devices.
46 .Pp
47 The
48 .Nm
49 driver has three layers: the controller, the bus, and the
50 device layer.
51 The controller attaches to a physical bus
52 (like
53 .Xr pci 4 ) .
54 The
55 .Tn USB
56 bus attaches to the controller, and the root hub attaches
57 to the controller.
58 Any devices attached to the bus will attach to the root hub
59 or another hub attached to the
60 .Tn USB
61 bus.
62 .Pp
63 The
64 .Nm uhub
65 device will always be present as it is needed for the
66 root hub.
67 .Ss Storage devices
68 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
69 .\".It Xr natausb 4
70 .\"...
71 .It Xr umass 4
72 Mass Storage Devices, e.g., external disk drives
73 .El
74 .Ss Wired network interfaces
75 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
76 .It Xr aue 4
77 ADMtek AN986 Pegasus Ethernet driver
78 .It Xr axe 4
79 ASIX Electronics AX88172 Ethernet driver
80 .It Xr cue 4
81 CATC USB-EL1210A Ethernet driver
82 .It Xr kue 4
83 Kawasaki LSI KL5KUSB101B Ethernet driver
84 .It Xr lgue 4
85 USB CDC (communication device class) driver for the LG P-500 smartphone
86 .It Xr rue 4
87 RealTek RTL8150 Ethernet driver
88 .El
89 .Ss Wireless network interfaces
90 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
91 .It Xr ndis 4
92 NDIS miniport driver wrapper
93 .It Xr rum 4
94 Ralink Technology RT2501USB/RT2601USB IEEE 802.11 driver
95 .It Xr run 4
96 Ralink Technology RT2700U/RT2800U/RT3000U IEEE 802.11 driver
97 .It Xr ubt 4
98 Bluetooth adapters
99 .\".It Xr ural 4
100 .\"Ralink Technology RT2500USB IEEE 802.11 driver
101 .El
102 .Ss Serial and parallel interfaces
103 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
104 .It Xr moscom 4
105 MosChip Semiconductor MCS7703 based serial adapters
106 .It Xr uark 4
107 Arkmicro Technologies ARK3116 based serial adapters
108 .It Xr ubsa 4
109 Belkin serial adapters
110 .It Xr uchcom 4
111 WinChipHead CH341/CH340 serial adapters
112 .It Xr ucom 4
113 tty support
114 .It Xr uftdi 4
115 serial devices based on the FTDI chips
116 .It Xr ugensa 4
117 generic serial device
118 .It Xr ulpt 4
119 printer support
120 .It Xr umct 4
121 Magic Control Technology USB-232 based serial adapters
122 .It Xr uplcom 4
123 Prolific PL-2303/2303X/2303HX serial adapters
124 .It Xr uslcom 4
125 Silicon Laboratories CP2101, CP2102 and CP2103 USB to serial bridge
126 .It Xr uticom 4
127 Texas Instruments TUSB3410 RS232 to USB converter
128 .It Xr uvisor 4
129 support for the Handspring Visor, a Palmpilot compatible PDA
130 .It Xr uvscom 4
131 SUNTAC Slipper U VS-10U serial adapters
132 .El
133 .Ss Audio devices
134 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
135 .It Xr snd_uaudio 4
136 audio device driver
137 .It Xr urio 4
138 driver for the Rio500 MP3 player
139 .El
140 .Ss Radio receiver devices
141 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
142 .It Xr ufm 4
143 Cypress Semiconductor FM Radio
144 .El
145 .Ss Human Interface Devices
146 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
147 .It Xr uhid 4
148 generic driver for Human Interface Devices
149 .It Xr ukbd 4
150 keyboards that follow the boot protocol
151 .It Xr ums 4
152 mouse devices
153 .El
154 .Ss Miscellaneous devices
155 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
156 .It Xr ugen 4
157 generic device support
158 .It Xr uscanner 4
159 scanner support
160 .El
161 .Sh INTRODUCTION TO USB
162 The
163 .Tn USB
164 is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
165 Each
166 .Tn USB
167 has a host controller that is the master of the bus;
168 all other devices on the bus only speak when spoken to.
169 .Pp
170 There can be up to 127 devices (apart from the host controller)
171 on a bus, each with its own address.
172 The addresses are assigned
173 dynamically by the host when each device is attached to the bus.
174 .Pp
175 Within each device there can be up to 16 endpoints.
176 Each endpoint
177 is individually addressed and the addresses are static.
178 Each of these endpoints will communicate in one of four different modes:
179 .Em control , isochronous , bulk ,
180 or
181 .Em interrupt .
182 A device always has at least one endpoint.
183 This endpoint has address 0 and is a control
184 endpoint and is used to give commands to and extract basic data,
185 such as descriptors, from the device.
186 Each endpoint, except the control endpoint, is unidirectional.
187 .Pp
188 The endpoints in a device are grouped into interfaces.
189 An interface is a logical unit within a device; e.g.\&
190 a compound device with both a keyboard and a trackball would present
191 one interface for each.
192 An interface can sometimes be set into different modes,
193 called alternate settings, which affects how it operates.
194 Different alternate settings can have different endpoints
195 within it.
196 .Pp
197 A device may operate in different configurations.
198 Depending on the
199 configuration, the device may present different sets of endpoints
200 and interfaces.
201 .\".Pp
202 .\"Each device located on a hub has several
203 .\".Xr config 8
204 .\"locators:
205 .\".Bl -tag -compact -width xxxxxx
206 .\".It Cd port
207 .\"this is the number of the port on the closest upstream hub.
208 .\".It Cd configuration
209 .\"this is the configuration the device must be in for this driver to attach.
210 .\"This locator does not set the configuration; it is iterated by the bus
211 .\"enumeration.
212 .\".It Cd interface
213 .\"this is the interface number within a device that an interface driver
214 .\"attaches to.
215 .\".It Cd vendor
216 .\"this is the 16 bit vendor id of the device.
217 .\".It Cd product
218 .\"this is the 16 bit product id of the device.
219 .\".It Cd release
220 .\"this is the 16 bit release (revision) number of the device.
221 .\".El
222 .\"The first locator can be used to pin down a particular device
223 .\"according to its physical position in the device tree.
224 .\"The last three locators can be used to pin down a particular
225 .\"device according to what device it actually is.
226 .Pp
227 The bus enumeration of the
228 .Tn USB
229 bus proceeds in several steps:
230 .Bl -enum
231 .It
232 Any device specific driver can attach to the device.
233 .It
234 If none is found, any device class specific driver can attach.
235 .It
236 If none is found, all configurations are iterated over.
237 For each configuration, all the interfaces are iterated over, and interface
238 drivers can attach.
239 If any interface driver attached in a certain
240 configuration, the iteration over configurations is stopped.
241 .It
242 If still no drivers have been found, the generic
243 .Tn USB
244 driver can attach.
245 .El
246 .Sh USB CONTROLLER INTERFACE
247 Use the following to get access to the
248 .Tn USB
249 specific structures and defines.
250 .Pp
251 .In bus/usb/usb.h
252 .Pp
253 The
254 .Pa /dev/usb Ns Ar N
255 can be opened and a few operations can be performed on it.
256 The
257 .Xr poll 2
258 system call will say that I/O is possible on the controller device when a
259 .Tn USB
260 device has been connected or disconnected to the bus.
261 .Pp
262 The following
263 .Xr ioctl 2
264 commands are supported on the controller device:
265 .Bl -tag -width xxxxxx
266 .It Dv USB_DISCOVER
267 This command will cause a complete bus discovery to be initiated.
268 If any devices attached or detached from the bus they will be
269 processed during this command.
270 This is the only way that new devices are found on the bus.
271 .It Dv USB_DEVICEINFO Vt "struct usb_device_info"
272 This command can be used to retrieve some information about a device
273 on the bus.
274 The
275 .Va udi_addr
276 field should be filled before the call and the other fields will
277 be filled by information about the device on that address.
278 Should no such device exist, an error is reported.
279 .Bd -literal
280 #define USB_MAX_DEVNAMES 4
281 #define USB_MAX_DEVNAMELEN 16
282 struct usb_device_info {
283         u_int8_t        udi_bus;
284         u_int8_t        udi_addr;       /* device address */
285         usb_event_cookie_t udi_cookie;
286         char            udi_product[USB_MAX_STRING_LEN];
287         char            udi_vendor[USB_MAX_STRING_LEN];
288         char            udi_release[8];
289         u_int16_t       udi_productNo;
290         u_int16_t       udi_vendorNo;
291         u_int16_t       udi_releaseNo;
292         u_int8_t        udi_class;
293         u_int8_t        udi_subclass;
294         u_int8_t        udi_protocol;
295         u_int8_t        udi_config;
296         u_int8_t        udi_speed;
297 #define USB_SPEED_LOW  1
298 #define USB_SPEED_FULL 2
299 #define USB_SPEED_HIGH 3
300         int             udi_power;      /* power consumption in mA, 0 if selfpowered */
301         int             udi_nports;
302         char            udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
303         u_int8_t        udi_ports[16];/* hub only: addresses of devices on ports */
304 #define USB_PORT_ENABLED 0xff
305 #define USB_PORT_SUSPENDED 0xfe
306 #define USB_PORT_POWERED 0xfd
307 #define USB_PORT_DISABLED 0xfc
308 };
309 .Ed
310 .Pp
311 .Va udi_bus
312 and
313 .Va udi_addr
314 contain the topological information for the device.
315 .Va udi_devnames
316 contains the device names of the connected drivers.
317 For example, the
318 third
319 .Tn USB
320 Zip drive connected will be
321 .Li umass2 .
322 The
323 .Va udi_product , udi_vendor
324 and
325 .Va udi_release
326 fields contain self-explanatory descriptions of the device.
327 .Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass
328 and
329 .Va udi_protocol
330 contain the corresponding values from the device descriptors.
331 The
332 .Va udi_config
333 field shows the current configuration of the device.
334 .Pp
335 .Va udi_speed
336 indicates whether the device is at low speed
337 .Pq Dv USB_SPEED_LOW ,
338 full speed
339 .Pq Dv USB_SPEED_FULL
340 or high speed
341 .Pq Dv USB_SPEED_HIGH .
342 The
343 .Va udi_power
344 field shows the power consumption in milli-amps drawn at 5 volts,
345 or zero if the device is self powered.
346 .Pp
347 If the device is a hub, the
348 .Va udi_nports
349 field is non-zero, and the
350 .Va udi_ports
351 field contains the addresses of the connected devices.
352 If no device is connected to a port, one of the
353 .Dv USB_PORT_*
354 values indicates its status.
355 .It Dv USB_DEVICESTATS Vt "struct usb_device_stats"
356 This command retrieves statistics about the controller.
357 .Bd -literal
358 struct usb_device_stats {
359         u_long  uds_requests[4];
360 };
361 .Ed
362 .Pp
363 The
364 .Va uds_requests
365 field is indexed by the transfer kind, i.e.\&
366 .Dv UE_* ,
367 and indicates how many transfers of each kind that has been completed
368 by the controller.
369 .It Dv USB_REQUEST Vt "struct usb_ctl_request"
370 This command can be used to execute arbitrary requests on the control pipe.
371 This is
372 .Em DANGEROUS
373 and should be used with great care since it
374 can destroy the bus integrity.
375 .El
376 .Pp
377 The include file
378 .In bus/usb/usb.h
379 contains definitions for the types used by the various
380 .Xr ioctl 2
381 calls.
382 The naming convention of the fields for the various
383 .Tn USB
384 descriptors exactly follows the naming in the
385 .Tn USB
386 specification.
387 Byte sized fields can be accessed directly, but word (16 bit)
388 sized fields must be access by the
389 .Fn UGETW field
390 and
391 .Fn USETW field value
392 macros to handle byte order and alignment properly.
393 .Pp
394 The include file
395 .In bus/usb/usbhid.h
396 similarly contains the definitions for
397 Human Interface Devices
398 .Pq Tn HID .
399 .Sh USB EVENT INTERFACE
400 All
401 .Tn USB
402 events are reported via the
403 .Pa /dev/usb
404 device.
405 This devices can be opened for reading and each
406 .Xr read 2
407 will yield an event record (if something has happened).
408 The
409 .Xr poll 2
410 system call can be used to determine if an event record is available
411 for reading.
412 .Pp
413 The event record has the following definition:
414 .Bd -literal
415 struct usb_event {
416         int                                 ue_type;
417 #define USB_EVENT_CTRLR_ATTACH 1
418 #define USB_EVENT_CTRLR_DETACH 2
419 #define USB_EVENT_DEVICE_ATTACH 3
420 #define USB_EVENT_DEVICE_DETACH 4
421 #define USB_EVENT_DRIVER_ATTACH 5
422 #define USB_EVENT_DRIVER_DETACH 6
423         struct timespec                     ue_time;
424         union {
425                 struct {
426                         int                 ue_bus;
427                 } ue_ctrlr;
428                 struct usb_device_info      ue_device;
429                 struct {
430                         usb_event_cookie_t  ue_cookie;
431                         char                ue_devname[16];
432                 } ue_driver;
433         } u;
434 };
435 .Ed
436 The
437 .Va ue_type
438 field identifies the type of event that is described.
439 The possible events are attach/detach of a host controller,
440 a device, or a device driver.
441 The union contains information
442 pertinent to the different types of events.
443 Macros,
444 .Fn USB_EVENT_IS_ATTACH "ue_type"
445 and
446 .Fn USB_EVENT_IS_DETACH "ue_type"
447 can be used to determine if an event was an
448 .Dq attach
449 or a
450 .Dq detach
451 request.
452 .Pp
453 The
454 .Va ue_bus
455 contains the number of the
456 .Tn USB
457 bus for host controller events.
458 .Pp
459 The
460 .Va ue_device
461 record contains information about the device in a device event.
462 .Pp
463 The
464 .Va ue_cookie
465 is an opaque value that uniquely determines which
466 device a device driver has been attached to (i.e., it equals
467 the cookie value in the device that the driver attached to).
468 .Pp
469 The
470 .Va ue_devname
471 contains the name of the device (driver) as seen in, e.g.,
472 kernel messages.
473 .Pp
474 Note that there is a separation between device and device
475 driver events.
476 A device event is generated when a physical
477 .Tn USB
478 device is attached or detached.
479 A single
480 .Tn USB
481 device may
482 have zero, one, or many device drivers associated with it.
483 .Sh SEE ALSO
484 The
485 .Tn USB
486 specifications can be found at:
487 .Pp
488 .D1 Pa http://www.usb.org/developers/docs/
489 .Pp
490 .Xr ehci 4 ,
491 .Xr ohci 4 ,
492 .Xr pci 4 ,
493 .Xr uhci 4 ,
494 .Xr usbd 8 ,
495 .Xr usbdevs 8
496 .Sh HISTORY
497 The
498 .Nm
499 driver first appeared in
500 .Fx 3.0 .
501 .Sh AUTHORS
502 The
503 .Nm
504 driver was written by
505 .An Lennart Augustsson Aq Mt augustss@carlstedt.se
506 for the
507 .Nx
508 project.