Name

Introduction

Often the best way to write a USB device driver will be to start with +an existing one and modify it as necessary. The information given here +is intended primarily as an outline rather than as a complete guide.

The Control Endpoint

A USB device driver should provide a single usbs_control_endpoint +data structure for every USB device. Typical peripherals will have +only one USB port so there will be just one such data structure in the +entire system, but theoretically it is possible to have multiple USB +devices. These may all involve the same chip, in which case a single +device driver should support multiple device instances, or they may +involve different chips. The name or names of these data structures +are determined by the device driver, but appropriate care should be +taken to avoid name clashes.

A USB device cannot be used unless the control endpoint data structure +exists. However, the presence of USB hardware in the target processor +or board does not guarantee that the application will necessarily want +to use that hardware. To avoid unwanted code or data overheads, the +device driver can provide a configuration option to determine whether +or not the endpoint 0 data structure is actually provided. A default +value of CYGINT_IO_USB_SLAVE_CLIENTS ensures that +the USB driver will be enabled automatically if higher-level code does +require USB support, while leaving ultimate control to the user.

The USB device driver is responsible for filling in the +start_fn, +poll_fn and +interrupt_vector fields. Usually this can +be achieved by static initialization. The driver is also largely +responsible for maintaining the state +field. The control_buffer array should be +used to hold the first packet of a control message. The +buffer and other fields related to data +transfers will be managed jointly by higher-level code and +the device driver. The remaining fields are generally filled in by +higher-level code, although the driver should initialize them to NULL +values.

Hardware permitting, the USB device should be inactive until the +start_fn is invoked, for example by +tristating the appropriate pins. This prevents the host from +interacting with the peripheral before all other parts of the system +have initialized. It is expected that the +start_fn will only be invoked once, shortly +after power-up.

Where possible the device driver should detect state changes, such as +when the connection between host and peripheral is established, and +report these to higher-level +code via the state_change_fn callback, if +any. The state change to and from configured state cannot easily be +handled by the device driver itself, instead higher-level code such as +the common USB slave package will take care of this.

Once the connection between host and peripheral has been established, +the peripheral must be ready to accept control messages at all times, +and must respond to these within certain time constraints. For +example, the standard set-address control message must be handled +within 50ms. The USB specification provides more information on these +constraints. The device driver is responsible for receiving the +initial packet of a control message. This packet will always be eight +bytes and should be stored in the +control_buffer field. Certain standard +control messages should be detected and handled by the device driver +itself. The most important is set-address, but usually the get-status, +set-feature and clear-feature requests when applied to halted +endpoints should also be handled by the driver. Other standard control +messages should first be passed on to the +standard_control_fn callback (if any), and +finally to the default handler +usbs_handle_standard_control provided by the +common USB slave package. Class, vendor and reserved control messages +should always be dispatched to the appropriate callback and there is +no default handler for these.

Some control messages will involve further data transfer, not just the +initial packet. The device driver must handle this in accordance with +the USB specification and the buffer management strategy. The +driver is also responsible for keeping track of whether or not the +control operation has succeeded and generating an ACK or STALL +handshake.

The polling support is optional and may not be feasible on all +hardware. It is only used in certain specialised environments such as +RedBoot. A typical implementation of the polling function would just +check whether or not an interrupt would have occurred and, if so, call +the same code that the interrupt handler would.

Data Endpoints

In addition to the control endpoint data structure, a USB device +driver should also provide appropriate data +endpoint data structures. Obviously this is only relevant if +the USB support generally is desired, that is if the control endpoint is +provided. In addition, higher-level code may not require all the +endpoints, so it may be useful to provide configuration options that +control the presence of each endpoint. For example, the intended +application might only involve a single transmit endpoint and of +course control messages, so supporting receive endpoints might waste +memory.

Conceptually, data endpoints are much simpler than the control +endpoint. The device driver has to supply two functions, one for +data transfers and another to control the halted condition. These +implement the functionality for +usbs_start_rx_buffer, +usbs_start_tx_buffer, +usbs_set_rx_endpoint_halted and +usbs_set_tx_endpoint_halted. +The device driver is also responsible for maintaining the +halted status.

For data transfers, higher-level code will have filled in the +buffer, +buffer_size, +complete_fn and +complete_data fields. The transfer function +should arrange for the transfer to start, allowing the host to send or +receive packets. Typically this will result in an interrupt at the end +of the transfer or after each packet. Once the entire transfer has +been completed, the driver's interrupt handling code should invoke the +completion function. This can happen either in DSR context or thread +context, depending on the driver's implementation. There are a number +of special cases to consider. If the endpoint is halted when the +transfer is started then the completion function can be invoked +immediately with -EAGAIN. If the transfer cannot be +completed because the connection is broken then the completion +function should be invoked with -EPIPE. If the +endpoint is stalled during the transfer, either because of a standard +control message or because higher-level code calls the appropriate +set_halted_fn, then again the completion +function should be invoked with -EAGAIN. Finally, +the <usbs_start_rx_endpoint_wait and +usbs_start_tx_endpoint_wait functions involve +calling the device driver's data transfer function with a buffer size +of 0 bytes.

Devtab Entries

For some applications or higher-level packages it may be more +convenient to use traditional open/read/write I/O calls rather than +the non-blocking USB I/O calls. To support this the device driver can +provide a devtab entry for each endpoint, for example:

#ifdef CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY








    +








    +static CHAR_DEVIO_TABLE(usbs_sa11x0_ep1_devtab_functions,








    +                        &cyg_devio_cwrite,








    +                        &usbs_devtab_cread,








    +                        &cyg_devio_bwrite,








    +                        &cyg_devio_bread,








    +                        &cyg_devio_select,








    +                        &cyg_devio_get_config,








    +                        &cyg_devio_set_config);








    +








    +static CHAR_DEVTAB_ENTRY(usbs_sa11x0_ep1_devtab_entry,








    +                         CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME "1r",








    +                         0,








    +                         &usbs_sa11x0_ep1_devtab_functions,








    +                         &usbs_sa11x0_devtab_dummy_init,








    +                         0,








    +                         (void*) &usbs_sa11x0_ep1);








    +#endif

Again care must be taken to avoid name clashes. This can be achieved +by having a configuration option to control the base name, with a +default value of e.g. /dev/usbs, and appending an +endpoint-specific string. This gives the application developer +sufficient control to eliminate any name clashes. The common USB slave +package provides functions usbs_devtab_cwrite and +usbs_devtab_cread, which can be used in the +function tables for transmit and receive endpoints respectively. The +private field priv of the devtab entry +should be a pointer to the underlying endpoint data structure.

Because devtab entries are never accessed directly, only indirectly, +they would usually be eliminated by the linker. To avoid this the +devtab entries should normally be defined in a separate source file +which ends up the special library libextras.a +rather than in the default library libtarget.a.

Not all applications or higher-level packages will want to use the +devtab entries and the blocking I/O facilities. It may be appropriate +for the device driver to provide additional configuration options that +control whether or not any or all of the devtab entries should be +provided, to avoid unnecessary memory overheads.

Interrupt Handling

A typical USB device driver will need to service interrupts for all of +the endpoints and possibly for additional USB events such as entering +or leaving suspended mode. Usually these interrupts need not be +serviced directly by the ISR. Instead, they can be left to a DSR. If +the peripheral is not able to accept or send another packet just yet, +the hardware will generate a NAK and the host will just retry a little +bit later. If high throughput is required then it may be desirable to +handle the bulk transfer protocol largely at ISR level, that is take +care of each packet in the ISR and only activate the DSR once the +whole transfer has completed.

