4.1.1.1 Driver Host Root Hub Interface

The USB Driver Common Interface requires the USB Driver to be operating in Host mode to provide root hub control functions. If the USB peripheral does not contain root hub features in hardware, these features must be emulated in software by the driver. The USB peripheral on PIC32MX and PIC32MZ devices does not contain root hub features; therefore, the USB Driver for these peripherals emulates the root hub functionality in software. The rootHubInterface member of the DRV_USB_HOST_INTERFACE structure is a structure of type DRV_USB_ROOT_HUB_INTERFACE. The members of this structure are function pointers to the root hub control functions of the USB Driver.

Along with other Host mode functions, the USB Driver while operating in Host mode must also ensure that the rootHubInterface member of DRV_USB_HOST_INTERFACE is set up correctly so that the USB Host Stack can access the root hub functions. Descriptions of the function pointer types in the DRV_USB_ROOT_HUB_INTERFACE include:

  • Driver Host Root Hub Speed Get Function
  • Driver Host Root Hub Port Numbers Get Function
  • Driver Host Root Hub Maximum Current Get Function
  • Driver Host Root Hub Operation Enable Function
  • Driver Host Root Hub Operation Enable Status Function
  • Driver Host Root Hub Initialize Function

Driver Host Root Hub Speed Get Function

The rootHubSpeedGet member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Speed Get function. The signature of this function is as follows:

USB_SPEED (*rootHubSpeedGet)(DRV_HANDLE handle);

The USB Driver Root Hub Speed Get function must match this signature. The USB Host Stack calls this function to identify the speed at which the root hub is operating. The handle parameter is the handle obtained by calling the USB Driver Open function. The operation speed is configured by the USB Driver initialization and depends on the capability of the USB peripheral. For example, the USB peripheral on PIC32MZ devices supports both Hi-Speed and Full-Speed Host mode operation. It can be configured through initialization to only operate at Full-Speed. The Root Hub Speed Get function must return the USB speed at which the USB peripheral is operating. This should not be confused with the speed of the attached device.

Driver Host Root Hub Port Numbers Get Function

The rootHubPortNumbersGet member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Numbers Get function. The signature of this function is as follows:

USB_SPEED (*rootHubSpeedGet)(DRV_HANDLE handle);

The USB Driver Root Hub Speed Get function must match this signature. This function should return the number of ports that the root hub contains. On the USB peripheral for both PIC32MZ and PIC32MX devices, this value is always '1'.

Driver Host Root Hub Maximum Current Get Function

The rootHubMaxCurrentGet member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Maximum Current Get function. The signature of this function is as follows:

uint32_t (*rootHubMaxCurrentGet)(DRV_HANDLE handle);

The USB Driver Root Hub Maximum Current Get function must match this signature. This function returns the maximum VBUS current that the root hub can provide. The USB Host Stack calls this function to know the maximum current that the root hub VBUS power supply can provide. This value is then used to determine if the Host can support the current requirements of the attached device. The handle parameter is the driver handle obtained by calling the driver Open function.

The PIC32MX and the PIC32MZ USB peripherals cannot supply VBUS. The root hub driver only switches the VBUS supply. The current rating of the VBUS is specified through the USB Driver initialization. The root hub maximum current get function implementation in these drivers returns this value to the Host Stack.

Driver Host Root Hub Operation Enable Function

The rootHubOperationEnable member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Operation Enable function. The signature of this function is as follows:

void (*rootHubOperationEnable)(DRV_HANDLE handle, bool enable);

The USB Driver Root Hub Operation Enable function must match this signature. The USB Host Stack calls this function when it ready to receive device attach events from the root hub. Calling this function will cause the USB Driver root hub functionality to enable detection of device attach and detach. The USB Driver will then raise events to the USB Host Stack. The handle parameter is the driver handle obtained by calling the driver Open function. Setting the enable parameter to true enables the root hub operation. Setting the enable parameter to false disables the root hub operation.

Driver Host Root Hub Operation Enable Status Function

The rootHubOperationIsEnabled member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Operation Enable Status function. The signature of this function is as follows:

bool (*rootHubOperationIsEnabled)(DRV_HANDLE handle);

The USB Driver Root Hub Operation Enable Status function must match this signature. This USB Host Stack calls this function after calling the operation enable function to check if this has completed. The function returns true if the operation enable function has completed. The USB Host Stack will call this function periodically until it returns true.

Driver Host Root Hub Initialize Function

The rootHubInitialize member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Initialize function. The signature of this function is as follows:

void (*rootHubInitialize)(DRV_HANDLE handle, USB_HOST_DEVICE_OBJ_HANDLE usbHostDeviceInfo);

The USB Driver Root Hub Initialize function must match this signature. The USB Host Stack calls this function to assign a device identifier (usbHostDeviceInfo) to the root hub. This function is called before the Host Stack enables the root hub operation. The USB Driver root hub should use this identifier as the parent identifier when it calls the USB_HOST_DeviceEnumerate function to enumerate the attached device. At the time of enumeration, the USB Host Stack will use this parent identifier to identify the parent hub (whether root hub or external hub) of the attached device. The USB Driver root hub should retain the usbHostDeviceInfo parameter for the life time of its operation.