SAMV71 Xplained Ultra Software Package 1.4

USB host Controller (UHC)
[USB Stack Host]

Collaboration diagram for USB host Controller (UHC):

Data Structures

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

Modules

 Implementation of UHC
 USB Host Controller (UHC) - Prerequisites
 USB Host Controller (UHC) - Example code
 USB Device Controller (UHC) - Workflow

Defines

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

Enumerations

enum  USBH_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 USBH_start (void)
 Starts the host mode.
void USBH_stop (bool b_id_stop)
 Stops the host mode.
void USBH_suspend (bool b_remotewakeup)
 Suspends a USB line.
bool USBH_is_suspend (void)
 Test if the suspend state is enabled on the USB line.
void USBH_resume (void)
 Resumes the USB line.

User functions to manage a device



uint8_t USBH_get_device_number (void)
 Returns the number of connected devices.
char * USBH_dev_get_string_manufacturer (USBH_device_t *dev)
 Gets the USB string manufacturer from a USB device.
char * USBH_dev_get_string_product (USBH_device_t *dev)
 Gets the USB string product from a USB device.
char * USBH_dev_get_string_serial (USBH_device_t *dev)
 Gets the USB string serial from a USB device.
char * USBH_dev_get_string (USBH_device_t *dev, uint8_t str_id)
 Gets a USB string from a USB device.
uint16_t USBH_dev_get_power (USBH_device_t *dev)
 Gets the maximum consumption of a device (mA).
USBH_Speed_t USBH_dev_get_speed (USBH_device_t *dev)
 Returns the current device speed.
bool USBH_dev_is_high_speed_support (USBH_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.

Detailed Description

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(USBH_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(USBH_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(USBH_device_t* dev, uint8_t b_status)
Called when a USB device enumeration is completed or fail.


Enumeration Type Documentation

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.

Definition at line 169 of file USBH.h.


Function Documentation

uint16_t USBH_dev_get_power ( USBH_device_t dev  ) 

Gets the maximum consumption of a device (mA).

Parameters:
dev Device to request
Returns:
Maximum consumption of the device (mA)

Definition at line 1212 of file USBH.c.

USBH_Speed_t USBH_dev_get_speed ( USBH_device_t dev  ) 

Returns the current device speed.

Parameters:
dev Device to request
Returns:
Device speed

Definition at line 1217 of file USBH.c.

char* USBH_dev_get_string ( USBH_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:
dev Device to request
str_id String ID requested
Returns:
Pointer on unicode string, or NULL if function fails.

Definition at line 1147 of file USBH.c.

Here is the call graph for this function:

char* USBH_dev_get_string_manufacturer ( USBH_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:
dev Device to request
Returns:
Pointer on unicode string, or NULL if function fails.

Definition at line 1123 of file USBH.c.

Here is the call graph for this function:

char* USBH_dev_get_string_product ( USBH_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:
dev Device to request
Returns:
Pointer on unicode string, or NULL if function fails.

Definition at line 1131 of file USBH.c.

Here is the call graph for this function:

char* USBH_dev_get_string_serial ( USBH_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:
dev Device to request
Returns:
Pointer on unicode string, or NULL if function fails.

Definition at line 1139 of file USBH.c.

Here is the call graph for this function:

bool USBH_dev_is_high_speed_support ( USBH_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:
dev Device to request
Returns:
True, if high speed is supported

Definition at line 1222 of file USBH.c.

Here is the call graph for this function:

uint8_t USBH_get_device_number ( void   ) 

Returns the number of connected devices.

Returns:
Number of device connected on USB tree

Definition at line 1102 of file USBH.c.

bool USBH_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

Definition at line 1058 of file USBH.c.

Here is the call graph for this function:

void USBH_stop ( bool  b_id_stop  ) 

Stops the host mode.

Parameters:
b_id_stop Stop USB ID pin management, if true.

Definition at line 1038 of file USBH.c.

void USBH_suspend ( bool  b_remotewakeup  ) 

Suspends a USB line.

Parameters:
b_remotewakeup Authorize the remote wakeup features, if true

Definition at line 1044 of file USBH.c.

Here is the call graph for this function:

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines