Description

A class driver translates between operations on a standard eCos device interface and operations on a USB device. For example the USB mass storage class driver translates between disk driver operations and USB mass storage operations.

USB Class Object

A class driver interfaces initially to the USB stack through a usb_class_driver object:

struct usb_class_driver
{
    usb_node            node;           // Link in class driver list
    int                 priority;       // Priority in list

    int                 (*attach)( usb_class_driver *class_driver,
                                   usb_device *device );

    int                 (*detach)( usb_class_driver *class_driver,
                                   usb_device *device );

    void                (*poll)( usb_class_driver *class_driver,
                                 usb_uint32 interval );
};

The fields in this structure are as follows:

USB Class API

The USB stack exports a number of functions that are intended for use by class drivers.

The function usb_class_driver_register() is used by a class driver to register itself with the USB stack. Typically a class driver is initialized as an instance of the driver type that it is intending to serve (e.g. disk, network, serial etc.) and during the initialization function for that driver will call usb_class_driver_register(). If the driver ever needs to detach itself from the USB stack then it can call usb_class_driver_deregister().

Within the attach() function, the class driver can call some USB stack functions to help it decide whether a device is one that it can support. The most important of these is usb_device_class_find() which scans the descriptors attached to a a device for an interface that implements the given class, subclass and protocol types. A value of -1 for subclass and protocol acts as a wildcard. If successful it returns pointers to the configuration and interface found. The function usb_descriptor_find() can be used on dev->desc_chain, or any other descriptor pointer, to find the next descriptor of a given type. The class driver can also just inspect the device and parse the descriptor chain itself if necessary.

Before returning, the attach() function should call usb_device_configure(). Which will configure the device to use the configuration descriptor is supplied. The class driver must also supply a callback which will be called when the configuration has been done, or has failed. Further device setup can then be done in the callback.

Putting all that together, the functions of a class driver should have the following approximate form:

//-----------------------------------------------------------------------------
// Attach device call

static int mydev_attach( usb_class_driver *class_driver, usb_device *dev )
{
    int result = USB_OK;
    mydev_data *mydev;

    // Look for configuration and interface. Here we assume that the
    // first configuration is the one we want to use and that we are
    // not worried about the function type, hence the wildcard.
    usb_descriptor *cdesc, *idesc;

    usb_device_class_find( dev, USB_CLASS_MYCLASS, USB_SUBCLASS_MYSUBCLASS, -1, &cdesc, &idesc );

    if( cdesc == NULL || idesc == NULL )
        return USB_ERR_NO_SUPPORT;

    // Set up device data structures here...
    mydev = mydev_alloc();
    mydev->dev = dev;

    // Extract any useful information from the interface descriptor
    // chain, such as endpoint addresses...

    // Reference the device
    usb_device_ref( dev );

    // Send off a command to select the configuration
    // we have found.
    result = usb_device_configure( dev, cdesc, mydev_attach_tfr_done, mydev );

    // If it all worked, set the device's class driver to point to us.
    if( result == USB_OK )
        dev->device.class_driver = class_driver;

    return result;
}

//-----------------------------------------------------------------------------
// Configuration callback

static int mydev_attach_tfr_done( usb_tfr *tfr )
{
    int result = tfr->status;
    mydev_data *mydev = tfr->callback_data;
    usb_device *dev = tfr->dev;

    // Release tfr object
    usb_tfr_unref( tfr );

    if( result != USB_OK )
    {
        // Handle configuration error by detaching from USB device and
        // freeing local resources.
        mydev_free( mydev );
        usb_device_unref( dev );
        return result;
    }

    // Continue device initialization...

    return result;
}

//-----------------------------------------------------------------------------
// Device detach call

static int mydev_detach( usb_class_driver *class_driver, usb_device *dev )
{
    int result = USB_OK;

    // Find my device data from device pointer.
    mydev_data *mydev = mydev_find( dev );

    // Shut down device...

    // Free device data structure
    mydev_free( mydev );

    // Release reference to device
    usb_device_unref( dev );

    return result;
}

//-----------------------------------------------------------------------------
// Device poll call

static void mydev_poll( usb_class_driver *class_driver, usb_uint32 interval )
{
    // Handle timeouts and delays in active devices...
}