CMSIS Driver  Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
USB Host Interface

Driver API for USB Host Peripheral (Driver_USBH.h) More...

Data Structures

struct  ARM_DRIVER_USBH
 Access structure of USB Host Driver. More...
 
struct  ARM_USBH_CAPABILITIES
 USB Host Driver Capabilities. More...
 
struct  ARM_USBH_STATE
 USB Host State. More...
 
struct  ARM_USBH_URB
 USB Host USB Request Block (URB) More...
 
union  ARM_USBH_URB.__unnamed__
 
struct  ARM_USBH_URB.__unnamed__.__unnamed__
 

Typedefs

typedef uint32_t ARM_USBH_EP_HANDLE
 USB Host Endpoint Handle.
 
typedef void(* ARM_USBH_SignalPortEvent_t )(uint8_t port, ARM_USBH_EVENT event)
 Pointer to ARM_USBH_SignalPortEvent : Signal Root HUB Port Event.
 
typedef void(* ARM_USBH_SignalEndpointEvent_t )(ARM_USBH_EP_HANDLE ep_hndl, ARM_USBH_URB *ptr_urb)
 Pointer to ARM_USBH_SignalEndpointEvent : Signal Endpoint Event.
 

Enumerations

enum  ARM_USBH_STATUS {
  ARM_USBH_OK = 0,
  ARM_USBH_ERROR = 1
}
 USB Host Status of executed operation. More...
 
enum  ARM_USBH_EVENT {
  ARM_USBH_EVENT_CONNECT,
  ARM_USBH_EVENT_DISCONNECT,
  ARM_USBH_EVENT_REMOTE_WAKEUP,
  ARM_USBH_EVENT_OVERCURRENT
}
 USB Host Root HUB Port Event Type. More...
 

Functions

DRV_VERSION ARM_USBH_GetVersion (void)
 Get driver version.
 
ARM_USBH_CAPABILITIES ARM_USBH_GetCapabilities (void)
 Get driver capabilities.
 
ARM_USBH_STATUS ARM_USBH_Initialize (ARM_USBH_SignalPortEvent_t cb_port_event, ARM_USBH_SignalEndpointEvent_t cb_endpoint_event)
 Initialize USB Host Interface.
 
ARM_USBH_STATUS ARM_USBH_Uninitialize (void)
 De-initialize USB Host Interface.
 
ARM_USBH_STATUS ARM_USBH_PowerControl (ARM_POWER_STATE state)
 Control USB Host Interface Power.
 
ARM_USBH_STATUS ARM_USBH_PortPowerOnOff (uint8_t port, bool power)
 Root HUB Port Power on/off.
 
ARM_USBH_STATUS ARM_USBH_PortReset (uint8_t port)
 Do Root HUB Port Reset.
 
ARM_USBH_STATUS ARM_USBH_PortSuspend (uint8_t port)
 Suspend Root HUB Port (stop generating SOFs).
 
ARM_USBH_STATUS ARM_USBH_PortResume (uint8_t port)
 Resume Root HUB Port (start generating SOFs).
 
ARM_USB_STATUS ARM_USBH_PortGetState (uint8_t port)
 Get current Root HUB Port connection State.
 
ARM_USBH_EP_HANDLE ARM_USBH_EndpointCreate (uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)
 Create Endpoint in System.
 
ARM_USBH_STATUS ARM_USBH_EndpointConfigure (ARM_USBH_EP_HANDLE ep_hndl, uint8_t dev_addr, uint8_t ep_speed, uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)
 Configure/reconfigure some properties of Endpoint.
 
fn ARM_USBH_STATUS ARM_USBH_EndpointDelete (ARM_USBH_EP_HANDLE ep_hndl)
 Delete Endpoint from System.
 
ARM_USBH_STATUS ARM_USBH_EndpointClearHalt (ARM_USBH_EP_HANDLE ep_hndl)
 Clear Halt condition on USB Endpoint.
 
