Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
USB host Controller (UHC)

The UHC provides a high-level abstraction of the usb host.

You can use these functions to control the main host state (start/suspend/resume/...).

USB host user configuration

The following USB host configuration must be included in the conf_usb_host.h file of the application.

USB_HOST_UHI (List of UHI APIs)
Define the list of UHI supported by USB host. (Ex.: UHI_MSC,UHI_HID_MOUSE).

USB_HOST_POWER_MAX (mA)
Maximum current allowed on Vbus.

USB_HOST_HS_SUPPORT (Only defined)
Authorize the USB host to run in High Speed.

USB_HOST_HUB_SUPPORT (Only defined)
Authorize the USB HUB support.

USB host user callback

The following optional USB host callback can be defined in the conf_usb_host.h file of the application.

void UHC_MODE_CHANGE(bool b_host_mode)
To notify that the USB mode are switched automatically. This is possible only when ID pin is available.

void UHC_VBUS_CHANGE(bool b_present)
To notify that the Vbus level has changed (Available only in USB hardware with Vbus monitoring).

void UHC_VBUS_ERROR(void)
To notify that a Vbus error has occurred (Available only in USB hardware with Vbus monitoring).

void UHC_CONNECTION_EVENT(uhc_device_t* dev,bool b_present)
To notify that a device has been connected or disconnected.

void UHC_WAKEUP_EVENT(void)
Called when a USB device or the host have wake up the USB line.

void UHC_SOF_EVENT(void)
Called for each received SOF each 1 ms. Available in High and Full speed mode.

uint8_t UHC_DEVICE_CONF(uhc_device_t* dev)
Called when a USB device configuration must be chosen. Thus, the application can choose either a configuration number for this device or a configuration number 0 to reject it. If callback not defined the configuration 1 is chosen.

void UHC_ENUM_EVENT(uhc_device_t* dev, uint8_t b_status)
Called when a USB device enumeration is completed or fail.

Modules

 Implementation of UHC
 Internal implementation.
 
 USB Host Controller (UHC) - Prerequisites
 Common prerequisites for all USB hosts.
 
 USB Host Controller (UHC) - Example code
 Common example code for all USB hosts.
 
 USB Device Controller (UHC) - Workflow
 Common workflow for all USB devices.
 

Data Structures

struct  uhc_device_t
 Structure to store device information. More...
 

Macros

#define UHC_BSS(x)   COMPILER_ALIGNED(x)
 
#define UHC_DATA(x)   COMPILER_ALIGNED(x)
 

Enumerations

enum  uhc_enum_status_t {
  UHC_ENUM_SUCCESS = 0,
  UHC_ENUM_UNSUPPORTED,
  UHC_ENUM_OVERCURRENT,
  UHC_ENUM_FAIL,
  UHC_ENUM_HARDWARE_LIMIT,
  UHC_ENUM_SOFTWARE_LIMIT,
  UHC_ENUM_MEMORY_LIMIT,
  UHC_ENUM_DISCONNECT
}
 Enumeration status Used in UHC_ENUM_EVENT() callback when a USB device enumeration is completed. More...
 

Functions to control the USB host stack

void uhc_start (void)
 Starts the host mode. More...
 
void uhc_stop (bool b_id_stop)
 Stops the host mode. More...
 
void uhc_suspend (bool b_remotewakeup)
 Suspends a USB line. More...
 
bool uhc_is_suspend (void)
 Test if the suspend state is enabled on the USB line. More...
 
void uhc_resume (void)
 Resumes the USB line. More...
 
bool uhc_suspend_lpm (bool b_remotewakeup, uint8_t hird)
 Suspends a USB line through LPM feature. More...
 

User functions to manage a device

uint8_t uhc_get_device_number (void)
 Returns the number of connected devices. More...
 
char * uhc_dev_get_string_manufacturer (uhc_device_t *dev)
 Gets the USB string manufacturer from a USB device. More...
 
