![]() |
CMSIS-Driver
Version 2.02
Peripheral Interface for Middleware and Application Code
|
Driver API for USB Host. More...
Content | |
USBH Port Events | |
The USB Host driver generates Port call back events that are notified via the function ARM_USBH_SignalPortEvent. | |
USBH Pipe Events | |
The USB Host driver generates Pipe call back events that are notified via the function ARM_USBH_SignalPipeEvent. | |
USBH Packet Information | |
Specify USB packet information used by the function ARM_USBH_PipeTransfer. | |
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_PORT_STATE |
USB Host Port State. More... | |
Typedefs | |
typedef uint32_t | ARM_USBH_PIPE_HANDLE |
USB Host Pipe Handle. | |
typedef void(* | ARM_USBH_SignalPortEvent_t )(uint8_t port, uint32_t event) |
Pointer to ARM_USBH_SignalPortEvent : Signal Root HUB Port Event. | |
typedef void(* | ARM_USBH_SignalPipeEvent_t )(ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t event) |
Pointer to ARM_USBH_SignalPipeEvent : Signal Pipe Event. | |
Functions | |
ARM_DRIVER_VERSION | ARM_USBH_GetVersion (void) |
Get driver version. | |
ARM_USBH_CAPABILITIES | ARM_USBH_GetCapabilities (void) |
Get driver capabilities. | |
int32_t | ARM_USBH_Initialize (ARM_USBH_SignalPortEvent_t cb_port_event, ARM_USBH_SignalPipeEvent_t cb_pipe_event) |
Initialize USB Host Interface. | |
int32_t | ARM_USBH_Uninitialize (void) |
De-initialize USB Host Interface. | |
int32_t | ARM_USBH_PowerControl (ARM_POWER_STATE state) |
Control USB Host Interface Power. | |
int32_t | ARM_USBH_PortVbusOnOff (uint8_t port, bool vbus) |
Root HUB Port VBUS on/off. | |
int32_t | ARM_USBH_PortReset (uint8_t port) |
Do Root HUB Port Reset. | |
int32_t | ARM_USBH_PortSuspend (uint8_t port) |
Suspend Root HUB Port (stop generating SOFs). | |
int32_t | ARM_USBH_PortResume (uint8_t port) |
Resume Root HUB Port (start generating SOFs). | |
ARM_USBH_PORT_STATE | ARM_USBH_PortGetState (uint8_t port) |
Get current Root HUB Port State. | |
ARM_USBH_PIPE_HANDLE | ARM_USBH_PipeCreate (uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval) |
Create Pipe in System. | |
int32_t | ARM_USBH_PipeModify (ARM_USBH_PIPE_HANDLE pipe_hndl, uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint16_t ep_max_packet_size) |
Modify Pipe in System. | |
int32_t | ARM_USBH_PipeDelete (ARM_USBH_PIPE_HANDLE pipe_hndl) |
Delete Pipe from System. | |
int32_t | ARM_USBH_PipeReset (ARM_USBH_PIPE_HANDLE pipe_hndl) |
Reset Pipe. | |
int32_t | ARM_USBH_PipeTransfer (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t packet, uint8_t *data, uint32_t num) |
Transfer packets through USB Pipe. | |
uint32_t | ARM_USBH_PipeTransferGetResult (ARM_USBH_PIPE_HANDLE pipe_hndl) |
Get result of USB Pipe transfer. | |
int32_t | ARM_USBH_PipeTransferAbort (ARM_USBH_PIPE_HANDLE pipe_hndl) |
Abort current USB Pipe transfer. | |
uint16_t | ARM_USBH_GetFrameNumber (void) |
Get current USB Frame Number. | |
void | ARM_USBH_SignalPortEvent (uint8_t port, uint32_t event) |
Signal Root HUB Port Event. | |
void | ARM_USBH_SignalPipeEvent (ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t event) |
Signal Pipe Event. | |
Driver API for USB Host.
struct ARM_DRIVER_USBH |
Access structure of USB Host Driver.
The functions of the USB Host driver are accessed by function pointers. Refer to Driver Functions for overview information.
Each instance of an USBH provides such an access struct. The instance is indicated by a postfix in the symbol name of the access struct, for example:
A configuration setting in the middleware allows connecting the middleware to a specific driver instance Driver_USBHn. The default is 0, which connects a middleware to the first instance of a driver.
Data Fields | |
ARM_DRIVER_VERSION(* | GetVersion )(void) |
Pointer to ARM_USBH_GetVersion : Get driver version. | |
ARM_USBH_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_USBH_GetCapabilities : Get driver capabilities. | |
int32_t(* | Initialize )(ARM_USBH_SignalPortEvent_t cb_port_event, ARM_USBH_SignalPipeEvent_t cb_pipe_event) |
Pointer to ARM_USBH_Initialize : Initialize USB Host Interface. | |
int32_t(* | Uninitialize )(void) |
Pointer to ARM_USBH_Uninitialize : De-initialize USB Host Interface. | |
int32_t(* | PowerControl )(ARM_POWER_STATE state) |
Pointer to ARM_USBH_PowerControl : Control USB Host Interface Power. | |
int32_t(* | PortVbusOnOff )(uint8_t port, bool vbus) |
Pointer to ARM_USBH_PortVbusOnOff : Root HUB Port VBUS on/off. | |
int32_t(* | PortReset )(uint8_t port) |
Pointer to ARM_USBH_PortReset : Do Root HUB Port Reset. | |
int32_t(* | PortSuspend )(uint8_t port) |
Pointer to ARM_USBH_PortSuspend : Suspend Root HUB Port (stop generating SOFs). | |
int32_t(* | PortResume )(uint8_t port) |
Pointer to ARM_USBH_PortResume : Resume Root HUB Port (start generating SOFs). | |
ARM_USBH_PORT_STATE(* | PortGetState )(uint8_t port) |
Pointer to ARM_USBH_PortGetState : Get current Root HUB Port State. | |
ARM_USBH_PIPE_HANDLE(* | PipeCreate )(uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval) |
Pointer to ARM_USBH_PipeCreate : Create Pipe in System. | |
int32_t(* | PipeModify )(ARM_USBH_PIPE_HANDLE pipe_hndl, uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint16_t ep_max_packet_size) |
Pointer to ARM_USBH_PipeModify : Modify Pipe in System. | |
int32_t(* | PipeDelete )(ARM_USBH_PIPE_HANDLE pipe_hndl) |
Pointer to ARM_USBH_PipeDelete : Delete Pipe from System. | |
int32_t(* | PipeReset )(ARM_USBH_PIPE_HANDLE pipe_hndl) |
Pointer to ARM_USBH_PipeReset : Reset Pipe. | |
int32_t(* | PipeTransfer )(ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t packet, uint8_t *data, uint32_t num) |
Pointer to ARM_USBH_PipeTransfer : Transfer packets through USB Pipe. | |
uint32_t(* | PipeTransferGetResult )(ARM_USBH_PIPE_HANDLE pipe_hndl) |
Pointer to ARM_USBH_PipeTransferGetResult : Get result of USB Pipe transfer. | |
int32_t(* | PipeTransferAbort )(ARM_USBH_PIPE_HANDLE pipe_hndl) |
Pointer to ARM_USBH_PipeTransferAbort : Abort current USB Pipe transfer. | |
uint16_t(* | GetFrameNumber )(void) |
Pointer to ARM_USBH_GetFrameNumber : Get current USB Frame Number. | |
ARM_USBH_CAPABILITIES(* GetCapabilities)(void) |
Pointer to ARM_USBH_GetCapabilities : Get driver capabilities.
uint16_t(* GetFrameNumber)(void) |
Pointer to ARM_USBH_GetFrameNumber : Get current USB Frame Number.
ARM_DRIVER_VERSION(* GetVersion)(void) |
Pointer to ARM_USBH_GetVersion : Get driver version.
int32_t(* Initialize)(ARM_USBH_SignalPortEvent_t cb_port_event, ARM_USBH_SignalPipeEvent_t cb_pipe_event) |
Pointer to ARM_USBH_Initialize : Initialize USB Host Interface.
ARM_USBH_PIPE_HANDLE(* PipeCreate)(uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval) |
Pointer to ARM_USBH_PipeCreate : Create Pipe in System.
int32_t(* PipeDelete)(ARM_USBH_PIPE_HANDLE pipe_hndl) |
Pointer to ARM_USBH_PipeDelete : Delete Pipe from System.
int32_t(* PipeModify)(ARM_USBH_PIPE_HANDLE pipe_hndl, uint8_t dev_addr, uint8_t dev_speed, uint8_t hub_addr, uint8_t hub_port, uint16_t ep_max_packet_size) |
Pointer to ARM_USBH_PipeModify : Modify Pipe in System.
int32_t(* PipeReset)(ARM_USBH_PIPE_HANDLE pipe_hndl) |
Pointer to ARM_USBH_PipeReset : Reset Pipe.
int32_t(* PipeTransfer)(ARM_USBH_PIPE_HANDLE pipe_hndl, uint32_t packet, uint8_t *data, uint32_t num) |
Pointer to ARM_USBH_PipeTransfer : Transfer packets through USB Pipe.
int32_t(* PipeTransferAbort)(ARM_USBH_PIPE_HANDLE pipe_hndl) |
Pointer to ARM_USBH_PipeTransferAbort : Abort current USB Pipe transfer.
uint32_t(* PipeTransferGetResult)(ARM_USBH_PIPE_HANDLE pipe_hndl) |
Pointer to ARM_USBH_PipeTransferGetResult : Get result of USB Pipe transfer.
ARM_USBH_PORT_STATE(* PortGetState)(uint8_t port) |
Pointer to ARM_USBH_PortGetState : Get current Root HUB Port State.
int32_t(* PortReset)(uint8_t port) |
Pointer to ARM_USBH_PortReset : Do Root HUB Port Reset.
int32_t(* PortResume)(uint8_t port) |
Pointer to ARM_USBH_PortResume : Resume Root HUB Port (start generating SOFs).
int32_t(* PortSuspend)(uint8_t port) |
Pointer to ARM_USBH_PortSuspend : Suspend Root HUB Port (stop generating SOFs).
int32_t(* PortVbusOnOff)(uint8_t port, bool vbus) |
Pointer to ARM_USBH_PortVbusOnOff : Root HUB Port VBUS on/off.
int32_t(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_USBH_PowerControl : Control USB Host Interface Power.
int32_t(* Uninitialize)(void) |
Pointer to ARM_USBH_Uninitialize : De-initialize USB Host Interface.
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_PORT_STATE |
USB Host Port State.
This structure stores information about the state of the USB Host Port. The bitfields encode whether a device is connected to the port, if port overcurrent is detected and the port speed.
Returned by:
Data Fields | ||
---|---|---|
uint32_t | connected: 1 | USB Host Port connected flag. |
uint32_t | overcurrent: 1 | USB Host Port overcurrent flag. |
uint32_t | speed: 2 | USB Host Port speed setting (ARM_USB_SPEED_xxx) |
uint32_t ARM_USBH_PIPE_HANDLE |
USB Host Pipe Handle.
Each pipe is identified through a unique number, which is created by the function ARM_USBH_PipeCreate.
Parameter for:
Retruned by:
ARM_USBH_SignalPipeEvent_t |
Pointer to ARM_USBH_SignalPipeEvent : Signal Pipe Event.
Provides the typedef for the callback function ARM_USBH_SignalPipeEvent.
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:
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:
uint16_t ARM_USBH_GetFrameNumber | ( | void | ) |
Get current USB Frame Number.
Retrieves the sequential 11-bit frame number of the last Start of Frame (SOF) packet.
ARM_DRIVER_VERSION ARM_USBH_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRIVER_VERSION
Example:
int32_t ARM_USBH_Initialize | ( | ARM_USBH_SignalPortEvent_t | cb_port_event, |
ARM_USBH_SignalPipeEvent_t | cb_pipe_event | ||
) |
Initialize USB Host Interface.
[in] | cb_port_event | Pointer to ARM_USBH_SignalPortEvent |
[in] | cb_pipe_event | Pointer to ARM_USBH_SignalPipeEvent |
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 port callback signals are required.
The parameter cb_pipe_event is a pointer to the ARM_USBH_SignalPipeEvent callback function.
Example:
ARM_USBH_PIPE_HANDLE ARM_USBH_PipeCreate | ( | uint8_t | dev_addr, |
uint8_t | dev_speed, | ||
uint8_t | hub_addr, | ||
uint8_t | hub_port, | ||
uint8_t | ep_addr, | ||
uint8_t | ep_type, | ||
uint16_t | ep_max_packet_size, | ||
uint8_t | ep_interval | ||
) |
Create Pipe in System.
[in] | dev_addr | Device Address |
[in] | dev_speed | Device Speed |
[in] | hub_addr | Hub Address |
[in] | hub_port | Hub Port |
[in] | ep_addr | Endpoint Address
|
[in] | ep_type | Endpoint Type (ARM_USB_ENDPOINT_xxx) |
[in] | ep_max_packet_size | Endpoint Maximum Packet Size |
[in] | ep_interval | Endpoint Polling Interval |
Creates pipe for transfers (allocates required resources and configures the pipe).
The parameters specify pipe information (connection between host and device endpoint):
The function returns an pipe handle that is used for all subsequent operations on that pipe. In case of errors an invalid handle (NULL) is returned.
int32_t ARM_USBH_PipeDelete | ( | ARM_USBH_PIPE_HANDLE | pipe_hndl | ) |
Delete Pipe from System.
[in] | pipe_hndl | Pipe Handle |
Deletes pipe that was created with ARM_USBH_PipeCreate (deactivates the pipe and releases used resources).
int32_t ARM_USBH_PipeModify | ( | ARM_USBH_PIPE_HANDLE | pipe_hndl, |
uint8_t | dev_addr, | ||
uint8_t | dev_speed, | ||
uint8_t | hub_addr, | ||
uint8_t | hub_port, | ||
uint16_t | ep_max_packet_size | ||
) |
Modify Pipe in System.
[in] | pipe_hndl | Pipe Handle |
[in] | dev_addr | Device Address |
[in] | dev_speed | Device Speed |
[in] | hub_addr | Hub Address |
[in] | hub_port | Hub Port |
[in] | ep_max_packet_size | Endpoint Maximum Packet Size |
Modifies pipe configuration that was created with ARM_USBH_PipeCreate.
int32_t ARM_USBH_PipeReset | ( | ARM_USBH_PIPE_HANDLE | pipe_hndl | ) |
Reset Pipe.
[in] | pipe_hndl | Pipe Handle |
This function is used to clear Halt condition and reset data toggle on the specified pipe.
int32_t ARM_USBH_PipeTransfer | ( | ARM_USBH_PIPE_HANDLE | pipe_hndl, |
uint32_t | packet, | ||
uint8_t * | data, | ||
uint32_t | num | ||
) |
Transfer packets through USB Pipe.
[in] | pipe_hndl | Pipe Handle |
[in] | packet | Packet information |
[in] | data | Pointer to buffer with data to send or for data to receive |
[in] | num | Number of data bytes to transfer |
This function is used to generate packets in order to send data to or receive data from USB Endpoint.
The function specifies the buffer for data to read or with data to write and the number of bytes to transfer. It also specifies USBH Packet Information with parameter packet.
The function is non-blocking and returns as soon as the driver starts the operation on the specified pipe. During the operation it is not allowed to call this function again on the same pipe. Also the data buffer must stay allocated and the contents of data must not be modified.
Operation is completed when the the requested number of data bytes have been transfered and is indicated with ARM_USBH_EVENT_TRANSFER_COMPLETE event. It can also finish earlier on reception of different handshake tokens which are also indicated through USBH Pipe Events.
Transfer operation can be aborted by calling ARM_USBH_PipeTransferAbort.
int32_t ARM_USBH_PipeTransferAbort | ( | ARM_USBH_PIPE_HANDLE | pipe_hndl | ) |
Abort current USB Pipe transfer.
[in] | pipe_hndl | Pipe Handle |
This function is used to abort active pipe transfer started by ARM_USBH_PipeTransfer.
uint32_t ARM_USBH_PipeTransferGetResult | ( | ARM_USBH_PIPE_HANDLE | pipe_hndl | ) |
Get result of USB Pipe transfer.
[in] | pipe_hndl | Pipe Handle |
Returns the number of successfully transferred data bytes started by ARM_USBH_PipeTransfer operation.
ARM_USBH_PORT_STATE ARM_USBH_PortGetState | ( | uint8_t | port | ) |
Get current Root HUB Port State.
[in] | port | Root HUB Port Number |
Retrieves the current state of the specified port.
int32_t ARM_USBH_PortReset | ( | uint8_t | port | ) |
Do Root HUB Port Reset.
[in] | port | Root HUB Port Number |
Executes reset signalling on the specified port.
int32_t ARM_USBH_PortResume | ( | uint8_t | port | ) |
Resume Root HUB Port (start generating SOFs).
[in] | port | Root HUB Port Number |
Resumes USB signaling on the specified port.
int32_t ARM_USBH_PortSuspend | ( | uint8_t | port | ) |
Suspend Root HUB Port (stop generating SOFs).
[in] | port | Root HUB Port Number |
Suspends USB signaling on the specified port.
int32_t ARM_USBH_PortVbusOnOff | ( | uint8_t | port, |
bool | vbus | ||
) |
Root HUB Port VBUS on/off.
[in] | port | Root HUB Port Number |
[in] | vbus |
|
Allows you to control the VBUS signal of the specified port.
int32_t ARM_USBH_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control USB Host Interface Power.
[in] | state | Power state |
Allows you to control the power modes of the USB Host interface.
void ARM_USBH_SignalPipeEvent | ( | ARM_USBH_PIPE_HANDLE | pipe_hndl, |
uint32_t | event | ||
) |
Signal Pipe Event.
[in] | pipe_hndl | Pipe Handle |
[in] | event | USBH Pipe Events |
The function ARM_USBH_SignalPipeEvent notifies the application of the USBH Pipe Events and it is registered by the function ARM_USBH_Initialize.
The argument pipe_hndl specifies the pipe handle.
The argument event represents the notification mask of the events. Each event is coded in a separate bit and therefore it is possible to signal multiple events in the event call back function. The following call back notifications are generated:
Bit | Event | Description |
---|---|---|
0 | ARM_USBH_EVENT_TRANSFER_COMPLETE | Occurs after all the data has been transferred without errors. |
1 | ARM_USBH_EVENT_HANDSHAKE_NAK | Occurs when NAK Handshake is received before all the data is transferred. |
2 | ARM_USBH_EVENT_HANDSHAKE_NYET | Occurs when NYET Handshake is received before all the data is transferred. |
3 | ARM_USBH_EVENT_HANDSHAKE_MDATA | Occurs when MDATA Handshake is received before all the data is transferred. |
4 | ARM_USBH_EVENT_HANDSHAKE_STALL | Occurs when STALL Handshake is received before all the data is transferred. |
5 | ARM_USBH_EVENT_HANDSHAKE_ERR | Occurs when ERR Handshake is received before all the data is transferred. |
6 | ARM_USBH_EVENT_BUS_ERROR | Occurs when bus error is detected before all the data is transferred. |
void ARM_USBH_SignalPortEvent | ( | uint8_t | port, |
uint32_t | event | ||
) |
Signal Root HUB Port Event.
[in] | port | Root HUB Port Number |
[in] | event | USBH Port Events |
The function ARM_USBH_SignalPortEvent notifies the application of the USBH Port Events and it is registered by the function ARM_USBH_Initialize. The function ARM_USBH_GetCapabilities returns information about the implemented optional events in a driver.
The argument port specifies the root hub port number.
The argument event represents the notification mask of the events. Each event is coded in a separate bit and therefore it is possible to signal multiple events in the event call back function. The following call back notifications are generated:
Bit | Event | Description |
---|---|---|
0 | ARM_USBH_EVENT_CONNECT | Occurs when USB Device connects to the Host. |
1 | ARM_USBH_EVENT_DISCONNECT | Occurs when USB Device disconnects from the Host. |
2 | ARM_USBH_EVENT_OVERCURRENT | Occurs when USB Overcurrent it detected. |
3 | ARM_USBH_EVENT_RESET | Occurs when USB Reset is completed after calling ARM_USBH_PortReset. |
4 | ARM_USBH_EVENT_SUSPEND | Occurs when USB Suspend is detected. |
5 | ARM_USBH_EVENT_RESUME | Occurs when USB Resume is detected. |
6 | ARM_USBH_EVENT_REMOTE_WAKEUP | Occurs when USB Remote wakeup is detected. |
int32_t ARM_USBH_Uninitialize | ( | void | ) |
De-initialize USB Host Interface.
The function ARM_USBH_Uninitialize de-initializes the resources of USB Host interface.
It is called when the middleware component stops operation and releases the software resources used by the interface.