4.1.1.2 Driver Host USB Root Hub Port Interface

The rootHubPortInterface member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Port functions. The data type of this member is USB_HUB_INTERFACE. This data type is a structure containing function pointers pointing to the port control functions of the root hub. The USB Driver must assign the function pointers in this structure to the root hub port control functions. These same functions are also exported by a Hub Driver to the USB Host Stack, which allow the Host Stack to control a device regardless of whether it is connected to a root hub or an external hub. The port functions are valid only when a device is attached to the port. The behavior of these functions on a port to which no device is connected is not defined. Descriptions of the port control functions are provided, which include:

  • Driver Host Hub Port Reset Function
  • Driver Host Hub Port Reset Completion Status Function
  • Driver Host Hub Port Suspend Function
  • Driver Host Hub Port Resume Function
  • Driver Host Hub Port Speed Get Function

Driver Host Hub Port Reset Function

The hubPortReset member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Reset function. The signature of this function is as follows:

USB_ERROR (*hubPortReset)(uintptr_t hubAddress, uint8_t port);

The USB Driver Root Hub Port Reset function must follow this signature. This function starts reset signaling on the port. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. The USB Host Stack uses the parent identifier provided by the root hub driver when the USB_HOST_DeviceEnumerate function was called to query the driver handle that is linked to this root hub. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier.

For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this must be set to the port to which the device is connected. The function returns USB_ERROR_NONE if the function was successful. If the reset signaling is already in progress on the port, calling this function has no effect. The USB Driver will itself time duration of the reset signal. This does not require USB Host Stack intervention. The USB Host Stack will call the port reset completion status function to check if the reset signaling has completed. Calling this function on a port which exists on an external hub will cause the hub driver to issue a control transfer to start the port reset procedure.

Driver Host Hub Port Reset Completion Status Function

The hubPortResetIsComplete member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Reset Completion Status function. The signature of this function is as follows:

bool (*hubPortResetIsComplete)(uintptr_t hubAddress, uint8_t port);

The USB Driver Root Hub Port Reset Completion Status function must follow this signature. The USB Host Stack calls this function to check if the port reset sequence that was started on a port has completed. The function returns true if the reset signaling has completed. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier.

For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this parameter must be set to the port to which the device is connected.

Driver Host Hub Port Suspend Function

The hubPortSuspend member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Suspend function. The signature of this function is as follows:

USB_ERROR(*hubPortSuspend)(uintptr_t hubAddress, uint8_t port);

The USB Driver Root Hub Port Suspend function must follow this signature. The USB Host Stack calls this function to suspend the port. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier.

For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this parameter must be set to the port to which the device is connected. The function returns USB_ERROR_NONE if the request was successful. Calling this function on a suspended port will not have any effect.

Driver Host Hub Port Resume Function

The hubPortResume member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Resume function. The signature of this function is as follows:

USB_ERROR(*hubPortResume)(uintptr_t hubAddress, uint8_t port);

The USB Driver Root Hub Port Resume function must follow this signature. The USB Host Stack calls this function to resume a suspended port. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier.

For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this parameter must be set to the port to which the device is connected. The function returns USB_ERROR_NONE if the request was successful. Calling this function on a port that is not suspended will not have any effect.

Driver Host Hub Port Speed Get Function

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

USB_SPEED(*hubPortSpeedGet)(uintptr_t hubAddress, uint8_t port);

The USB Driver Root Hub Port Speed Get function must follow this signature. The USB Host Stack calls this function to obtain the USB speed of the device that is attached to the port. The Host Stack calls this function only after it has completed reset of the port. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier.

For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this parameter must be set to the port to which the device is connected. The function returns USB_SPEED_ERROR if the request was not successful. It will return the functional USB speed otherwise.

This concludes the section describing the USB Driver Host mode Client Functions. The USB Driver Device Mode Client Functions are discussed in the next section.