uint32_t ARM_USBH_URB_Submit (ARM_USBH_EP_HANDLE ep_hndl, ARM_USBH_URB *ptr_urb)
 Submit USB Request Block (URB) for Processing.
 
uint32_t ARM_USBH_URB_Abort (ARM_USBH_EP_HANDLE ep_hndl, ARM_USBH_URB *ptr_urb)
 Abort Processing of USB Request Block (URB).
 
void ARM_USBH_SignalPortEvent (uint8_t port, ARM_USBH_EVENT event)
 Signal Root HUB Port Event.
 
void ARM_USBH_SignalEndpointEvent (ARM_USBH_EP_HANDLE ep_hndl, ARM_USBH_URB *ptr_urb)
 Signal Endpoint Event. Occurs when URB processing completes.
 

Description

Driver API for USB Host Peripheral (Driver_USBH.h)

USB Host API

The header file Driver_USBH.h defines the API for the USB Host Driver interface used by middleware components. The driver implementation itself is a typical part of the Device Family Pack, which provides entry points to the interface as function pointers in the struct ARM_DRIVER_USBH. This structure can be available several times in each interface to control multiple USBH interfaces.

Driver_USBH.h also defines callback routines, which are categorized in port event callbacks and endpoint event callbacks. Callbacks are called by the driver, in interrupt context when an appropriate event occurs, to signal port related events (ARM_USBH_SignalPortEvent) and endpoint related events (ARM_USBH_SignalEndpointEvent).

USB Host Function Call Sequence

To use the USBH driver invoke the API functions in the following order:

msc_inline_mscgraph_2


Data Structure Documentation

struct ARM_DRIVER_USBH

Access structure of USB Host Driver.

Contains the function entry address of all USBH interface functions. Functions marked as optional expose a NULL pointer when not implemented.

Note
The struct must remain unchanged.

Data Fields

ARM_DRV_VERSION(* GetVersion )(void)
 Pointer to ARM_USBH_GetVersion : Get driver version.
 
ARM_USBH_CAPABILITIES(* GetCapabilities )(void)
 Pointer to ARM_USBH_GetCapabilities : Get driver capabilities.
 
ARM_USBH_STATUS(* Initialize )(ARM_USBH_SignalPortEvent_t cb_port_event, ARM_USBH_SignalEndpointEvent_t cb_endpoint_event)
 Pointer to ARM_USBH_Initialize : Initialize USB Host Interface.
 
ARM_USBH_STATUS(* Uninitialize )(void)
 Pointer to ARM_USBH_Uninitialize : De-initialize USB Host Interface.
 
ARM_USBH_STATUS(* PowerControl )(ARM_POWER_STATE state)
 Pointer to ARM_USBH_PowerControl : Control USB Host Interface Power.
 
ARM_USBH_STATUS(* PortPowerOnOff )(uint8_t port, bool power)
 Pointer to ARM_USBH_PortPowerOnOff : Root HUB Port Power on/off.
 
ARM_USBH_STATUS(* PortReset )(uint8_t port)
 Pointer to ARM_USBH_PortReset : Do Root HUB Port Reset.
 
ARM_USBH_STATUS(* PortSuspend )(uint8_t port)
 Pointer to ARM_USBH_PortSuspend : Suspend Root HUB Port (stop generating SOFs).
 
ARM_USBH_STATUS(* PortResume )(uint8_t port)
 Pointer to ARM_USBH_PortResume : Resume Root HUB Port (start generating SOFs).
 
ARM_USBH_STATE(* PortGetState )(uint8_t port)
 Pointer to ARM_USBH_PortGetState : Get current Root HUB Port connection State.
 
ARM_USBH_EP_HANDLE(* EndpointCreate )(uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)
 Pointer to ARM_USBH_EndpointCreate : Create Endpoint in System.
 