Control messages may involve invoking arbitrary callback functions in +higher-level code. This should normally happen at DSR level. Doing it +at ISR level could seriously affect the system's interrupt latency and +impose unacceptable constraints on what operations can be performed by +those callbacks. If the device driver requires a thread anyway then it +may be appropriate to use this thread for invoking the callbacks, but +usually it is not worthwhile to add a new thread to the system just +for this; higher-level code is expected to write callbacks that +function sensibly at DSR level. Much the same applies to the +completion functions associated with data transfers. These should also +be invoked at DSR or thread level.

Support for USB Testing

Optionally a USB device driver can provide support for the +USB test software. This requires +defining a number of additional data structures, allowing the +generic test code to work out just what the hardware is capable of and +hence what testing can be performed.

The key data structure is +usbs_testing_endpoint, defined in cyg/io/usb/usbs.h. In addition some +commonly required constants are provided by the common USB package in +cyg/io/usb/usb.h. One +usbs_testing_endpoint structure should be +defined for each supported endpoint. The following fields need to be +filled in:

The device driver should provide an array of these structures +usbs_testing_endpoints[]. The USB testing code +examines this array and uses the information to perform appropriate +tests. Because different USB devices support different numbers of +endpoints the number of entries in the array is not known in advance, +so instead the testing code looks for a special terminator +USBS_TESTING_ENDPOINTS_TERMINATOR. An example +array, showing just the control endpoint and the terminator, might +look like this:

usbs_testing_endpoint usbs_testing_endpoints[] = {








    +    {








    +        endpoint_type       : USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL,








    +        endpoint_number     : 0,








    +        endpoint_direction  : USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN,








    +        endpoint            : (void*) &ep0.common,








    +        devtab_entry        : (const char*) 0,








    +        min_size            : 1,








    +        max_size            : 0x0FFFF,








    +        max_in_padding      : 0,








    +        alignment           : 0








    +    },








    +    …,








    +    USBS_TESTING_ENDPOINTS_TERMINATOR








    +};

Name

Synopsis

#include <cyg/io/usb/usb.h>








    +#include <cyg/io/usb/usbs.h>








    +








    +typedef struct usb_device_descriptor {








    +    …








    +} usb_device_descriptor __attribute__((packed));








    +








    +typedef struct usb_configuration_descriptor {








    +    …








    +} usb_configuration_descriptor __attribute__((packed));








    +








    +typedef struct usb_interface_descriptor {








    +    …








    +} usb_interface_descriptor __attribute__((packed));








    +








    +typedef struct usb_endpoint_descriptor {








    +    …








    +} usb_endpoint_descriptor;








    +








    +typedef struct usbs_enumeration_data {








    +    usb_device_descriptor               device;








    +    int                                 total_number_interfaces;








    +    int                                 total_number_endpoints;








    +    int                                 total_number_strings;








    +    const usb_configuration_descriptor* configurations;








    +    const usb_interface_descriptor*     interfaces;








    +    const usb_endpoint_descriptor*      endpoints;








    +    const unsigned char**               strings;








    +} usbs_enumeration_data;

USB Enumeration Data

When a USB host detects that a peripheral has been plugged in or +powered up, one of the first steps is to ask the peripheral to +describe itself by supplying enumeration data. Some of this data +depends on the class of peripheral. Other fields are vendor-specific. +There is also a dependency on the hardware, specifically which +endpoints are available should be used. In general it is not possible +for generic code to provide this information, so it is the +responsibility of application code to provide a suitable +usbs_enumeration_data data structure and +install it in the endpoint 0 data structure during initialization. +This must happen before the USB device is enabled by a call to +usbs_start, for example:

const usbs_enumeration_data usb_enum_data = {








    +    …








    +};








    +








    +int








    +main(int argc, char** argv)








    +{








    +    usbs_sa11x0_ep0.enumeration_data = &usb_enum_data;








    +    …








    +    usbs_start(&usbs_sa11x0_ep0);








    +    …








    +}

For most applications the enumeration data will be static, although +the usbs_enumeration_data structure can be +filled in at run-time if necessary. Full details of the enumeration +data can be found in the Universal Serial Bus specification obtainable +from the USB Implementers Forum web +site, although the meaning of most fields is fairly obvious. +The various data structures and utility macros are defined in the +header files cyg/io/usb/usb.h +and cyg/io/usb/usbs.h. Note +that the example code below makes use of the gcc labelled element +extension.

const usbs_enumeration_data usb_enum_data = {








    +    {








    +        length:                 USB_DEVICE_DESCRIPTOR_LENGTH,








    +        type:                   USB_DEVICE_DESCRIPTOR_TYPE,








    +        usb_spec_lo:            USB_DEVICE_DESCRIPTOR_USB11_LO,








    +        usb_spec_hi:            USB_DEVICE_DESCRIPTOR_USB11_HI,








    +        device_class:           USB_DEVICE_DESCRIPTOR_CLASS_VENDOR,








    +        device_subclass:        USB_DEVICE_DESCRIPTOR_SUBCLASS_VENDOR,








    +        device_protocol:        USB_DEVICE_DESCRIPTOR_PROTOCOL_VENDOR,








    +        max_packet_size:        8,








    +        vendor_lo:              0x42,








    +        vendor_hi:              0x42,








    +        product_lo:             0x42,








    +        product_hi:             0x42,








    +        device_lo:              0x00,








    +        device_hi:              0x01,








    +        manufacturer_str:       1,








    +        product_str:            2,








    +        serial_number_str:      0,








    +        number_configurations:  1








    +    },








    +    …








    +};

const usb_configuration_descriptor usb_configuration = {








    +    length:             USB_CONFIGURATION_DESCRIPTOR_LENGTH,








    +    type:               USB_CONFIGURATION_DESCRIPTOR_TYPE,








    +    total_length_lo:    USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_LO(1, 2),








    +    total_length_hi:    USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_HI(1, 2),








    +    number_interfaces:  1,








    +    configuration_id:   1,








    +    configuration_str:  0,








    +    attributes:         USB_CONFIGURATION_DESCRIPTOR_ATTR_REQUIRED |








    +                        USB_CONFIGURATION_DESCRIPTOR_ATTR_SELF_POWERED,








    +    max_power:          50








    +};








    +








    +const usbs_enumeration_data usb_enum_data = {








    +    …








    +    configurations:             &usb_configuration,








    +    …








    +};

const usb_interface_descriptor usb_interface = {








    +    length:             USB_INTERFACE_DESCRIPTOR_LENGTH,








    +    type:               USB_INTERFACE_DESCRIPTOR_TYPE,








    +    interface_id:       0,








    +    alternate_setting:  0,








    +    number_endpoints:   2,








    +    interface_class:    USB_INTERFACE_DESCRIPTOR_CLASS_VENDOR,








    +    interface_subclass: USB_INTERFACE_DESCRIPTOR_SUBCLASS_VENDOR,








    +    interface_protocol: USB_INTERFACE_DESCRIPTOR_PROTOCOL_VENDOR,








    +    interface_str:      0








    +};








    +








    +const usbs_enumeration_data usb_enum_data = {








    +    …








    +    total_number_interfaces:    1,








    +    interfaces:                 &usb_interface,








    +    …








    +};

