Description

In order to support a target device, application code must create and initialize a usb_target object, which is then passed to the USB stack.

Throughout this section the code that instantiates and uses the target object is referred to an an "application". Normally this will be a device driver or other middleware that translates USB operations into some other interface that eCosPro understands. Examples would be the CDC ACM driver that translates USB traffic into a serial device, or the RNDIS driver that translates into a Ethernet driver interface.

The target mode stack retains the USB terminology for data transfer direction, which can be a little confusing. So a transfer which involves data being passed from the host to be received by the target, is referred to as an OUT transfer. Similarly, transmission from the target to the host is referred to an an IN transfer.

Target Object

A target object has the following structure:

struct usb_target
{
    usb_pcdi                    *pcdi;          // PCD device instance

    usb_uint32                  flags;          // Flags
    usb_uint8                   refcount;       // Reference counter
    usb_uint8                   id;             // Device ID
    usb_uint8                   state;          // Current target state

    const usb_device_descriptor *desc;          // Device descriptor
    const usb_device_qual_descriptor *qdesc;    // Device qualifier descriptor

    const usb_config_descriptor **configs;      // Array of configurations
    int                         config_count;   // Size of array
    const usb_config_descriptor *config_current;// Currently selected config

    const usb_string_descriptor **strings;      // Array of string descriptors
    int                         string_count;   // Size of array

    usb_target_endpoint         ep0;            // Control endpoint

    usb_target_interface        *interfaces;    // List of active interfaces

    void                        *data;          // Client private data pointer


    // Optional callbacks to user code

    // Control message escape
    int (*control)(usb_target *tgt, usb_request *req, void **buf, usb_uint16 *len );

    int (*new_state)(usb_target *tgt);          // Signals state change

    // Dynamic descriptor callback, called if the addressed static
    // descriptor pointer is NULL.
    int (*get_descriptor)(usb_target *tgt, usb_uint8 type, usb_uint8 index,
                          usb_uint8 **buf, usb_uint16 *len );

#if CYGINT_IO_USB_TARGET_INTERFACE_CALLBACK>0
    // Interface change callback
    int (*set_interface)(usb_target *tgt, usb_uint8 intf, usb_uint8 alt);
#endif
};

The fields of the target object are as follows:

String Descriptor Encoding

USB string descriptors are in Unicode, encoded in UTF-16LE. Unfortunately, this is not a character encoding that is directly supported by the GCC toolchain. There are a number of ways to work around this. The first, and simplest is to use the -fshort-char compiler option to force wchar_t to be 16 bits rather than the default 32 bits. Strings can then be prefixed by L to ensure 16 bit Unicode encoding. A typical static descriptor can then be defined as follows:

static const usb_string_descriptor mytgt_string_manufacturer =
{
    .bLength                            = 2+2*11,
    .bDescriptorType                    = USB_DESC_STRING,
    .bString                            = L"eCosCentric"
};

However, there are a number of problems with this. The encoding is strictly 16 bits, and any code points that require a surrogate pair cannot be defined. Compiling files with the -fshort-char option will throw up compiler warnings since it differs from the defaults with which the libraries will have been built. But, most importantly, it only works for little endian targets; big endian targets will generate the 16 bit values in big endian byte order.

A more portable approach would be to encode the UTF-16LE directly using optional byte swaps where necessary, as in the following example:

static const usb_string_descriptor mytgt_string_manufacturer =
{
    .bLength                            = 2+2*11,
    .bDescriptorType                    = USB_DESC_STRING,
    .bString                            = { USB_CPU_TO_LE16('e'),
                                            USB_CPU_TO_LE16('C'),
                                            USB_CPU_TO_LE16('o'),
                                            USB_CPU_TO_LE16('s'),
                                            …
                                          }
};

However, this approach is clumsy and does not allow the size or contents of the string to be made a configuration option, or even easy to change in the code.

The preferred approach in the USB stack is to generate and store string descriptors in UTF-8 and to convert them to UTF-16LE at run time, when the descriptor is requested. A UTF-8 string is just a sequence of bytes and can be defined and manipulated like any other byte array. Most text editors will allow a UTF-8 string to be created or pasted in from some other source without any problems. Most UTF-8 strings occupy less space than their UTF-16LE equivalents. A standard ASCII string is just a UTF-8 string that contains no code points beyond the basic ASCII set.

To simplify use of UTF-8 strings, the USB stack exports a couple of helper functions. The function usb_string_descriptor_utf8() takes a pointer and length of a buffer in which a string descriptor is created, and a pointer to a UTF-8 string. It recodes the UTF-8 string into UTF-16LE in the buffer together with setting the descriptor size and type. If successful, the buffer will contain a string descriptor ready to be transmitted. If the buffer is not large enough for the descriptor, an error code will be returned.

The function usb_string_descriptor_create() is passed a buffer pointer and length, the index of the descriptor to be returned and a pointer to an array of UTF-8 strings. It checks that the index is correct and then creates a new string descriptor in the buffer using the indexed string from the array; it calls usb_string_descriptor_utf8() to do this.