ARM_USBH_STATUS(* EndpointConfigure )(ARM_USBH_EP_HANDLE ep_hndl, uint8_t dev_addr, uint8_t ep_speed, uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)
 Pointer to ARM_USBH_EndpointConfigure : Configure/reconfigure some properties of Endpoint.
 
ARM_USBH_STATUS(* EndpointDelete )(ARM_USBH_EP_HANDLE ep_hndl)
 Pointer to ARM_USBH_EndpointDelete : Delete Endpoint from System.
 
ARM_USBH_STATUS(* EndpointClearHalt )(ARM_USBH_EP_HANDLE ep_hndl)
 Pointer to ARM_USBH_EndpointClearHalt : Clear Halt condition on Endpoint.
 
ARM_USBH_STATUS(* URB_Submit )(ARM_USBH_EP_HANDLE ep_hndl, ARM_USBH_URB *ptr_urb)
 Pointer to ARM_USBH_URB_Submit : Submit USB Request Block (URB) for Processing.
 
ARM_USBH_STATUS(* URB_Abort )(ARM_USBH_EP_HANDLE ep_hndl, ARM_USBH_URB *ptr_urb)
 Pointer to ARM_USBH_URB_Abort : Abort Processing of USB Request Block (URB).
 

Field Documentation

ARM_USBH_STATUS(* EndpointClearHalt)(ARM_USBH_EP_HANDLE ep_hndl)

Pointer to ARM_USBH_EndpointClearHalt : Clear Halt condition on Endpoint.

ARM_USBH_STATUS(* EndpointConfigure)(ARM_USBH_EP_HANDLE ep_hndl, uint8_t dev_addr, uint8_t ep_speed, uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)

Pointer to ARM_USBH_EndpointConfigure : Configure/reconfigure some properties of Endpoint.

ARM_USBH_EP_HANDLE(* EndpointCreate)(uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval)

Pointer to ARM_USBH_EndpointCreate : Create Endpoint in System.

ARM_USBH_STATUS(* EndpointDelete)(ARM_USBH_EP_HANDLE ep_hndl)

Pointer to ARM_USBH_EndpointDelete : Delete Endpoint from System.

ARM_USBH_CAPABILITIES(* GetCapabilities)(void)

Pointer to ARM_USBH_GetCapabilities : Get driver capabilities.

ARM_DRV_VERSION(* GetVersion)(void)

Pointer to ARM_USBH_GetVersion : Get driver version.

ARM_USBH_STATUS(* Initialize)(ARM_USBH_SignalPortEvent_t cb_port_event, ARM_USBH_SignalEndpointEvent_t cb_endpoint_event)

Pointer to ARM_USBH_Initialize : Initialize USB Host Interface.

ARM_USBH_STATE(* PortGetState)(uint8_t port)

Pointer to ARM_USBH_PortGetState : Get current Root HUB Port connection State.

ARM_USBH_STATUS(* PortPowerOnOff)(uint8_t port, bool power)

Pointer to ARM_USBH_PortPowerOnOff : Root HUB Port Power on/off.

ARM_USBH_STATUS(* PortReset)(uint8_t port)

Pointer to ARM_USBH_PortReset : Do Root HUB Port Reset.

ARM_USBH_STATUS(* PortResume)(uint8_t port)

Pointer to ARM_USBH_PortResume : Resume Root HUB Port (start generating SOFs).

ARM_USBH_STATUS(* PortSuspend)(uint8_t port)

Pointer to ARM_USBH_PortSuspend : Suspend Root HUB Port (stop generating SOFs).

ARM_USBH_STATUS(* PowerControl)(ARM_POWER_STATE state)

Pointer to ARM_USBH_PowerControl : Control USB Host Interface Power.

ARM_USBH_STATUS(* Uninitialize)(void)

Pointer to ARM_USBH_Uninitialize : De-initialize USB Host Interface.

