572 lines
16 KiB
Groff
572 lines
16 KiB
Groff
.\" $NetBSD: usb.4,v 1.122 2022/07/10 19:49:24 nia Exp $
|
|
.\"
|
|
.\" Copyright (c) 1999-2014 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.
|
|
.\"
|
|
.\" 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 10, 2022
|
|
.Dt USB 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm usb
|
|
.Nd Universal Serial Bus driver
|
|
.Sh SYNOPSIS
|
|
.Cd "ehci* at cardbus? function ?"
|
|
.Cd "ehci* at pci? dev ? function ?"
|
|
.Cd "ohci* at cardbus? function ?"
|
|
.Cd "ohci* at pci? dev ? function ?"
|
|
.Cd "xhci* at pci? dev ? function ?"
|
|
.Cd "slhci* at isa? port ? irq ?"
|
|
.Cd "slhci* at pcmcia? function ?"
|
|
.Cd "uhci* at cardbus? function ?"
|
|
.Cd "uhci* at pci? dev ? function ?"
|
|
.Cd "usb* at ehci?"
|
|
.Cd "usb* at ohci?"
|
|
.Cd "usb* at uhci?"
|
|
.Cd "usb* at slhci?"
|
|
.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 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 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
|
|
USB device tree.
|
|
For each USB device there may be additional 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
|
|
.Nx
|
|
supports the following machine-independent USB drivers:
|
|
.Ss Storage devices
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr umass 4
|
|
USB Mass Storage Devices, e.g., external disk drives
|
|
.El
|
|
.Ss Wired network interfaces
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr aue 4
|
|
ADMtek AN986/ADM8511 Pegasus family 10/100 USB Ethernet device
|
|
.It Xr axe 4
|
|
ASIX Electronics AX88172/AX88178/AX88772 10/100/Gigabit USB Ethernet device
|
|
.It Xr axen 4
|
|
ASIX Electronics AX88178a/AX88179 10/100/Gigabit USB Ethernet device
|
|
.It Xr cdce 4
|
|
USB Communication Device Class Ethernet device
|
|
.It Xr cue 4
|
|
CATC USB-EL1201A USB Ethernet device
|
|
.It Xr kue 4
|
|
Kawasaki LSI KL5KUSB101B USB Ethernet device
|
|
.It Xr mos 4
|
|
MosChip MCS7730/7830/7832 10/100 USB Ethernet device
|
|
.It Xr mue 4
|
|
Microchip LAN75xx/LAN78xx 10/100/Gigabit USB Ethernet device
|
|
.It Xr udav 4
|
|
Davicom DM9601 10/100 USB Ethernet device
|
|
.It Xr ure 4
|
|
Realtek RTL8152/RTL8153 10/100/Gigabit USB Ethernet device
|
|
.It Xr url 4
|
|
Realtek RTL8150L 10/100 USB Ethernet device
|
|
.It Xr urndis 4
|
|
USB Remote NDIS Ethernet device
|
|
.It Xr usmsc 4
|
|
SMSC LAN95xx 10/100 USB Ethernet device
|
|
.El
|
|
.Ss Wireless network interfaces
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr atu 4
|
|
Atmel AT76C50x IEEE 802.11b wireless network device
|
|
.It Xr ral 4
|
|
Ralink Technology USB IEEE 802.11b/g wireless network device
|
|
.It Xr rum 4
|
|
Ralink Technology USB IEEE 802.11a/b/g wireless network device
|
|
.It Xr run 4
|
|
Ralink Technology USB IEEE 802.11a/b/g/n wireless network device
|
|
.It Xr ubt 4
|
|
USB Bluetooth dongles
|
|
.It Xr upgt 4
|
|
Conexant/Intersil PrismGT SoftMAC USB 802.11b/g wireless network device
|
|
.It Xr urtwn 4
|
|
Realtek RTL8188CU/RTL8192CU USB IEEE 802.11b/g/n wireless network device
|
|
.It Xr zyd 4
|
|
ZyDAS ZD1211/ZD1211B USB IEEE 802.11b/g wireless network device
|
|
.El
|
|
.Ss Serial and parallel interfaces
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr uark 4
|
|
Arkmicro Technologies ARK3116 based USB serial adapters
|
|
.It Xr ubsa 4
|
|
Belkin USB serial adapter
|
|
.It Xr uchcom 4
|
|
WinChipHead CH341/340 based USB serial adapter
|
|
.It Xr ucom 4
|
|
USB tty support
|
|
.It Xr ucycom 4
|
|
Cypress microcontroller based USB serial adapter
|
|
.It Xr uftdi 4
|
|
FT8U100AX USB serial adapter
|
|
.It Xr ugensa 4
|
|
USB generic serial adapter
|
|
.It Xr uipaq 4
|
|
iPAQ USB units
|
|
.It Xr ukyopon 4
|
|
USB Kyocera AIR-EDGE PHONE device
|
|
.It Xr ulpt 4
|
|
USB printer support
|
|
.It Xr umct 4
|
|
MCT USB-RS232 USB serial adapter
|
|
.It Xr umodem 4
|
|
USB modem support
|
|
.It Xr uplcom 4
|
|
Prolific PL-2303 USB serial adapter
|
|
.It Xr uslsa 4
|
|
Silicon Laboratories CP2101/CP2102 based USB serial adapter
|
|
.It Xr uvisor 4
|
|
USB Handspring Visor
|
|
.It Xr uvscom 4
|
|
SUNTAC Slipper U VS-10U USB serial adapter
|
|
.It Xr uxrcom 4
|
|
Exar XR21V141x USB serial adapter
|
|
.El
|
|
.Ss Cellular WAN interfaces
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr u3g 4
|
|
USB 3G modems
|
|
.It Xr uhmodem 4
|
|
Huawei 3G wireless modems
|
|
.It Xr uhso 4
|
|
Option N.V. Wireless WAN modems
|
|
.It Xr umb 4
|
|
USB Mobile Broadband Interface Model (MBIM) devices
|
|
.El
|
|
.Ss Audio devices
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr uaudio 4
|
|
USB audio devices
|
|
.It Xr umidi 4
|
|
USB MIDI devices
|
|
.El
|
|
.Ss Radio receiver devices
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr slurm 4
|
|
Silicon Labs USB FM radios
|
|
.It Xr udsbr 4
|
|
D-Link DSB-R100 USB radio device
|
|
.El
|
|
.Ss Human Interface Devices
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr uatp 4
|
|
Apple trackpads
|
|
.It Xr uep 4
|
|
eGalax touch panel controllers
|
|
.It Xr uhid 4
|
|
Generic driver for Human Interface Devices
|
|
.It Xr uhidev 4
|
|
Base driver for all Human Interface Devices
|
|
.It Xr uintuos 4
|
|
Wacom Intuos drawing tablets
|
|
.It Xr ukbd 4
|
|
USB keyboards that follow the boot protocol
|
|
.It Xr ums 4
|
|
USB mouse devices
|
|
.It Xr uthum 4
|
|
TEMPer and TEMPerHUM temperature and humidity sensors
|
|
.It Xr uts 4
|
|
Generic driver for touchscreens and touch digitizers
|
|
.El
|
|
.Ss Miscellaneous devices
|
|
.Bl -tag -width 12n -offset ind -compact
|
|
.It Xr stuirda 4
|
|
Sigmaltel 4116/4220 USB-IrDA bridge
|
|
.It Xr ualea 4
|
|
USB Araneus Alea I/II random number generators
|
|
.It Xr uberry 4
|
|
Battery charging RIM BlackBerry phones via USB
|
|
.It Xr udl 4
|
|
DisplayLink DL-1x0/1x5 USB display devices
|
|
.\" .It Xr udsir 4
|
|
.\" KingSun/DonShine USB IrDA bridge
|
|
.It Xr ugen 4
|
|
USB generic devices
|
|
.It Xr uipad 4
|
|
Battery charging iOS devices via USB
|
|
.It Xr uirda 4
|
|
USB IrDA bridges
|
|
.It Xr upl 4
|
|
Prolific based host-to-host adapters
|
|
.It Xr usscanner 4
|
|
SCSI-over-USB scanners
|
|
.It Xr ustir 4
|
|
SigmaTel STIr4200 USB IrDA bridges
|
|
.It Xr utoppy 4
|
|
Topfield TF5000PVR range of digital video recorders
|
|
.El
|
|
.Sh INTRODUCTION TO USB
|
|
The USB 1.x is a 12 Mb/s serial bus with 1.5 Mb/s for low speed devices.
|
|
USB 2.x handles 480 Mb/s.
|
|
Each 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 1
|
|
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 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 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 structures and defines.
|
|
.Bd -literal
|
|
#include <dev/usb/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 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 {
|
|
uint8_t udi_bus;
|
|
uint8_t udi_addr;
|
|
usb_event_cookie_t udi_cookie;
|
|
char udi_product[USB_MAX_ENCODED_STRING_LEN];
|
|
char udi_vendor[USB_MAX_ENCODED_STRING_LEN];
|
|
char udi_release[8];
|
|
char udi_serial[USB_MAX_ENCODED_STRING_LEN];
|
|
uint16_t udi_productNo;
|
|
uint16_t udi_vendorNo;
|
|
uint16_t udi_releaseNo;
|
|
uint8_t udi_class;
|
|
uint8_t udi_subclass;
|
|
uint8_t udi_protocol;
|
|
uint8_t udi_config;
|
|
uint8_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];
|
|
uint8_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 ,
|
|
.Va release ,
|
|
and
|
|
.Va serial
|
|
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 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 have 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
|
|
.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 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
|
|
.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 (HID).
|
|
.Sh USB EVENT INTERFACE
|
|
All 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
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The
|
|
.Va ue_bus
|
|
contains the number of the 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).
|
|
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
|
|
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
|
|
.Xr usbhidaction 1 ,
|
|
.Xr usbhidctl 1 ,
|
|
.Xr cardbus 4 ,
|
|
.Xr ehci 4 ,
|
|
.Xr isa 4 ,
|
|
.Xr ohci 4 ,
|
|
.Xr pci 4 ,
|
|
.Xr pcmcia 4 ,
|
|
.Xr slhci 4 ,
|
|
.Xr uhci 4 ,
|
|
.Xr xhci 4 ,
|
|
.Xr usbdevs 8
|
|
.Rs
|
|
.%T Universal Serial Bus Specifications Documents
|
|
.%U http://www.usb.org/developers/docs/
|
|
.Re
|
|
.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.
|