char * uhc_dev_get_string_product (uhc_device_t *dev)
 Gets the USB string product from a USB device. More...
 
char * uhc_dev_get_string_serial (uhc_device_t *dev)
 Gets the USB string serial from a USB device. More...
 
char * uhc_dev_get_string (uhc_device_t *dev, uint8_t str_id)
 Gets a USB string from a USB device. More...
 
uint16_t uhc_dev_get_power (uhc_device_t *dev)
 Gets the maximum consumption of a device (mA) More...
 
uhd_speed_t uhc_dev_get_speed (uhc_device_t *dev)
 Returns the current device speed. More...
 
bool uhc_dev_is_high_speed_support (uhc_device_t *dev)
 Tests if the device supports the USB high speed This function can wait the end of a setup request and the timing can be long (1ms to 5s). More...
 
void uhc_dev_reset (uhc_device_t *dev)
 Reset to re-enumerate. More...
 

#define UHC_BSS (   x)    COMPILER_ALIGNED(x)
#define UHC_DATA (   x)    COMPILER_ALIGNED(x)

Enumeration status Used in UHC_ENUM_EVENT() callback when a USB device enumeration is completed.

Enumerator
UHC_ENUM_SUCCESS 

Device is enumerated.

The supported USB device interfaces has been enabled.

UHC_ENUM_UNSUPPORTED 

None of the interfaces are supported by the UHIs.

UHC_ENUM_OVERCURRENT 

Device power is not supported.

UHC_ENUM_FAIL 

A problem occurred during USB enumeration.

UHC_ENUM_HARDWARE_LIMIT 

USB hardware can not support it. Not enough free pipes.

UHC_ENUM_SOFTWARE_LIMIT 

USB software can not support it. Implementation limit.

UHC_ENUM_MEMORY_LIMIT 

USB software can not support it. Not enough memory.

UHC_ENUM_DISCONNECT 

The device has been disconnected during USB enumeration.

uint16_t uhc_dev_get_power ( uhc_device_t dev)

Gets the maximum consumption of a device (mA)

Parameters
devDevice to request
Returns
Maximum consumption of the device (mA)

References usb_conf_desc_t::bMaxPower, and uhc_device_t::conf_desc.

uhd_speed_t uhc_dev_get_speed ( uhc_device_t dev)

Returns the current device speed.

Parameters
devDevice to request
Returns
Device speed

References uhc_device_t::speed.

char* uhc_dev_get_string ( uhc_device_t dev,
uint8_t  str_id 
)

Gets a USB string from a USB device.

This function waits the end of setup requests and the timing can be long (3ms to 15s). Thus, do not call it in an interrupt routine. This function allocates a buffer which must be free by user application.

Parameters
devDevice to request
str_idString ID requested
Returns
Pointer on unicode string, or NULL if function fails.

References usb_str_desc_t::bLength, usb_setup_req_t::bmRequestType, usb_setup_req_t::bRequest, le16_to_cpu, usb_str_lgid_desc_t::string, uhc_setup_request_callback(), uhc_setup_request_finish, uhc_setup_request_finish_status, uhd_setup_request(), UNUSED, USB_DT_STRING, USB_REQ_DIR_IN, USB_REQ_GET_DESCRIPTOR, USB_REQ_RECIP_DEVICE, USB_REQ_TYPE_STANDARD, usb_setup_req_t::wIndex, usb_setup_req_t::wLength, and usb_setup_req_t::wValue.

Referenced by uhc_dev_get_string_manufacturer(), uhc_dev_get_string_product(), and uhc_dev_get_string_serial().

char* uhc_dev_get_string_manufacturer ( uhc_device_t dev)

Gets the USB string manufacturer from a USB device.

This function waits the end of setup requests and the timing can be long (3ms to 15s). Thus, do not call it in an interrupt routine. This function allocates a buffer which must be free by user application.

Parameters
devDevice to request
Returns
Pointer on unicode string, or NULL if function fails.

