![]() |
CMSIS Driver
Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
|
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. | |
Driver API for USB Host Peripheral (Driver_USBH.h)
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).
To use the USBH driver invoke the API functions in the following order:
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.
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). | |
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:
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__ |
uint32_t ARM_USBH_EP_HANDLE |
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:
enum ARM_USBH_EVENT |
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:
enum ARM_USBH_STATUS |
USB Host Status of executed operation.
Defines status and error codes returned by most of the USBH driver functions.
Returned by:
ARM_USBH_STATUS ARM_USBH_EndpointClearHalt | ( | ARM_USBH_EP_HANDLE | ep_hndl | ) |
Clear Halt condition on USB Endpoint.
[in] | ep_hndl | Endpoint Handle |
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.
[in] | ep_hndl | Endpoint Handle |
[in] | dev_addr | Device Address |
[in] | ep_speed | Endpoint Speed |
[in] | ep_addr | Endpoint Address
|
[in] | ep_type | Endpoint Type |
[in] | ep_max_packet_size | Endpoint Maximum Packet Size |
[in] | ep_interval | Endpoint Polling Interval |
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.
[in] | ep_addr | Endpoint Address
|
[in] | ep_type | Endpoint Type |
[in] | ep_max_packet_size | Endpoint Maximum Packet Size |
[in] | ep_interval | Endpoint Polling Interval |
ARM_USBH_STATUS ARM_USBH_EndpointDelete | ( | ARM_USBH_EP_HANDLE | ep_hndl | ) |
Delete Endpoint from System.
[in] | ep_hndl | Endpoint Handle |
ARM_USBH_CAPABILITIES ARM_USBH_GetCapabilities | ( | void | ) |
Get driver 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:
ARM_DRV_VERSION ARM_USBH_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRV_VERSION
Example:
ARM_USBH_STATUS ARM_USBH_Initialize | ( | ARM_USBH_SignalPortEvent_t | cb_port_event, |
ARM_USBH_SignalEndpointEvent_t | cb_endpoint_event | ||
) |
Initialize USB Host Interface.
[in] | cb_port_event | Pointer to ARM_USBH_SignalPortEvent |
[in] | cb_endpoint_event | Pointer to ARM_USBH_SignalEndpointEvent |
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.
[in] | port | Root HUB Port Number |
ARM_USBH_STATUS ARM_USBH_PortPowerOnOff | ( | uint8_t | port, |
bool | power | ||
) |
Root HUB Port Power on/off.
[in] | port | Root HUB Port Number |
[in] | power | Operation
|
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.
[in] | port | Root HUB Port Number |
ARM_USBH_STATUS ARM_USBH_PortResume | ( | uint8_t | port | ) |
Resume Root HUB Port (start generating SOFs).
[in] | port | Root HUB Port Number |
ARM_USBH_STATUS ARM_USBH_PortSuspend | ( | uint8_t | port | ) |
Suspend Root HUB Port (stop generating SOFs).
[in] | port | Root HUB Port Number |
ARM_USBH_STATUS ARM_USBH_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control USB Host Interface Power.
[in] | state | Power state |
void ARM_USBH_SignalEndpointEvent | ( | ARM_USBH_EP_HANDLE | ep_hndl, |
ARM_USBH_URB * | ptr_urb | ||
) |
Signal Endpoint Event. Occurs when URB processing completes.
[in] | ep_hndl | Endpoint Handle |
[in] | ptr_urb | Pointer to URB |
void ARM_USBH_SignalPortEvent | ( | uint8_t | port, |
ARM_USBH_EVENT | event | ||
) |
Signal Root HUB Port Event.
[in] | port | Root HUB Port Number |
[in] | event | ARM_USBH_EVENT |
ARM_USBH_STATUS ARM_USBH_Uninitialize | ( | void | ) |
De-initialize USB Host Interface.
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).
[in] | ep_hndl | Endpoint Handle |
[in] | ptr_urb | Pointer to USB Request Block (URB) |
uint32_t ARM_USBH_URB_Submit | ( | ARM_USBH_EP_HANDLE | ep_hndl, |
ARM_USBH_URB * | ptr_urb | ||
) |
Submit USB Request Block (URB) for Processing.
[in] | ep_hndl | Endpoint Handle |
[in] | ptr_urb | Pointer to USB Request Block (URB) |