546 lines
15 KiB
Groff
546 lines
15 KiB
Groff
.\" $NetBSD: usb.4,v 1.68 2004/05/25 10:54:22 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1999, 2000, 2001, 2002 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Lennart Augustsson.
|
|
.\"
|
|
.\" 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 the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 THE FOUNDATION OR CONTRIBUTORS
|
|
.\" 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.
|
|
.\"
|
|
.Dd May 25, 2004
|
|
.Dt USB 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm usb
|
|
.Nd Universal Serial Bus driver
|
|
.Sh SYNOPSIS
|
|
.Cd "ehci* at cardbus? dev ? function ?"
|
|
.Cd "ehci* at pci? dev ? function ?"
|
|
.Cd "ohci* at cardbus? dev ? function ?"
|
|
.Cd "ohci* at pci? dev ? function ?"
|
|
.Cd "slhci* at isa? port ? irq ?"
|
|
.Cd "uhci* at pci? dev ? function ?"
|
|
.Cd "usb* at ehci? flags X"
|
|
.Cd "usb* at ohci? flags X"
|
|
.Cd "usb* at uhci? flags X"
|
|
.Cd "usb* at slhci? flags X"
|
|
.Cd "uhub* at usb?"
|
|
.Cd "uhub* at uhub? port ? configuration ? interface ? vendor ? product ? release ?"
|
|
.Cd "XX* at uhub? port ? configuration ? interface ? vendor ? product ? release ?"
|
|
.Pp
|
|
.Cd options USBVERBOSE
|
|
.Pp
|
|
.In dev/usb/usb.h
|
|
.In dev/usb/usbhid.h
|
|
.Sh DESCRIPTION
|
|
.Nx
|
|
provides machine-independent bus support and drivers for
|
|
.Tn USB
|
|
devices.
|
|
.Pp
|
|
The
|
|
.Nx
|
|
.Nm
|
|
driver has three layers (like
|
|
.Xr scsi 4
|
|
and
|
|
.Xr pcmcia 4 ) :
|
|
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 bus.
|
|
Further devices, which may include further hubs,
|
|
attach to other hubs.
|
|
The attachment forms the same tree structure as the physical
|
|
.Tn USB
|
|
device tree.
|
|
For each
|
|
.Tn USB
|
|
device there may be additional drivers attached to it.
|
|
.Pp
|
|
The
|
|
.Cm uhub
|
|
device controls
|
|
.Tn USB
|
|
hubs and must always be present since there is at least a root hub in any
|
|
.Tn USB
|
|
system.
|
|
.Pp
|
|
The
|
|
.Va flags
|
|
argument to the
|
|
.Va usb
|
|
device affects the order in which the device detection happens
|
|
during cold boot.
|
|
Normally, only the USB host controller and the
|
|
.Va usb
|
|
device are detected during the autoconfiguration when the
|
|
machine is booted. The rest of the devices are detected once
|
|
the system becomes functional and the kernel thread for the
|
|
.Va usb
|
|
device is started.
|
|
Sometimes it is desirable to have a device detected early in the
|
|
boot process, e.g., the console keyboard. To achieve this use
|
|
a
|
|
.Va flags
|
|
value of 1.
|
|
.Sh SUPPORTED DEVICES
|
|
.Nx
|
|
includes machine-independent
|
|
.Tn USB
|
|
drivers, sorted by driver name:
|
|
.Bl -tag -width usscanner -offset indent
|
|
.It aue
|
|
driver for ADMtek AN986 Pegasus USB Ethernet.
|
|
.It cue
|
|
driver for CATC USB-EL1201A USB Ethernet.
|
|
.It kue
|
|
driver for Kawasaki LSI KL5KUSB101B USB Ethernet.
|
|
.It uaudio
|
|
driver for audio devices.
|
|
.It uax
|
|
driver for ASIX AX88172 USB Ethernet.
|
|
.It ubsa
|
|
driver for Belkin serial adapters.
|
|
.It udsbr
|
|
driver for D-Link DSB-R100 USB radio.
|
|
.It uftdi
|
|
driver for FTDI based serial adapters.
|
|
.It ugen
|
|
generic driver for
|
|
.Tn USB
|
|
devices.
|
|
.It uhid
|
|
generic driver for Human Interface Devices.
|
|
.It uhidev
|
|
top level HID driver.
|
|
.It uirda
|
|
driver for USB-IrDA bridges.
|
|
.It ukbd
|
|
keyboard driver.
|
|
.It ulpt
|
|
printer driver.
|
|
.It umass
|
|
driver for mass storage devices, such as disks.
|
|
.It umct
|
|
driver for MCT USB RS-232 serial adapter.
|
|
.It umidi
|
|
driver for MIDI devices.
|
|
.It umodem
|
|
driver for communication devices that use the Abstract Control Model.
|
|
.It ums
|
|
mouse driver.
|
|
.It upl
|
|
driver for
|
|
.Tn Prolific
|
|
host-to-host adapter.
|
|
.It uplcom
|
|
driver for Prolific 2303 serial adapter.
|
|
.It urio
|
|
driver for the
|
|
.Tn Diamond
|
|
Rio 500 MP3 player.
|
|
.It url
|
|
driver for Realtek RTL8150L USB Ethernet.
|
|
.It uscanner
|
|
driver for some USB scanners.
|
|
.It usscanner
|
|
driver for some SCSI-over-USB scanners.
|
|
.It ustir
|
|
driver for SigmaTel STIr4200 USB-IrDA bridges.
|
|
.It uvisor
|
|
Handspring Visor driver.
|
|
.It uvscom
|
|
driver for SUNTAC Slipper U VS-10U serial adapter.
|
|
.El
|
|
.Sh INTRODUCTION TO USB
|
|
The
|
|
.Tn USB
|
|
1.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices.
|
|
.Tn USB
|
|
2.x handles 480 Mb/s.
|
|
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 xxxxxxxxx
|
|
.It Cd port
|
|
this is the number of the port on 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 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 structures and defines.
|
|
.Bd -literal
|
|
#include \*[Lt]dev/usb/usb.h\*[Gt]
|
|
.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 udi_bus;
|
|
u_int8_t udi_addr;
|
|
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;
|
|
int udi_nports;
|
|
char udi_devnames[USB_MAX_DEVNAMES][USB_MAX_DEVNAMELEN];
|
|
u_int8_t udi_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 release
|
|
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 uds_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 USB EVENT INTERFACE
|
|
All
|
|
.Tn USB
|
|
events are reported via the
|
|
.Pa /dev/usb
|
|
device. This devices 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.
|
|
.br
|
|
The
|
|
.Va ue_bus
|
|
contains the number of the
|
|
.Tn USB
|
|
bus for host controller events.
|
|
.br
|
|
The
|
|
.Va ue_device
|
|
record contains information about the device in a device event event.
|
|
.br
|
|
The
|
|
.Va ue_cookie
|
|
is an opaque value that uniquely determines which which
|
|
device a device driver has been attached to (i.e., it equals
|
|
the cookie value in the device that the driver attached to).
|
|
The
|
|
.Va ue_devname
|
|
contains the name of the device (driver) as seen in, e.g.,
|
|
kernel messages.
|
|
.Pp
|
|
Note that that there is a separation between device and device
|
|
driver events. A device event is generated when a physical
|
|
USB device is attached or detached. A single USB device may
|
|
have zero, one, or many device drivers associated with it.
|
|
.Sh KERNEL THREADS
|
|
For each USB bus, i.e., for each host controller, there is
|
|
a kernel thread that handles attach and detach of devices on
|
|
that bus.
|
|
The thread is named
|
|
.Va usbN
|
|
where
|
|
.Va N
|
|
is the bus number.
|
|
.Pp
|
|
In addition there is a kernel thread,
|
|
.Va usbtask ,
|
|
which handles various minor tasks that are initiated from
|
|
an interrupt context, but need to sleep, e.g., time-out
|
|
abort of transfers.
|
|
.Sh SEE ALSO
|
|
The
|
|
.Tn USB
|
|
specifications can be found at:
|
|
.D1 http://www.usb.org/developers/docs/
|
|
.Pp
|
|
.Xr aue 4 ,
|
|
.Xr cardbus 4 ,
|
|
.Xr cue 4 ,
|
|
.Xr ehci 4 ,
|
|
.Xr isa 4 ,
|
|
.Xr kue 4 ,
|
|
.Xr ohci 4 ,
|
|
.Xr pci 4 ,
|
|
.Xr slhci 4 ,
|
|
.Xr uaudio 4 ,
|
|
.Xr uax 4 ,
|
|
.Xr ubsa 4 ,
|
|
.Xr ucom 4 ,
|
|
.Xr udsbr 4 ,
|
|
.Xr uep 4 ,
|
|
.Xr ugen 4 ,
|
|
.Xr uhci 4 ,
|
|
.Xr uhid 4 ,
|
|
.Xr uhidev 4 ,
|
|
.Xr uirda 4 ,
|
|
.Xr ukbd 4 ,
|
|
.Xr ulpt 4 ,
|
|
.Xr umass 4 ,
|
|
.Xr umct 4 ,
|
|
.Xr umidi 4 ,
|
|
.Xr ums 4 ,
|
|
.Xr upl 4 ,
|
|
.Xr urio 4 ,
|
|
.Xr url 4 ,
|
|
.Xr uscanner 4 ,
|
|
.Xr usscanner 4 ,
|
|
.Xr ustir 4 ,
|
|
.Xr uvisor 4 ,
|
|
.Xr usbdevs 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
driver
|
|
appeared in
|
|
.Nx 1.4 .
|
|
.Sh BUGS
|
|
There should be a serial number locator, but
|
|
.Nx
|
|
does not have string valued locators.
|