ARM_USBH_STATUS(* URB_Abort)(ARM_USBH_EP_HANDLE ep_hndl, ARM_USBH_URB *ptr_urb)

Pointer to ARM_USBH_URB_Abort : Abort Processing of USB Request Block (URB).

ARM_USBH_STATUS(* URB_Submit)(ARM_USBH_EP_HANDLE ep_hndl, ARM_USBH_URB *ptr_urb)

Pointer to ARM_USBH_URB_Submit : Submit USB Request Block (URB) for Processing.

struct ARM_USBH_CAPABILITIES

USB Host Driver Capabilities.

A USB Host driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.

Returned by:

Note
The struct must remain unchanged.
Data Fields
uint32_t event_connect: 1 Signal Connect event.
uint32_t event_disconnect: 1 Signal Disconnect event.
uint32_t event_overcurrent: 1 Signal Overcurrent event.
uint32_t event_remote_wakeup: 1 Signal Remote Wakeup event.
uint32_t reserved: 12 reserved for future use
uint32_t rh_port_mask: 16 Root HUB available Ports Mask.
struct ARM_USBH_STATE

USB Host State.

This structure stores information about the state of a USB Host. The bitfields encode whether the device is active, connected, and powered. Finally, it stores the established speed.

Returned by:

Data Fields
uint8_t active: 1 USB Host active flag.
uint8_t connected: 1 USB Host connected flag.
uint8_t overcurrent: 1 USB Host overcurrent flag.
uint8_t speed: 2 USB Host speed setting.
struct ARM_USBH_URB

USB Host USB Request Block (URB)

Data Fields
union ARM_USBH_URB __unnamed__
union ARM_USBH_URB __unnamed__
uint8_t * buf < USB Request Block (URB) Buffer for read/write data
uint8_t * buf_cur Current position in read/write buffer.
uint32_t len Requested read/write length.
uint32_t len_cur Current length transferred.
uint32_t nak_retries Number of NAK retries.
union ARM_USBH_URB.__unnamed__
Data Fields
__unnamed__ __unnamed__
uint8_t parameters Transfer Parameters.
struct ARM_USBH_URB.__unnamed__.__unnamed__
Data Fields
uint8_t packet_type: 4 Packet Type.
uint8_t toggle_bit: 1 Toggle Bit Value.
uint8_t toggle_force: 1 Toggle Bit Forced (if cleared toggle_bit value is ignored)

Typedef Documentation

USB Host Endpoint Handle.

Each Endpoint is identified through a unique number, which is created by the function ARM_USBH_EndpointCreate.

Parameter for:

Retruned by:

ARM_USBH_SignalEndpointEvent_t

Pointer to ARM_USBH_SignalEndpointEvent : Signal Endpoint Event.

Provides the typedef for the callback function ARM_USBH_SignalEndpointEvent.

Parameter for:

ARM_USBH_SignalPortEvent_t

Pointer to ARM_USBH_SignalPortEvent : Signal Root HUB Port Event.

Provides the typedef for the callback function ARM_USBH_SignalPortEvent.

Parameter for:

Enumeration Type Documentation

USB Host Root HUB Port Event Type.

Provides the event information for the ARM_USBH_SignalPortEvent callback function (which is registered by the function ARM_USBH_Initialize). The function ARM_USBH_GetCapabilities returns information of the implemented callback events in a driver.

Parameter for:

Enumerator:
ARM_USBH_EVENT_CONNECT 

USBH Event: USB Device Connected to Port.

ARM_USBH_EVENT_DISCONNECT 

USBH Event: USB Device Disconnected from Port.

ARM_USBH_EVENT_REMOTE_WAKEUP 

USBH Event: USB Device activated Remote Wakeup.

ARM_USBH_EVENT_OVERCURRENT 

USBH Event: USB Device caused Overcurrent.

USB Host Status of executed operation.

Defines status and error codes returned by most of the USBH driver functions.

