Description

Whenever a new device or hub is attached to a USB, a device object is created to represent it in the USB stack. Most users of the USB stack do not need to concern themselves with the contents of a device object, so most of the information here is for the use of USB stack developers.

Host Device Object

This structure does double duty for both standard devices and for hubs. The internal union separates out the role specific fields. This structure also has two typedef names, usb_device and usb_hub, which can be used interchangeably, but help keep track of which role the structure is currently being used in. A device object has the following structure:

struct usb_device
{
    usb_node                    node;           // Node in per-hub list
    usb_bus                     *bus;           // Controlling bus
    usb_hub                     *parent;        // Parent hub

    usb_uint32                  flags;          // Flags
    usb_uint8                   refcount;       // Reference counter
    usb_uint8                   id;             // Device ID
    usb_uint8                   port;           // Port on parent hub
    usb_uint8                   state;          // Current device state
    usb_uint8                   state_data;     // Associated data

    usb_device_descriptor       desc;           // Device descriptor
    usb_descriptor              *config;        // Current configuration
    usb_descriptor              *interface;     // Current interface
    usb_descriptor              *desc_chain;    // Chain of all descriptors

    usb_resource_client         res_client;     // Resource client

    void                        *hcd_priv;      // HCD private data

    usb_device_endpoint         *endpoints;     // List of active endpoints

    union
    {
        struct
        {
            union
            {
                // Used only during initialization
                usb_uint8               *buf;          // Descriptor read buffer
                usb_config_descriptor   *config;       // Config descriptor view of buf

                // Used only when state >= RUNNING
                usb_class_driver        *class_driver; // Attached class driver

            };

        } device;
        struct
        {
            int                 port_count;     // Number of downstream ports
            usb_hub_port_status port_status[USB_HUB_PORT_MAX+1];

            usb_uint8           *buf;           // Descriptor read buffer

            usb_list            devices;        // List of attached devices

            // Status tfr state
            usb_tfr             *status_tfr;    // Current status change tfr
            usb_uint8           status_buf[4];  // Status change buffer
            usb_descriptor      *intr_desc;     // Interrupt endpoint descriptor

            // TODO: Power allocation stuff

            // TODO: Transaction translator stuff
        } hub;
    };
};

The fields of the device are as follows:

Device Lifecycle

From initial attachment through configuration, data transfer and final detachment, a device goes through a lifecycle in the USB stack. This section looks at this lifecycle.

When a physical device is attached to a port on a hub the state change is detected by the hub state machine (see Hub Lifecycle). This results in a device object being created and initialized. The refcount is set to 1, representing a reference held by the physical device.

A device runs through a state machine that is generally run in the callbacks of transfers, delays and resource allocations. Each state assesses the result of the previous operation, issues new transfers/delays/allocations, sets the next state and waits for completion. States are generally named for the operation for which they waiting to complete. The device moves through the following states:

When a device detach is detected by the hub state machine, usb_device_detach() is called. This function puts the device into DETACH state, deallocates the device ID and unlinks the device from the parent hub. If the device is a hub, then it also recursively detaches any devices attached to the ports of this hub. If the device has a class driver attached to it, then the driver's detach routine is called. Finally, usb_device_unref() is called to remove the physical device's reference. This should result in the device being deallocated once any pending transfers have terminated.

Hub Lifecycle

Initially a hub passes through the same state machine as any other device to reset it, allocate an ID and read the descriptors. Once this is done and the device is identified as a hub, control moves to the hub state machine, which is an additional set of states to the device state machine.