const usb_endpoint_descriptor usb_endpoints[] = {








    +    {








    +        length:         USB_ENDPOINT_DESCRIPTOR_LENGTH,








    +        type:           USB_ENDPOINT_DESCRIPTOR_TYPE,








    +        endpoint:       USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT | 1,








    +        attributes:     USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,








    +        max_packet_lo:  64,








    +        max_packet_hi:  0,








    +        interval:       0








    +    },








    +    {








    +        length:         USB_ENDPOINT_DESCRIPTOR_LENGTH,








    +        type:           USB_ENDPOINT_DESCRIPTOR_TYPE,








    +        endpoint:       USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN | 2,








    +        attributes:     USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,








    +        max_packet_lo:  64,








    +        max_packet_hi:  0,








    +        interval:       0








    +    }








    +};








    +








    +const usbs_enumeration_data usb_enum_data = {








    +    …








    +    total_number_endpoints:     2,








    +    endpoints:                  usb_endpoints,








    +    …








    +};

const unsigned char* usb_strings[] = {








    +    "\004\003\011\004",








    +    "\020\003R\000e\000d\000 \000H\000a\000t\000"








    +};








    +








    +const usbs_enumeration_data usb_enum_data = {








    +    …








    +    total_number_strings:       2,








    +    strings:                    usb_strings,








    +    …








    +};

Name

Synopsis

#include <cyg/io/usb/usbs.h>

Description

usbs_start_rx_buffer is a USB-specific function +to accept a transfer from host to peripheral. It can be used for bulk, +interrupt or isochronous transfers, but not for control messages. +Instead those involve manipulating the usbs_control_endpoint +data structure directly. The function takes five arguments:

1. The first argument identifies the specific endpoint that should be +used. Different USB devices will support different sets of endpoints +and the device driver will provide appropriate data structures. The +device driver's documentation should be consulted for details of which +endpoints are available.

2. The buffer and length +arguments control the actual transfer. USB device drivers are not +expected to perform any buffering or to support partial transfers, so +the length specified should correspond to the maximum transfer that is +currently possible and the buffer should be at least this large. For +isochronous transfers the USB specification imposes an upper bound of +1023 bytes, and a smaller limit may be set in the enumeration data. Interrupt +transfers are similarly straightforward with an upper bound of 64 +bytes, or less as per the enumeration data. Bulk transfers are more +complicated because they can involve multiple 64-byte packets plus a +terminating packet of less than 64 bytes, so there is no predefined +limit on the transfer size. Instead it is left to higher-level +protocols to specify an appropriate upper bound.

   One technique that may work for bulk transfers is to exploit the fact +that such transfers happen in 64-byte packets: it may be possible to +receive an initial 64 bytes, corresponding to the first packet in the +transfer; these 64 bytes can then be examined to determine the total +transfer size, and the remaining data can be transferred in another +receive operation. This technique is not guaranteed to work with all +USB hardware. Also, if the delay between accepting the first packet and +the remainder of the transfer is excessive then this could cause +timeout problems for the host-side software. For these reasons this +technique should be avoided.

3. usbs_start_rx_buffer is non-blocking. It merely +starts the receive operation, and does not wait for completion. At +some later point the USB device driver will invoke the completion +function parameter with two arguments: the completion data defined by +the last parameter and a result field. A result >= +0 indicates a successful transfer of that many +bytes, which may be less than the upper bound imposed by the +length argument. A result < +0 indicates an error. The most likely errors are +-EPIPE to indicate that the connection between the +host and the target has been broken, and -EAGAIN +for when the endpoint has been halted. Specific USB device drivers may +specify additional error conditions.

The normal sequence of events is that the USB device driver will +update the appropriate hardware registers. At some point after that +the host will attempt to send data by transmitting an OUT token +followed by a data packet, and since a receive operation is now in +progress the data will be accepted and ACK'd. If there were no receive +operation then the peripheral would instead generate a NAK. The USB +hardware will generate an interrupt once the whole packet has been +received, and the USB device driver will service this interrupt and +arrange for a DSR to be called. Isochronous and interrupt transfers +involve just a single packet. However, bulk transfers may involve +multiple packets so the device driver has to check whether the packet +was a full 64 bytes or whether it was a terminating packet of less +than this. When the device driver DSR detects a complete transfer it +will inform higher-level code by invoking the supplied completion +function.

This means that the completion function will normally be invoked by a +DSR and not in thread context - although some USB device drivers may +have a different implementation. Therefore the completion function is +restricted in what it can do. In particular it must not make any +calls that will or may block such as locking a mutex or allocating +memory. The kernel documentation should be consulted for more details +of DSR's and interrupt handling generally.

It is possible that the completion function will be invoked before +usbs_start_rx_buffer returns. Such an event would +be unusual because the transfer cannot happen until the next time the +host tries to send data to this peripheral, but it may happen if for +example another interrupt happens and a higher priority thread is +scheduled to run. Also, if the endpoint is currently halted then the +completion function will be invoked immediately with +-EAGAIN: typically this will happen in the current +thread rather than in a separate DSR. The completion function is +allowed to start another transfer immediately by calling +usbs_start_rx_buffer again.

USB device drivers are not expected to perform any locking. It is the +responsibility of higher-level code to ensure that there is only one +receive operation for a given endpoint in progress at any one time. If +there are concurrent calls to +usbs_start_rx_buffer then the resulting behaviour +is undefined. For typical USB applications this does not present any +problems, because only one piece of code will access a given endpoint +at any particular time.

The following code fragment illustrates a very simple use of +usbs_start_rx_buffer to implement a blocking +receive, using a semaphore to synchronise between the foreground +thread and the DSR. For a simple example like this no completion data +is needed.

static int error_code = 0;








    +static cyg_sem_t completion_wait;








    +








    +static void








    +completion_fn(void* data, int result)








    +{








    +    error_code = result;








    +    cyg_semaphore_post(&completion_wait);








    +}








    +








    +int








    +blocking_receive(usbs_rx_endpoint* ep, unsigned char* buf, int len)








    +{








    +    error_code = 0;








    +    usbs_start_rx_buffer(ep, buf, len, &completion_fn, NULL);








    +    cyg_semaphore_wait(&completion_wait);








    +    return error_code;








    +}

There is also a utility function usbs_start_rx. This +can be used by code that wants to manipulate data endpoints directly, specifically the +complete_fn, +complete_data, +buffer and +buffer_size fields. +usbs_start_tx just invokes a function +supplied by the device driver.

Name

Synopsis

/dev/usb0c








    +/dev/usb1r








    +/dev/usb2w

Devtab Entries

USB device drivers provide two ways of transferring data between host +and peripheral. The first involves USB-specific functionality such as +usbs_start_rx_buffer. +This provides non-blocking I/O: a transfer is started, and some time +later the device driver will call a supplied completion function. The +second uses the conventional I/O model: there are entries in the +device table corresponding to the various endpoints. Standard calls +such as open can then be used to get a suitable +handle. Actual I/O happens via blocking read and +write calls. In practice the blocking operations +are simply implemented using the underlying non-blocking +functionality.

Each endpoint will have its own devtab entry. The exact names are +controlled by the device driver package, but typically the root will +be /dev/usb. This is followed by one or more +decimal digits giving the endpoint number, followed by +c for a control endpoint, r for +a receive endpoint (host to peripheral), and w for +a transmit endpoint (peripheral to host). If the target hardware +involves more than one USB device then different roots should be used, +for example /dev/usb0c and +/dev/usb1_0c. This may require explicit +manipulation of device driver configuration options by the application +developer.

At present the devtab entry for a control endpoint does not support +any I/O operations.

Name

Synopsis

#include <cyg/io/usb/usbs.h>

Description

usbs_start_tx_buffer is a USB-specific function +to transfer data from peripheral to host. It can be used for bulk, +interrupt or isochronous transfers, but not for control messages; +instead those involve manipulating the usbs_control_endpoint +data structure directly. The function takes five arguments:

