Description

	Important
	This eCosPro-USB Middleware package is STRICTLY LICENSED FOR NON-COMMERCIAL PURPOSES ONLY. It may not be used for Commercial purposes in full or in part in any format, including source code, binary code and object code format. A Commercial eCosPro License version 3 (or above) which explicity includes this Middleware Package is required for Commercial use.

The eCosPro-USB package only provides USB functionality for embedded systems. Where USB connectivity between eCos-based USB devices and host systems is required, it is your responsibility to ensure that a suitable host operating system class driver is available. Common host operating systems such as Windows, Linux and OS X include support for several standard USB classes. Unfortunately the specific classes supported varies considerably between them. If a host operating system you wish to support does not provide the necessary class support, then a suitable driver will need to be sourced from a third party USB class provider.

All USB Vendor and Product IDs used within this stack are for testing purposes only. It is your responsibility to obtain and deploy valid identifiers for your product; information about this can be found at the following link: www.usb.org/developers/vendor . It is also your responsibility to undertake any compliance testing needed to use the USB logo. Information regarding the USB-IF compliance program can be found here: http://www.usb.org/developers/compliance/.

Class Support

The individual USB classes are documented in the sections of the eCosPro documentation most relevant to that functionality. For example, information regarding the configuration and use of the Host Mass Storage Class is organized together with other file system related documentation.

Stack Limitations

The eCosPro USB stack stack currently implements a subset of the complete USB functionality. It is intended that it will eventually fully support not just host and target sides of the USB protocol, but also On-The-Go functionality. The current state of the stack is as follows:

Terminology

USB has its own terminology, some of which conflicts with similar terms used in eCos. Some terms are used several times for slightly different but related concepts. The following lists some of the terms used and how they relate to the eCosPro USB stack.

To configure and use the USB stack support, you should mainly refer to the class specific documentation linked to above. The following sections of this document are intended for developers who wish to build a deeper understanding of how the USB stack functions, for example to add their own class support.

Host Support Overview

Host support comprises the USB stack itself, one or more Host Controller Drivers and one or more Class Drivers.

During initialization the USB stack calls the init routine of each HCD. Platform-specific code called by the HCD locates all the instances of that host controller and configures it for host usage. This usually involves supplying power and clocks to the HC, configuring external pin multiplexing and enabling any external PHY, charge pump or power switches. Each HC is then registered with the USB stack as a separate USB bus. The first thing that happens for each bus is that a new device object is created to represent the root hub for that bus. The root hub is a virtual USB hub implemented by the USB stack to control the downstream ports of the HC. The USB stack controls the downstream ports by calling functions in the HCD.

All hubs, including the root hubs, are polled on a regular basis by the USB stack to detect any new device connections. If a new connection is detected then a device object is allocated and initialized. This object is then driven through a state machine that resets the device, assigns an address to it and fetches its device and configuration descriptors. Once this is done the device type is inspected. If it is a hub then the device object is passed over to the hub state machine which fetches further descriptors and starts polling the downstream ports for new connections. If it is not a hub, then the list of registered class drivers is searched for a class driver that recognizes the device type.

Class drivers interact with the device by allocating and initializing USB transfer objects and passing them to the USB stack for execution. Each transfer object identifies the device it applies to together with the endpoint and transfer type. It also points to a data buffer to/from which the data will be transferred and for control messages also contains the SETUP packet. Transfers are passed into the USB stack and are processed asynchronously to the client; completion of a transfer is signalled by calling a callback function in the transfer. The transfer's status indicates whether this was a successful exchange of data, some error has occurred, or the device has been disconnected. At this point the class driver is free to release the transfer, or resubmit it.

Device disconnection usually results in any active transfers receiving an error. It is also noticed by the hub polling machine and results in the device being detached from its parent hub. A call is also made to the class driver, which should then cancel any active transfers, dismantle any device specific data structures and optionally signal the event to its clients in turn.

The existence of transfers and device objects is controlled by reference counts. For each device the presence of the physical device counts as a reference, as should its use by a class driver; each active transfer also counts as a reference. So, when a device is detached, the physical device reference will be removed, but it will only be returned to the free pool once all transfers have completed and the class driver has finished with it. Similarly, transfers are created with a single reference, but the HCD will take one or more references while the transfer is active in the controller. To release a transfer, the class driver simply needs to decrement the reference counter in the completion callback, which will return it to the pool immediately, or maybe a little later when the HCD has finished with it.

Target Support Overview

Target, or peripheral, support comprises the USB stack itself plus one or more Peripheral Controller Drivers. There is currently no equivalent of the host class driver mechanism for targets and instead peripheral functionality is provided by application code. See the acm_example.c source for an example; this can be found in the packages/io/usb/<version>/tests directory.

Initialization of the target USB stack is similar to that for the host stack as far as Peripheral Controller Drivers are concerned. The USB stack calls the init routine of each PCD. Platform-specific code called by the PCD locates all the instances of that peripheral controller and configures them for peripheral usage. This usually involves supplying power and clocks to the Peripheral Controller, configuring external pin multiplexing and enabling any external PHY, charge pump or power switches. For dual mode OTG controllers, much of this can be shared with the host controller mode. Finally, the peripheral controller is registered with the USB stack under a unique name.

Application code instantiates a target by creating a target object and populating it with pointers to device, string and configuration descriptors. Most of this can be done statically, and apart from the target object, can be constant data stored in ROM or flash memory. The target object also contains pointers to a number of callback routines that the USB stack uses to signal events to the application. The target is activated by attaching it to the specific peripheral controller that controls the external USB socket on which the peripheral is to be presented.

The USB stack remains quiescent until the PCD detects that the peripheral port has been attached to a host controller. From this point the USB stack handles most of the initial interaction with the host as it resets the peripheral port, assigns an address and fetches descriptors. Most descriptors will be fetched from those statically defined in the target object, but if any are not found then a callback to the application is made which allows it to manufacture any special descriptors dynamically. Also during this process, callbacks will be made to indicate the progress of the peripheral through the USB peripheral state machine.

Once the target reaches CONFIGURED state it is ready for operation and application code can start exchanging messages with the host. This is done using exactly the same transfer objects as are used in host mode. Each transfer object identifies the endpoint, transfer type and data to be exchanged, and its completion is signalled by calling a callback function. Transfers are controlled by reference counts in the same way as for host support; since the target is statically allocated by the application it is not subject to reference count control in the same way as host device objects.

If the peripheral is detached then any active transfers will be cancelled and the target is returned to an earlier state. Reconnection will restart the configuration process and eventually return the target to CONFIGURED state. Application code should avoid submitting transfers unless the target is in CONFIGURED state.

Structure of this Document

This document is divided into a number of sections. Some of these are of interest to all users, others will only be useful to writers of class or host controller drivers. Other parts are only useful to those who are working on the USB stack itself: