diff options
Diffstat (limited to 'share/man/man4/usb.4')
| -rw-r--r-- | share/man/man4/usb.4 | 297 |
1 files changed, 297 insertions, 0 deletions
diff --git a/share/man/man4/usb.4 b/share/man/man4/usb.4 new file mode 100644 index 0000000..0c6f989 --- /dev/null +++ b/share/man/man4/usb.4 @@ -0,0 +1,297 @@ +.\" Copyright (c) 1997, 1998 +.\" Nick Hibma <hibma@skylink.it>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Bill Paul. +.\" 4. Neither the name of the author nor the names of any co-contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY NICK HIBMA AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL NICK HIBMA OR THE VOICES IN HIS HEAD +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $Id: xl.4,v 1.3 1998/12/05 09:36:15 rnordier Exp $ +.\" +.Dd February 21, 1999 +.Dt USB 4 i386 +.Os FreeBSD +.Sh NAME +.Nm usb +.Nd Universal Serial Bus +.Sh SYNOPSIS +.Cd "controller usb0" +.Sh DESCRIPTION +.Nx +provides machine-independent bus support and drivers for +.Tn USB +devices. +.Pp +The +.Nm +driver has three layers: the controller, the bus, and the +device layer. The controller attaches to a physical bus +(like +.Xr pci 4 ). +The +.Tn USB +bus attaches to the controller and the root hub attaches +to the controller. +Any devices attached to the bus will attach to the root hub +or another hub attached to the USB bus. +.Pp +The +.Nm uhub +device will always be present as it is needed for the +root hub. +.Pp +.Sh INTRODUCTION TO USB +The +.Tn USB +is a 12 Mb/s serial bus (1.5 Mb/s for low speed devices). +Each +.Tn USB +has a host controller that is the master of the bus; +all other devices on the bus only speak when spoken to. +.Pp +There can be up to 127 devices (apart from the host controller) +on a bus, each with its own address. +The addresses are assigned +dynamically by the host when each device is attached to the bus. +.Pp +Within each device there can be up to 16 endpoints. +Each endpoint +is individually addressed and the addresses are static. +Each of these endpoints will communicate in one of four different modes: +control, isochronous, bulk, or interrupt. +A device always has at least one endpoint. +This endpoint has address 0 and is a control +endpoint and is used to give commands to and extract basic data, +such as descriptors, from the device. +Each endpoint, except the control endpoint, is unidirectional. +.Pp +The endpoints in a device are grouped into interfaces. +An interface is a logical unit within a device; e.g. +a compound device with both a keyboard and a trackball would present +one interface for each. +An interface can sometimes be set into different modes, +called alternate settings, which affects how it operates. +Different alternate settings can have different endpoints +within it. +.Pp +A device may operate in different configurations. +Depending on the +configuration the device may present different sets of endpoints +and interfaces. +.Pp +Each device located on a hub has several +.Xr config 8 +locators: +.Bl -tag -compact -width xxxxxx +.It Cd port +this is the number of the port on the closest upstream hub. +.It Cd configuration +this is the configuration the device must be in for this driver to attach. +This locator does not set the configuration; it is iterated by the bus +enumeration. +.It Cd interface +this is the interface number within a device that an interface driver +attaches to. +.El +.Pp +The bus enumeration of the +.Tn USB +bus proceeds in several steps: +.Bl -enum +.It +Any device specific driver can to attach to the device. +.It +If none is found, any device class specific driver can attach. +.It +If none is found, all configurations are iterated over. +For each configuration all the interface are iterated over and interface +drivers can attach. +If any interface driver attached in a certain +configuration the iteration over configurations is stopped. +.It +If still no drivers have been found, the generic +.Tn USB +driver can attach. +.El +.Sh USB CONTROLLER INTERFACE +Use the following to get access to the +.Tn USB +specific structurs and defines. +.Bd -literal +#include <sys/dev/usb.h> +.Ed +.Pp +The +.Pa /dev/usbN +can be opened and a few operations can be performed on it. +The +.Xr poll 2 +system call will say that I/O is possible on the controller device when a +.Tn USB +device has been connected or disconnected to the bus. +.Pp +The following +.Xr ioctl 2 +commands are supported on the controller device: +.Bl -tag -width xxxxxx +.It Dv USB_DISCOVER +This command will cause a complete bus discovery to be initiated. +If any devices attached or detached from the bus they will be +processed during this command. +This is the only way that new devices are found on the bus. +.It Dv USB_DEVICEINFO Fa "struct usb_device_info" +This command can be used to retrieve some information about a device +on the bus. +The +.Va addr +field should be filled before the call and the other fields will +be filled by information about the device on that address. +Should no such device exist an error is reported. +.Bd -literal +struct usb_device_info { + uByte addr; /* device address */ + char product[USB_MAX_STRING_LEN]; + char vendor[USB_MAX_STRING_LEN]; + char revision[8]; + uByte class; + uByte config; + uByte lowspeed; + int power; + int nports; + uByte ports[16]; +#define USB_PORT_ENABLED 0xff +#define USB_PORT_SUSPENDED 0xfe +#define USB_PORT_POWERED 0xfd +#define USB_PORT_DISABLED 0xfc +}; +.Ed +.Pp +The +.Va product , +.Va vendor , +and +.Va revision +fields contain self-explanatory descriptions of the device. +.Pp +The +.Va class +field contains the device class. +.Pp +The +.Va config +field shows the current configuration of the device. +.Pp +The +.Va lowspeed +field +is set if the device is a +.Tn USB +low speed device. +.Pp +The +.Va power +field shows the power consumption in milli-amps drawn at 5 volts, +or zero if the device is self powered. +.Pp +If the device is a hub the +.Va nports +field is non-zero and the +.Va ports +field contains the addresses of the connected devices. +If no device is connected to a port one of the +.Va USB_PORT_* +values indicates its status. +.It Dv USB_DEVICESTATS Fa "struct usb_device_stats" +This command retrieves statistics about the controller. +.Bd -literal +struct usb_device_stats { + u_long requests[4]; +}; +.Ed +.Pp +The +.Va requests +field is indexed by the transfer kind, i.e. +.Va UE_* , +and indicates how many transfers of each kind that has been completed +by the controller. +.It Dv USB_REQUEST Fa "struct usb_ctl_request" +This command can be used to execute arbitrary requests on the control pipe. +This is +.Em DANGEROUS +and should be used with great care since it +can destroy the bus integrity. +.El +.Pp +The include file +.Aq Pa dev/usb/usb.h +contains definitions for the types used by the various +.Xr ioctl 2 +calls. +The naming convention of the fields for the various +.Tn USB +descriptors exactly follows the naming in the +.Tn USB +specification. +Byte sized fields can be accessed directly, but word (16 bit) +sized fields must be access by the +.Fn UGETW field +and +.Fn USETW field value +macros to handle byte order and alignment properly. +.Pp +The include file +.Aq Pa dev/usb/usbhid.h +similarly contains the definitions for +Human Interface Devices +.Pq Tn HID . +.Sh SEE ALSO +The +.Tn USB +specifications can be found at +.Dv http://www.usb.org/developers/docs.htm . +.Pp +.Xr pci 4 , +.Xr ohci 4 , +.Xr uhci 4 , +.Xr ugen 4 , +.Xr uhid 4 , +.Xr ukbd 4 , +.Xr ulpt 4 , +.Xr ums 4 , +.Xr usbd 8 , +.Xr usbdevs 8 +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 3.0 . +.Sh AUTHOR +The +.Nm +driver was written by +.An Lennart Augustsson (augustss@carlstedt.se) for the +.Nx +project. |