1. The first argument identifies the specific endpoint that should be +used. Different USB devices will support different sets of endpoints +and the device driver will provide appropriate data structures. The +device driver's documentation should be consulted for details of which +endpoints are available.

2. The buffer and length +arguments control the actual transfer. USB device drivers are not +allowed to modify the buffer during the transfer, so the data can +reside in read-only memory. The transfer will be for all the data +specified, and it is the responsibility of higher-level code to make +sure that the host is expecting this amount of data. For isochronous +transfers the USB specification imposes an upper bound of 1023 bytes, +but a smaller limit may be set in the enumeration data. Interrupt +transfers have an upper bound of 64 bytes or less, as per the +enumeration data. Bulk transfers are more complicated because they can +involve multiple 64-byte packets plus a terminating packet of less +than 64 bytes, so the basic USB specification does not impose an upper +limit on the total transfer size. Instead it is left to higher-level +protocols to specify an appropriate upper bound. If the peripheral +attempts to send more data than the host is willing to accept then the +resulting behaviour is undefined and may well depend on the specific +host operating system being used.

   For bulk transfers, the USB device driver or the underlying hardware +will automatically split the transfer up into the appropriate number +of full-size 64-byte packets plus a single terminating packet, which +may be 0 bytes.

3. usbs_start_tx_buffer is non-blocking. It merely +starts the transmit operation, and does not wait for completion. At +some later point the USB device driver will invoke the completion +function parameter with two arguments: the completion data defined by +the last parameter, and a result field. This result will be either an +error code < 0, or the amount of data +transferred which should correspond to the +length argument. The most likely errors are +-EPIPE to indicate that the connection between the +host and the target has been broken, and -EAGAIN +for when the endpoint has been halted. Specific USB device drivers may +define additional error conditions.

The normal sequence of events is that the USB device driver will +update the appropriate hardware registers. At some point after that +the host will attempt to fetch data by transmitting an IN token. Since +a transmit operation is now in progress the peripheral can send a +packet of data, and the host will generate an ACK. At this point the +USB hardware will generate an interrupt, and the device driver will +service this interrupt and arrange for a DSR to be called. Isochronous +and interrupt transfers involve just a single packet. However, bulk +transfers may involve multiple packets so the device driver has to +check whether there is more data to send and set things up for the +next packet. When the device driver DSR detects a complete transfer it +will inform higher-level code by invoking the supplied completion +function.

This means that the completion function will normally be invoked by a +DSR and not in thread context - although some USB device drivers may +have a different implementation. Therefore the completion function is +restricted in what it can do, in particular it must not make any +calls that will or may block such as locking a mutex or allocating +memory. The kernel documentation should be consulted for more details +of DSR's and interrupt handling generally.

It is possible that the completion function will be invoked before +usbs_start_tx_buffer returns. Such an event would +be unusual because the transfer cannot happen until the next time the +host tries to fetch data from this peripheral, but it may happen if, +for example, another interrupt happens and a higher priority thread is +scheduled to run. Also, if the endpoint is currently halted then the +completion function will be invoked immediately with +-EAGAIN: typically this will happen in the current +thread rather than in a separate DSR. The completion function is +allowed to start another transfer immediately by calling +usbs_start_tx_buffer again.

USB device drivers are not expected to perform any locking. It is the +responsibility of higher-level code to ensure that there is only one +transmit operation for a given endpoint in progress at any one time. +If there are concurrent calls to +usbs_start_tx_buffer then the resulting behaviour +is undefined. For typical USB applications this does not present any +problems because only piece of code will access a given endpoint at +any particular time.

The following code fragment illustrates a very simple use of +usbs_start_tx_buffer to implement a blocking +transmit, using a semaphore to synchronise between the foreground +thread and the DSR. For a simple example like this no completion data +is needed.

static int error_code = 0;








    +static cyg_sem_t completion_wait;








    +








    +static void








    +completion_fn(void* data, int result)








    +{








    +    error_code = result;








    +    cyg_semaphore_post(&completion_wait);








    +}








    +








    +int








    +blocking_transmit(usbs_tx_endpoint* ep, const unsigned char* buf, int len)








    +{








    +    error_code = 0;








    +    usbs_start_tx_buffer(ep, buf, len, &completion_fn, NULL);








    +    cyg_semaphore_wait(&completion_wait);








    +    return error_code;








    +}

There is also a utility function usbs_start. This +can be used by code that wants to manipulate data endpoints directly, specifically the +complete_fn, +complete_data, +buffer and +buffer_size fields. +usbs_start_tx just calls a function supplied by +the device driver.

Name

Synopsis

#include <cyg/io/usb/usbs.h>

Description

Normal USB traffic involves straightforward handshakes, with either an +ACK to indicate that a packet was transferred +without errors, or a NAK if an error occurred, or +if a peripheral is currently unable to process another packet from the +host, or has no packet to send to the host. There is a third form of +handshake, a STALL, which indicates that the +endpoint is currently halted.

When an endpoint is halted it means that the host-side code needs to +take some sort of recovery action before communication over that +endpoint can resume. The exact circumstances under which this can +happen are not defined by the USB specification, but one example would +be a protocol violation if say the peripheral attempted to transmit +more data to the host than was permitted by the protocol in use. The +host can use the standard control messages get-status, set-feature and +clear-feature to examine and manipulate the halted status of a given +endpoint. There are USB-specific functions which can be used inside +the peripheral to achieve the same effect. Once an endpoint has been +halted the host can then interact with the peripheral using class or +vendor control messages to perform appropriate recovery, and then the +halted condition can be cleared.

Halting an endpoint does not constitute a device state change, and +there is no mechanism by which higher-level code can be informed +immediately. However, any ongoing receive or transmit operations will +be aborted with an -EAGAIN error, and any new +receives or transmits will fail immediately with the same error.

There are six functions to support halted endpoints, one set for +receive endpoints and another for transmit endpoints, with both sets +behaving in essentially the same way. The first, +usbs_rx_endpoint_halted, can be used to determine +whether or not an endpoint is currently halted: it takes a single +argument that identifies the endpoint of interest. The second +function, usbs_set_rx_endpoint_halted, can be +used to change the halted condition of an endpoint: it takes two +arguments; one to identify the endpoint and another to specify the new +state. The last function +usbs_start_rx_endpoint_wait operates in much the +same way as usbs_start_rx_buffer: when the +endpoint is no longer halted the device driver will invoke the +supplied completion function with a status of 0. The completion +function has the same signature as that for a transfer operation. +Often it will be possible to use a single completion function and have +the foreground code invoke either +usbs_start_rx_buffer or +usbs_start_rx_endpoint_wait depending on the +current state of the endpoint.

Name

Synopsis

#include <cyg/io/usb/usbs.h>








    +








    +typedef struct usbs_rx_endpoint {








    +    void                 (*start_rx_fn)(struct usbs_rx_endpoint*);








    +    void                 (*set_halted_fn)(struct usbs_rx_endpoint*, cyg_bool);








    +    void                 (*complete_fn)(void*, int);








    +    void*                complete_data;








    +    unsigned char*       buffer;








    +    int                  buffer_size;








    +    cyg_bool             halted;








    +} usbs_rx_endpoint;








    +








    +typedef struct usbs_tx_endpoint {








    +    void                 (*start_tx_fn)(struct usbs_tx_endpoint*);








    +    void                 (*set_halted_fn)(struct usbs_tx_endpoint*, cyg_bool);








    +    void                 (*complete_fn)(void*, int);








    +    void*                complete_data;








    +    const unsigned char* buffer;








    +    int                  buffer_size;








    +    cyg_bool             halted;








    +} usbs_tx_endpoint;