To put all this together, the strings for a device can be defined statically as follows:

static const usb_string_descriptor mytgt_string_langid =
{
    .bLength                            = 2+2*1,
    .bDescriptorType                    = USB_DESC_STRING,
    .bString                            = { USB_CPU_TO_LE16(0x0809) },
};

static const usb_string_descriptor *mytgt_string_descriptors[1] =
{
    [0]                 = &mytgt_string_langid,
};

static const char *mytgt_descriptor_strings[] =
{
    [1]                 = "eCosCentric",
    [2]                 = "My Device",
    [3]                 = "01234567890",
};

In the target object, the strings field is set to point to mytgt_string_descriptors and string_count set to 1. This will cause the USB target stack to call the target's get_descriptor function for the remaining string descriptors. This function should look like the following example:

static usb_uint8 mytgt_dynamic_desc[64];       // Dynamic descriptor buffer

static int mytgt_get_descriptor(usb_target *tgt, usb_uint8 type, usb_uint8 index,
                                usb_uint8 **buf, usb_uint16 *len )
{
    int result = USB_OK;

    // A non-NULL buffer pointer is the USB stack returning the buffer
    // to us for reuse.
    if( *buf != NULL )
        return USB_OK;

    if( type == USB_DESC_STRING )
    {
        result = usb_string_descriptor_create( mytgt_dynamic_desc, sizeof(mytgt_dynamic_desc),
                                               index,
                                               mytgt_descriptor_strings,
                                               sizeof(mytgt_descriptor_strings)/sizeof(char *) );
        if( result == USB_OK )
        {
            *buf = mytgt_dynamic_desc;
            *len = mytgt_dynamic_desc[0];
        }
    }
    else
    {
        // Handle any other descriptor types
    }

    return result;
}

Note that in this example the serial number string is a constant. For devices where a unique serial number is required for each unit, a different approach may be needed. First the unit must have a unique identifier that can be used for this purpose. Depending on the platform this could be fetched from EPROM, FLASH, a serial number chip or a built-in chip ID. The simplest approach is to convert this value into an ASCII string. Then in the get_descriptor() function this string can be converted to a string descriptor when the serial number is requested. For an example take a look at the hid_test.c test program where a serial number is manufactured from a checksum of the executable.

Target Object API

The USB stack exports a number of functions that are intended for use by applications using targets.

The function usb_target_attach() must be called to attach a target to a specific peripheral interface. Peripheral interfaces are named and a pointer to a particular interface can be obtained by calling usb_pcdi_find_by_name(). Following this, most target events will be handled by the USB stack with calls to the callbacks as necessary. If the application wants to stop the target, it should call usb_target_detach().

Some USB protocols require an endpoint stall to signal various conditions. The function usb_target_endpoint_stall() allows this to be done. The ep argument contains the endpoint address, and should have USB_ENDPOINT_ADDR_IN set for IN endpoints. The stall argument is 1 to stall the endpoints and zero to clear the stall condition.

An application must instantiate a usb_target object and initialize it before calling usb_target_attach(). Typically this object can be defined statically as in the following example:

static usb_target mytgt_target =
{
    .desc               = &mytgt_device_descriptor,
    .qdesc              = &mytgt_device_qual_descriptor,

    .configs            = mytgt_config_descriptors,
    .config_count       = 1,

    .strings            = mytgt_string_descriptors,
    .string_count       = 1,

    .control            = mytgt_control,
    .new_state          = mytgt_new_state,
    .get_descriptor     = mytgt_get_descriptor,

    .data               = &mytgt_data,
};

This defines the target object, initializes the static descriptors and callbacks. No fields beyond those shown above need to be initialized. While none of the fields is mandatory, if a static descriptor is not present, the get_descriptor() callback will be called, so it is not sensible to have both NULL descriptors and no get_descriptor().

Once the application has started, it should locate the PCDI it wants to attach the target to and call usb_target_attach(), as in the following example:

void mytgt_init( void )
{
    usb_pcdi *pcdi;

    // Find PCDI by name
    pcdi = usb_pcdi_find_by_name( "usb_fs" );

    if( pcdi == NULL )
    {
        // Handle error
    }

    // Attach our target to the PCDI
    result = usb_target_attach( &mytgt_target, pcdi );

    if( result != USB_OK )
    {
        // Handle error
    }
}

Once the target has been attached, all further interaction with the application will be via the callbacks. Most new_state() callbacks can be ignored while the target is going through the initial connect/reset/address sequence. The transition to CONFIGURED state is the most important since this is when the target should become ready to interact with the host. Normally this will be the point at which it submits transfers to the OUT endpoints to receive packets from the host and maybe starts sending data via the IN endpoints.

For a complete example take a look at the acm_example.c test program. This source is annotated with extra comments. The usbms_tgt.c and hid_test.c test programs in packages/io/usb/<version>/tests directory. The CDC/ACM protocol driver can also examined for example code.