usbdfunc(7)

SYNPOSIS

#include "usbd.h"
#include "usbd-func.h"

DESCRIPTION

This man page documents the interface that the USB Function Driver uses to connect to the USB Device core layer.

In the USB Device Architecture the Function Driver implements a matching function for a specific USB host Class Driver. Typically this implements or emulates a standard Unix driver such as a network or character device.

Specifically the top layer of the Function Driver implements the standard interface for some function. It encapsulates the data given it and sends it to the USB host Class Driver via the USB bus.

Similarily data received from USB host is given to the user of the device.

The main interface to the USB Device core layer is through two routines:

    usbd_register_function(struct *usb_function_driver)

    usbd_deregister_function(struct *usb_function_driver)

These pass a pointer to a struct usb_function_driver.

This structure contains information required by the USB Device core layer to identify the Function being implemented and the various functions required to send and receive data.

    struct usb_function_driver {
        const char *name;
        struct usb_function_operations
    	*ops;

        struct usb_device_description
    	*device_description;
        struct usb_configuration_description
    	*configuration_description;
        int configurations;

        ....
    };

    ops
         this is a list of C functions this module implements to perform the operations required by the USB Device core layer.

    device_description
         this is a pointer to a structure that contains information used by the USB Device core layer to create a Device Descriptor. This is passed to the USB host during the enumeration process.

    configuration description
         this is a pointer to a structure that contains information used by the USB Device core layer to create a Configuration Descriptors. These are passed to the USB host during the enumeration process.

    configurations
         the number of different configurations that the configuration description describes.

The usb_function_operations structure is used to pass pointers to the functions implemented by the Function driver.

    struct usb_function_operations {
        void (* event)(struct usb_device_instance *, usb_device_event_t);
        int (* urb_sent) (struct urb *, int);
        int (* recv_urb) (struct urb *);
        int (* recv_setup) (struct urb *);
        int (* alloc_urb_data) (struct urb *, int );
        void (* dealloc_urb_data) (struct urb *);
        void (* function_init) (struct usb_bus_instance *,
    	struct usb_device_instance *, struct usb_function_driver *);
        void (* function_exit) (struct usb_bus_instance *);
    };

    event
        This function is called by the USB Device core layer to pass various events to the Function driver. These match the changes defined in the state diagram defined in chapter 9 USB Device Framework, section 9.1.1, in the USB specification. The events are passed through a task queue. This means that these functions are not executing in an interrupt context and may call other kernel functions that may sleep.

    urb_sent
        The Function driver sends data in a structure called an urb using a function called usbd_send_urb(). When the urb has been sent the USB Device core layer will call the urb_sent function to notify the Function driver that it has finished sending the data or has stopped attempting to send the data.

    recv_urb
        The USB Device core layer will use the recv_urb function to pass received (from the USB host via an OUT transaction) to the Function driver.

    recv_setup
        The USB Device core layer will use the recv_setup function to pass received setup packets (from the USB host via an OUT transaction) to the Function driver.

    alloc_urb_data
        The USB Device core layer implements a function called usbd_alloc_urb which is used to allocate an urb structure with associated data storage. The data storage can optionally be allocated by the Function driver if it implements the usbd_alloc_urb function.

    dealloc_urb_data
        The USB Device core layer implements a function called usbd_dealloc_urb which is used to deallocate an urb structure and associated data storage. The data storage can optionally be deallocated by the Function driver if it implements the usbd_dealloc_urb function.

    function_init
        The USB Device core layer will call function_init after a USB bus interface driver has called to create a new logical USB device.

    function_exit
        The USB Device core layer will call function_exit after a USB bus interface driver has called to destroy a new logical USB device.

The usb_device_description struture describes the Function device sufficently for the USB Device core layer to construct a device descriptor. The definition of the device descriptor is given chapter 9 USB Device Framework, section 9.6.1 in the USB specification.

    struct usb_device_description {
        __u8                bDeviceClass;
        __u8                bDeviceSubClass;
        __u8                bDeviceProtocol;
        __u16               idVendor;
        __u16               idProduct;
        char               *iManufacturer;
        char               *iProduct;
        char               *iSerialNumber;
    };

