xref: /freebsd/share/man/man4/usb.4 (revision b2c1f437de7aef486a782f998757a9c3886f700f)
1b2c1f437SNick Hibma.\" Copyright (c) 1997, 1998
2b2c1f437SNick Hibma.\"	Nick Hibma <hibma@skylink.it>. All rights reserved.
3b2c1f437SNick Hibma.\"
4b2c1f437SNick Hibma.\" Redistribution and use in source and binary forms, with or without
5b2c1f437SNick Hibma.\" modification, are permitted provided that the following conditions
6b2c1f437SNick Hibma.\" are met:
7b2c1f437SNick Hibma.\" 1. Redistributions of source code must retain the above copyright
8b2c1f437SNick Hibma.\"    notice, this list of conditions and the following disclaimer.
9b2c1f437SNick Hibma.\" 2. Redistributions in binary form must reproduce the above copyright
10b2c1f437SNick Hibma.\"    notice, this list of conditions and the following disclaimer in the
11b2c1f437SNick Hibma.\"    documentation and/or other materials provided with the distribution.
12b2c1f437SNick Hibma.\" 3. All advertising materials mentioning features or use of this software
13b2c1f437SNick Hibma.\"    must display the following acknowledgement:
14b2c1f437SNick Hibma.\"	This product includes software developed by Bill Paul.
15b2c1f437SNick Hibma.\" 4. Neither the name of the author nor the names of any co-contributors
16b2c1f437SNick Hibma.\"    may be used to endorse or promote products derived from this software
17b2c1f437SNick Hibma.\"   without specific prior written permission.
18b2c1f437SNick Hibma.\"
19b2c1f437SNick Hibma.\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND
20b2c1f437SNick Hibma.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21b2c1f437SNick Hibma.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22b2c1f437SNick Hibma.\" ARE DISCLAIMED.  IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD
23b2c1f437SNick Hibma.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24b2c1f437SNick Hibma.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25b2c1f437SNick Hibma.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26b2c1f437SNick Hibma.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27b2c1f437SNick Hibma.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28b2c1f437SNick Hibma.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
29b2c1f437SNick Hibma.\" THE POSSIBILITY OF SUCH DAMAGE.
30b2c1f437SNick Hibma.\"
31b2c1f437SNick Hibma.\"	$Id: xl.4,v 1.3 1998/12/05 09:36:15 rnordier Exp $
32b2c1f437SNick Hibma.\"
33b2c1f437SNick Hibma.Dd February 21, 1999
34b2c1f437SNick Hibma.Dt USB 4 i386
35b2c1f437SNick Hibma.Os FreeBSD
36b2c1f437SNick Hibma.Sh NAME
37b2c1f437SNick Hibma.Nm usb
38b2c1f437SNick Hibma.Nd Universal Serial Bus
39b2c1f437SNick Hibma.Sh SYNOPSIS
40b2c1f437SNick Hibma.Cd "controller usb0"
41b2c1f437SNick Hibma.Sh DESCRIPTION
42b2c1f437SNick Hibma.Nx
43b2c1f437SNick Hibmaprovides machine-independent bus support and drivers for
44b2c1f437SNick Hibma.Tn USB
45b2c1f437SNick Hibmadevices.
46b2c1f437SNick Hibma.Pp
47b2c1f437SNick HibmaThe
48b2c1f437SNick Hibma.Nm
49b2c1f437SNick Hibmadriver has three layers: the controller, the bus, and the
50b2c1f437SNick Hibmadevice layer. The controller attaches to a physical bus
51b2c1f437SNick Hibma(like
52b2c1f437SNick Hibma.Xr pci 4 ).
53b2c1f437SNick HibmaThe
54b2c1f437SNick Hibma.Tn USB
55b2c1f437SNick Hibmabus attaches to the controller and the root hub attaches
56b2c1f437SNick Hibmato the controller.
57b2c1f437SNick HibmaAny devices attached to the bus will attach to the root hub
58b2c1f437SNick Hibmaor another hub attached to the USB bus.
59b2c1f437SNick Hibma.Pp
60b2c1f437SNick HibmaThe
61b2c1f437SNick Hibma.Nm uhub
62b2c1f437SNick Hibmadevice will always be present as it is needed for the
63b2c1f437SNick Hibmaroot hub.
64b2c1f437SNick Hibma.Pp
65b2c1f437SNick Hibma.Sh INTRODUCTION TO USB
66b2c1f437SNick HibmaThe
67b2c1f437SNick Hibma.Tn USB
68b2c1f437SNick Hibmais a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
69b2c1f437SNick HibmaEach
70b2c1f437SNick Hibma.Tn USB
71b2c1f437SNick Hibmahas a host controller that is the master of the bus;
72b2c1f437SNick Hibmaall other devices on the bus only speak when spoken to.
73b2c1f437SNick Hibma.Pp
74b2c1f437SNick HibmaThere can be up to 127 devices (apart from the host controller)
75b2c1f437SNick Hibmaon a bus, each with its own address.
76b2c1f437SNick HibmaThe addresses are assigned
77b2c1f437SNick Hibmadynamically by the host when each device is attached to the bus.
78b2c1f437SNick Hibma.Pp
79b2c1f437SNick HibmaWithin each device there can be up to 16 endpoints.
80b2c1f437SNick HibmaEach endpoint
81b2c1f437SNick Hibmais individually addressed and the addresses are static.
82b2c1f437SNick HibmaEach of these endpoints will communicate in one of four different modes:
83b2c1f437SNick Hibmacontrol, isochronous, bulk, or interrupt.
84b2c1f437SNick HibmaA device always has at least one endpoint.
85b2c1f437SNick HibmaThis endpoint has address 0 and is a control
86b2c1f437SNick Hibmaendpoint and is used to give commands to and extract basic data,
87b2c1f437SNick Hibmasuch as descriptors, from the device.
88b2c1f437SNick HibmaEach endpoint, except the control endpoint, is unidirectional.
89b2c1f437SNick Hibma.Pp
90b2c1f437SNick HibmaThe endpoints in a device are grouped into interfaces.
91b2c1f437SNick HibmaAn interface is a logical unit within a device; e.g.
92b2c1f437SNick Hibmaa compound device with both a keyboard and a trackball would present
93b2c1f437SNick Hibmaone interface for each.
94b2c1f437SNick HibmaAn interface can sometimes be set into different modes,
95b2c1f437SNick Hibmacalled alternate settings, which affects how it operates.
96b2c1f437SNick HibmaDifferent alternate settings can have different endpoints
97b2c1f437SNick Hibmawithin it.
98b2c1f437SNick Hibma.Pp
99b2c1f437SNick HibmaA device may operate in different configurations.
100b2c1f437SNick HibmaDepending on the
101b2c1f437SNick Hibmaconfiguration the device may present different sets of endpoints
102b2c1f437SNick Hibmaand interfaces.
103b2c1f437SNick Hibma.Pp
104b2c1f437SNick HibmaEach device located on a hub has several
105b2c1f437SNick Hibma.Xr config 8
106b2c1f437SNick Hibmalocators:
107b2c1f437SNick Hibma.Bl -tag -compact -width xxxxxx
108b2c1f437SNick Hibma.It Cd port
109b2c1f437SNick Hibmathis is the number of the port on the closest upstream hub.
110b2c1f437SNick Hibma.It Cd configuration
111b2c1f437SNick Hibmathis is the configuration the device must be in for this driver to attach.
112b2c1f437SNick HibmaThis locator does not set the configuration; it is iterated by the bus
113b2c1f437SNick Hibmaenumeration.
114b2c1f437SNick Hibma.It Cd interface
115b2c1f437SNick Hibmathis is the interface number within a device that an interface driver
116b2c1f437SNick Hibmaattaches to.
117b2c1f437SNick Hibma.El
118b2c1f437SNick Hibma.Pp
119b2c1f437SNick HibmaThe bus enumeration of the
120b2c1f437SNick Hibma.Tn USB
121b2c1f437SNick Hibmabus proceeds in several steps:
122b2c1f437SNick Hibma.Bl -enum
123b2c1f437SNick Hibma.It
124b2c1f437SNick HibmaAny device specific driver can to attach to the device.
125b2c1f437SNick Hibma.It
126b2c1f437SNick HibmaIf none is found, any device class specific driver can attach.
127b2c1f437SNick Hibma.It
128b2c1f437SNick HibmaIf none is found, all configurations are iterated over.
129b2c1f437SNick HibmaFor each configuration all the interface are iterated over and interface
130b2c1f437SNick Hibmadrivers can attach.
131b2c1f437SNick HibmaIf any interface driver attached in a certain
132b2c1f437SNick Hibmaconfiguration the iteration over configurations is stopped.
133b2c1f437SNick Hibma.It
134b2c1f437SNick HibmaIf still no drivers have been found, the generic
135b2c1f437SNick Hibma.Tn USB
136b2c1f437SNick Hibmadriver can attach.
137b2c1f437SNick Hibma.El
138b2c1f437SNick Hibma.Sh USB CONTROLLER INTERFACE
139b2c1f437SNick HibmaUse the following to get access to the
140b2c1f437SNick Hibma.Tn USB
141b2c1f437SNick Hibmaspecific structurs and defines.
142b2c1f437SNick Hibma.Bd -literal
143b2c1f437SNick Hibma#include <sys/dev/usb.h>
144b2c1f437SNick Hibma.Ed
145b2c1f437SNick Hibma.Pp
146b2c1f437SNick HibmaThe
147b2c1f437SNick Hibma.Pa /dev/usbN
148b2c1f437SNick Hibmacan be opened and a few operations can be performed on it.
149b2c1f437SNick HibmaThe
150b2c1f437SNick Hibma.Xr poll 2
151b2c1f437SNick Hibmasystem call will say that I/O is possible on the controller device when a
152b2c1f437SNick Hibma.Tn USB
153b2c1f437SNick Hibmadevice has been connected or disconnected to the bus.
154b2c1f437SNick Hibma.Pp
155b2c1f437SNick HibmaThe following
156b2c1f437SNick Hibma.Xr ioctl 2
157b2c1f437SNick Hibmacommands are supported on the controller device:
158b2c1f437SNick Hibma.Bl -tag -width xxxxxx
159b2c1f437SNick Hibma.It Dv USB_DISCOVER
160b2c1f437SNick HibmaThis command will cause a complete bus discovery to be initiated.
161b2c1f437SNick HibmaIf any devices attached or detached from the bus they will be
162b2c1f437SNick Hibmaprocessed during this command.
163b2c1f437SNick HibmaThis is the only way that new devices are found on the bus.
164b2c1f437SNick Hibma.It Dv USB_DEVICEINFO Fa "struct usb_device_info"
165b2c1f437SNick HibmaThis command can be used to retrieve some information about a device
166b2c1f437SNick Hibmaon the bus.
167b2c1f437SNick HibmaThe
168b2c1f437SNick Hibma.Va addr
169b2c1f437SNick Hibmafield should be filled before the call and the other fields will
170b2c1f437SNick Hibmabe filled by information about the device on that address.
171b2c1f437SNick HibmaShould no such device exist an error is reported.
172b2c1f437SNick Hibma.Bd -literal
173b2c1f437SNick Hibmastruct usb_device_info {
174b2c1f437SNick Hibma        uByte   addr;           /* device address */
175b2c1f437SNick Hibma        char    product[USB_MAX_STRING_LEN];
176b2c1f437SNick Hibma        char    vendor[USB_MAX_STRING_LEN];
177b2c1f437SNick Hibma        char    revision[8];
178b2c1f437SNick Hibma        uByte   class;
179b2c1f437SNick Hibma        uByte   config;
180b2c1f437SNick Hibma        uByte   lowspeed;
181b2c1f437SNick Hibma        int     power;
182b2c1f437SNick Hibma        int     nports;
183b2c1f437SNick Hibma        uByte   ports[16];
184b2c1f437SNick Hibma#define USB_PORT_ENABLED 0xff
185b2c1f437SNick Hibma#define USB_PORT_SUSPENDED 0xfe
186b2c1f437SNick Hibma#define USB_PORT_POWERED 0xfd
187b2c1f437SNick Hibma#define USB_PORT_DISABLED 0xfc
188b2c1f437SNick Hibma};
189b2c1f437SNick Hibma.Ed
190b2c1f437SNick Hibma.Pp
191b2c1f437SNick HibmaThe
192b2c1f437SNick Hibma.Va product ,
193b2c1f437SNick Hibma.Va vendor ,
194b2c1f437SNick Hibmaand
195b2c1f437SNick Hibma.Va revision
196b2c1f437SNick Hibmafields contain self-explanatory descriptions of the device.
197b2c1f437SNick Hibma.Pp
198b2c1f437SNick HibmaThe
199b2c1f437SNick Hibma.Va class
200b2c1f437SNick Hibmafield contains the device class.
201b2c1f437SNick Hibma.Pp
202b2c1f437SNick HibmaThe
203b2c1f437SNick Hibma.Va config
204b2c1f437SNick Hibmafield shows the current configuration of the device.
205b2c1f437SNick Hibma.Pp
206b2c1f437SNick HibmaThe
207b2c1f437SNick Hibma.Va lowspeed
208b2c1f437SNick Hibmafield
209b2c1f437SNick Hibmais set if the device is a
210b2c1f437SNick Hibma.Tn USB
211b2c1f437SNick Hibmalow speed device.
212b2c1f437SNick Hibma.Pp
213b2c1f437SNick HibmaThe
214b2c1f437SNick Hibma.Va power
215b2c1f437SNick Hibmafield shows the power consumption in milli-amps drawn at 5 volts,
216b2c1f437SNick Hibmaor zero if the device is self powered.
217b2c1f437SNick Hibma.Pp
218b2c1f437SNick HibmaIf the device is a hub the
219b2c1f437SNick Hibma.Va nports
220b2c1f437SNick Hibmafield is non-zero and the
221b2c1f437SNick Hibma.Va ports
222b2c1f437SNick Hibmafield contains the addresses of the connected devices.
223b2c1f437SNick HibmaIf no device is connected to a port one of the
224b2c1f437SNick Hibma.Va USB_PORT_*
225b2c1f437SNick Hibmavalues indicates its status.
226b2c1f437SNick Hibma.It Dv USB_DEVICESTATS Fa "struct usb_device_stats"
227b2c1f437SNick HibmaThis command retrieves statistics about the controller.
228b2c1f437SNick Hibma.Bd -literal
229b2c1f437SNick Hibmastruct usb_device_stats {
230b2c1f437SNick Hibma        u_long  requests[4];
231b2c1f437SNick Hibma};
232b2c1f437SNick Hibma.Ed
233b2c1f437SNick Hibma.Pp
234b2c1f437SNick HibmaThe
235b2c1f437SNick Hibma.Va requests
236b2c1f437SNick Hibmafield is indexed by the transfer kind, i.e.
237b2c1f437SNick Hibma.Va UE_* ,
238b2c1f437SNick Hibmaand indicates how many transfers of each kind that has been completed
239b2c1f437SNick Hibmaby the controller.
240b2c1f437SNick Hibma.It Dv USB_REQUEST Fa "struct usb_ctl_request"
241b2c1f437SNick HibmaThis command can be used to execute arbitrary requests on the control pipe.
242b2c1f437SNick HibmaThis is
243b2c1f437SNick Hibma.Em DANGEROUS
244b2c1f437SNick Hibmaand should be used with great care since it
245b2c1f437SNick Hibmacan destroy the bus integrity.
246b2c1f437SNick Hibma.El
247b2c1f437SNick Hibma.Pp
248b2c1f437SNick HibmaThe include file
249b2c1f437SNick Hibma.Aq Pa dev/usb/usb.h
250b2c1f437SNick Hibmacontains definitions for the types used by the various
251b2c1f437SNick Hibma.Xr ioctl 2
252b2c1f437SNick Hibmacalls.
253b2c1f437SNick HibmaThe naming convention of the fields for the various
254b2c1f437SNick Hibma.Tn USB
255b2c1f437SNick Hibmadescriptors exactly follows the naming in the
256b2c1f437SNick Hibma.Tn USB
257b2c1f437SNick Hibmaspecification.
258b2c1f437SNick HibmaByte sized fields can be accessed directly, but word (16 bit)
259b2c1f437SNick Hibmasized fields must be access by the
260b2c1f437SNick Hibma.Fn UGETW field
261b2c1f437SNick Hibmaand
262b2c1f437SNick Hibma.Fn USETW field value
263b2c1f437SNick Hibmamacros to handle byte order and alignment properly.
264b2c1f437SNick Hibma.Pp
265b2c1f437SNick HibmaThe include file
266b2c1f437SNick Hibma.Aq Pa dev/usb/usbhid.h
267b2c1f437SNick Hibmasimilarly contains the definitions for
268b2c1f437SNick HibmaHuman Interface Devices
269b2c1f437SNick Hibma.Pq Tn HID .
270b2c1f437SNick Hibma.Sh SEE ALSO
271b2c1f437SNick HibmaThe
272b2c1f437SNick Hibma.Tn USB
273b2c1f437SNick Hibmaspecifications can be found at
274b2c1f437SNick Hibma.Dv http://www.usb.org/developers/docs.htm .
275b2c1f437SNick Hibma.Pp
276b2c1f437SNick Hibma.Xr pci 4 ,
277b2c1f437SNick Hibma.Xr ohci 4 ,
278b2c1f437SNick Hibma.Xr uhci 4 ,
279b2c1f437SNick Hibma.Xr ugen 4 ,
280b2c1f437SNick Hibma.Xr uhid 4 ,
281b2c1f437SNick Hibma.Xr ukbd 4 ,
282b2c1f437SNick Hibma.Xr ulpt 4 ,
283b2c1f437SNick Hibma.Xr ums 4 ,
284b2c1f437SNick Hibma.Xr usbd 8 ,
285b2c1f437SNick Hibma.Xr usbdevs 8
286b2c1f437SNick Hibma.Sh HISTORY
287b2c1f437SNick HibmaThe
288b2c1f437SNick Hibma.Nm
289b2c1f437SNick Hibmadriver first appeared in
290b2c1f437SNick Hibma.Fx 3.0 .
291b2c1f437SNick Hibma.Sh AUTHOR
292b2c1f437SNick HibmaThe
293b2c1f437SNick Hibma.Nm
294b2c1f437SNick Hibmadriver was written by
295b2c1f437SNick Hibma.An Lennart Augustsson (augustss@carlstedt.se) for the
296b2c1f437SNick Hibma.Nx
297b2c1f437SNick Hibmaproject.
298