usbdcore(7)

SYNOPSIS
usbd

DESCRIPTION
This page gives an overview of the USB Device support system from a programmer's perspective.

The USB Device subsystem is divided into three layers: bus interface (lowest) core (middle) function (highest)

USB TERMINOLOGY
This section stnadardizes USB architecture elements for the purposes of the Lineo USB Device Framework. This terminology is largely consistent with the relevant documents of the USB Forum and of usage elswehere.

Since USB is an asymmetrical protocol, with greatly differing architecture at the host (PC) side and device (peripheral) side, it is convenient to use different terms for parallel layers of the architecture at each end.

This document gives only the briefest overview of how standard USB architecture is reflected in the framework. Refer to standards documents and other publications for more detailed information.

The basic idea of USB architecture is the same at both the host and device ends. There is a low layer, which is mostly a data pump, and a high layer, which is shielded from most but not all aspects ofthe lower layer.

On the host side, the host sees a root hub which has 0 or more devices connected to it. Certain conditions, such as conmnecting or detaching a USB device, will trigger an enumeration. This is the process by which the host determines what devices are physically present, which configurations the devices offer, and matches (if possible) the devices with suitable class drivers on the host side.

USB multiplexes multiple data streams known as endpoints which may be of four types: isochronous, control, bulk, and interrupt The first, isochronous, is special-purpose and will not be discussed further. Each device has exactly 1 control endpoint, also known as endpoint 0. Most devices will also have two bulk endpoints, one in each direction, for normal data flow. This may include setup activity above the USB layer. Finally, there may be a fourth interrupt endpoint available on some devices for out-of-band data. The principal use of this is flow control. Many particular USB architectures of interest do not support this type of endpoint.

USB data is sent over the wire in short packets, During the setup (enumeration) phase, packets are limited in size to what will fit into 1 packet. For The enumeration phase takes place over this endpoint. In some USB architectures, the USB interface chip assumes all responsibility for this.

GENERAL
Originally, the idea of USB was that devices would be divided into a small number of classes (human interface device [mouse/trackball], communications, storage, etc) and that the host would only need support for 1 mouse device, 1 network device. and so on. Thus, function ids were envisaged as a mechanism for host class drivers to match

However, the USB standard was rushed into use before the definitions of the
 device classes were complete, and with respect to 802.3 network and serial drivers, the situation has not improved. Therefore, currently available host drivers recognize cooperating peripherals soley on the basis of vendorid and productid. This requires a new generation of host drivers to be issued when a new product is issued, From this point of view, a firmware upgrade can look like a different product.

ARCHITECTURE
       USB Host                      USB Device
----------------+                  +-------------------
   Class driver | <-- logical  --> | Function driver
----------------|                  |-------------------
       USB Host |                  | USB Device
     Core layer |                  | Core layer
----------------|                  |-------------------
 Host interface |                  | Bus interface
         driver | <-- physical --> | driver
----------------+                  +------------------

FUNCTION LAYER

To implement a Function to work with a corresponding Class driver on the USB host.

Generally speaking the Function driver sits between the USB Device support and the rest of the operating system implementing some other type of driver. For example it might implement a serial or network driver that allows it to pass data to the USB host in either a serial data stream or as network frames.

BUS INTERFACE LAYER

To support USB on a new hardware architecture,

ENDPOINT ZERO

A special limited function driver is builtin to the USB Device core layer to handle Standard Device Requests sent to Endpoint Zero. (See Section 9.4 Standard Device Requests in the USB Specification.)

This function driver handles typically handles all requests sent by the USB host during the enumeration process.

It cannot by definition handle Vendor requests. Any Function that requires support for Vendor requests must implement the Function driver function recv_setup().

ENDPOINT ARCHITECTURE

The Function driver defines and describes the Endpoints that it requires.

For each endpoint the USB Device core maintains transmit and receive queues for urbs for each endpoint.

An urb is a structure containing data that is to be sent to the USB host when requested (the host sent an IN token), or data that was sent from the USB host (the sent an OUT token followed by data).

For sending the Function driver prepares an urb and gives it to the USB Device core layer using the usbd_send_urb() function. This simply places the urb into the transmit queue for the specified endpoint and notifies the Bus Interface driver using the send_urb() function. The Bus Interface driver transmit interrupt handler will manage the sending of the data and signal that the urb has been sent using the usbd_urb_sent_irq() function.