Receive and Transmit Data Structures

In addition to a single usbs_control_endpoint +data structure per USB slave device, the USB device driver should also +provide receive and transmit data structures corresponding to the +other endpoints. The names of these are determined by the device +driver. For example, the SA1110 USB device driver package provides +usbs_sa11x0_ep1 for receives and +usbs_sa11x0_ep2 for transmits.

Unlike control endpoints, the common USB slave package does provide a +number of utility routines to manipulate data endpoints. For example +usbs_start_rx_buffer +can be used to receive data from the host into a buffer. In addition +the USB device driver can provide devtab entries such as +/dev/usbs1r and /dev/usbs2w, so +higher-level code can open these devices and then +perform blocking read and +write operations.

However, the operation of data endpoints and the various +endpoint-related functions is relatively straightforward. First +consider a usbs_rx_endpoint structure. The +device driver will provide the members +start_rx_fn and +set_halted_fn, and it will maintain the +halted field. To receive data, higher-level +code sets the buffer, +buffer_size, +complete_fn and optionally the +complete_data fields. Next the +start_rx_fn member should be called. When +the transfer has finished the device driver will invoke the completion +function, using complete_data as the first +argument and a size field for the second argument. A negative size +indicates an error of some sort: -EGAIN indicates +that the endpoint has been halted, usually at the request of the host; +-EPIPE indicates that the connection between the +host and the peripheral has been broken. Certain device drivers may +generate other error codes.

If higher-level code needs to halt or unhalt an endpoint then it can +invoke the set_halted_fn member. When an +endpoint is halted, invoking start_rx_fn +wit buffer_size set to 0 indicates that +higher-level code wants to block until the endpoint is no longer +halted; at that point the completion function will be invoked.

USB device drivers are allowed to assume that higher-level protocols +ensure that host and peripheral agree on the amount of data that will +be transferred, or at least on an upper bound. Therefore there is no +need for the device driver to maintain its own buffers, and copy +operations are avoided. If the host sends more data than expected then +the resulting behaviour is undefined.

Transmit endpoints work in essentially the same way as receive +endpoints. Higher-level code should set the +buffer and +buffer_size fields to point at the data to +be transferred, then call start_tx_fn, and +the device driver will invoked the completion function when the +transfer has completed.

USB device drivers are not expected to perform any locking. If at any +time there are two concurrent receive operations for a given endpoint, +or two concurrent transmit operations, then the resulting behaviour is +undefined. It is the responsibility of higher-level code to perform +any synchronisation that may be necessary. In practice, conflicts are +unlikely because typically a given endpoint will only be accessed +sequentially by just one part of the overall system.

Name

Introduction

The eCos USB slave support allows developers to produce USB +peripherals. It consists of a number of different eCos packages:

1. Device drivers for specific implementations of USB slave hardware, for +example the on-chip USB Device Controller provided by the Intel SA1110 +processor. A typical USB peripheral will only provide one USB slave +port and therefore only one such device driver package will be needed. +Usually the device driver package will be loaded automatically when +you create an eCos configuration for target hardware that has a USB +slave device. If you select a target which does have a USB slave +device but no USB device driver is loaded, this implies that no such +device driver is currently available.

2. The common USB slave package. This serves two purposes. It defines the +API that specific device drivers should implement. It also provides +various utilities that will be needed by most USB device drivers and +applications, such as handlers for standard control messages. +Usually this package will be loaded automatically at the same time as +the USB device driver.

3. The common USB package. This merely provides some information common +to both the host and slave sides of USB, such as details of the +control protocol. It is also used to place the other USB-related +packages appropriately in the overall configuration hierarchy. Usually +this package will be loaded at the same time as the USB device driver.

4. Class-specific USB support packages. These make it easier to develop +specific classes of USB peripheral, such as a USB-ethernet device. If +no suitable package is available for a given class of peripheral then +the USB device driver can instead be accessed directly from +application code. Such packages will never be loaded automatically +since the configuration system has no way of knowing what class of USB +peripheral is being developed. Instead developers have to add the +appropriate package or packages explicitly.

These packages only provide support for developing USB peripherals, +not USB hosts.

USB Concepts

Information about USB can be obtained from a number of sources +including the USB Implementers Forum +web site. Only a brief summary is provided here.

A USB network is asymmetrical: it consists of a single host, one or +more slave devices, and possibly some number of intermediate hubs. The +host side is significantly more complicated than the slave side. +Essentially, all operations are initiated by the host. For example, if +the host needs to receive some data from a particular USB peripheral +then it will send an IN token to that peripheral; the latter should +respond with either a NAK or with appropriate data. Similarly, when +the host wants to transmit data to a peripheral it will send an OUT +token followed by the data; the peripheral will return a NAK if it is +currently unable to receive more data or if there was corruption, +otherwise it will return an ACK. All transfers are check-summed and +there is a clearly-defined error recovery process. USB peripherals can +only interact with the host, not with each other.

USB supports four different types of communication: control messages, +interrupt transfers, isochronous transfers, and bulk transfers. +Control messages are further subdivided into four categories: +standard, class, vendor and a reserved category. All USB peripherals +must respond to certain standard control messages, and usually this +will be handled by the common USB slave package (for complicated +peripherals, application support will be needed). Class and vendor +control messages may be handled by an class-specific USB support +package, for example the USB-ethernet package will handle control +messages such as getting the MAC address or enabling/disabling +promiscuous mode. Alternatively, some or all of these messages will +have to be handled by application code.

Interrupt transfers are used for devices which need to be polled +regularly. For example, a USB keyboard might be polled once every +millisecond. The host will not poll the device more frequently than +this, so interrupt transfers are best suited to peripherals that +involve a relatively small amount of data. Isochronous transfers are +intended for multimedia-related peripherals where typically a large +amount of video or audio data needs to be exchanged continuously. +Given appropriate host support a USB peripheral can reserve some of +the available bandwidth. Isochronous transfers are not reliable; if a +particular packet is corrupted then it will just be discarded and +software is expected to recover from this. Bulk transfers are used for +everything else: after taking care of any pending control, isochronous +and interrupt transfers the host will use whatever bandwidth remains +for bulk transfers. Bulk transfers are reliable.

Transfers are organized into USB packets, with the details depending +on the transfer type. Control messages always involve an initial +8-byte packet from host to peripheral, optionally followed by some +additional packets; in theory these additional packets can be up to 64 +bytes, but hardware may limit it to 8 bytes. Interrupt transfers +involve a single packet of up to 64 bytes. Isochronous transfers +involve a single packet of up to 1024 bytes. Bulk transfers involve +multiple packets. There will be some number, possibly zero, of 64-byte +packets. The transfer is terminated by a single packet of less than 64 +bytes. If the transfer involves an exact multiple of 64 bytes than the +final packet will be 0 bytes, consisting of just a header and checksum +which typically will be generated by the hardware. There is no +pre-defined limit on the size of a bulk transfer. Instead higher-level +protocols are expected to handle this, so for a USB-ethernet +peripheral the protocol could impose a limit of 1514 bytes of data +plus maybe some additional protocol overhead.

Transfers from the host to a peripheral are addressed not just to that +peripheral but to a specific endpoint within that peripheral. +Similarly, the host requests incoming data from a specific endpoint +rather than from the peripheral as a whole. For example, a combined +keyboard/touchpad device could provide the keyboard events on endpoint +1 and the mouse events on endpoint 2. A given USB peripheral can have +up to 16 endpoints for incoming data and another 16 for outgoing data. +However, given the comparatively high speed of USB I/O this endpoint +addressing is typically implemented in hardware rather than software, +and the hardware will only implement a small number of endpoints. +Endpoint 0 is generally used only for control messages.

