USB Device Driver

Introduction to USB devices

As perceived by humans, a USB device is a piece of hardware that does useful things.

From the USB host point of view a USB device is a piece of hardware exhibiting the following behaviour:

1. it may appear and disappear on the USB bus at any time or be already present when USB host powers on
2. when it appears, it needs to be reset. After reset, it will answer requests at address 0. At this point, certain pieces of device-specific data become available and software running on the host can determine device type
3. if we want to communicate with the device, host needs to assign it the non-zero address and pick device configuration
4. after addressing and configuring we can start exchanging useful information with the device. The exchange is specific to the device (class).

Steps 2 and 3 are called enumeration.

In UHS3, enumeration is performed by USB Core component. Since different devices require different actions to be performed

Base device driver class

The UHS_USBInterface class in UHS_usbhost.h file provides common interface to device drivers. Every new device must inherit from it.

Coding device driver

The members are described here.

    `UHS_USB_HOST_BASE *pUsb` - a pointer to USB class instance 


    volatile uint8_t bNumEP; // total number of EP in this interface
    volatile UHS_EpInfo epInfo[16]; // This is a stub, override in the driver header.

    volatile uint8_t bAddress; // address of the device
    volatile uint8_t bConfNum; // configuration number
    volatile uint8_t bIface; // interface value
    volatile bool bPollEnable; // poll enable flag, operating status
    volatile uint32_t qNextPollTime; // next poll time

    /**
     * Resets interface driver to unused state
     */
    virtual void DriverDefaults(void) {
            pUsb->DeviceDefaults(bNumEP, this);
    };

    virtual bool OKtoEnumerate(ENUMERATION_INFO *ei) {
            return false;
    };

This function is called by the USB core after device descriptor is retrieved, signalling back whether a 
 particular device is supported.



    /**
     * Configures any needed endpoint information for an interface.
     *
     * @param ei
     * @return zero on success
     */
    virtual uint8_t SetInterface(ENUMERATION_INFO *ei) {
            return UHS_HOST_ERROR_NOT_IMPLEMENTED;
    };

    /**
     * Interface specific additional setup and enumeration that
     * can't occur when the descriptor stream is open.
     * Also used for collection of unclaimed interfaces, to link to the master.
     *
     * @return zero on success
     */
    virtual uint8_t Finalize(void) {
            return 0;
    };

    /**
     *  Executed after interface is finalized but, before polling has started.
     *
     * @return 0 on success
     */
    virtual uint8_t OnStart(void) {
            return 0;
    };

    /**
     * Start interface polling
     * @return
     */
    virtual uint8_t Start(void) {
            uint8_t rcode = OnStart();
            if(!rcode) bPollEnable = true;
            return rcode;
    };

    /**
     * Executed before anything else in Release().
     *
     */
    virtual void OnRelease(void) {
            return;
    };

    /**
     * Release resources when device is disconnected
     */
    virtual void Release(void) {
            OnRelease();
            DriverDefaults();
    };

    /**
     * Executed when there is an important change detected during polling.
     * Examples:
     * Media status change for bulk, e.g. ready, not-ready, media changed, door opened.
     * Button state/joystick position/etc changes on a HID device.
     * Flow control status change on a communication device, e.g. CTS on serial
     */
    virtual void OnPoll(void) {
            return;
    };

    /**
     * Poll interface driver
     */
    virtual void Poll() {
            OnPoll();
    };

    /**
     * This is only for a hub.
     * @param port
     */
    virtual void ResetHubPort(uint8_t port) {
            return;
    };

    /**
     *
     * @return true if this interface is Vendor Specific.
     */
    virtual bool IsVSI() {
            return false;
    }