For receiving the Bus Interface driver will fill an urb until it sees the end of a bulk transfer (signalled by a USB packet less than the full packetsize or by reaching the maximum transfer size for the endpoint). It will then call the usbd_rcv_complete_irq() function. This function will put the urb into the receive queue and schedule the USB Device core layer bottom half handler usbd_device_bh().

The bottom half handler runs as kernel task process (the equivalent of an interrupt context but at a lower priority). The bottom half handler will remove urbs from the receive queue and pass them to the Function driver using it's recv_urb() function.

USBCORE SERVICES TO FUNCTION MODULES

Function Driver Registration

int
usbd_register_function(struct usb_function_driver *);

    Called by a Function driver to register with the USB Device core layer.

void
usbd_deregister_function(struct usb_function_driver *);

    Called by a Function driver to deregister with the USB Device core layer.

Bus Interface Driver Registration

struct usb_bus_instance *
usbd_register_bus(struct usb_bus_driver *);

    Called by a Bus Interface driver to register with the USB Device core layer.

void
usbd_deregister_bus(struct usb_bus_driver *);

    Called by a Bus Interface driver to deregister with the USB Device core layer.

USB Device Registration

struct usb_device_instance *
usbd_register_device(char *, struct usb_bus_instance *, int);

    Called by a Bus Interface driver to register with the USB Device core layer.

void
usbd_deregister_device(struct usb_bus_instance *);

    Called by a Bus Interface driver to deregister with the USB Device core layer.

Commonly Used Functions

struct urb *
usbd_alloc_urb(struct usb_device_instance *,
	struct usb_function_instance *,
	__u8 endpoint,
	int length );

    Called to allocate an URB. The USB Device core layer will call the Function driver alloc_urb_data() function if defined to allocate required data storage.

void
usbd_dealloc_urb(struct urb *);

    Called to deallocate an URB. The USB Device core layer will call the Function driver dealloc_urb_data() function if defined to deallocate the data storage.

Functions Used by Endpoint Zero Driver

int
usbd_endpoint_halted(struct usb_device_instance *, int);

    Called by a Endpoint Zero driver to check if an endpoint is halted in response to a Standard Device Request (see section 9.4 Standard Device Requests and 9.4.5 Get Status in the USB specification). The USB Device core layer will call the Bus driver endpoint_halted() function.

int
usbd_device_feature(struct usb_device_instance *, int, int);

    Called by a Endpoint Zero driver to set a feature as requested by the USB host with a Standard Device Request (see section 9.4 Standard Device Requests and 9.4.r Set Feature in the USB specification). USB Device core layer. The USB Device core layer will call the Bus driver device_feature() function.

Functions Used by Function Drivers

int usbd_send_urb(struct urb *);

    Called by a Function driver to send an urb.

int usbd_cancel_urb(struct urb *);

    Called by a Function driver to cancel a previously sent urb.

Functions Used by Bus Interface Drivers

void
usbd_device_event_irq(struct usb_device_instance *conf, usb_device_event_t);
void
usbd_device_event(struct usb_device_instance *conf, usb_device_event_t);

    Called by a Bus Interface driver to notify the USB Device core layer of an event. The USB Device core layer will pass the event to the Bus driver driver_event() function and Function driver event() functions.

    The _irq version can be used from interrupt context or where interrupts are disabled.

struct urb *
usbd_next_rcv_urb(struct usb_endpoint_instance *);

    Called by a Bus Interface to get the next available urb for receiving into.

 int usbd_recv_setup(struct urb *);

    Called by a Bus Interface driver to pass a setup packet up to the USB Device core layer which will call the Function driver recv_setup() function.

void usbd_rcv_complete_irq(struct usb_endpoint_instance *, int );

    Called by a Bus Interface driver to tell the USB Device core layer that it has received some data. The USB Device core layer will determine if the end of a bulk transfer has been detected and setup the endpoint to receive more data.

 void usbd_tx_complete_irq(struct usb_endpoint_instance *, int );

    Called by a Bus Interface driver to tell the USB Device core layer that it has finished transmitting all of the data in an urb. The USB Device core layer will notify the Function driver using the recv_urb() function.

AUTHOR

Stuart Lynne <sl@lineo.com>

Bruce Balden <balden@lineo.com>

Tom Rushworth <tbr@lineo.com>

SEE ALSO

usbdbus(7), usbdfunc(7), usbd(8), usbdcore(8)

Universal Serial Bus Specification, Revision 2.0

Universal Serial Bus Class Definitions for Communications Devices, Version 1.1