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