Returned by:

Enumerator:
ARM_USBH_OK 

USBH Status: Operation succeeded.

ARM_USBH_ERROR 

USBH Status: Unspecified error.

Function Documentation

ARM_USBH_STATUS ARM_USBH_EndpointClearHalt ( ARM_USBH_EP_HANDLE  ep_hndl)

Clear Halt condition on USB Endpoint.

Parameters
[in]ep_hndlEndpoint Handle
Returns
execution status ARM_USBH_STATUS

Clear Hald condition on USB Endpoint.

ARM_USBH_STATUS ARM_USBH_EndpointConfigure ( ARM_USBH_EP_HANDLE  ep_hndl,
uint8_t  dev_addr,
uint8_t  ep_speed,
uint8_t  ep_addr,
ARM_USB_ENDPOINT_TYPE  ep_type,
uint16_t  ep_max_packet_size,
uint8_t  ep_interval 
)

Configure/reconfigure some properties of Endpoint.

Parameters
[in]ep_hndlEndpoint Handle
[in]dev_addrDevice Address
[in]ep_speedEndpoint Speed
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
[in]ep_typeEndpoint Type
[in]ep_max_packet_sizeEndpoint Maximum Packet Size
[in]ep_intervalEndpoint Polling Interval
Returns
execution status ARM_USBH_STATUS
ARM_USBH_EP_HANDLE ARM_USBH_EndpointCreate ( uint8_t  ep_addr,
ARM_USB_ENDPOINT_TYPE  ep_type,
uint16_t  ep_max_packet_size,
uint8_t  ep_interval 
)

Create Endpoint in System.

Parameters
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
[in]ep_typeEndpoint Type
[in]ep_max_packet_sizeEndpoint Maximum Packet Size
[in]ep_intervalEndpoint Polling Interval
Returns
Endpoint Handle ARM_USBH_EP_HANDLE
ARM_USBH_STATUS ARM_USBH_EndpointDelete ( ARM_USBH_EP_HANDLE  ep_hndl)

Delete Endpoint from System.

Parameters
[in]ep_hndlEndpoint Handle
Returns
execution status ARM_USBH_STATUS
ARM_USBH_CAPABILITIES ARM_USBH_GetCapabilities ( void  )

Get driver capabilities.

Returns
ARM_USBH_CAPABILITIES

Retrieves information about capabilities in this driver implementation. The bitfield members of the struct ARM_USBH_CAPABILITIES encode various capabilities, for example available HUB ports or if the hardware can generate signal events using the ARM_USBH_SignalPortEvent callback function.

Example:

extern ARM_DRIVER_USBH ARM_Driver_USBH0;
ARM_DRIVER_USBH *drv_info;
void read_capabilities (void) {
ARM_USBH_CAPABILITIES drv_capabilities;
drv_info = &ARM_Driver_USBH0;
drv_capablilities = drv_info->GetCapabilities ();
// interrogate capabilities
}
ARM_DRV_VERSION ARM_USBH_GetVersion ( void  )

Get driver version.

Returns
ARM_DRV_VERSION

Returns version information of the driver implementation in ARM_DRV_VERSION

  • API version is the version of the CMSIS-Driver specification used to implement this driver.
  • Driver version is source code version of the actual driver implementation.

Example:

