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.
35 .Nd Universal Serial Bus
37 To compile this driver into the kernel,
38 place the following line in your
39 kernel configuration file:
40 .Bd -ragged -offset indent
44 Alternatively, to load the driver as a
45 module at boot time, place the following line in
47 .Bd -literal -offset indent
55 provides machine-independent bus support and drivers for
61 driver has three layers: the controller, the bus, and the
63 The controller attaches to a physical bus
68 bus attaches to the controller, and the root hub attaches
70 Any devices attached to the bus will attach to the root hub
71 or another hub attached to the
77 device will always be present as it is needed for the
79 .Sh INTRODUCTION TO USB
82 is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
85 has a host controller that is the master of the bus;
86 all other devices on the bus only speak when spoken to.
88 There can be up to 127 devices (apart from the host controller)
89 on a bus, each with its own address.
90 The addresses are assigned
91 dynamically by the host when each device is attached to the bus.
93 Within each device there can be up to 16 endpoints.
95 is individually addressed and the addresses are static.
96 Each of these endpoints will communicate in one of four different modes:
97 .Em control , isochronous , bulk ,
100 A device always has at least one endpoint.
101 This endpoint has address 0 and is a control
102 endpoint and is used to give commands to and extract basic data,
103 such as descriptors, from the device.
104 Each endpoint, except the control endpoint, is unidirectional.
106 The endpoints in a device are grouped into interfaces.
107 An interface is a logical unit within a device; e.g.\&
108 a compound device with both a keyboard and a trackball would present
109 one interface for each.
110 An interface can sometimes be set into different modes,
111 called alternate settings, which affects how it operates.
112 Different alternate settings can have different endpoints
115 A device may operate in different configurations.
117 configuration, the device may present different sets of endpoints
120 .\" Each device located on a hub has several
123 .\" .Bl -tag -compact -width xxxxxx
125 .\" this is the number of the port on the closest upstream hub.
126 .\" .It Cd configuration
127 .\" this is the configuration the device must be in for this driver to attach.
128 .\" This locator does not set the configuration; it is iterated by the bus
131 .\" this is the interface number within a device that an interface driver
134 .\" this is the 16 bit vendor id of the device.
136 .\" this is the 16 bit product id of the device.
138 .\" this is the 16 bit release (revision) number of the device.
140 .\" The first locator can be used to pin down a particular device
141 .\" according to its physical position in the device tree.
142 .\" The last three locators can be used to pin down a particular
143 .\" device according to what device it actually is.
145 The bus enumeration of the
147 bus proceeds in several steps:
150 Any device specific driver can attach to the device.
152 If none is found, any device class specific driver can attach.
154 If none is found, all configurations are iterated over.
155 For each configuration, all the interfaces are iterated over, and interface
157 If any interface driver attached in a certain
158 configuration, the iteration over configurations is stopped.
160 If still no drivers have been found, the generic
164 .Sh USB CONTROLLER INTERFACE
165 Use the following to get access to the
167 specific structures and defines.
171 can be opened and a few operations can be performed on it.
174 system call will say that I/O is possible on the controller device when a
176 device has been connected or disconnected to the bus.
180 commands are supported on the controller device:
181 .Bl -tag -width xxxxxx
183 This command will cause a complete bus discovery to be initiated.
184 If any devices attached or detached from the bus they will be
185 processed during this command.
186 This is the only way that new devices are found on the bus.
187 .It Dv USB_DEVICEINFO Vt "struct usb_device_info"
188 This command can be used to retrieve some information about a device
192 field should be filled before the call and the other fields will
193 be filled by information about the device on that address.
194 Should no such device exist, an error is reported.
196 #define USB_MAX_DEVNAMES 4
197 #define USB_MAX_DEVNAMELEN 16
198 struct usb_device_info {
200 u_int8_t udi_addr; /* device address */
201 usb_event_cookie_t udi_cookie;
202 char udi_product[USB_MAX_STRING_LEN];
203 char udi_vendor[USB_MAX_STRING_LEN];
205 u_int16_t udi_productNo;
206 u_int16_t udi_vendorNo;
207 u_int16_t udi_releaseNo;
209 u_int8_t udi_subclass;
210 u_int8_t udi_protocol;
213 #define USB_SPEED_LOW 1
214 #define USB_SPEED_FULL 2
215 #define USB_SPEED_HIGH 3
216 int udi_power;/* power consumption in mA, 0 if selfpowered */
218 char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
219 u_int8_t udi_ports[16];/* hub only: addresses of devices on ports */
220 #define USB_PORT_ENABLED 0xff
221 #define USB_PORT_SUSPENDED 0xfe
222 #define USB_PORT_POWERED 0xfd
223 #define USB_PORT_DISABLED 0xfc
230 contain the topological information for the device.
232 contains the device names of the connected drivers.
236 Zip drive connected will be
239 .Va udi_product , udi_vendor
242 fields contain self-explanatory descriptions of the device.
243 .Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass
246 contain the corresponding values from the device descriptors.
249 field shows the current configuration of the device.
252 indicates whether the device is at low speed
253 .Pq Dv USB_SPEED_LOW ,
255 .Pq Dv USB_SPEED_FULL
257 .Pq Dv USB_SPEED_HIGH .
260 field shows the power consumption in milli-amps drawn at 5 volts,
261 or zero if the device is self powered.
263 If the device is a hub, the
265 field is non-zero, and the
267 field contains the addresses of the connected devices.
268 If no device is connected to a port, one of the
270 values indicates its status.
271 .It Dv USB_DEVICESTATS Vt "struct usb_device_stats"
272 This command retrieves statistics about the controller.
274 struct usb_device_stats {
275 u_long uds_requests[4];
281 field is indexed by the transfer kind, i.e.\&
283 and indicates how many transfers of each kind that has been completed
285 .It Dv USB_REQUEST Vt "struct usb_ctl_request"
286 This command can be used to execute arbitrary requests on the control pipe.
289 and should be used with great care since it
290 can destroy the bus integrity.
295 contains definitions for the types used by the various
298 The naming convention of the fields for the various
300 descriptors exactly follows the naming in the
303 Byte sized fields can be accessed directly, but word (16 bit)
304 sized fields must be access by the
307 .Fn USETW field value
308 macros to handle byte order and alignment properly.
312 similarly contains the definitions for
313 Human Interface Devices
315 .Sh USB EVENT INTERFACE
318 events are reported via the
321 This device can be opened for reading and each
323 will yield an event record (if something has happened).
326 system call can be used to determine if an event record is available
329 The event record has the following definition:
333 #define USB_EVENT_CTRLR_ATTACH 1
334 #define USB_EVENT_CTRLR_DETACH 2
335 #define USB_EVENT_DEVICE_ATTACH 3
336 #define USB_EVENT_DEVICE_DETACH 4
337 #define USB_EVENT_DRIVER_ATTACH 5
338 #define USB_EVENT_DRIVER_DETACH 6
339 struct timespec ue_time;
344 struct usb_device_info ue_device;
346 usb_event_cookie_t ue_cookie;
354 field identifies the type of event that is described.
355 The possible events are attach/detach of a host controller,
356 a device, or a device driver.
357 The union contains information
358 pertinent to the different types of events.
360 .Fn USB_EVENT_IS_ATTACH "ue_type"
362 .Fn USB_EVENT_IS_DETACH "ue_type"
363 can be used to determine if an event was an
371 contains the number of the
373 bus for host controller events.
377 record contains information about the device in a device event event.
381 is an opaque value that uniquely determines which
382 device a device driver has been attached to (i.e., it equals
383 the cookie value in the device that the driver attached to).
387 contains the name of the device (driver) as seen in, e.g.,
390 Note that there is a separation between device and device
392 A device event is generated when a physical
394 device is attached or detached.
398 have zero, one, or many device drivers associated with it.
402 specifications can be found at:
404 .D1 Pa http://www.usb.org/developers/docs/
431 driver first appeared in
436 driver was written by
437 .An Lennart Augustsson Aq augustss@carlstedt.se