Description

Most interaction between clients of the USB stack and the stack itself happens through the use of transfer objects (or just transfers). These data structures are allocated and initialized by the client and passed to the USB stack. When the transfer completes, the client is notified via a callback, following which it may release or reuse the object for another transfer.

Transfer Class Object

A transfer has the following structure:

struct usb_tfr
{
    usb_node                    node;           // List/queue node

    union
    {
        usb_device              *dev;           // Host device
        usb_target              *tgt;           // Target device
    };

    usb_uint16                  refcount;       // Reference count
    usb_uint16                  endpoint;       // Endpoint address
    usb_uint8                   attr;           // Transfer type
    usb_uint8                   flags;          // Additional flags
    int                         status;         // Current/returned status

    void                        *tfr_buffer;    // Data buffer
    usb_uint16                  tfr_size;       // Size of transfer/buffer
    usb_uint16                  tfr_actual;     // Actual size transferred

    usb_tfr_callback            *callback[2];   // Completion callback stack
    void                        *callback_data; // Callback data

    // The following fields are used by the HCD or PCD
    void                        *hcd_endpoint;  // HCD endpoint private data
    usb_list                    hcd_list;       // HCD transfer list

    // Per-transfer-type fields.
    union
    {
        struct
        {
            usb_uint8           setup[8];       // Setup packet
        } control;
        struct
        {
        } bulk;
#ifdef USB_CONFIG_INTERRUPT
        struct
        {
        } interrupt;
#endif
#ifdef USB_CONFIG_ISOCHRONOUS
        struct
        {
            int                 start_frame;    // Start frame
            int                 interval;       // transfer interval
            int                 pkt_count;      // Number of packets
            usb_iso_packet_desc *iso_packet;    // packet descriptors
        } isochronous;
#endif
    };
};

The fields of the transfer are as follows:

API

There are a number of API functions associated with the management of transfer objects.

Host mode clients should allocate a transfer by calling usb_device_tfr_alloc(). The result will be a pointer to a transfer which has been zeroed except that the node field will be initialized, the dev field will be set to the supplied device pointer and the refcount will be set to 1. Additionally, usb_device_ref() will have been called on the device. This function will return a NULL pointer if there are no transfers available for allocation.

Target mode clients should allocate a transfer by calling usb_target_tfr_alloc(). The result will be a pointer to a transfer which has been zeroed except that the node field will be initialized, the tgt field will be set to the supplied target pointer, the refcount will be set to 1 and usb_target_ref() will have been called on the target. The flags field will be initialized with the USB_TFR_FLAGS_TARGET flag. This function will return a NULL pointer if there are no transfers available for allocation.

If a client needs to take further reference to the transfer it can call usb_tfr_ref(). References are released by calling usb_tfr_unref(). When a client is finished with a transfer it should call usb_tfr_unref() a last time to release the initial reference. This may have the side-effect of calling usb_device_unref() or usb_target_unref() which may result in the device object being freed.

In general, a transfer is initialized by one of several routines to create a specific type of transfer. The most general initialization routine is usb_tfr_init() which sets up the transfer with the endpoint address and attributes, a data buffer, and a callback. This is the only initialization function that should be applied to target mode transfers, the remaining initialization functions only apply to host mode transfers.

Control transfer initialization is supported by a number of functions. The function usb_tfr_control() initializes a general control transfer. The endpoint argument is used to look up the endpoint in the device and initialize the endpoint and attr fields in the transfer. The req argument points to a completed USB request that will be copied into the setup buffer. The data buffer and callback are initialized too. The USB request can be initialized using the usb_request_init() macro. The first argument to this is the name of the request to initialize, not a pointer. The remaining arguments give values for the various fields; the 16 bit fields will potentially be byte swapped into little endian order.

The function usb_control_tfr() provided a higher level interface to create control transfers that do not transfer additional data. This is given the destination device plus values for the request type, request code, value and index field (but not the length), and the callback. Using these parameters, a transfer is allocated, a request buffer created and the transfer initialized with an endpoint address of zero. If a transfer cannot be allocated, a NULL pointer is returned.

A bulk transfer can be initialized using usb_tfr_bulk(). The endpoint argument is used to look up the endpoint in the device and initialize the endpoint and attr fields in the transfer. The buffer and callback are also initialized.

Interrupt and Isochronous transfers are not currently supported, but when they are similar functions to initialize those will be available.

A transfer is submitted to the USB stack by calling usb_submit(). This function performs some simple checks before passing the transfer on to the appropriate driver. If this function is passed a NULL transfer, it will return USB_ERR_TFR_ALLOC. The transfer initialization routines also return if a NULL transfer is passed to them. This allows detection and handling of transfer allocation failures in most cases to be deferred until this call, keeping error handling simpler.

A transfer can be cancelled by calling usb_cancel(). This may simply mark the transfer for cancellation, the transfer may not actually be cancelled until some time after this function returns. When the transfer is actually cancelled, its callback will be called with a status of USB_TFR_CANCELLED. However, if the transfer was already finished, or caused an error, the callback status may be USB_OK or an error code. Thus client code cannot rely on the transfer completing with a CANCELLED status; this call just ensures that the transfer will be returned to the client in some way. Note that it is not very useful to cancel host mode control or bulk transfers since they will usually be processed as soon as submitted and will be returned quickly; the client is unlikely to catch them in time.