Nick Hibma <n_hibma@FreeBSD.org>. 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. Neither the name of the author nor the names of any co-contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY NICK HIBMA 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 NICK HIBMA OR THE VOICES IN HIS HEAD
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.
Copyright (c) 2008 Hans Petter Selasky. 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.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
$FreeBSD: head/share/man/man4/usb.4 192551 2009-05-21 17:26:20Z thompsa $
.Dd May 20, 2009 .Dt USB 4 .Os .Sh NAME .Nm usb .Nd Universal Serial Bus .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: d -ragged -offset indent .Cd "device usb" .Ed
p Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : d -literal -offset indent usb_load="YES" .Ed .Sh USERLAND PROGRAMMING USB functions can be accessed from userland through the libusb library. See .Xr libusb 3 for more information. .Sh DESCRIPTION .Fx provides machine-independent bus support and drivers for .Tn USB devices in host and device side mode.
p The .Nm driver has three layers: l -tag t USB Controller (Bus) t USB Device t USB Driver .El
p 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 controller. Any devices attached to the bus will attach to the root hub or another hub attached to the .Tn USB bus.
p The .Nm uhub device will always be present as it is needed for the root hub. .Sh INTRODUCTION TO USB The .Tn USB is a system where external devices can be connected to a PC. The most common USB speeds are: l -tag t Low Speed (1.5MBit/sec) t Full Speed (12MBit/sec) t High Speed (480MBit/sec) .El
p Each .Tn USB has a USB controller that is the master of the bus. The physical communication is simplex which means the host controller only communicates with one USB device at a time.
p There can be up to 127 devices connected to an USB HUB tree. The addresses are assigned dynamically by the host when each device is attached to the bus.
p 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: .Em control , isochronous , bulk , or .Em 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.
p 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.
p A device may operate in different configurations. Depending on the configuration, the device may present different sets of endpoints and interfaces.
p The bus enumeration of the .Tn USB bus proceeds in several steps: l -enum t Any interface specific driver can attach to the device. t If none is found, generic interface class drivers can attach. .El .Sh USB KERNEL PROGRAMMING Here is a list of commonly used functions:
p . .Ft "usb2_error_t" .Fo "usb2_transfer_setup" .Fa "udev" .Fa "ifaces" .Fa "pxfer" .Fa "setup_start" .Fa "n_setup" .Fa "priv_sc" .Fa "priv_mtx" .Fc .
p . .Ft "void" .Fo "usb2_transfer_unsetup" .Fa "pxfer" .Fa "n_setup" .Fc .
p . .Ft "void" .Fo "usb2_transfer_start" .Fa "xfer" .Fc .
p . .Ft "void" .Fo "usb2_transfer_stop" .Fa "xfer" .Fc .
p . .Ft "void" .Fo "usb2_transfer_drain" .Fa "xfer" .Fc . . .Sh DESCRIPTION The .Nm module implements the core functionality of the USB standard and many helper functions to make USB device driver programming easier and more safe. . The .Nm module supports both USB Host and USB Device side mode! . .Sh 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: .
p . .Fn usb2_transfer_setup This function will allocate memory for and initialise an array of USB transfers and all required DMA memory. . This function can sleep or block waiting for resources to become available. .Fa udev is a pointer to "struct usb2_device". .Fa ifaces is an array of interface index numbers to use. See "if_index". .Fa pxfer is a pointer to an array of USB transfer pointers that are initialized to NULL, and then pointed to allocated USB transfers. .Fa setup_start is a pointer to an array of USB config structures. .Fa n_setup is a number telling the USB system how many USB transfers should be setup. .Fa priv_sc is the private softc pointer, which will be used to initialize "xfer->priv_sc". .Fa 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. .
p . .Fn usb2_transfer_unsetup This function will release the given USB transfers and all allocated resources associated with these USB transfers. .Fa pxfer is a pointer to an array of USB transfer pointers, that may be NULL, that should be freed by the USB system. .Fa 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. .
p . .Fn usb2_transfer_start This function will start the USB transfer pointed to by .Fa 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. .
p . .Fn usb2_transfer_stop This function will stop the USB transfer pointed to by .Fa 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 function 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". .
p . .Fn 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. . .Sh 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 recursion. . That means one can start and stop whatever transfer from the callback of another transfer one desires. . Also the transfer that is currently called back. . Recursion is handled like this that when the callback that wants to recurse returns it is called one more time. . .
p . .Fn 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 complete "frlengths[]" is updated to the actual USB transfer length for the given frame. d -literal -offset indent 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; } .Ed . .Sh 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. . d -literal -offset indent 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); .Ed .Sh USB TRANSFER CONFIG To simply the search for endpoints the .Nm module defines a USB config structure where it is possible to specify the characteristics of the wanted endpoint. d -literal -offset indent struct usb2_config { bufsize, callback direction, endpoint, frames, index flags, interval, timeout, type, }; .Ed .
p .Fa 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. .
p .Fa 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. .
p .Fa 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. .
p .Fa 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: l -tag t UE_INTERRUPT "0" use the default interrupt interval based on endpoint descriptor. "Else" use the given value for polling rate. t UE_ISOCHRONOUS "0" use default. "Else" the value is ignored. t UE_BULK t 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.
p NOTE: The transfer timeout, if any, is started after that the pre-delay has elapsed! .El .
p .Fa timeout field, if non-zero, will set the transfer timeout in milliseconds. If the "timeout" field is zero and the transfer type is ISOCHRONOUS a timeout of 250ms will be used. .
p .Fa frames field sets the maximum number of frames. If zero is specified it will yield the following results: l -tag t UE_BULK xfer->nframes = 1; t UE_INTERRUPT xfer->nframes = 1; t UE_CONTROL xfer->nframes = 2; t UE_ISOCHRONOUS Not allowed. Will cause an error. .El .
p .Fa 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. .
p .Fa 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. .
p .Fa flags field has type "struct usb2_xfer_flags" and allows one to set initial flags an USB transfer. Valid flags are: l -tag t 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 "wMaxPacketSize". This flag can be changed during operation. t short_xfer_ok This flag allows the received transfer length, "xfer->actlen" to be less than "xfer->sumlen" upon completion of a transfer. This flag can be changed during operation. t short_frames_ok This flag allows the reception of multiple short USB frames. This flag only has effect for BULK and INTERRUPT endpoints and if the number of frames received is greater than 1. This flag can be changed during operation. t 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: l -tag t 1 The failing USB transfer is stopped using "usb2_transfer_stop()". t 2 The failing USB transfer performs a successful transfer. .El 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 executed at the same time the clear-stall command is executed on the USB control endpoint. . This flag can be changed during operation.
p "BOF" is short for "Block On Failure"
p 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. . . t 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. . . t 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. . . t 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. . . t no_pipe_ok Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This flag can not be changed during operation. . . t stall_pipe l -tag t Device Side Mode Setting this flag will cause STALL pids to be sent to the endpoint belonging to this transfer 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. t Host Side Mode Setting this flag will cause a clear-stall control request to be executed on the endpoint before the USB transfer is started. .El
p 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! This flag is automatically cleared after that the stall or clear stall has been executed. . .El
p .Fa 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 interrupt pipes. . This field is mandatory.
p NOTE: For control transfers "bufsize" includes the length of the request structure. .
p .Fa callback pointer sets the USB callback. This field is mandatory. . . .Sh USB LINUX COMPAT LAYER The .Nm module supports the Linux USB API. . . . .Sh SEE ALSO The .Tn USB specifications can be found at:
p .D1 Pa http://www.usb.org/developers/docs/
p .Xr libusb 3 , .Xr aue 4 , .Xr axe 4 , .Xr cue 4 , .Xr ehci 4 , .Xr kue 4 , .Xr ohci 4 , .Xr pci 4 , .Xr rue 4 , .Xr ucom 4 , .Xr udav 4 , .Xr uhci 4 , .Xr uhid 4 , .Xr ukbd 4 , .Xr ulpt 4 , .Xr umass 4 , .Xr ums 4 , .Xr uplcom 4 , .Xr urio 4 , .Xr uvscom 4 , .Xr usbconfig 8 .Sh STANDARDS The .Nm module complies with the USB 2.0 standard. .Sh HISTORY The .Nm module has been inspired by the NetBSD USB stack initially written by Lennart Augustsson. The .Nm module was written by .An Hans Petter Selasky Aq hselasky@freebsd.org .