426 lines
12 KiB
Groff
426 lines
12 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. 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 April 20, 2005
|
|
.Dt USB 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm usb
|
|
.Nd Universal Serial Bus
|
|
.Sh SYNOPSIS
|
|
.Cd "device usb"
|
|
.Pp
|
|
.In dev/usb/usb.h
|
|
.In dev/usb/usbhid.h
|
|
.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
|
|
.Tn USB
|
|
bus.
|
|
.Pp
|
|
The
|
|
.Nm uhub
|
|
device will always be present as it is needed for the
|
|
root hub.
|
|
.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:
|
|
.Em control , isochronous , bulk ,
|
|
or
|
|
.Em 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.
|
|
.\" .It Cd vendor
|
|
.\" this is the 16 bit vendor id of the device.
|
|
.\" .It Cd product
|
|
.\" this is the 16 bit product id of the device.
|
|
.\" .It Cd release
|
|
.\" this is the 16 bit release (revision) number of the device.
|
|
.\" .El
|
|
.\" The first locator can be used to pin down a particular device
|
|
.\" according to its physical position in the device tree.
|
|
.\" The last three locators can be used to pin down a particular
|
|
.\" device according to what device it actually is.
|
|
.Pp
|
|
The bus enumeration of the
|
|
.Tn USB
|
|
bus proceeds in several steps:
|
|
.Bl -enum
|
|
.It
|
|
Any device specific driver can 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 interfaces 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 structures and defines.
|
|
.Pp
|
|
The
|
|
.Pa /dev/usb Ns Ar N
|
|
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 Vt "struct usb_device_info"
|
|
This command can be used to retrieve some information about a device
|
|
on the bus.
|
|
The
|
|
.Va udi_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
|
|
#define USB_MAX_DEVNAMES 4
|
|
#define USB_MAX_DEVNAMELEN 16
|
|
struct usb_device_info {
|
|
u_int8_t udi_bus;
|
|
u_int8_t udi_addr; /* device address */
|
|
usb_event_cookie_t udi_cookie;
|
|
char udi_product[USB_MAX_STRING_LEN];
|
|
char udi_vendor[USB_MAX_STRING_LEN];
|
|
char udi_release[8];
|
|
u_int16_t udi_productNo;
|
|
u_int16_t udi_vendorNo;
|
|
u_int16_t udi_releaseNo;
|
|
u_int8_t udi_class;
|
|
u_int8_t udi_subclass;
|
|
u_int8_t udi_protocol;
|
|
u_int8_t udi_config;
|
|
u_int8_t udi_speed;
|
|
#define USB_SPEED_LOW 1
|
|
#define USB_SPEED_FULL 2
|
|
#define USB_SPEED_HIGH 3
|
|
int udi_power;/* power consumption in mA, 0 if selfpowered */
|
|
int udi_nports;
|
|
char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
|
|
u_int8_t udi_ports[16];/* hub only: addresses of devices on ports */
|
|
#define USB_PORT_ENABLED 0xff
|
|
#define USB_PORT_SUSPENDED 0xfe
|
|
#define USB_PORT_POWERED 0xfd
|
|
#define USB_PORT_DISABLED 0xfc
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Va udi_bus
|
|
and
|
|
.Va udi_addr
|
|
contain the topological information for the device.
|
|
.Va udi_devnames
|
|
contains the device names of the connected drivers.
|
|
For example, the
|
|
third
|
|
.Tn USB
|
|
Zip drive connected will be
|
|
.Li umass2 .
|
|
The
|
|
.Va udi_product , udi_vendor
|
|
and
|
|
.Va udi_release
|
|
fields contain self-explanatory descriptions of the device.
|
|
.Va udi_productNo , udi_vendorNo , udi_releaseNo , udi_class , udi_subclass
|
|
and
|
|
.Va udi_protocol
|
|
contain the corresponding values from the device descriptors.
|
|
The
|
|
.Va udi_config
|
|
field shows the current configuration of the device.
|
|
.Pp
|
|
.Va udi_speed
|
|
indicates whether the device is at low speed
|
|
.Pq Dv USB_SPEED_LOW ,
|
|
full speed
|
|
.Pq Dv USB_SPEED_FULL
|
|
or high speed
|
|
.Pq Dv USB_SPEED_HIGH .
|
|
The
|
|
.Va udi_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 udi_nports
|
|
field is non-zero, and the
|
|
.Va udi_ports
|
|
field contains the addresses of the connected devices.
|
|
If no device is connected to a port, one of the
|
|
.Dv USB_PORT_*
|
|
values indicates its status.
|
|
.It Dv USB_DEVICESTATS Vt "struct usb_device_stats"
|
|
This command retrieves statistics about the controller.
|
|
.Bd -literal
|
|
struct usb_device_stats {
|
|
u_long uds_requests[4];
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va udi_requests
|
|
field is indexed by the transfer kind, i.e.\&
|
|
.Dv UE_* ,
|
|
and indicates how many transfers of each kind that has been completed
|
|
by the controller.
|
|
.It Dv USB_REQUEST Vt "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
|
|
.In 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
|
|
.In dev/usb/usbhid.h
|
|
similarly contains the definitions for
|
|
Human Interface Devices
|
|
.Pq Tn HID .
|
|
.Sh USB EVENT INTERFACE
|
|
All
|
|
.Tn USB
|
|
events are reported via the
|
|
.Pa /dev/usb
|
|
device.
|
|
This device can be opened for reading and each
|
|
.Xr read 2
|
|
will yield an event record (if something has happened).
|
|
The
|
|
.Xr poll 2
|
|
system call can be used to determine if an event record is available
|
|
for reading.
|
|
.Pp
|
|
The event record has the following definition:
|
|
.Bd -literal
|
|
struct usb_event {
|
|
int ue_type;
|
|
#define USB_EVENT_CTRLR_ATTACH 1
|
|
#define USB_EVENT_CTRLR_DETACH 2
|
|
#define USB_EVENT_DEVICE_ATTACH 3
|
|
#define USB_EVENT_DEVICE_DETACH 4
|
|
#define USB_EVENT_DRIVER_ATTACH 5
|
|
#define USB_EVENT_DRIVER_DETACH 6
|
|
struct timespec ue_time;
|
|
union {
|
|
struct {
|
|
int ue_bus;
|
|
} ue_ctrlr;
|
|
struct usb_device_info ue_device;
|
|
struct {
|
|
usb_event_cookie_t ue_cookie;
|
|
char ue_devname[16];
|
|
} ue_driver;
|
|
} u;
|
|
};
|
|
.Ed
|
|
The
|
|
.Va ue_type
|
|
field identifies the type of event that is described.
|
|
The possible events are attach/detach of a host controller,
|
|
a device, or a device driver.
|
|
The union contains information
|
|
pertinent to the different types of events.
|
|
Macros,
|
|
.Fn USB_EVENT_IS_ATTACH "ue_type"
|
|
and
|
|
.Fn USB_EVENT_IS_DETACH "ue_type"
|
|
can be used to determine if an event was an
|
|
.Dq attach
|
|
or a
|
|
.Dq detach
|
|
request.
|
|
.Pp
|
|
The
|
|
.Va ue_bus
|
|
contains the number of the
|
|
.Tn USB
|
|
bus for host controller events.
|
|
.Pp
|
|
The
|
|
.Va ue_device
|
|
record contains information about the device in a device event event.
|
|
.Pp
|
|
The
|
|
.Va ue_cookie
|
|
is an opaque value that uniquely determines which
|
|
device a device driver has been attached to (i.e., it equals
|
|
the cookie value in the device that the driver attached to).
|
|
.Pp
|
|
The
|
|
.Va ue_devname
|
|
contains the name of the device (driver) as seen in, e.g.,
|
|
kernel messages.
|
|
.Pp
|
|
Note that there is a separation between device and device
|
|
driver events.
|
|
A device event is generated when a physical
|
|
.Tn USB
|
|
device is attached or detached.
|
|
A single
|
|
.Tn USB
|
|
device may
|
|
have zero, one, or many device drivers associated with it.
|
|
.Sh SEE ALSO
|
|
The
|
|
.Tn USB
|
|
specifications can be found at:
|
|
.Pp
|
|
.D1 Pa http://www.usb.org/developers/docs/
|
|
.Pp
|
|
.Xr aue 4 ,
|
|
.Xr cue 4 ,
|
|
.Xr ehci 4 ,
|
|
.Xr kue 4 ,
|
|
.Xr ohci 4 ,
|
|
.Xr pci 4 ,
|
|
.Xr ucom 4 ,
|
|
.Xr ugen 4 ,
|
|
.Xr uhci 4 ,
|
|
.Xr uhid 4 ,
|
|
.Xr ukbd 4 ,
|
|
.Xr ulpt 4 ,
|
|
.Xr umass 4 ,
|
|
.Xr ums 4 ,
|
|
.Xr uplcom 4 ,
|
|
.Xr urio 4 ,
|
|
.Xr uscanner 4 ,
|
|
.Xr uvscom 4 ,
|
|
.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.
|