In practice, many of these details are irrelevant to application code +or to class packages. Instead, such higher-level code usually just +performs blocking read and +write, or non-blocking USB-specific calls, to +transfer data between host and target via a specific endpoint. Control +messages are more complicated but are usually handled by existing +code.

When a USB peripheral is plugged into the host there is an initial +enumeration and configuration process. The peripheral provides +information such as its class of device (audio, video, etc.), a +vendor id, which endpoints should be used for what kind of data, and +so on. The host OS uses this information to identify a suitable host +device driver. This could be a generic driver for a class of +peripherals, or it could be a vendor-specific driver. Assuming a +suitable driver is installed the host will then activate the USB +peripheral and perform additional application-specific initialisation. +For example for a USB-ethernet device this would involve obtaining an +ethernet MAC address. Most USB peripherals will be fairly simple, but +it is possible to build multifunction peripherals with multiple +configurations, interfaces, and alternate interface settings.

It is not possible for any of the eCos packages to generate all the +enumeration data automatically. Some of the required information such +as the vendor id cannot be supplied by generic packages; only by the +application developer. Class support code such as the USB-ethernet +package could in theory supply some of the information automatically, +but there are also hardware dependencies such as which endpoints get +used for incoming and outgoing ethernet frames. Instead it is the +responsibility of the application developer to provide all the +enumeration data and perform some additional initialisation. In +addition, the common USB slave package can handle all the standard +control messages for a simple USB peripheral, but for something like a +multifunction peripheral additional application support is needed.

eCos USB I/O Facilities

For protocols other than control messages, eCos provides two ways of +performing USB I/O. The first involves device table or devtab entries such +as /dev/usb1r, +with one entry per endpoint per USB device. It is possible to +open these devices and use conventional blocking +I/O functions such as read and +write to exchange data between host and +peripheral.

There is also a lower-level USB-specific API, consisting of functions +such as usbs_start_rx_buffer. +A USB device driver will supply a data structure for each endpoint, +for example a usbs_rx_endpoint +structure for every receive endpoint. The first argument to +usbs_start_rx_buffer should be a pointer to such +a data structure. The USB-specific API is non-blocking: the initial +call merely starts the transfer; some time later, once the transfer +has completed or has been aborted, the device driver will invoke a +completion function.

Control messages are different. With four different categories of +control messages including application and vendor specific ones, the +conventional +open/read/write +model of I/O cannot easily be applied. Instead, a USB device driver +will supply a usbs_control_endpoint +data structure which can be manipulated appropriately. In practice the +standard control messages will usually be handled by the common USB +slave package, and other control messages will be handled by +class-specific code such as the USB-ethernet package. Typically, +application code remains responsible for supplying the enumeration data and for actually starting up the USB device.

Enabling the USB code

If the target hardware contains a USB slave device then the +appropriate USB device driver and the common packages will typically +be loaded into the configuration automatically when that target is +selected (assuming a suitable device driver exists). However, the +driver will not necessarily be active. For example a processor might +have an on-chip USB device, but not all applications using that +processor will want to use USB functionality. Hence by default the USB +device is disabled, ensuring that applications do not suffer any +memory or other penalties for functionality that is not required.

If the application developer explicitly adds a class support package +such as the USB-ethernet one then this implies that the USB device is +actually needed, and the device will be enabled automatically. +However, if no suitable class package is available and the USB device +will instead be accessed by application code, it is necessary to +enable the USB device manually. Usually the easiest way to do this is +to enable the configuration option +CYGGLO_IO_USB_SLAVE_APPLICATION, and the USB device +driver and related packages will adjust accordingly. Alternatively, +the device driver may provide some configuration options to provide +more fine-grained control.

Name

Synopsis

#include <cyg/io/usb/usbs.h>

Description

Initializing a USB device requires some support from higher-level +code, typically the application, in the form of enumeration data. +Hence it is not possible for the low-level USB driver to activate a +USB device itself. Instead the higher-level code has to take care of +this by invoking usbs_start. This function takes +a pointer to a USB control endpoint data structure. USB device drivers +should provide exactly one such data structure for every USB device, +so the pointer uniquely identifies the device.

const usbs_enumeration_data usb_enum_data = {








    +    …








    +};








    +








    +int








    +main(int argc, char** argv)








    +{








    +    usbs_sa11x0_ep0.enumeration_data = &usb_enum_data;








    +    …








    +    usbs_start(&usbs_sa11x0_ep0);








    +    …








    +}

The exact behaviour of usbs_start depends on the +USB hardware and the device driver. A typical implementation would +change the USB data pins from tristated to active. If the peripheral +is already plugged into a host then the latter should detect this +change and start interacting with the peripheral, including requesting +the enumeration data. Some of this may happen before +usbs_start returns, but given that multiple +interactions between USB host and peripheral are required it is likely +that the function will return before the peripheral is fully +configured. Control endpoints provide a mechanism for informing +higher-level code of USB state changes. +usbs_start will return even if the peripheral is +not currently connected to a host: it will not block until the +connection is established.

usbs_start should only be called once for a given +USB device. There are no defined error conditions. Note that the +function affects the entire USB device and not just the control +endpoint: there is no need to start any data endpoints as well.

Name

Introduction

The support for USB testing provided by the eCos USB common slave +package is somewhat different in nature from the kind of testing used +in many other packages. One obvious problem is that USB tests cannot +be run on just a bare target platform: instead the target platform +must be connected to a suitable USB host machine, and that host +machine must be running appropriate software for the test code to +interact with. This is very different from say a kernel test which +typically will have no external dependencies. Another important +difference between USB testing and say a C library +strcmp test is sensitivity to timing and to +hardware boundary conditions: although a simple test case that just +performs a small number of USB transfers is better than no testing at +all, it should also be possible to run tests for hours or days on end, +under a variety of loads. In order to provide the required +functionality the basic architecture of the USB testing support is as +follows:

1. There is a single target-side program + usbtarget. By default when this is run + on a target platform it will appear to do nothing. In fact it is + waiting to be contacted by another program + usbhost which will tell it what test or + tests to run. usbtarget provides + mechanisms for running a wide range of tests. +

2. usbtarget is a generic program, but USB + testing depends to some extent on the functionality provided by the + hardware. For example there is no point in testing bulk transmits + to endpoint 12 if the target hardware does not support an endpoint + 12. Therefore each USB device driver should supply information about + what the hardware is actually capable of, in the form of an array of + usbs_testing_endpoint data structures. +

3. There is a single host-side program + usbhost, which acts as a counterpart to + usbtarget. Again + usbhost has no built-in knowledge of + the test or tests that are supposed to run, it only provides + mechanisms for running a wide range of tests. On start-up + usbhost will search the USB bus for + hardware running the target-side program, specifically a USB device + that identifies itself as the product "Red Hat eCos + USB test". +

4. usbhost contains a Tcl interpreter, and + will execute any Tcl scripts specified on the command line + together with appropriate arguments. The Tcl interpreter has been + extended with various commands such as + usbtest::bulktest, so the script can perform + the desired test or tests. +

5. Adding a new test simply involves writing a short Tcl script that + invokes the appropriate USB-specific commands. Running multiple + tests involves passing appropriate arguments to + usbhost, or alternatively writing a + single script that just invokes other scripts. +

