usb.4 (936663c887a0349c4ded41efcf4799ad2fee76dd) usb.4 (b2c1f437de7aef486a782f998757a9c3886f700f)
1.\" Copyright (c) 1997, 1998 Nick Hibma <n_hibma@FreeBSD.org>
2.\" Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
1.\" Copyright (c) 1997, 1998
2.\" Nick Hibma <hibma@skylink.it>. 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.
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. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by Bill Paul.
15.\" 4. Neither the name of the author nor the names of any co-contributors
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
12.\"
18.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19.\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
22.\" ARE DISCLAIMED. IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD
23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
29.\" THE POSSIBILITY OF SUCH DAMAGE.
24.\"
30.\"
25.\" $FreeBSD$
31.\" $Id: xl.4,v 1.3 1998/12/05 09:36:15 rnordier Exp $
26.\"
32.\"
27.Dd May 20, 2009
28.Dt USB 4
29.Os
33.Dd February 21, 1999
34.Dt USB 4 i386
35.Os FreeBSD
30.Sh NAME
31.Nm usb
32.Nd Universal Serial Bus
33.Sh SYNOPSIS
36.Sh NAME
37.Nm usb
38.Nd Universal Serial Bus
39.Sh SYNOPSIS
34To compile this driver into the kernel,
35place the following line in your
36kernel configuration file:
37.Bd -ragged -offset indent
38.Cd "device usb"
39.Ed
40.Pp
41Alternatively, to load the driver as a
42module at boot time, place the following line in
43.Xr loader.conf 5 :
44.Bd -literal -offset indent
45usb_load="YES"
46.Ed
47.Sh USERLAND PROGRAMMING
48USB functions can be accessed from userland through the libusb library.
49See
50.Xr libusb 3
51for more information.
40.Cd "controller usb0"
52.Sh DESCRIPTION
41.Sh DESCRIPTION
53.Fx
42.Nx
54provides machine-independent bus support and drivers for
55.Tn USB
43provides machine-independent bus support and drivers for
44.Tn USB
56devices in host and device side mode.
45devices.
57.Pp
58The
59.Nm
46.Pp
47The
48.Nm
60driver has three layers:
61.Bl -tag
62.It USB Controller (Bus)
63.It USB Device
64.It USB Driver
65.El
66.Pp
67The controller attaches to a physical bus
68like
69.Xr pci 4 .
49driver has three layers: the controller, the bus, and the
50device layer. The controller attaches to a physical bus
51(like
52.Xr pci 4 ).
70The
71.Tn USB
53The
54.Tn USB
72bus attaches to the controller, and the root hub attaches
55bus attaches to the controller and the root hub attaches
73to the controller.
74Any devices attached to the bus will attach to the root hub
56to the controller.
57Any devices attached to the bus will attach to the root hub
75or another hub attached to the
76.Tn USB
77bus.
58or another hub attached to the USB bus.
78.Pp
79The
80.Nm uhub
81device will always be present as it is needed for the
82root hub.
59.Pp
60The
61.Nm uhub
62device will always be present as it is needed for the
63root hub.
64.Pp
83.Sh INTRODUCTION TO USB
84The
85.Tn USB
65.Sh INTRODUCTION TO USB
66The
67.Tn USB
86is a system where external devices can be connected to a PC.
87The most common USB speeds are:
88.Bl -tag
89.It Low Speed (1.5MBit/sec)
90.It Full Speed (12MBit/sec)
91.It High Speed (480MBit/sec)
92.El
93.Pp
68is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices).
94Each
95.Tn USB
69Each
70.Tn USB
96has a USB controller that is the master of the bus.
97The physical communication is simplex which means the host controller only communicates with one USB device at a time.
71has a host controller that is the master of the bus;
72all other devices on the bus only speak when spoken to.
98.Pp
73.Pp
99There can be up to 127 devices connected to an USB HUB tree.
74There can be up to 127 devices (apart from the host controller)
75on a bus, each with its own address.
100The addresses are assigned
101dynamically by the host when each device is attached to the bus.
102.Pp
103Within each device there can be up to 16 endpoints.
104Each endpoint
105is individually addressed and the addresses are static.
106Each of these endpoints will communicate in one of four different modes:
76The addresses are assigned
77dynamically by the host when each device is attached to the bus.
78.Pp
79Within each device there can be up to 16 endpoints.
80Each endpoint
81is individually addressed and the addresses are static.
82Each of these endpoints will communicate in one of four different modes:
107.Em control , isochronous , bulk ,
108or
109.Em interrupt .
83control, isochronous, bulk, or interrupt.
110A device always has at least one endpoint.
111This endpoint has address 0 and is a control
112endpoint and is used to give commands to and extract basic data,
113such as descriptors, from the device.
114Each endpoint, except the control endpoint, is unidirectional.
115.Pp
116The endpoints in a device are grouped into interfaces.
84A device always has at least one endpoint.
85This endpoint has address 0 and is a control
86endpoint and is used to give commands to and extract basic data,
87such as descriptors, from the device.
88Each endpoint, except the control endpoint, is unidirectional.
89.Pp
90The endpoints in a device are grouped into interfaces.
117An interface is a logical unit within a device; e.g.\&
91An interface is a logical unit within a device; e.g.
118a compound device with both a keyboard and a trackball would present
119one interface for each.
120An interface can sometimes be set into different modes,
121called alternate settings, which affects how it operates.
122Different alternate settings can have different endpoints
123within it.
124.Pp
125A device may operate in different configurations.
126Depending on the
92a compound device with both a keyboard and a trackball would present
93one interface for each.
94An interface can sometimes be set into different modes,
95called alternate settings, which affects how it operates.
96Different alternate settings can have different endpoints
97within it.
98.Pp
99A device may operate in different configurations.
100Depending on the
127configuration, the device may present different sets of endpoints
101configuration the device may present different sets of endpoints
128and interfaces.
129.Pp
102and interfaces.
103.Pp
104Each device located on a hub has several
105.Xr config 8
106locators:
107.Bl -tag -compact -width xxxxxx
108.It Cd port
109this is the number of the port on the closest upstream hub.
110.It Cd configuration
111this is the configuration the device must be in for this driver to attach.
112This locator does not set the configuration; it is iterated by the bus
113enumeration.
114.It Cd interface
115this is the interface number within a device that an interface driver
116attaches to.
117.El
118.Pp
130The bus enumeration of the
131.Tn USB
132bus proceeds in several steps:
133.Bl -enum
134.It
119The bus enumeration of the
120.Tn USB
121bus proceeds in several steps:
122.Bl -enum
123.It
135Any interface specific driver can attach to the device.
124Any device specific driver can to attach to the device.
136.It
125.It
137If none is found, generic interface class drivers can attach.
126If none is found, any device class specific driver can attach.
127.It
128If none is found, all configurations are iterated over.
129For each configuration all the interface are iterated over and interface
130drivers can attach.
131If any interface driver attached in a certain
132configuration the iteration over configurations is stopped.
133.It
134If still no drivers have been found, the generic
135.Tn USB
136driver can attach.
138.El
137.El
139.Sh SEE ALSO
138.Sh USB CONTROLLER INTERFACE
139Use the following to get access to the
140.Tn USB
141specific structurs and defines.
142.Bd -literal
143#include <sys/dev/usb.h>
144.Ed
145.Pp
140The
146The
147.Pa /dev/usbN
148can be opened and a few operations can be performed on it.
149The
150.Xr poll 2
151system call will say that I/O is possible on the controller device when a
141.Tn USB
152.Tn USB
142specifications can be found at:
153device has been connected or disconnected to the bus.
143.Pp
154.Pp
144.D1 Pa http://www.usb.org/developers/docs/
155The following
156.Xr ioctl 2
157commands are supported on the controller device:
158.Bl -tag -width xxxxxx
159.It Dv USB_DISCOVER
160This command will cause a complete bus discovery to be initiated.
161If any devices attached or detached from the bus they will be
162processed during this command.
163This is the only way that new devices are found on the bus.
164.It Dv USB_DEVICEINFO Fa "struct usb_device_info"
165This command can be used to retrieve some information about a device
166on the bus.
167The
168.Va addr
169field should be filled before the call and the other fields will
170be filled by information about the device on that address.
171Should no such device exist an error is reported.
172.Bd -literal
173struct usb_device_info {
174 uByte addr; /* device address */
175 char product[USB_MAX_STRING_LEN];
176 char vendor[USB_MAX_STRING_LEN];
177 char revision[8];
178 uByte class;
179 uByte config;
180 uByte lowspeed;
181 int power;
182 int nports;
183 uByte ports[16];
184#define USB_PORT_ENABLED 0xff
185#define USB_PORT_SUSPENDED 0xfe
186#define USB_PORT_POWERED 0xfd
187#define USB_PORT_DISABLED 0xfc
188};
189.Ed
145.Pp
190.Pp
146.Xr libusb 3 ,
147.Xr usbdi 4 ,
148.Xr aue 4 ,
149.Xr axe 4 ,
150.Xr cue 4 ,
151.Xr ehci 4 ,
152.Xr kue 4 ,
153.Xr ohci 4 ,
191The
192.Va product ,
193.Va vendor ,
194and
195.Va revision
196fields contain self-explanatory descriptions of the device.
197.Pp
198The
199.Va class
200field contains the device class.
201.Pp
202The
203.Va config
204field shows the current configuration of the device.
205.Pp
206The
207.Va lowspeed
208field
209is set if the device is a
210.Tn USB
211low speed device.
212.Pp
213The
214.Va power
215field shows the power consumption in milli-amps drawn at 5 volts,
216or zero if the device is self powered.
217.Pp
218If the device is a hub the
219.Va nports
220field is non-zero and the
221.Va ports
222field contains the addresses of the connected devices.
223If no device is connected to a port one of the
224.Va USB_PORT_*
225values indicates its status.
226.It Dv USB_DEVICESTATS Fa "struct usb_device_stats"
227This command retrieves statistics about the controller.
228.Bd -literal
229struct usb_device_stats {
230 u_long requests[4];
231};
232.Ed
233.Pp
234The
235.Va requests
236field is indexed by the transfer kind, i.e.
237.Va UE_* ,
238and indicates how many transfers of each kind that has been completed
239by the controller.
240.It Dv USB_REQUEST Fa "struct usb_ctl_request"
241This command can be used to execute arbitrary requests on the control pipe.
242This is
243.Em DANGEROUS
244and should be used with great care since it
245can destroy the bus integrity.
246.El
247.Pp
248The include file
249.Aq Pa dev/usb/usb.h
250contains definitions for the types used by the various
251.Xr ioctl 2
252calls.
253The naming convention of the fields for the various
254.Tn USB
255descriptors exactly follows the naming in the
256.Tn USB
257specification.
258Byte sized fields can be accessed directly, but word (16 bit)
259sized fields must be access by the
260.Fn UGETW field
261and
262.Fn USETW field value
263macros to handle byte order and alignment properly.
264.Pp
265The include file
266.Aq Pa dev/usb/usbhid.h
267similarly contains the definitions for
268Human Interface Devices
269.Pq Tn HID .
270.Sh SEE ALSO
271The
272.Tn USB
273specifications can be found at
274.Dv http://www.usb.org/developers/docs.htm .
275.Pp
154.Xr pci 4 ,
276.Xr pci 4 ,
155.Xr rue 4 ,
156.Xr ucom 4 ,
157.Xr udav 4 ,
277.Xr ohci 4 ,
158.Xr uhci 4 ,
278.Xr uhci 4 ,
279.Xr ugen 4 ,
159.Xr uhid 4 ,
160.Xr ukbd 4 ,
161.Xr ulpt 4 ,
280.Xr uhid 4 ,
281.Xr ukbd 4 ,
282.Xr ulpt 4 ,
162.Xr umass 4 ,
163.Xr ums 4 ,
283.Xr ums 4 ,
164.Xr uplcom 4 ,
165.Xr urio 4 ,
166.Xr uvscom 4 ,
167.Xr usbconfig 8
168.Sh STANDARDS
284.Xr usbd 8 ,
285.Xr usbdevs 8
286.Sh HISTORY
169The
170.Nm
287The
288.Nm
171module complies with the USB 2.0 standard.
172.Sh HISTORY
289driver first appeared in
290.Fx 3.0 .
291.Sh AUTHOR
173The
174.Nm
292The
293.Nm
175module has been inspired by the NetBSD USB stack initially written by
176Lennart Augustsson. The
177.Nm
178module was written by
179.An Hans Petter Selasky Aq hselasky@freebsd.org .
294driver was written by
295.An Lennart Augustsson (augustss@carlstedt.se) for the
296.Nx
297project.