4.1.3 Driver General Client Functions

The DRV_USB_HOST_INTERFACE and the DRV_USB_DEVICE_INTERFACE structures contain pointers to the USB Driver’s General Client functions. These functions are not specific to the operation mode (Host, Device, or Dual Role) of the driver. A USB Driver must implement these functions and ensure that the Host or Device Stack can access these functions through the driver’s common interface structures. The common interface contains three general client functions:

  • Driver Open Function
  • Driver Close Function
  • Driver Event Handler Set Function

Driver Open Function

The open member of the DRV_USB_HOST_INTERFACE and the DRV_USB_DEVICE_INTERFACE structures should point to the USB Driver Open function. The signature of the Open function is as follows:

DRV_HANDLE (*open)(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent);

The USB Driver Open function must match this signature. The Driver Client uses the USB Driver index (drvIndex) to specify the instance of the USB module that Host Stack or the Device Stack should open. The USB Driver should ignore the intent parameter. The function should return a driver handle. If the driver is not ready to be opened, it should return an invalid handle (DRV_HANDLE_INVALID). In such a case, the client will continue trying to open the driver by calling the Open function again. The driver may also fail to open for an invalid index parameter or if USB module is in an error condition.

When supporting Dual Role operation, both the Host Stack and Device Stack will call the Driver Open function in one application. The USB Driver must support multiple calls to the Open function in the same application. The Open function should be thread-safe.

Driver Close Function

The close member of the DRV_USB_HOST_INTERFACE and the DRV_USB_DEVICE_INTERFACE structures should point to the USB Driver Close function. The signature of the Close function is as follows:

void (*close)(DRV_HANDLE handle);

The USB Driver Close function must match this signature. The Driver Client passes the handle obtained from the Driver Open function as a parameter to the close. The USB Host Stack or USB Device Stack will close the driver only when the stack is deinitialized (which is typically a rare case). The USB Driver should deallocate any client-related resources in the Close function. If the specified driver handle is not valid, the Close function should not have any side effects. The USB Driver expects the Close function to be called from the context of the thread in which the driver was opened; therefore, this function is not expected to be thread-safe.

Driver Event Handler Set Function

The eventHandlerSet member of the DRV_USB_HOST_INTERFACE and the DRV_USB_DEVICE_INTERFACE structures should point to the USB Driver Event Handler Set function. The signature of the Event Handler Set function is as follows:

void (*eventHandlerSet)(DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USB_EVENT_CALLBACK eventHandler);

The USB Driver Event Handler Set function must match this signature. The signature of the Client Event Handling function should match DRV_USB_EVENT_CALLBACK. The USB Driver calls this function when it must communicate USB events to the client. The client can set the eventHandler parameter to NULL if it does not want to receive USB Driver events. The client will receive Host mode events if the USB Driver is operating in Host mode. It will receive Device mode events if the USB Driver is operating in Device mode. The DRV_USB_EVENT type enumeration contains all the possible events that the USB Driver would generate. The following code example shows the enumeration.

// *****************************************************************************
/* USB Driver Events Enumeration

  Summary:
    Identifies the different events that the USB Driver provides.

  Description:
    Identifies the different events that the USB Driver provides. The USB Driver
    should be able to provide these events.

  Remarks:
    None.
*/typedefenum
{
    /* Bus error occurred and was reported. This event can be generated in both
     * Host and Device mode. */
    DRV_USB_EVENT_ERROR = 1,

    /* Host has issued a device Reset. This event occurs only in Device mode */
    DRV_USB_EVENT_RESET_DETECT,

    /* Resume detected while USB in suspend mode. This event can be generated in
     * both Host and Device mode. In Host mode, the events occurs when a remote
     * wakeup capable device has generated resume signaling. In Device mode,
     * this event will occur when the Host has issued resume signaling. */
    DRV_USB_EVENT_RESUME_DETECT,

    /* This event is generated in Device mode only. It occurs when the Host
     * suspends the bus and the bus goes idle. */
    DRV_USB_EVENT_IDLE_DETECT,

    /* This event is generated in Host mode and Device mode. In Host mode, this
     * event occurs when the device has stalled the Host. In Device mode, this
     * event occurs when the Host has accessed a stalled endpoint thus
     * triggering the device to send a STALL to the Host. */
    DRV_USB_EVENT_STALL,

    /* This event is generated in Host mode and Device mode. In Device mode,
     * this event occurs when a SOF has been generated by the Host. In Host
     * mode, this event occurs when controller is about to generate an SOF.
     * */
    DRV_USB_EVENT_SOF_DETECT,

    /* This event is generated in Device mode when the VBUS voltage is above
     * VBUS session valid. */
    DRV_USB_EVENT_DEVICE_SESSION_VALID,

    /* This event is generated in Device mode when the VBUS voltage falls
     * below VBUS session valid. */
    DRV_USB_EVENT_DEVICE_SESSION_INVALID,

} DRV_USB_EVENT;

This completes the discussion on the Driver General Client Functions.