The usb_configuration_description struture describes the Function device configurations sufficently for the USB Device core layer to construct a set of configuration descriptors. The definition of the configuration descriptor is given chapter 9 USB Device Framework, section 9.6.3 in the USB specification.

    struct usb_configuration_description {
        char               *iConfiguration;
        __u8                bmAttributes;
        __u8                bMaxPower;

        __u8                interfaces;
        struct usb_interface_description *interface_list;
        int                 configuration_type;
    };

The usb_interface_description struture describes the Function device sufficently for the USB Device core layer to construct an interface descriptor. The definition of the interface descriptor is given chapter 9 USB Device Framework, section 9.6.5 in the USB specification.

    struct usb_interface_description {
        __u8                bInterfaceClass;
        __u8                bInterfaceSubClass;
        __u8                bInterfaceProtocol;
        char               *iInterface;
        __u8                alternates;
        struct usb_alternate_description *alternate_list;
    };

The usb_alternate_description struture describes the Function device sufficently for the USB Device core layer to construct alternate versions of interface descriptors.
    struct usb_alternate_description {
        char               *iInterface;
        __u8                bAlternateSetting;

        __u8                classes;
        struct usb_class_description *class_list;

        __u8                endpoints;
        struct usb_endpoint_description *endpoint_list;
    };

The usb_endpoint_description struture describes an Function device endpoint sufficently for the USB Device core layer to construct an endpoint descriptor. The definition of the endpoint descriptor is given chapter 9 USB Device Framework, section 9.6.6 in the USB specification.

    struct usb_endpoint_description {
        __u8                bEndpointAddress;
        __u8                bmAttributes;
        __u16               wMaxPacketSize;
        __u8                bInterval;
        __u8                direction;
        __u32               transferSize;
    };

    transferSize
        This is additional information provided by the Function driver to tell the Bus Interface driver that maximum size of Bulk Data Transfers.

EXAMPLES

This is a the descriptions for a simple serial device.

static struct usb_endpoint_description serial_default[] =
{
    { bEndpointAddress: 1, bmAttributes: BULK,
        wMaxPacketSize: 64, bInterval: 0,
        direction: OUT, transferSize: 64, },
    { bEndpointAddress: 2, bmAttributes: BULK,
        wMaxPacketSize: 64, bInterval: 0,
        direction: IN, transferSize: 64, },
    { bEndpointAddress: 3, bmAttributes: INTERRUPT,
        wMaxPacketSize: 16, bInterval: 0,
        direction: IN, transferSize: 16, },
};
static __initdata struct usb_alternate_description
	serial_data_alternate_descriptions[] =
{
    {   iInterface: "Simple Serial Data Interface - Bulk mode",
        bAlternateSetting: 0,
        endpoints: sizeof(serial_default)/
		sizeof(struct usb_endpoint_description),
        endpoint_list: serial_default, },
};
static __initdata struct usb_interface_description serial_interfaces[] =
{
    {   iInterface: "Simple Serial Data Interface",
        bInterfaceClass: 0xff,
        bInterfaceSubClass: 0xff,
        bInterfaceProtocol: 0xff,
        alternates: sizeof(serial_data_alternate_descriptions)/
		sizeof(struct usb_alternate_description),
        alternate_list: serial_data_alternate_descriptions, },
};
struct __initdata usb_configuration_description serial_description[] =
{
    {   iConfiguration: "USB Simple Serial Configuration",
        bmAttributes: BMATTRIBUTE,
        bMaxPower: BMAXPOWER,
        interfaces: sizeof(serial_interfaces)/sizeof(struct usb_interface_description),
        interface_list: serial_interfaces, },
};
struct __initdata usb_device_description serial_device_description =
{
    bDeviceClass:       VENDOR,
    bDeviceSubClass:    0,
    bDeviceProtocol:    0,
    idVendor:           0x555,
    idProduct:          0x666,
    iManufacturer:      "USB Products Co.",
    iProduct:           "USB Dummy Serial Device",
    iSerialNumber:      "01234",
};

BUGS

AUTHOR

Stuart Lynne <sl@lineo.com>

Bruce Balden <balden@lineo.com>

Tom Rushworth <tbr@lineo.com>

SEE ALSO

usbd(7), usbdfunc(7)

Universal Serial Bus Specification, Revision 2.0

Universal Serial Bus Class Definitions for Communications Devices, Version 1.1