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;