extern ARM_DRIVER_USBH ARM_Driver_USBH0;
ARM_DRIVER_USBH *drv_info;
void setup_usbh (void) {
ARM_DRV_VERSION version;
drv_info = &ARM_Driver_USBH0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
ARM_USBH_STATUS ARM_USBH_Initialize ( ARM_USBH_SignalPortEvent_t  cb_port_event,
ARM_USBH_SignalEndpointEvent_t  cb_endpoint_event 
)

Initialize USB Host Interface.

Parameters
[in]cb_port_eventPointer to ARM_USBH_SignalPortEvent
[in]cb_endpoint_eventPointer to ARM_USBH_SignalEndpointEvent
Returns
execution status ARM_USBH_STATUS

The function initializes the USB Host interface. It is called when the middleware component starts operation.

The function performs the following operations:

The parameter cb_port_event is a pointer to the ARM_USBH_SignalPortEvent callback function; use a NULL pointer when no device callback signals are required.

The parameter cb_endpoint_event is a pointer to the ARM_USBH_SignalEndpointEvent callback function; use a NULL pointer when no endpoint callback signals are required.

Example:

ARM_USB_STATUS ARM_USBH_PortGetState ( uint8_t  port)

Get current Root HUB Port connection State.

Parameters
[in]portRoot HUB Port Number
Returns
execution status ARM_USBH_STATUS
ARM_USBH_STATUS ARM_USBH_PortPowerOnOff ( uint8_t  port,
bool  power 
)

Root HUB Port Power on/off.

Parameters
[in]portRoot HUB Port Number
[in]powerOperation
  • false Power off
  • true Power on
Returns
execution status ARM_USBH_STATUS
ARM_USBH_STATUS ARM_USBH_PortReset ( uint8_t  port)

Do Root HUB Port Reset.

fn ARM_USBH_STATUS ARM_USBH_PortPowerOnOff (uint8_t port, bool power)

Root HUB Port Power on/off.

Parameters
[in]portRoot HUB Port Number
Returns
execution status ARM_USBH_STATUS
ARM_USBH_STATUS ARM_USBH_PortResume ( uint8_t  port)

Resume Root HUB Port (start generating SOFs).

Parameters
[in]portRoot HUB Port Number
Returns
execution status ARM_USBH_STATUS
ARM_USBH_STATUS ARM_USBH_PortSuspend ( uint8_t  port)

Suspend Root HUB Port (stop generating SOFs).

Parameters
[in]portRoot HUB Port Number
Returns
execution status ARM_USBH_STATUS
ARM_USBH_STATUS ARM_USBH_PowerControl ( ARM_POWER_STATE  state)

Control USB Host Interface Power.

Parameters
[in]statePower state
Returns
execution status ARM_USBH_STATUS
void ARM_USBH_SignalEndpointEvent ( ARM_USBH_EP_HANDLE  ep_hndl,
ARM_USBH_URB ptr_urb 
)

Signal Endpoint Event. Occurs when URB processing completes.

Parameters
[in]ep_hndlEndpoint Handle
[in]ptr_urbPointer to URB
Returns
none
void ARM_USBH_SignalPortEvent ( uint8_t  port,
ARM_USBH_EVENT  event 
)

Signal Root HUB Port Event.

Parameters
[in]portRoot HUB Port Number
[in]eventARM_USBH_EVENT
Returns
none
ARM_USBH_STATUS ARM_USBH_Uninitialize ( void  )

De-initialize USB Host Interface.

Returns
execution status ARM_USBH_STATUS

The function ARM_USBH_Uninitialize de-initializes the resources of USBH interface and sets the peripheral to ARM_POWER_OFF power mode.

It is called when the middleware component stops operation and releases the software resources used by the interface.

uint32_t ARM_USBH_URB_Abort ( ARM_USBH_EP_HANDLE  ep_hndl,
ARM_USBH_URB ptr_urb 
)

Abort Processing of USB Request Block (URB).

Parameters
[in]ep_hndlEndpoint Handle
[in]ptr_urbPointer to USB Request Block (URB)
Returns
execution status ARM_USBH_STATUS
uint32_t ARM_USBH_URB_Submit ( ARM_USBH_EP_HANDLE  ep_hndl,
ARM_USBH_URB ptr_urb 
)

Submit USB Request Block (URB) for Processing.

Parameters
[in]ep_hndlEndpoint Handle
[in]ptr_urbPointer to USB Request Block (URB)
Returns
execution status ARM_USBH_STATUS