References uhc_device_t::dev_desc, usb_dev_desc_t::iManufacturer, and uhc_dev_get_string().

char* uhc_dev_get_string_product ( uhc_device_t dev)

Gets the USB string product from a USB device.

This function waits the end of setup requests and the timing can be long (3ms to 15s). Thus, do not call it in an interrupt routine. This function allocates a buffer which must be free by user application.

Parameters
devDevice to request
Returns
Pointer on unicode string, or NULL if function fails.

References uhc_device_t::dev_desc, usb_dev_desc_t::iProduct, and uhc_dev_get_string().

char* uhc_dev_get_string_serial ( uhc_device_t dev)

Gets the USB string serial from a USB device.

This function waits the end of setup requests and the timing can be long (3ms to 15s). Thus, do not call it in an interrupt routine. This function allocates a buffer which must be free by user application.

Parameters
devDevice to request
Returns
Pointer on unicode string, or NULL if function fails.

References uhc_device_t::dev_desc, usb_dev_desc_t::iSerialNumber, and uhc_dev_get_string().

bool uhc_dev_is_high_speed_support ( uhc_device_t dev)

Tests if the device supports the USB high speed This function can wait the end of a setup request and the timing can be long (1ms to 5s).

Thus, do not call it in an interrupt routine.

Parameters
devDevice to request
Returns
True, if high speed is supported

References usb_setup_req_t::bmRequestType, usb_setup_req_t::bRequest, uhc_device_t::speed, uhc_setup_request_callback(), uhc_setup_request_finish, uhc_setup_request_finish_status, uhd_setup_request(), UHD_SPEED_FULL, UHD_SPEED_HIGH, USB_DT_DEVICE_QUALIFIER, USB_REQ_DIR_IN, USB_REQ_GET_DESCRIPTOR, USB_REQ_RECIP_DEVICE, USB_REQ_TYPE_STANDARD, usb_setup_req_t::wIndex, usb_setup_req_t::wLength, and usb_setup_req_t::wValue.

void uhc_dev_reset ( uhc_device_t dev)

Reset to re-enumerate.

Parameters
devDevice to request

References uhc_device_t::conf_desc, dev, uhc_enum_try, uhc_enumeration_step3(), UHC_NB_UHI, and uhi_api_t::uninstall.

uint8_t uhc_get_device_number ( void  )

Returns the number of connected devices.

Returns
Number of device connected on USB tree

References uhc_device_t::address, dev, g_uhc_device_root, and UHC_USB_ADD_NOT_VALID.

bool uhc_is_suspend ( void  )

Test if the suspend state is enabled on the USB line.

Returns
USB line in SUSPEND state or device not connected, if true

References uhc_device_t::address, UHC_USB_ADD_NOT_VALID, and uhd_is_suspend().

Referenced by uhc_resume(), and UI_WAKEUP_HANDLER().

void uhc_resume ( void  )

Resumes the USB line.

References uhc_is_suspend(), and uhd_resume().

Referenced by UI_WAKEUP_HANDLER().

void uhc_start ( void  )

Starts the host mode.

void uhc_stop ( bool  b_id_stop)

Stops the host mode.

Parameters
b_id_stopStop USB ID pin management, if true.
void uhc_suspend ( bool  b_remotewakeup)

Suspends a USB line.

Parameters
b_remotewakeupAuthorize the remote wakeup features, if true

References uhc_enum_try, uhc_remotewakeup(), and uhd_suspend().

Referenced by ui_usb_sof_event().

bool uhc_suspend_lpm ( bool  b_remotewakeup,
uint8_t  hird 
)

Suspends a USB line through LPM feature.

Parameters
b_remotewakeupAuthorize the remote wakeup features, if true
hirdHost Initiated Resume Duration
Returns
flase if the LPM is not supported by USB Device

References uhc_device_t::lpm_desc, uhc_enum_try, and uhd_suspend_lpm().