The current implementation of usbhost +depends heavily on functionality provided by the Linux kernel and in +particular the usbdevfs support. It uses +/proc/bus/usb/devices to find out what devices +are attached to the bus, and will then access the device by opening +/proc/bus/usb/xxx/yyy and performing +ioctl operations. This allows USB testing to take +place without having to write a new host-side device driver, but +getting the code working on host machines not running Linux would +obviously be problematical.

Building and Running the Target-side Code

The target-side component of the USB testing software consists of a +single program usbtarget which contains +support for a range of different tests, under the control of host-side +software. This program is not built by default alongside other eCos +test cases since it will only operate in certain environments, +specifically when the target board's connector is plugged into a Linux +host, and when the appropriate host-side software has been installed +on that host. Instead the user must enable a configuration option +CYGBLD_IO_USB_SLAVE_USBTEST to add the program to +the list of tests for the current configuration.

Starting the usbtarget program does not +require anything unusual, so it can be run in a normal +gdb session just like any eCos application. +After initialization the program will wait for activity from the host. +Depending on the hardware, the Linux host will detect that a new USB +peripheral is present on the bus either when the +usbtarget initialization is complete or +when the cable between target and host is connected. The host will +perform the normal USB enumeration sequence and discover that the +peripheral does not match any known vendor or product id and that +there is no device driver for "Red Hat eCos USB +test", so it will ignore the peripheral. When the +usbhost program is run on the host it will +connect to the target-side software, and testing can now commence.

Building and Running the Host-side Code

The host-side software should be built via the usual sequence of +"configure/make/make install". It can only be built on a +Linux host and the configure script contains an +explicit test for this. Because the eCos component repository should +generally be treated as a read-only resource the configure script will +also prevent you from trying to build inside the source tree. Instead +a separate build tree is required. Hence a typical sequence for +building the host-side software would be as follows:

$ mkdir usbhost_build








    +$ cd usbhost_build








    +$ <repo>packages/io/usb/slave/current/host/configure   <args> 








    +$ make








    +<output from make>








    +$ su 








    +$ make install








    +<output from make install>








    +$

During make install the following actions will take +place:

1. usbhost will be installed in /usr/local/bin, +or some other bin directory if +the default location is changed at configure-time using a +--prefix= or similar option. It will be +installed as the executable +usbhost_<version>, for example +usbhost_current, thus allowing several +releases of the USB slave package to co-exist. For convenience a +symbolic link from usbhost to this executable +will be created, so users can just run usbhost to +access the most recently-installed version.

2. usbchmod will be installed in +/usr/local/libexec/ecos/io_usb_slave_<version>. +This program should only be run by usbhost, +not invoked directly, so it is not placed in the bin +directory. Again the presence of the package version in the directory +name allows multiple releases of the package to co-exist.

3. A Tcl script usbhost.tcl will get installed in +the same directory as usbchmod. This Tcl +script is loaded automatically by the +usbhost executable.

4. A number of additional Tcl scripts, for example +list.tcl will get installed alongside +usbhost.tcl. These correspond to various test +cases provided as standard. If a given test case is specified on the +command line and cannot be found relative to the current directory +then usbhost will search the install +directory for these test cases.

   Note: Strictly speaking installing the usbhost.tcl and +other Tcl scripts below the libexec +directory deviates from standard practice: they are +architecture-independent data files so should be installed below +the share subdirectory. In +practice the files are sufficiently small that there is no point in +sharing them, and keeping them below libexec +simplifies the host-side software somewhat.

The usbhost should be run only when there is a +suitable target attached to the USB bus and running the +usbtarget program. It will search +/proc/bus/usb/devices for an entry corresponding +to this program, invoke usbchmod if +necessary to change the access rights, and then interact with +usbtarget over the USB bus. +usbhost should be invoked as follows:

$ usbhost [-v|--version] [-h|--help] [-V|--verbose] <test> [<test parameters>]

1. The -v or --version +option will display version information for +usbhost including the version of the USB +slave package that was used to build the executable.

2. The -h or --help option +will display usage information.

3. The -V or --verbose +option can be used to obtain more information at run-time, for example +some output for every USB transfer. This option can be repeated +multiple times to increase the amount of output.

4. The first argument that does not begin with a hyphen specifies a test +that should be run, in the form of a Tcl script. For example an +argument of list.tcl will cause +usbhost to look for a script with that +name, adding a .tcl suffix if necessarary, and +run that script. usbhost will look in the +current directory first, then in the install tree for standard test +scripts provided by the USB slave package.

5. Some test scripts may want their own parameters, for example a +duration in seconds. These can be passed on the command line after +the name of the test, for example +usbhost mytest 60.

Writing a Test

Each test is defined by a Tcl script, running inside an interpreter +provided by usbhost. In addition to the +normal Tcl functionality this interpreter provides a number of +variables and functions related to USB testing. For example there is a +variable bulk_in_endpoints that lists all the +endpoints on the target that can perform bulk IN operations, and a +related array bulk_in which contains information +such as the minimum and maximum packets sizes. There is a function +bulktest which can be used to perform bulk tests +on a particular endpoint. A simple test script aimed at specific +hardware could ignore the information variables since it would know +exactly what USB hardware is available on the target, whereas a +general-purpose script would use the information to adapt to the +hardware capabilities.

To avoid namespace pollution all USB-related Tcl variables and +functions live in the usbtest:: namespace. +Therefore accessing requires either explicitly including the +namespace any references, for example +$usbtest::bulk_in_endpoints, or by using Tcl's +namespace import facility.

A very simple test script might look like this:

usbtest::bulktest 1 out 4000








    +usbtest::bulktest 2 in  4000








    +if { [usbtest::start 60] } {








    +    puts "Test successful"








    +} else








    +    puts "Test failed"








    +    foreach result $usbtest::results {








    +        puts $result








    +    }








    +}

This would perform a test run involving 4000 bulk transfers from the +host to the target's endpoint 1, and concurrently 4000 bulk transfers +from endpoint 2. Default settings for packet sizes, contents, and +delays would be used. The actual test would not start running until +usbtest is invoked, and it is expected that the +test would complete within 60 seconds. If any failures occur then they +are reported.

Available Hardware

Each target-side USB device driver provides information about the +actual capabilities of the hardware, for example which endpoints are +available. Strictly speaking it provides information about what is +actually supported by the device driver, which may be a subset of what +the hardware is capable of. For example, the hardware may support +isochronous transfers on a particular endpoint but if there is no +software support for this in the driver then this endpoint will not be +listed. When usbhost first contacts the +usbtarget program running on the target +platform, it obtains this information and makes it available to test +scripts via Tcl variables:

Testing Bulk Transfers

The main function for initiating a bulk test is +usbtest::bulktest. This takes three compulsory +arguments, and can be given a number of additional arguments to +control the exact behaviour. The compulsory arguments are:

Additional arguments can be used to control the exact transfer. For +example a txdelay+ argument can be used to +slowly increase the delay between transfers. All such arguments involve +a value which can be passed either as part of the argument itself, +for example txdelay+=5, or as a subsequent +argument, txdelay+ 5. The possible arguments fall +into a number of categories: data, I/O mechanism, transmit size, +receive size, transmit delay, and receive delay.

bulktest 2 IN 1000 data=wordseq data1=42 \








    +    data* $usbtest::MULTIPLIER data+ $usbtest::INCREMENT

Other Types of Transfer

Support for testing other types of USB traffic such as isochronous +transfers is not yet implemented.

Starting a Test and Collecting Results

A USB test script should prepare one or more transfers using +appropriate functions such as usbtest::bulktest. +Once all the individual tests have been prepared they can be started +by a call to usbtest::start. This takes a single +argument, a maximum duration measured in seconds. If all transfers +have not been completed in the specified time then any remaining +transfers will be aborted.

