Name

Overview — eCosPro Support for USB

Description

[Important]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.

Table 5. USB class support

USB ClasseCos Package Name and Documentation LinkDescription
Host Mass Storage Class (MSC) Host mass storage driver package

(CYGPKG_DEVS_DISK_USBMS)

Supports use of USB memory sticks, hard disk drives and similar storage devices. USB mass storage devices essentially provide a block level interface, which by convention, a FAT format file system is layered over.
Host Communication Device Class (CDC), Abstract Control Model (ACM) subclass Host CDC ACM protocol driver package

(CYGPKG_IO_USB_CDC_ACM_HOST)

This class enables USB to serial converters conforming to the USB-IF defined CDC ACM class to be connected to embedded hardware. This can be used to expand the number of serial port connections available and can also be used for straightforward interconnection of embedded hardware; where one side implements the USB host class, and the other the device (target) side support. Read the USB Serial Support section for an overview of general USB serial functionality.
Host FTDI serial adapter class Host FTDI protocol driver package

(CYGPKG_IO_USB_FTDI)

This class enables FTDI USB to serial adapters to be connected to the embedded hardware, expanding the number of serial port connections available. This is a proprietary standard defined and supported by FTDI. Read the USB Serial Support section for an overview of general USB serial functionality.
Target Communication Device Class (CDC), Abstract Control Model (ACM) subclass Target CDC ACM protocol driver package

(CYGPKG_IO_USB_CDC_ACM)

This class enables simple, straightforward connectivity and communication between embedded hardware and host PC's, or other embedded hardware. It is a USB-IF defined class that is supported by all major host operating systems. Read the USB Serial Support section for an overview of general USB serial functionality.
Target Remote Network Driver Interface Specification (RNDIS) Class Target RNDIS driver package

(CYGPKG_DEVS_ETH_USB_RNDIS)

The RNDIS support provides network level connectivity to host PCs. Note that this does not provide physical network access, but rather enables generic networking level communications between the USB attached Host and Target devices. RNDIS is a proprietary Microsoft defined class and is particularly suited for use with Windows-based systems. Compatible drivers are also available for other major operating systems.
Target Communication Device Class (CDC), Ethernet Emulation Model (EEM) subclass Target CDC EEM driver package

(CYGPKG_DEVS_ETH_USB_CDCEEM)

CDC-EEM provides direct network level connectivity between embedded targets and host PCs. Note that this does not provide physical network access, but rather enables generic networking level communications between the USB attached Host and Target devices. It is a USB-IF defined USB standard and is supported natively by both Linux and Mac OS.

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:

  • OTG support is not implemented.
  • The host stack implements only control and bulk transfers. Interrupt and Isochronous transfers are not currently implemented. Additionally, only fixed size transfers are supported, short transfers are not, and scatter/gather support is not implemented.
  • Hub and root hub support is limited to those control requests directly needed by the stack. Hub connect state is polled, hub interrupt status transfers are not supported.
  • There is a limited set of host controllers supported. Currently only OHCI and the Synopsys DWC_usb controller are supported.
  • The target stack implements control, bulk and interrupt transfers. Isochronous transfers are not implemented. Limited support for short OUT transfers is implemented.
  • A relatively limited set of peripheral controllers is currently supported. For example, the Synopsys DWC_usb controller, as used on the STM32 Cortex-M family and the Atmel UDPHS controller driver.
  • There is no intrinsic support for composite devices. In target mode applications can define and service composite devices directly. In host mode class drivers should be able to extract the specific interfaces they need from a composite device, although this has never been tested.
  • The stack can currently only function within eCos with the kernel present. Support for unthreaded, non-interrupting environments such as RedBoot has not been implemented.

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.

Device

A device is something that is plugged into a USB bus, for example a flash drive, a serial adaptor or an ethernet adaptor. When its attachment is detected it is given an address and descriptors are fetched. These will generally be referred to by the term physical device.

In the eCosPro USB host stack the term device is also used to refer to the data structure allocated in the host stack to represent and manage the physical device while it is attached.

Target
A target is the name used in the eCosPro USB stack for a peripheral device implemented by eCosPro.
Host Controller (HC)
A host controller is the hardware device that provides access to a USB bus. It typically controls the transfer of packets between the USB stack and devices. It usually also provides support for one or more external ports into which devices and hubs are plugged.
Host Controller Driver (HCD)
A host controller driver is the software component that controls the host controller hardware and provides a standard interface by which the rest of the USB stack accesses the bus.
Peripheral Controller (PC)
A peripheral controller is the hardware device that provides access to a USB bus in peripheral mode. It typically controls the transfer of packets between the USB stack and the USB host.
Peripheral Controller Driver (PCD)
A peripheral controller driver is the software component that controls the peripheral controller hardware and provides a standard interface by which the rest of the USB stack accesses the bus.
Hub

A hub is a USB bus component that splits the USB bus into a number of additional ports. A typical external hub has four downstream ports for connecting new devices and a single upstream port that connects to a downstream port of another hub or host controller.

A host controller also acts as a hub, known as a root hub. It typically contains one, two or more ports which form the external interface to the USB bus. These are usually controlled by a handful of registers in the controller and accessed by the HCD. The USB host stack usually virtualizes the root hub so that it can be controlled in exactly the same way as an external hub through the exchange of control messages.

Endpoint

In the USB specification an endpoint is the terminus of communication between the host and a device. All USB transfers are directed to a combination of device address and endpoint number. Endpoints are uni-directional, and each device can have up to 16 endpoints in each direction, except endpoint 0 which is bidirectional.

In the eCosPro USB stack, the term endpoint is often used to refer to data structures that represent and manage transfers between the host and the target. Endpoint data structures can exist in both the USB stack itself and in the HCD/PCD.

Transfer
All communication is handled through a usb_tfr object. Internally to an HCD/PCD, the term transfer may also refer to an internal data structure. There may be a many-to-one relationship between HCD/PCD transfers and usb_tfr objects.
Port
A port is the connection point for attached devices. Both external hubs and host controllers have downstream ports. A hub's port is the target of various control operations to enable/disable and reset the connected device.
Class Driver
A class driver is a software component that converts a USB device into a particular eCos device type. Typically it operates between two interfaces, acting as a client to the USB stack and providing an eCos device interface to higher level components.

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:

  • The Configuration section describes the CDL configuration options that can be applied to the USB stack.
  • The Transfer Objects section describes the message-like transfer objects that are used for all data transfers in the USB stack, together with various API functions that apply to them.
  • The Host Device Object section describes the data structure used to represent a device connected to the stack in host mode. This section also describes the lifecycle of a device and a hub.
  • The Class Drivers section describes the interface to host device class drivers.
  • The Host Controller Drivers section describes the interface to Host Controller Drivers.
  • The Target Objects section describes the data structure used to represent a target device connected to the stack in peripheral mode. This section also describes the support for string descriptor encoding and the target object API together with a description of what an application should do to create a target peripheral device.
  • The Peripheral Controller Drivers section describes the interface to Peripheral Controller Drivers.