311 lines
9.1 KiB
Groff
311 lines
9.1 KiB
Groff
.\" Copyright (c) 1997, 1998
|
|
.\" Nick Hibma <n_hibma@FreeBSD.org>. 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 21, 1999
|
|
.Dt USB 4
|
|
.Os FreeBSD
|
|
.Sh NAME
|
|
.Nm usb
|
|
.Nd Universal Serial Bus
|
|
.Sh SYNOPSIS
|
|
.Cd "device usb"
|
|
.Sh DESCRIPTION
|
|
.Fx
|
|
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 {
|
|
u_int8_t bus;
|
|
u_int8_t addr;
|
|
# define USBDEVNAME_NR 4
|
|
# define USBDEVNAME_LEN 10
|
|
char devnames[USBDEVNAME_NR][USBDEVNAME_LEN];
|
|
char product[USB_MAX_STRING_LEN];
|
|
char vendor[USB_MAX_STRING_LEN];
|
|
char release[8];
|
|
u_int16_t productNo;
|
|
u_int16_t vendorNo;
|
|
u_int16_t releaseNo;
|
|
u_int8_t class;
|
|
u_int8_t subclass;
|
|
u_int8_t protocol;
|
|
u_int8_t config;
|
|
u_int8_t lowspeed;
|
|
int power;
|
|
int nports;
|
|
u_int8_t ports[16];
|
|
#define USB_PORT_ENABLED 0xff
|
|
#define USB_PORT_SUSPENDED 0xfe
|
|
#define USB_PORT_POWERED 0xfd
|
|
#define USB_PORT_DISABLED 0xfc
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Va bus
|
|
and
|
|
.Va addr
|
|
contain the topological information for the device.
|
|
.Va devnames
|
|
contains the device names of the connected drivers.
|
|
For example the
|
|
third USB Zip drive connected will be
|
|
.Li umass2 .
|
|
The
|
|
.Va product , vendor
|
|
and
|
|
.Va release
|
|
fields contain self-explanatory descriptions of the device.
|
|
.Va productNo , vendorNo , releaseNo , class , subclass
|
|
and
|
|
.Va protocol
|
|
contain the corresponding values from the device descriptors.
|
|
The
|
|
.Va config
|
|
field shows the current configuration of the device.
|
|
.Pp
|
|
.Va lowspeed
|
|
indicates whether the device is a full speed (0) or low speed (1)
|
|
device.
|
|
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 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 AUTHORS
|
|
The
|
|
.Nm
|
|
driver was written by
|
|
.An Lennart Augustsson Aq augustss@carlstedt.se
|
|
for the
|
|
.Nx
|
|
project.
|