usb(4)

NAME

usb - Universal Serial Bus

SYNOPSIS

device usb
#include <dev/usb/usb.h>
#include <dev/usb/usbhid.h>

DESCRIPTION

FreeBSD provides machine-independent bus support and drivers
for USB devices.
The usb driver has three layers: the controller, the bus,
and the device layer. The controller attaches to a physical bus (like
pci(4)). The 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.
The uhub device will always be present as it is needed for
the root hub.

INTRODUCTION TO USB

The USB is a 12 Mb/s serial bus (1.5 Mb/s for low speed de
vices). Each USB has a host controller that is the master of the bus; all
other devices on the bus only speak when spoken to.
There can be up to 127 devices (apart from the host con
troller) on a bus, each with its own address. The addresses are assigned dy
namically by the host when each device is attached to the bus.
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 end
point and is used to give commands to and extract basic data, such as descrip
tors, from the device. Each endpoint, except the control endpoint, is uni
directional.
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 set
tings, which affects how it operates. Different alternate settings can
have different endpoints within it.
A device may operate in different configurations. Depending
on the configuration, the device may present different sets of end
points and interfaces.
The bus enumeration of the USB bus proceeds in several
steps:
1. Any device specific driver can attach to the device.
2. If none is found, any device class specific driver can
attach.
3. 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.
4. If still no drivers have been found, the generic USB
driver can attach.

USB CONTROLLER INTERFACE

Use the following to get access to the USB specific struc
tures and defines.
The /dev/usbN can be opened and a few operations can be per
formed on it. The 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.
The following ioctl(2) commands are supported on the con
troller device:
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.
USB_DEVICEINFO struct usb_device_infoThis command can be used to retrieve some informa
tion about a
device on the bus. The udi_addr field should be
filled before the call and the other fields will be filled by in
formation about the device on that address. Should no such device
exist, an error is reported.
#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_prod
uct[USB_MAX_STRING_LEN]; char udi_ven
dor[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 3int udi_power;/* power consump
tion in mA, 0 if selfpowered */ int udi_nports; char udi_devnames[USB_MAX_DEV
NAMES][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 };
udi_bus and udi_addr contain the topological infor
mation for the
device. udi_devnames contains the device names of
the connected drivers. For example, the third USB Zip drive con
nected will be
umass2. The udi_product, udi_vendor and udi_release
fields contain self-explanatory descriptions of the device.
udi_productNo,
udi_vendorNo, udi_releaseNo, udi_class, udi_subclass
and
udi_protocol contain the corresponding values from
the device
descriptors. The udi_config field shows the current
configuration of the device.
udi_speed indicates whether the device is at low
speed (USB_SPEED_LOW), full speed (USB_SPEED_FULL) or high
speed
(USB_SPEED_HIGH). The udi_power field shows the
power consumption in milli-amps drawn at 5 volts, or zero if the
device is self powered.
If the device is a hub, the udi_nports field is non
zero, and the
udi_ports field contains the addresses of the con
nected devices. If no device is connected to a port, one of the
USB_PORT_* values indicates its status.
USB_DEVICESTATS struct usb_device_statsThis command retrieves statistics about the con
troller.
struct usb_device_stats { u_long uds_requests[4];
};
The udi_requests field is indexed by the transfer
kind, i.e. UE_*, and indicates how many transfers of each kind
that has been completed by the controller.
USB_REQUEST struct usb_ctl_requestThis command can be used to execute arbitrary re
quests on the control pipe. This is DANGEROUS and should be used
with great care since it can destroy the bus integrity.
The include file #include <dev/usb/usb.h> contains definitions for the types used by the various
ioctl(2) calls. The naming convention of the fields for the various USB de
scriptors 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 UGETW(field) and USETW(field, value) macros to handle
byte order and alignment properly.
The include file #include <dev/usb/usbhid.h> similarly contains the definitions for Human Interface De
vices (HID).

USB EVENT INTERFACE

All USB events are reported via the /dev/usb device. This
devices can be opened for reading and each read(2) will yield an event
record (if something has happened). The poll(2) system call can be used to
determine if an event record is available for reading.
The event record has the following definition:
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;
};
The ue_type field identifies the type of event that is de
scribed. 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, USB_EVENT_IS_ATTACH(ue_type) and USB_EVENT_IS_DETACH(ue_type) can be used to determine if an
event was an ``attach'' or a ``detach'' request.
The ue_bus contains the number of the USB bus for host con
troller events.
The ue_device record contains information about the device
in a device event event.
The 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 ue_devname contains the name of the device (driver) as
seen in, e.g., kernel messages.
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.

HISTORY

The usb driver first appeared in FreeBSD 3.0.

AUTHORS

The usb driver was written by Lennart Augustsson <au
gustss@carlstedt.se> for the NetBSD project.
BSD April 20, 2005

docs.sk

comprehensive documentation repository

See also

usb(4)

NAME

SYNOPSIS

DESCRIPTION

INTRODUCTION TO USB

USB CONTROLLER INTERFACE

USB EVENT INTERFACE

SEE ALSO

HISTORY

AUTHORS