usbtest::start will return 1 +if all the tests have succeeded, or 0 if any of +them have failed. More detailed reports will be stored in the +Tcl variable usbtests::results, which will be a +list of string messages.

Existing Test Scripts

A number of test scripts are provided as standard. These are located +in the host subdirectory of the +common USB slave package, and will be installed as part of the process +of building the host-side software. When a script is specified on the +command line usbhost will first search for +it in the current directory, then in the install tree. Standard +test scripts include the following:

Possible Problems

If all transfers succeed within the specified time then both host and +target remain in synch and further tests can be run without problem. +However, if at any time a failure occurs then things get more +complicated. For example, if the current test involves a series of +bulk OUT transfers and the target detects that for one of these +transfers it received less data than was expected then the test has +failed, and the target will stop accepting data on this endpoint. +However the host-side software may not have detected anything wrong +and is now blocked trying to send the next lot of data.

The test code goes to considerable effort to recover from problems +such as these. On the host-side separate threads are used for +concurrent transfers, and on the target-side appropriate asynchronous +I/O mechanisms are used. In addition there is a control thread on the +host that checks the state of all the main host-side threads, and the +state of the target using private control messages. If it discovers +that one side has stopped sending or receiving data because of an +error and the other side is blocked as a result, it will set certain +flags and then cause one additional transfer to take place. That +additional transfer will have the effect of unblocking the other side, +which then discovers that an error has occurred by checking the +appropriate flags. In this way both host and target should end up back +in synch, and it is possible to move on to the next set of tests.

However, the above assumes that the testing has not triggered any +serious hardware conditions. If instead the target-side hardware has +been left in some strange state so that, for example, it will no +longer raise an interrupt for traffic on a particular endpoint then +recovery is not currently possible, and the testing software will just +hang.

A possible future enhancement to the testing software would allow the +host-side to raise a USB reset signal whenever a failure occurs, in +the hope that this would clear any remaining problems within the +target-side USB hardware.

Name

Synopsis

#include <cyg/io/usb/usbs.h>








    +








    +typedef struct usbs_control_endpoint {








    +    *hellip;








    +} usbs_control_endpoint;

usbs_control_endpoint Data Structure

The device driver for a USB slave device should supply one +usbs_control_endpoint data structure per USB +device. This corresponds to endpoint 0 which will be used for all +control message interaction between the host and that device. The data +structure is also used for internal management purposes, for example +to keep track of the current state. In a typical USB peripheral there +will only be one such data structure in the entire system, but if +there are multiple USB slave ports, allowing the peripheral to be +connected to multiple hosts, then there will be a separate data +structure for each one. The name or names of the data structures are +determined by the device drivers. For example, the SA11x0 USB device +driver package provides usbs_sa11x0_ep0.

The operations on a control endpoint do not fit cleanly into a +conventional open/read/write I/O model. For example, when the host +sends a control message to the USB peripheral this may be one of four +types: standard, class, vendor and reserved. Some or all of the +standard control messages will be handled automatically by the common +USB slave package or by the device driver itself. Other standard +control messages and the other types of control messages may be +handled by a class-specific package or by application code. Although +it would be possible to have devtab entries such as +/dev/usbs_ep0/standard and +/dev/usbs_ep0/class, and then support read and +write operations on these devtab entries, this would add significant +overhead and code complexity. Instead, all of the fields in the +control endpoint data structure are public and can be manipulated +directly by higher level code if and when required.

Control endpoints involve a number of callback functions, with +higher-level code installing suitable function pointers in the control +endpoint data structure. For example, if the peripheral involves +vendor-specific control messages then a suitable handler for these +messages should be installed. Although the exact details depend on the +device driver, typically these callback functions will be invoked at +DSR level rather than thread level. Therefore, only certain eCos +functions can be invoked; specifically, those functions that are +guaranteed not to block. If a potentially blocking function such as a +semaphore wait or a mutex lock operation is invoked from inside the +callback then the resulting behaviour is undefined, and the system as +a whole may fail. In addition, if one of the callback functions +involves significant processing effort then this may adversely affect +the system's real time characteristics. The eCos kernel documentation +should be consulted for more details of DSR handling.

typedef struct usbs_control_endpoint {








    +    …








    +    const usbs_enumeration_data* enumeration_data;








    +    void                         (*start_fn)(usbs_control_endpoint*);








    +    …








    +};

typedef struct usbs_control_endpoint {








    +    …








    +    int     state;








    +    void    (*state_change_fn)(struct usbs_control_endpoint*, void*,








    +                               usbs_state_change, int);








    +    void*   state_change_data;








    +    …








    +};








    +








    +#define USBS_STATE_DETACHED             0x01








    +#define USBS_STATE_ATTACHED             0x02








    +#define USBS_STATE_POWERED              0x03








    +#define USBS_STATE_DEFAULT              0x04








    +#define USBS_STATE_ADDRESSED            0x05








    +#define USBS_STATE_CONFIGURED           0x06








    +#define USBS_STATE_MASK                 0x7F








    +#define USBS_STATE_SUSPENDED            (1 << 7)








    +








    +typedef enum {








    +    USBS_STATE_CHANGE_DETACHED          = 1,








    +    USBS_STATE_CHANGE_ATTACHED          = 2,








    +    USBS_STATE_CHANGE_POWERED           = 3,








    +    USBS_STATE_CHANGE_RESET             = 4,








    +    USBS_STATE_CHANGE_ADDRESSED         = 5,








    +    USBS_STATE_CHANGE_CONFIGURED        = 6,








    +    USBS_STATE_CHANGE_DECONFIGURED      = 7,








    +    USBS_STATE_CHANGE_SUSPENDED         = 8,








    +    USBS_STATE_CHANGE_RESUMED           = 9








    +} usbs_state_change;

typedef struct usbs_control_endpoint {








    +    …








    +    unsigned char       control_buffer[8];








    +    usbs_control_return (*standard_control_fn)(struct usbs_control_endpoint*, void*);








    +    void*               standard_control_data;








    +    …








    +} usbs_control_endpoint;








    +








    +typedef enum {








    +    USBS_CONTROL_RETURN_HANDLED = 0,








    +    USBS_CONTROL_RETURN_UNKNOWN = 1,








    +    USBS_CONTROL_RETURN_STALL   = 2








    +} usbs_control_return;








    +








    +extern usbs_control_return usbs_handle_standard_control(struct usbs_control_endpoint*);

typedef struct usbs_control_endpoint {








    +    …








    +    usbs_control_return (*class_control_fn)(struct usbs_control_endpoint*, void*);








    +    void*               class_control_data;








    +    usbs_control_return (*vendor_control_fn)(struct usbs_control_endpoint*, void*);








    +    void*               vendor_control_data;








    +    usbs_control_return (*reserved_control_fn)(struct usbs_control_endpoint*, void*);








    +    void*               reserved_control_data;








    +    …








    +} usbs_control_endpoint;

typedef struct usbs_control_endpoint {








    +    …








    +    unsigned char*      buffer;








    +    int                 buffer_size;








    +    void                (*fill_buffer_fn)(struct usbs_control_endpoint*);








    +    void*               fill_data;








    +    int                 fill_index;








    +    usbs_control_return (*complete_fn)(struct usbs_control_endpoint*, int);








    +    …








    +} usbs_control_endpoint;

typedef struct usbs_control_endpoint {








    +    void                (*poll_fn)(struct usbs_control_endpoint*);








    +    int                 interrupt_vector;








    +    …








    +} usbs_control_endpoint;