1 .\" Copyright (c) 1997, 1998
2 .\" Nick Hibma <n_hibma@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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.
28 .\" $FreeBSD: src/share/man/man4/usb.4,v 1.32 2005/04/20 07:33:09 simon Exp $
35 .Nd Universal Serial Bus
43 provides machine-independent bus support and drivers for
49 driver has three layers: the controller, the bus, and the
51 The controller attaches to a physical bus
56 bus attaches to the controller, and the root hub attaches
58 Any devices attached to the bus will attach to the root hub
59 or another hub attached to the
65 device will always be present as it is needed for the
68 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
72 Mass Storage Devices, e.g., external disk drives
74 .Ss Wired network interfaces
75 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
77 ADMtek AN986 Pegasus Ethernet driver
79 ASIX Electronics AX88172 Ethernet driver
81 CATC USB-EL1210A Ethernet driver
83 Kawasaki LSI KL5KUSB101B Ethernet driver
85 USB CDC (communication device class) driver for the LG P-500 smartphone
87 RealTek RTL8150 Ethernet driver
89 .Ss Wireless network interfaces
90 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
92 .\"Ralink Technology RT2501USB/RT2601USB IEEE 802.11 driver
96 .\"Ralink Technology RT2500USB IEEE 802.11 driver
98 .Ss Serial and parallel interfaces
99 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
101 MosChip Semiconductor MCS7703 based serial adapters
103 Arkmicro Technologies ARK3116 based serial adapters
105 Belkin serial adapters
107 WinChipHead CH341/CH340 serial adapters
111 serial devices based on the FTDI chips
113 generic serial device
117 Magic Control Technology USB-232 based serial adapters
119 Prolific PL-2303/2303X/2303HX serial adapters
121 Silicon Laboratories CP2101, CP2102 and CP2103 USB to serial bridge
123 Texas Instruments TUSB3410 RS232 to USB converter
125 support for the Handspring Visor, a Palmpilot compatible PDA
127 SUNTAC Slipper U VS-10U serial adapters
130 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
134 driver for the Rio500 MP3 player
136 .Ss Radio receiver devices
137 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
139 Cypress Semiconductor FM Radio
141 .Ss Human Interface Devices
142 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
144 generic driver for Human Interface Devices
146 base driver for all Human Interface Devices
148 keyboards that follow the boot protocol
152 .Ss Miscellaneous devices
153 .Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
155 generic device support
159 .Sh INTRODUCTION TO USB
162 is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
165 has a host controller that is the master of the bus;
166 all other devices on the bus only speak when spoken to.
168 There can be up to 127 devices (apart from the host controller)
169 on a bus, each with its own address.
170 The addresses are assigned
171 dynamically by the host when each device is attached to the bus.
173 Within each device there can be up to 16 endpoints.
175 is individually addressed and the addresses are static.
176 Each of these endpoints will communicate in one of four different modes:
177 .Em control , isochronous , bulk ,
180 A device always has at least one endpoint.
181 This endpoint has address 0 and is a control
182 endpoint and is used to give commands to and extract basic data,
183 such as descriptors, from the device.
184 Each endpoint, except the control endpoint, is unidirectional.
186 The endpoints in a device are grouped into interfaces.
187 An interface is a logical unit within a device; e.g.\&
188 a compound device with both a keyboard and a trackball would present
189 one interface for each.
190 An interface can sometimes be set into different modes,
191 called alternate settings, which affects how it operates.
192 Different alternate settings can have different endpoints
195 A device may operate in different configurations.
197 configuration, the device may present different sets of endpoints
200 .\"Each device located on a hub has several
203 .\".Bl -tag -compact -width xxxxxx
205 .\"this is the number of the port on the closest upstream hub.
206 .\".It Cd configuration
207 .\"this is the configuration the device must be in for this driver to attach.
208 .\"This locator does not set the configuration; it is iterated by the bus
211 .\"this is the interface number within a device that an interface driver
214 .\"this is the 16 bit vendor id of the device.
216 .\"this is the 16 bit product id of the device.
218 .\"this is the 16 bit release (revision) number of the device.
220 .\"The first locator can be used to pin down a particular device
221 .\"according to its physical position in the device tree.
222 .\"The last three locators can be used to pin down a particular
223 .\"device according to what device it actually is.
225 The bus enumeration of the
227 bus proceeds in several steps:
230 Any device specific driver can attach to the device.
232 If none is found, any device class specific driver can attach.
234 If none is found, all configurations are iterated over.
235 For each configuration, all the interfaces are iterated over, and interface
237 If any interface driver attached in a certain
238 configuration, the iteration over configurations is stopped.
240 If still no drivers have been found, the generic
244 .Sh USB CONTROLLER INTERFACE
245 Use the following to get access to the
247 specific structures and defines.
253 can be opened and a few operations can be performed on it.
256 system call will say that I/O is possible on the controller device when a
258 device has been connected or disconnected to the bus.
262 commands are supported on the controller device:
263 .Bl -tag -width xxxxxx
265 This command will cause a complete bus discovery to be initiated.
266 If any devices attached or detached from the bus they will be
267 processed during this command.
268 This is the only way that new devices are found on the bus.
269 .It Dv USB_DEVICEINFO Vt "struct usb_device_info"
270 This command can be used to retrieve some information about a device
274 field should be filled before the call and the other fields will
275 be filled by information about the device on that address.
276 Should no such device exist, an error is reported.
278 #define USB_MAX_DEVNAMES 4
279 #define USB_MAX_DEVNAMELEN 16
280 struct usb_device_info {
282 u_int8_t udi_addr; /* device address */
283 usb_event_cookie_t udi_cookie;
284 char udi_product[USB_MAX_STRING_LEN];
285 char udi_vendor[USB_MAX_STRING_LEN];
287 u_int16_t udi_productNo;
288 u_int16_t udi_vendorNo;
289 u_int16_t udi_releaseNo;
291 u_int8_t udi_subclass;
292 u_int8_t udi_protocol;
295 #define USB_SPEED_LOW 1
296 #define USB_SPEED_FULL 2
297 #define USB_SPEED_HIGH 3
298 int udi_power; /* power consumption in mA, 0 if selfpowered */
300 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
301 u_int8_t udi_ports[16];/* hub only: addresses of devices on ports */
302 #define USB_PORT_ENABLED 0xff
303 #define USB_PORT_SUSPENDED 0xfe
304 #define USB_PORT_POWERED 0xfd
305 #define USB_PORT_DISABLED 0xfc
312 contain the topological information for the device.
314 contains the device names of the connected drivers.
318 Zip drive connected will be
321 .Va udi_product , udi_vendor
324 fields contain self-explanatory descriptions of the device.
325 .Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass
328 contain the corresponding values from the device descriptors.
331 field shows the current configuration of the device.
334 indicates whether the device is at low speed
335 .Pq Dv USB_SPEED_LOW ,
337 .Pq Dv USB_SPEED_FULL
339 .Pq Dv USB_SPEED_HIGH .
342 field shows the power consumption in milli-amps drawn at 5 volts,
343 or zero if the device is self powered.
345 If the device is a hub, the
347 field is non-zero, and the
349 field contains the addresses of the connected devices.
350 If no device is connected to a port, one of the
352 values indicates its status.
353 .It Dv USB_DEVICESTATS Vt "struct usb_device_stats"
354 This command retrieves statistics about the controller.
356 struct usb_device_stats {
357 u_long uds_requests[4];
363 field is indexed by the transfer kind, i.e.\&
365 and indicates how many transfers of each kind that has been completed
367 .It Dv USB_REQUEST Vt "struct usb_ctl_request"
368 This command can be used to execute arbitrary requests on the control pipe.
371 and should be used with great care since it
372 can destroy the bus integrity.
377 contains definitions for the types used by the various
380 The naming convention of the fields for the various
382 descriptors exactly follows the naming in the
385 Byte sized fields can be accessed directly, but word (16 bit)
386 sized fields must be access by the
389 .Fn USETW field value
390 macros to handle byte order and alignment properly.
394 similarly contains the definitions for
395 Human Interface Devices
397 .Sh USB EVENT INTERFACE
400 events are reported via the
403 This devices can be opened for reading and each
405 will yield an event record (if something has happened).
408 system call can be used to determine if an event record is available
411 The event record has the following definition:
415 #define USB_EVENT_CTRLR_ATTACH 1
416 #define USB_EVENT_CTRLR_DETACH 2
417 #define USB_EVENT_DEVICE_ATTACH 3
418 #define USB_EVENT_DEVICE_DETACH 4
419 #define USB_EVENT_DRIVER_ATTACH 5
420 #define USB_EVENT_DRIVER_DETACH 6
421 struct timespec ue_time;
426 struct usb_device_info ue_device;
428 usb_event_cookie_t ue_cookie;
436 field identifies the type of event that is described.
437 The possible events are attach/detach of a host controller,
438 a device, or a device driver.
439 The union contains information
440 pertinent to the different types of events.
442 .Fn USB_EVENT_IS_ATTACH "ue_type"
444 .Fn USB_EVENT_IS_DETACH "ue_type"
445 can be used to determine if an event was an
453 contains the number of the
455 bus for host controller events.
459 record contains information about the device in a device event event.
463 is an opaque value that uniquely determines which
464 device a device driver has been attached to (i.e., it equals
465 the cookie value in the device that the driver attached to).
469 contains the name of the device (driver) as seen in, e.g.,
472 Note that there is a separation between device and device
474 A device event is generated when a physical
476 device is attached or detached.
480 have zero, one, or many device drivers associated with it.
484 specifications can be found at:
486 .D1 Pa http://www.usb.org/developers/docs/
497 driver first appeared in
502 driver was written by
503 .An Lennart Augustsson Aq augustss@carlstedt.se