USB2_CORE(4) FreeBSD Kernel Interfaces Manual USB2_CORE(4)
NAME
usb2_core -- USB core functions
SYNOPSIS
To compile this module into the kernel, place the following line in your kernel
configuration file:
device usb2_core
To load the module at boot time, place the following line in loader.conf(5):
usb2_core_load="YES"
Here is a list of commonly used functions:
usb2_error_t usb2_transfer_setup(udev, ifaces, pxfer, setup_start, n_setup, priv_sc,
priv_mtx);
void usb2_transfer_unsetup(pxfer, n_setup);
void usb2_transfer_start(xfer);
void usb2_transfer_stop(xfer);
void usb2_transfer_drain(xfer);
DESCRIPTION
The usb2_core module implements the core functionality of the USB stan- dard and many
helper functions to make USB device driver programming eas- ier and more safe. The
usb2_core module supports both USB Host and USB Device side mode!
USB TRANSFER MANAGEMENT FUNCTIONS
The USB standard defines four types of USB transfers. Control transfers, Bulk
transfers, Interrupt transfers and Isochronous transfers. All the transfer types are
managed using the following five functions:
usb2_transfer_setup() This function will allocate memory for and ini- tialise an
array of USB transfers and all required DMA memory. This function can sleep or block
waiting for resources to become available. udev is a pointer to "struct
usb2_device". ifaces is an array of inter- face index numbers to use. See
"if_index". pxfer is a pointer to an array of USB transfer pointers that are
initialized to NULL, and then pointed to allocated USB transfers. setup_start is a
pointer to an array of USB config structures. n_setup is a number telling the USB
system how many USB transfers should be setup. priv_sc is the private softc pointer,
which will be used to initialize "xfer->priv_sc". priv_mtx is the private mutex
protecting the transfer structure and the softc. This pointer is used to initialize
"xfer->priv_mtx". This function returns zero upon success. A non-zero return value
indicates failure.
usb2_transfer_unsetup() This function will release the given USB trans- fers and all
allocated resources associated with these USB transfers. pxfer is a pointer to an
array of USB transfer pointers, that may be NULL, that should be freed by the USB
system. n_setup is a number telling the USB system how many USB transfers should be
unsetup. This function can sleep waiting for USB transfers to complete. This
function is NULL safe with regard to the USB transfer structure pointer. It is not
allowed to call this function from the USB transfer callback.
usb2_transfer_start() This function will start the USB transfer pointed to by xfer,
if not already started. This function is always non-blocking and must be called with
the so-called private USB mutex locked. This function is NULL safe with regard to
the USB transfer structure pointer.
usb2_transfer_stop() This function will stop the USB transfer pointed to by xfer, if
not already stopped. This function is always non-blocking and must be called with
the so-called private USB mutex locked. This function can return before the USB
callback has been called. This func- tion is NULL safe with regard to the USB
transfer structure pointer. If the transfer was in progress, the callback will
called with "USB_ST_ERROR" and "xfer->error = USB_ERR_CANCELLED".
usb2_transfer_drain() This function will stop an USB transfer, if not already stopped
and wait for any additional USB hardware operations to complete. Buffers that are
loaded into DMA using "usb2_set_frame_data()" can safely be freed after that this
function has returned. This function can block the caller and will not return before
the USB callback has been called. This function is NULL safe with regard to the USB
transfer structure pointer.
USB TRANSFER CALLBACK
The USB callback has three states. USB_ST_SETUP, USB_ST_TRANSFERRED and
USB_ST_ERROR. USB_ST_SETUP is the initial state. After the callback has been called
with this state it will always be called back at a later stage in one of the other
two states. In the USB_ST_ERROR state the "error" field of the USB transfer
structure is set to the error cause. The USB callback should not restart the USB
transfer in case the error cause is USB_ERR_CANCELLED. The USB callback is protected
from recur- sion. That means one can start and stop whatever transfer from the call-
back of another transfer one desires. Also the transfer that is cur- rently called
back. Recursion is handled like this that when the call- back that wants to recurse
returns it is called one more time.
usb2_start_hardware() This function should only be called from within the USB
callback and is used to start the USB hardware. Typical parameters that should be
set in the USB transfer structure before this function is called are "frlengths[]",
"nframes" and "frbuffers[]". An USB transfer can have multiple frames consisting of
one or more USB packets making up an I/O vector for all USB transfer types. After
the USB transfer is com- plete "frlengths[]" is updated to the actual USB transfer
length for the given frame.
void usb2_default_callback(struct usb2_xfer *xfer) {
switch (USB_GET_STATE(xfer)) { case USB_ST_SETUP:
/*
* Setup xfer->frlengths[], xfer->nframes * and write data to
xfer->frbuffers[], if any */
usb2_start_hardware(xfer); break;
case USB_ST_TRANSFERRED:
/*
* Read data from xfer->frbuffers[], if any. *
"xfer->frlengths[]" should now have been * updated to the
actual length. */
break;
default: /* Error */
/*
* Print error message and clear stall * for example. */
break;
} /*
* Here it is safe to do something without the private * USB mutex
locked. */
return;
}
USB CONTROL TRANSFERS
An USB control transfer has three parts. First the SETUP packet, then DATA packet(s)
and then a STATUS packet. The SETUP packet is always pointed to by
"xfer->frbuffers[0]" and the length is stored in "xfer->frlengths[0]" also if there
should not be sent any SETUP packet! If an USB control transfer has no DATA stage,
then "xfer->nframes" should be set to 1. Else the default value is "xfer->nframes"
equal to 2.
Example1: SETUP + STATUS
xfer->nframes = 1; xfer->frlenghts[0] = 8; usb2_start_hardware(xfer);
Example2: SETUP + DATA + STATUS
xfer->nframes = 2; xfer->frlenghts[0] = 8; xfer->frlenghts[1] = 1;
usb2_start_hardware(xfer);
Example3: SETUP + DATA + STATUS - split 1st callback:
xfer->nframes = 1; xfer->frlenghts[0] = 8; usb2_start_hardware(xfer);
2nd callback:
/* IMPORTANT: frbuffers[0] must still point at the setup packet! */
xfer->nframes = 2; xfer->frlenghts[0] = 0; xfer->frlenghts[1] = 1;
usb2_start_hardware(xfer);
Example4: SETUP + STATUS - split 1st callback:
xfer->nframes = 1; xfer->frlenghts[0] = 8; xfer->flags.manual_status = 1;
usb2_start_hardware(xfer);
2nd callback:
xfer->nframes = 1; xfer->frlenghts[0] = 0; xfer->flags.manual_status = 0;
usb2_start_hardware(xfer);
USB TRANSFER CONFIG
To simply the search for endpoints the usb2_core module defines a USB config
structure where it is possible to specify the characteristics of the wanted endpoint.
struct usb2_config {
bufsize, callback direction, endpoint, frames, index flags, interval,
timeout, type,
};
type field selects the USB pipe type. Valid values are: UE_INTERRUPT, UE_CONTROL,
UE_BULK, UE_ISOCHRONOUS. The special value UE_BULK_INTR will select BULK and
INTERRUPT pipes. This field is mandatory.
endpoint field selects the USB endpoint number. A value of 0xFF, "-1" or
"UE_ADDR_ANY" will select the first matching endpoint. This field is mandatory.
direction field selects the USB endpoint direction. A value of "UE_DIR_ANY" will
select the first matching endpoint. Else valid values are: "UE_DIR_IN" and
"UE_DIR_OUT". "UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which
means that the direction will be swapped in case of USB_MODE_DEVICE. Note that
"UE_DIR_IN" refers to the data transfer direction of the "IN" tokens and "UE_DIR_OUT"
refers to the data transfer direction of the "OUT" tokens. This field is mandatory.
interval field selects the interrupt interval. The value of this field is given in
milliseconds and is independent of device speed. Depending on the endpoint type,
this field has different meaning:
UE_INTERRUPT "0" use the default interrupt interval based on endpoint
descriptor. "Else" use the given value for polling rate.
UE_ISOCHRONOUS
"0" use default. "Else" the value is ignored.
UE_BULK
UE_CONTROL "0" no transfer pre-delay. "Else" a delay as given by this
field in milliseconds is inserted before the hardware is started when
"usb2_start_hardware()" is called.
NOTE: The transfer timeout, if any, is started after that the pre-delay
has elapsed!
timeout field, if non-zero, will set the transfer timeout in millisec- onds. If the
"timeout" field is zero and the transfer type is ISOCHRONOUS a timeout of 250ms will
be used.
frames field sets the maximum number of frames. If zero is specified it will yield
the following results:
UE_BULK xfer->nframes = 1;
UE_INTERRUPT xfer->nframes = 1;
UE_CONTROL xfer->nframes = 2;
UE_ISOCHRONOUS
Not allowed. Will cause an error.
ep_index field allows you to give a number, in case more endpoints match the
description, that selects which matching "ep_index" should be used.
if_index field allows you to select which of the interface numbers in the "ifaces"
array parameter passed to "usb2_transfer_setup" that should be used when setting up
the given USB transfer.
flags field has type "struct usb2_xfer_flags" and allows one to set ini- tial flags
an USB transfer. Valid flags are:
force_short_xfer
This flag forces the last transmitted USB packet to be short. A short
packet has a length of less than "xfer->max_packet_size", which derives
from "wMaxPacket- Size". This flag can be changed during operation.
short_xfer_ok
This flag allows the received transfer length, "xfer->actlen" to be
less than "xfer->sumlen" upon comple- tion of a transfer. This flag
can be changed during opera- tion.
pipe_bof This flag causes a failing USB transfer to remain first in
the PIPE queue except in the case of "xfer->error" equal to
"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue
will be started until either:
1 The failing USB transfer is stopped using
"usb2_transfer_stop()".
2 The failing USB transfer performs a success-
ful transfer.
The purpose of this flag is to avoid races when multiple transfers are
queued for execution on an USB endpoint, and the first executing
transfer fails leading to the need for clearing of stall for example.
In this case this flag is used to prevent the following USB transfers
from being exe- cuted at the same time the clear-stall command is
executed on the USB control endpoint. This flag can be changed dur-
ing operation.
"BOF" is short for "Block On Failure"
NOTE: This flag should be set on all BULK and INTERRUPT USB transfers
which use an endpoint that can be shared between userland and kernel.
proxy_buffer Setting this flag will cause that the total buffer size
will be rounded up to the nearest atomic hardware transfer size. The
maximum data length of any USB transfer is always stored in the
"xfer->max_data_length". For control transfers the USB kernel will
allocate additional space for the 8-bytes of SETUP header. These
8-bytes are not counted by the "xfer->max_data_length" variable. This
flag can not be changed during operation.
ext_buffer Setting this flag will cause that no data buffer will be
allocated. Instead the USB client must supply a data buffer. This
flag can not be changed during operation.
manual_status
Setting this flag prevents an USB STATUS stage to be appended to the
end of the USB control transfer. If no control data is transferred
this flag must be cleared. Else an error will be returned to the USB
callback. This flag is mostly useful for the USB device side. This
flag can be changed during operation.
no_pipe_ok Setting this flag causes the USB_ERR_NO_PIPE error to be
ignored. This flag can not be changed during operation.
stall_pipe
Device Side Mode
Setting this flag will cause STALL pids to be sent to the
endpoint belonging to this trans- fer before the transfer
is started. The transfer is started at the moment the
host issues a clear-stall command on the STALL'ed
endpoint. This flag can be changed during operation.
Host Side Mode
Setting this flag will cause a clear-stall control
request to be executed on the end- point before the USB
transfer is started.
If this flag is changed outside the USB callback function you have to
use the "usb2_transfer_set_stall()" and "usb2_transfer_clear_stall()"
functions !
bufsize field sets the total buffer size in bytes. If this field is zero,
"wMaxPacketSize" will be used, multiplied by the "frames" field if the transfer type
is ISOCHRONOUS. This is useful for setting up inter- rupt pipes. This field is
mandatory.
NOTE: For control transfers "bufsize" includes the length of the request structure.
callback pointer sets the USB callback. This field is mandatory.
USB LINUX COMPAT LAYER
The usb2_core module supports the Linux USB API.
USB SECURITY MODEL
The usb2_core module implements fine grained read and write access based on username
and group. Access is granted at four levels:
Level 4 - USB interface
USB interfaces can be given individual access rights.
Level 3 - USB device
USB devices can be given individual access rights.
Level 2 - USB BUS
USB busses can be given individual access rights.
Level 1 - USB
USB as a whole can be given individual access rights.
The usb2_core module will search for access rights starting at level 4 continuing
downwards to USB at level 1. For critical applications you should be aware that the
outgoing serial BUS traffic will be broadcasted to all USB devices. For absolute
security USB devices that require dif- ferent access rights should not be placed on
the same USB BUS or con- troller. If connected to the same USB bus, it is possible
that a USB device can sniff and intercept the communication of another USB device.
Using USB HUBs will not solve this problem.
SEE ALSO
usb2_controller(4) usbconfig(8)
STANDARDS
The usb2_core module complies with the USB 2.0 standard.
HISTORY
The usb2_core module has been inspired by the NetBSD USB stack initially written by
Lennart Augustsson. The usb2_core module was written by Hans Petter Selasky
.