kernel/usb4bsd: Bring in the axge(4) ethernet driver.
[dragonfly.git] / share / man / man4 / usb.4
CommitLineData
a169dc2a
SW
1.\" Copyright (c) 1997, 1998 Nick Hibma <n_hibma@FreeBSD.org>
2.\" Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
984263bc
MD
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.
984263bc 12.\"
a169dc2a 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
984263bc
MD
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
a169dc2a
SW
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.
984263bc 24.\"
a169dc2a 25.\" $FreeBSD: head/share/man/man4/usb.4 258618 2013-11-26 07:52:40Z lwhsu $
984263bc 26.\"
3d2b9530 27.Dd November 15, 2014
984263bc
MD
28.Dt USB 4
29.Os
30.Sh NAME
31.Nm usb
32.Nd Universal Serial Bus
33.Sh SYNOPSIS
a169dc2a
SW
34To compile this driver into the kernel,
35place the following line in your
36kernel configuration file:
37.Bd -ragged -offset indent
984263bc 38.Cd "device usb"
a169dc2a 39.Ed
984263bc 40.Pp
a169dc2a
SW
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.
984263bc 52.Sh DESCRIPTION
9bb2a92d 53.Dx
984263bc
MD
54provides machine-independent bus support and drivers for
55.Tn USB
a169dc2a 56devices in host and device side mode.
984263bc
MD
57.Pp
58The
59.Nm
a169dc2a
SW
60driver has three layers:
61.Bl -tag -width 6n -offset indent
62.It USB Controller (Bus)
63.It USB Device
64.It USB Driver
65.El
66.Pp
984263bc 67The controller attaches to a physical bus
a169dc2a
SW
68like
69.Xr pci 4 .
984263bc
MD
70The
71.Tn USB
72bus attaches to the controller, and the root hub attaches
73to the controller.
74Any devices attached to the bus will attach to the root hub
75or another hub attached to the
76.Tn USB
77bus.
78.Pp
79The
80.Nm uhub
81device will always be present as it is needed for the
82root hub.
a169dc2a
SW
83.Pp
84.Dx
85provides support for the following devices.
477afb1f
SW
86.Ss Storage devices
87.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
88.\".It Xr natausb 4
89.\"...
90.It Xr umass 4
91Mass Storage Devices, e.g., external disk drives
a169dc2a
SW
92.It Xr usfs 4
93Mass storage driver for device-side mode
477afb1f
SW
94.El
95.Ss Wired network interfaces
96.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
79be21c5
SW
97.It Xr aue 4
98ADMtek AN986 Pegasus Ethernet driver
477afb1f 99.It Xr axe 4
a169dc2a 100ASIX Electronics AX88x7x/760 USB Ethernet driver
3d2b9530
SW
101.It Xr axge 4
102ASIX Electronics AX88178A/AX88179 USB Gigabit Ethernet driver
79be21c5
SW
103.It Xr cue 4
104CATC USB-EL1210A Ethernet driver
105.It Xr ipheth 4
106USB Apple iPhone/iPad tethered Ethernet driver
107.It Xr kue 4
108Kawasaki LSI KL5KUSB101B Ethernet driver
a169dc2a
SW
109.\".It Xr lgue 4
110.\"USB CDC (communication device class) driver for the LG P-500 smartphone
f8577199
SW
111.It Xr mos 4
112Moschip MCS7730/MCS7830/MCS7832 USB Ethernet driver
a169dc2a
SW
113.\".It Xr rue 4
114.\"RealTek RTL8150 Ethernet driver
115.It Xr udav 4
116Davicom DM9601 USB Ethernet driver
477afb1f
SW
117.El
118.Ss Wireless network interfaces
119.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
efba76b4
SW
120.It Xr ndis 4
121NDIS miniport driver wrapper
f794c13f
SW
122.It Xr rum 4
123Ralink Technology RT2501USB/RT2601USB IEEE 802.11 driver
10f2cea7
SW
124.It Xr run 4
125Ralink Technology RT2700U/RT2800U/RT3000U IEEE 802.11 driver
a169dc2a
SW
126.\".It Xr ubt 4
127.\"Bluetooth adapters
4097c65c
SW
128.\".It Xr ural 4
129.\"Ralink Technology RT2500USB IEEE 802.11 driver
e4ca69a1
SW
130.It Xr urndis 4
131RNDIS USB ethernet driver
790340ea
SW
132.It Xr urtwn 4
133Realtek RTL8188CU/RTL8192CU IEEE 802.11 driver
477afb1f
SW
134.El
135.Ss Serial and parallel interfaces
136.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
a169dc2a
SW
137.\".It Xr moscom 4
138.\"MosChip Semiconductor MCS7703 based serial adapters
139.It Xr u3g 4
140support for 3G datacards
477afb1f
SW
141.It Xr uark 4
142Arkmicro Technologies ARK3116 based serial adapters
143.It Xr ubsa 4
144Belkin serial adapters
a169dc2a
SW
145.It Xr ubser 4
146support for BWCT console serial adapters
477afb1f
SW
147.It Xr uchcom 4
148WinChipHead CH341/CH340 serial adapters
149.It Xr ucom 4
150tty support
a169dc2a
SW
151.It Xr ucycom 4
152Cypress CY7C63743 and CY7C64013 USB to RS232 bridges
153.It Xr ufoma 4
154mobile phone support
477afb1f
SW
155.It Xr uftdi 4
156serial devices based on the FTDI chips
86906a69
SW
157.It Xr ugensa 4
158generic serial device
a169dc2a
SW
159.It Xr uipaq 4
160support for iPAQ units
477afb1f
SW
161.It Xr ulpt 4
162printer support
a169dc2a
SW
163.It Xr umcs 4
164serial adapters based on the MCS7820 and MCS7840 chips
477afb1f
SW
165.It Xr umct 4
166Magic Control Technology USB-232 based serial adapters
a169dc2a
SW
167.It Xr umodem 4
168modem support
169.It Xr umoscom 4
170serial adapters based on the MCS7703 chip
477afb1f
SW
171.It Xr uplcom 4
172Prolific PL-2303/2303X/2303HX serial adapters
173.It Xr uslcom 4
174Silicon Laboratories CP2101, CP2102 and CP2103 USB to serial bridge
a169dc2a
SW
175.\".It Xr uticom 4
176.\"Texas Instruments TUSB3410 RS232 to USB converter
477afb1f
SW
177.It Xr uvisor 4
178support for the Handspring Visor, a Palmpilot compatible PDA
179.It Xr uvscom 4
180SUNTAC Slipper U VS-10U serial adapters
181.El
a169dc2a
SW
182.\".Ss Audio devices
183.\".Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
184.\".It Xr snd_uaudio 4
185.\"audio device driver
186.\".It Xr urio 4
187.\"driver for the Rio500 MP3 player
188.\".El
4596d2c5
SW
189.Ss Radio receiver devices
190.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
191.It Xr ufm 4
192Cypress Semiconductor FM Radio
193.El
477afb1f
SW
194.Ss Human Interface Devices
195.Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
a169dc2a
SW
196.It Xr uep 4
197eGalax touchscreen driver
477afb1f
SW
198.It Xr uhid 4
199generic driver for Human Interface Devices
477afb1f
SW
200.It Xr ukbd 4
201keyboards that follow the boot protocol
202.It Xr ums 4
203mouse devices
204.El
a169dc2a
SW
205.\".Ss Miscellaneous devices
206.\".Bl -tag -width ".Xr snd_uaudio 4" -offset indent -compact
207.\".It Xr uscanner 4
208.\"scanner support
209.\".El
984263bc
MD
210.Sh INTRODUCTION TO USB
211The
212.Tn USB
a169dc2a
SW
213is a system where external devices can be connected to a PC.
214The most common USB speeds are:
215.Bl -tag -width 6n -offset indent
216.It Low Speed (1.5MBit/sec)
217.It Full Speed (12MBit/sec)
218.It High Speed (480MBit/sec)
219.El
220.Pp
984263bc
MD
221Each
222.Tn USB
a169dc2a
SW
223has a USB controller that is the master of the bus.
224The physical communication is simplex which means the host controller only communicates with one USB device at a time.
984263bc 225.Pp
a169dc2a 226There can be up to 127 devices connected to an USB HUB tree.
984263bc
MD
227The addresses are assigned
228dynamically by the host when each device is attached to the bus.
229.Pp
230Within each device there can be up to 16 endpoints.
231Each endpoint
232is individually addressed and the addresses are static.
233Each of these endpoints will communicate in one of four different modes:
234.Em control , isochronous , bulk ,
235or
236.Em interrupt .
237A device always has at least one endpoint.
238This endpoint has address 0 and is a control
239endpoint and is used to give commands to and extract basic data,
240such as descriptors, from the device.
241Each endpoint, except the control endpoint, is unidirectional.
242.Pp
243The endpoints in a device are grouped into interfaces.
244An interface is a logical unit within a device; e.g.\&
245a compound device with both a keyboard and a trackball would present
246one interface for each.
247An interface can sometimes be set into different modes,
248called alternate settings, which affects how it operates.
249Different alternate settings can have different endpoints
250within it.
251.Pp
252A device may operate in different configurations.
253Depending on the
254configuration, the device may present different sets of endpoints
255and interfaces.
984263bc
MD
256.Pp
257The bus enumeration of the
258.Tn USB
259bus proceeds in several steps:
260.Bl -enum
261.It
a169dc2a 262Any interface specific driver can attach to the device.
984263bc 263.It
a169dc2a 264If none is found, generic interface class drivers can attach.
984263bc 265.El
984263bc
MD
266.Sh SEE ALSO
267The
268.Tn USB
269specifications can be found at:
270.Pp
9797c794 271.D1 Pa http://www.usb.org/developers/docs/
984263bc 272.Pp
a169dc2a 273.Xr libusb 3 ,
79be21c5 274.Xr aue 4 ,
a169dc2a 275.Xr axe 4 ,
3d2b9530 276.Xr axge 4 ,
79be21c5 277.Xr cue 4 ,
9797c794 278.Xr ehci 4 ,
79be21c5
SW
279.Xr ipheth 4 ,
280.Xr kue 4 ,
f8577199 281.Xr mos 4 ,
a169dc2a 282.Xr ndis 4 ,
984263bc
MD
283.Xr ohci 4 ,
284.Xr pci 4 ,
a169dc2a
SW
285.\".Xr rue 4 ,
286.Xr rum 4 ,
287.Xr run 4 ,
288.Xr u3g 4 ,
289.Xr uark 4 ,
290.Xr ubsa 4 ,
291.Xr ubser 4 ,
292.Xr uchcom 4 ,
293.Xr ucom 4 ,
294.Xr ucycom 4 ,
295.Xr udav 4 ,
296.Xr uep 4 ,
94bea27b 297.Xr ufm 4 ,
a169dc2a
SW
298.Xr ufoma 4 ,
299.Xr uftdi 4 ,
300.Xr ugensa 4 ,
984263bc 301.Xr uhci 4 ,
a169dc2a
SW
302.Xr uhid 4 ,
303.Xr uipaq 4 ,
304.Xr ukbd 4 ,
305.Xr ulpt 4 ,
306.Xr umass 4 ,
307.Xr umcs 4 ,
308.Xr umct 4 ,
309.Xr umodem 4 ,
310.Xr umoscom 4 ,
311.Xr ums 4 ,
312.Xr uplcom 4 ,
313.\".Xr urio 4 ,
314.Xr urtwn 4 ,
315.Xr usfs 4 ,
316.Xr uslcom 4 ,
317.Xr uvisor 4 ,
318.Xr uvscom 4 ,
b0ab9bec 319.Xr xhci 4 ,
a169dc2a 320.Xr usbconfig 8 ,
b0ab9bec 321.Xr usbdi 9
a169dc2a
SW
322.Sh STANDARDS
323The
324.Nm
325module complies with the USB 2.0 standard.
984263bc
MD
326.Sh HISTORY
327The
328.Nm
b0ab9bec
SW
329module has been inspired by the
330.Nx
331USB stack initially written by Lennart Augustsson.
984263bc
MD
332The
333.Nm
a169dc2a
SW
334module was written by
335.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org .