262 lines
8.6 KiB
Groff
262 lines
8.6 KiB
Groff
.\" $NetBSD: usb.4,v 1.7 1998/12/08 14:21:48 augustss Exp $
|
|
.\" Copyright (c) 1998 The NetBSD Foundation, Inc.
|
|
.\" 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 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 July 12, 1998
|
|
.Dt USB 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm usb
|
|
.Nd introduction to USB support
|
|
.Sh SYNOPSIS
|
|
.Cd "uhci* at pci? function ?"
|
|
.Cd "ohci* at pci? function ?"
|
|
.Cd "usb* at uhci?"
|
|
.Cd "usb* at ohci?"
|
|
.Cd "uhub* at usb?"
|
|
.Cd "uhub* at uhub?"
|
|
.Cd "XX* at uhub? port ? configuration ? interface ?"
|
|
.Pp
|
|
.Cd "#include <dev/usb/usb.h>"
|
|
.Cd "#include <dev/usb/usbhid.h>"
|
|
.Pp
|
|
.Sh INTRODUCTION
|
|
.Nx
|
|
provides machine-independent bus support and
|
|
drivers for USB devices.
|
|
.Pp
|
|
The
|
|
.Nx
|
|
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 USB bus attaches to the controller and the root hub attaches
|
|
to the controller. Further devices, which include further hubs,
|
|
attach to other hubs. The attachment forms the same tree structure
|
|
as the physical USB device tree.
|
|
For each USB device there may be further drivers attached to it.
|
|
.Pp
|
|
The
|
|
.Cm uhub
|
|
device controls USB hubs and must always be present since there
|
|
is at least a root hub in any USB system.
|
|
.Pp
|
|
.Sh INTRODUCTION TO USB
|
|
The USB is a 12Mb/s serial bus (1.5 Mb/s for low speed devices).
|
|
Each USB bus 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 locators:
|
|
.Bl -tag -width indent -compact
|
|
.It Dv port
|
|
this is the number of the port on closest upstream hub.
|
|
.It Dv 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 Dv interface
|
|
this is the interface number within a device that an interface driver
|
|
attaches to.
|
|
.El
|
|
.Pp
|
|
The bus enumeration of the USB bus proceeds in several steps:
|
|
.Bl -dash
|
|
.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 USB driver can attach.
|
|
.El
|
|
.Sh USB CONTROLLER INTERFACE
|
|
Use the following to get access to the 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
|
|
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 indent -compact
|
|
.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 (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
|
|
The
|
|
.Va product ,
|
|
.Va vendor ,
|
|
and
|
|
.Va revision
|
|
fields contain (self-explanatory) descriptions of the device.
|
|
The
|
|
.Va class
|
|
field contains the device class.
|
|
The
|
|
.Va config
|
|
field shows the current configuration of the device.
|
|
The
|
|
.Va lowspeed
|
|
field
|
|
is set if the device is a USB low speed device.
|
|
The
|
|
.Va power
|
|
field shows the power consumption in mA (drawn a 5V), or 0 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 (struct usb_device_stats)
|
|
.Bd -literal
|
|
This command retrieves statisctics about the controller.
|
|
struct usb_device_stats {
|
|
u_long requests[4];
|
|
};
|
|
.Ed
|
|
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 (struct usb_ctl_request)
|
|
This command can be used to execute arbitrary requests on the control
|
|
pipe. This is DANGEROUS and should be used with great care since it
|
|
can destroy the bus integrity.
|
|
.El
|
|
.Pp
|
|
The include file
|
|
.Dv <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 USB
|
|
descriptors exactly follows the naming in the USB specification.
|
|
Byte sized fields can be accessed directly, but word (16 bit)
|
|
sized fields must be access by the
|
|
.Dv "UGETW(field)"
|
|
and
|
|
.Dv "USETW(field,value)"
|
|
macros to handle byte order and alignment properly.
|
|
.br
|
|
The include file
|
|
.Dv <dev/usb/usbhid.h>
|
|
similarely contains the definitions for HID devices.
|
|
.Sh SEE ALSO
|
|
.Xr pci 4 ,
|
|
.Xr uaudio 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
|
|
appeared in
|
|
.Nx 1.4 .
|