![]() |
CMSIS Driver
Version 1.10 - Preliminary
Middleware Driver API for microcontroller peripherals
|
Driver API for USB Device Peripheral (Driver_USBD.h) More...
Data Structures | |
struct | ARM_DRIVER_USBD |
Access structure of the USB Device Driver. More... | |
struct | ARM_USBD_CAPABILITIES |
USB Device Driver Capabilities. More... | |
struct | ARM_USBD_STATE |
USB Device State. More... | |
Typedefs | |
typedef void(* | ARM_USBD_SignalDeviceEvent_t )(ARM_USBD_EVENT event) |
Pointer to ARM_USBD_SignalDeviceEvent : Signal USB Device Event. | |
typedef void(* | ARM_USBD_SignalEndpointEvent_t )(uint8_t ep_addr, ARM_USBD_EP_EVENT ep_event) |
Pointer to ARM_USBD_SignalEndpointEvent : Signal USB Endpoint Event. | |
Enumerations | |
enum | ARM_USBD_SET_ADDRESS_STAGE { ARM_USBD_SET_ADDRESS_SETUP, ARM_USBD_SET_ADDRESS_STATUS } |
USB Device SET_ADDRESS Stage. More... | |
enum | ARM_USBD_STATUS { ARM_USBD_OK = 0, ARM_USBD_ERROR = 1 } |
USB Device Status of executed operation. More... | |
enum | ARM_USBD_EVENT { ARM_USBD_EVENT_POWER_ON, ARM_USBD_EVENT_POWER_OFF, ARM_USBD_EVENT_CONNECT, ARM_USBD_EVENT_DISCONNECT, ARM_USBD_EVENT_RESET, ARM_USBD_EVENT_HIGH_SPEED, ARM_USBD_EVENT_SUSPEND, ARM_USBD_EVENT_RESUME, ARM_USBD_EVENT_REMOTE_WAKEUP } |
USB Device Event. More... | |
enum | ARM_USBD_EP_EVENT { ARM_USBD_EP_EVENT_SETUP, ARM_USBD_EP_EVENT_OUT, ARM_USBD_EP_EVENT_IN } |
USB Endpoint Event. More... | |
Functions | |
ARM_DRV_VERSION | ARM_USBD_GetVersion (void) |
Get driver version. | |
ARM_USBD_CAPABILITIES | ARM_USBD_GetCapabilities (void) |
Get driver capabilities. | |
ARM_USBD_STATUS | ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event) |
Initialize USB Device Interface. | |
ARM_USBD_STATUS | ARM_USBD_Uninitialize (void) |
De-initialize USB Device Interface. | |
ARM_USBD_STATUS | ARM_USBD_PowerControl (ARM_POWER_STATE state) |
Control USB Device Interface Power. | |
ARM_USBD_STATUS | ARM_USBD_DeviceConnect (void) |
Connect USB Device. | |
ARM_USBD_STATUS | ARM_USBD_DeviceDisconnect (void) |
Disconnect USB Device. | |
ARM_USBD_STATE | ARM_USBD_DeviceGetState (void) |
Get current USB Device State. | |
ARM_USBD_STATUS | ARM_USBD_DeviceRemoteWakeup (void) |
Trigger USB Remote Wakeup. | |
ARM_USBD_STATUS | ARM_USBD_DeviceSetAddress (uint8_t dev_addr, ARM_USBD_SET_ADDRESS_STAGE stage) |
Set USB Device Address. | |
ARM_USBD_STATUS | ARM_USBD_DeviceConfigure (bool configure) |
Configure/unconfigure USB Device. | |
ARM_USBD_STATUS | ARM_USBD_EndpointConfigure (uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size) |
Configure USB Endpoint. | |
ARM_USBD_STATUS | ARM_USBD_EndpointUnconfigure (uint8_t ep_addr) |
Unconfigure USB Endpoint. | |
ARM_USBD_STATUS | ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall) |
Set/Clear Stall for USB Endpoint. | |
ARM_USBD_STATUS | ARM_USBD_EndpointReadStart (uint8_t ep_addr, uint8_t *buf, uint32_t len) |
Start USB Endpoint Read operation. | |
int32_t | ARM_USBD_EndpointRead (uint8_t ep_addr, uint8_t *buf, uint32_t len) |
Read data from USB Endpoint. | |
int32_t | ARM_USBD_EndpointWrite (uint8_t ep_addr, const uint8_t *buf, uint32_t len) |
Write data to USB Endpoint. | |
ARM_USBD_STATUS | ARM_USBD_EndpointAbort (uint8_t ep_addr) |
Abort current USB Endpoint transfer. | |
uint16_t | ARM_USBD_GetFrameNumber (void) |
Get current USB Frame Number. | |
void | ARM_USBD_SignalDeviceEvent (ARM_USBD_EVENT event) |
Signal USB Device Event. | |
void | ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, ARM_USBD_EP_EVENT ep_event) |
Signal USB Endpoint Event. Occurs when Endpoint Read/Write completes. | |
Driver API for USB Device Peripheral (Driver_USBD.h)
The header file Driver_USBD.h defines the API for the USB Device 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_USBD. This structure can be available several times in each interface to control multiple USBD interfaces.
Header file Driver_USBD.h also defines callback routines that can be categorized as device event callbacks and endpoint event callbacks. Callbacks are called by the driver, in interrupt context when an appropriate event occurs, to signal device related events (ARM_USBD_EVENT) and endpoint related events (ARM_USBD_EP_EVENT).
To use the USBD driver invoke the API functions in the following order:
struct ARM_DRIVER_USBD |
Access structure of the USB Device Driver.
The functions of the USB Device driver are accessed by function pointers. Refer to Driver Functions for overview information.
Each instance of an USBD 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 ARM_DRIVER_USBDn. The default is 0, which connects a middleware to the first instance of a driver.
Data Fields | |
ARM_DRV_VERSION(* | GetVersion )(void) |
Pointer to ARM_USBD_GetVersion : Get driver version. | |
ARM_USBD_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_USBD_GetCapabilities : Get driver capabilities. | |
ARM_USBD_STATUS(* | Initialize )(ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event) |
Pointer to ARM_USBD_Initialize : Initialize USB Device Interface. | |
ARM_USBD_STATUS(* | Uninitialize )(void) |
Pointer to ARM_USBD_Uninitialize : De-initialize USB Device Interface. | |
ARM_USBD_STATUS(* | PowerControl )(ARM_POWER_STATE state) |
Pointer to ARM_USBD_PowerControl : Control USB Device Interface Power. | |
ARM_USBD_STATUS(* | DeviceConnect )(void) |
Pointer to ARM_USBD_DeviceConnect : Connect USB Device. | |
ARM_USBD_STATUS(* | DeviceDisconnect )(void) |
Pointer to ARM_USBD_DeviceDisconnect : Disconnect USB Device. | |
ARM_USBD_STATE(* | DeviceGetState )(void) |
Pointer to ARM_USBD_DeviceGetState : Get current USB Device State. | |
ARM_USBD_STATUS(* | DeviceRemoteWakeup )(void) |
Pointer to ARM_USBD_DeviceRemoteWakeup : Trigger USB Remote Wakeup. | |
ARM_USBD_STATUS(* | DeviceSetAddress )(uint8_t dev_addr, ARM_USBD_SET_ADDRESS_STAGE stage) |
Pointer to ARM_USBD_DeviceSetAddress : Set USB Device Address. | |
ARM_USBD_STATUS(* | DeviceConfigure )(bool configure) |
Pointer to ARM_USBD_DeviceConfigure : Configure/unconfigure USB Device. | |
ARM_USBD_STATUS(* | EndpointConfigure )(uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size) |
Pointer to ARM_USBD_EndpointConfigure : Configure USB Endpoint. | |
ARM_USBD_STATUS(* | EndpointUnconfigure )(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointUnconfigure : Unconfigure USB Endpoint. | |
ARM_USBD_STATUS(* | EndpointStall )(uint8_t ep_addr, bool stall) |
Pointer to ARM_USBD_EndpointStall : Set/Clear Stall for USB Endpoint. | |
ARM_USBD_STATUS(* | EndpointReadStart )(uint8_t ep_addr, uint8_t *buf, uint32_t len) |
Pointer to ARM_USBD_EndpointReadStart : Start USB Endpoint Read operation. | |
int32_t(* | EndpointRead )(uint8_t ep_addr, uint8_t *buf, uint32_t len) |
Pointer to ARM_USBD_EndpointRead : Read data from USB Endpoint. | |
int32_t(* | EndpointWrite )(uint8_t ep_addr, const uint8_t *buf, uint32_t len) |
Pointer to ARM_USBD_EndpointWrite : Write data to USB Endpoint. | |
ARM_USBD_STATUS(* | EndpointAbort )(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointAbort : Abort current USB Endpoint transfer. | |
uint16_t(* | GetFrameNumber )(void) |
Pointer to ARM_USBD_GetFrameNumber : Get current USB Frame Number. | |
ARM_USBD_STATUS(* DeviceConfigure)(bool configure) |
Pointer to ARM_USBD_DeviceConfigure : Configure/unconfigure USB Device.
ARM_USBD_STATUS(* DeviceConnect)(void) |
Pointer to ARM_USBD_DeviceConnect : Connect USB Device.
ARM_USBD_STATUS(* DeviceDisconnect)(void) |
Pointer to ARM_USBD_DeviceDisconnect : Disconnect USB Device.
ARM_USBD_STATE(* DeviceGetState)(void) |
Pointer to ARM_USBD_DeviceGetState : Get current USB Device State.
ARM_USBD_STATUS(* DeviceRemoteWakeup)(void) |
Pointer to ARM_USBD_DeviceRemoteWakeup : Trigger USB Remote Wakeup.
ARM_USBD_STATUS(* DeviceSetAddress)(uint8_t dev_addr, ARM_USBD_SET_ADDRESS_STAGE stage) |
Pointer to ARM_USBD_DeviceSetAddress : Set USB Device Address.
ARM_USBD_STATUS(* EndpointAbort)(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointAbort : Abort current USB Endpoint transfer.
ARM_USBD_STATUS(* EndpointConfigure)(uint8_t ep_addr, ARM_USB_ENDPOINT_TYPE ep_type, uint16_t ep_max_packet_size) |
Pointer to ARM_USBD_EndpointConfigure : Configure USB Endpoint.
int32_t(* EndpointRead)(uint8_t ep_addr, uint8_t *buf, uint32_t len) |
Pointer to ARM_USBD_EndpointRead : Read data from USB Endpoint.
ARM_USBD_STATUS(* EndpointReadStart)(uint8_t ep_addr, uint8_t *buf, uint32_t len) |
Pointer to ARM_USBD_EndpointReadStart : Start USB Endpoint Read operation.
ARM_USBD_STATUS(* EndpointStall)(uint8_t ep_addr, bool stall) |
Pointer to ARM_USBD_EndpointStall : Set/Clear Stall for USB Endpoint.
ARM_USBD_STATUS(* EndpointUnconfigure)(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointUnconfigure : Unconfigure USB Endpoint.
int32_t(* EndpointWrite)(uint8_t ep_addr, const uint8_t *buf, uint32_t len) |
Pointer to ARM_USBD_EndpointWrite : Write data to USB Endpoint.
ARM_USBD_CAPABILITIES(* GetCapabilities)(void) |
Pointer to ARM_USBD_GetCapabilities : Get driver capabilities.
uint16_t(* GetFrameNumber)(void) |
Pointer to ARM_USBD_GetFrameNumber : Get current USB Frame Number.
ARM_DRV_VERSION(* GetVersion)(void) |
Pointer to ARM_USBD_GetVersion : Get driver version.
ARM_USBD_STATUS(* Initialize)(ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event) |
Pointer to ARM_USBD_Initialize : Initialize USB Device Interface.
ARM_USBD_STATUS(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_USBD_PowerControl : Control USB Device Interface Power.
ARM_USBD_STATUS(* Uninitialize)(void) |
Pointer to ARM_USBD_Uninitialize : De-initialize USB Device Interface.
struct ARM_USBD_CAPABILITIES |
USB Device Driver Capabilities.
A USB Device driver can be implemented with different capabilities. The bitfield members of this struct encode the capabilities implemented by this driver.
Returned by:
struct ARM_USBD_STATE |
USB Device State.
This structure stores information about the state of a USB Device. 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 Device active lag. |
uint8_t | connected: 1 | USB Device connected flag. |
uint8_t | powered: 1 | USB Device powered flag. |
uint8_t | speed: 2 | USB Device speed setting. |
ARM_USBD_SignalDeviceEvent_t |
Pointer to ARM_USBD_SignalDeviceEvent : Signal USB Device Event.
Provides the typedef for the callback function ARM_USBD_SignalDeviceEvent.
Parameter for:
ARM_USBD_SignalEndpointEvent_t |
Pointer to ARM_USBD_SignalEndpointEvent : Signal USB Endpoint Event.
Provides the typedef for the callback function ARM_USBD_SignalEndpointEvent.
Parameter for:
enum ARM_USBD_EP_EVENT |
USB Endpoint Event.
Provides the event information for the ARM_USBD_SignalEndpointEvent callback function (which is registered by the function ARM_USBD_Initialize).
Parameter for:
enum ARM_USBD_EVENT |
USB Device Event.
Provides the event information for the ARM_USBD_SignalDeviceEvent callback function (which is registered by the function ARM_USBD_Initialize). The function ARM_USBD_GetCapabilities returns information of the implemented callback events in a driver.
Parameter for:
USB Device SET_ADDRESS Stage.
Provides values for
Parameter for:
enum ARM_USBD_STATUS |
USB Device Status of executed operation.
Defines status and error codes returned by most of the USBD driver functions.
Returned by:
ARM_USBD_STATUS ARM_USBD_DeviceConfigure | ( | bool | configure | ) |
Configure/unconfigure USB Device.
[in] | configure | Operation
|
ARM_USBD_STATUS ARM_USBD_DeviceConnect | ( | void | ) |
Connect USB Device.
ARM_USBD_STATUS ARM_USBD_DeviceDisconnect | ( | void | ) |
Disconnect USB Device.
ARM_USBD_STATE ARM_USBD_DeviceGetState | ( | void | ) |
Get current USB Device State.
ARM_USBD_STATUS ARM_USBD_DeviceRemoteWakeup | ( | void | ) |
Trigger USB Remote Wakeup.
ARM_USBD_STATUS ARM_USBD_DeviceSetAddress | ( | uint8_t | dev_addr, |
ARM_USBD_SET_ADDRESS_STAGE | stage | ||
) |
Set USB Device Address.
[in] | dev_addr | Device Address |
[in] | stage | Stage in which the function is called |
ARM_USBD_STATUS ARM_USBD_EndpointAbort | ( | uint8_t | ep_addr | ) |
Abort current USB Endpoint transfer.
[in] | ep_addr | Endpoint Address
|
ARM_USBD_STATUS ARM_USBD_EndpointConfigure | ( | uint8_t | ep_addr, |
ARM_USB_ENDPOINT_TYPE | ep_type, | ||
uint16_t | ep_max_packet_size | ||
) |
Configure USB Endpoint.
[in] | ep_addr | Endpoint Address
|
[in] | ep_type | Endpoint Type |
[in] | ep_max_packet_size | Endpoint Maximum Packet Size |
int32_t ARM_USBD_EndpointRead | ( | uint8_t | ep_addr, |
uint8_t * | buf, | ||
uint32_t | len | ||
) |
Read data from USB Endpoint.
[in] | ep_addr | Endpoint Address
|
[out] | buf | Buffer for data read from Endpoint |
[in] | len | Buffer length |
ARM_USBD_STATUS ARM_USBD_EndpointReadStart | ( | uint8_t | ep_addr, |
uint8_t * | buf, | ||
uint32_t | len | ||
) |
Start USB Endpoint Read operation.
[in] | ep_addr | Endpoint Address
|
[out] | buf | Buffer for data read from Endpoint |
[in] | len | Buffer length |
ARM_USBD_STATUS ARM_USBD_EndpointStall | ( | uint8_t | ep_addr, |
bool | stall | ||
) |
Set/Clear Stall for USB Endpoint.
[in] | ep_addr | Endpoint Address
|
[in] | stall | Operation
|
ARM_USBD_STATUS ARM_USBD_EndpointUnconfigure | ( | uint8_t | ep_addr | ) |
Unconfigure USB Endpoint.
[in] | ep_addr | Endpoint Address
|
int32_t ARM_USBD_EndpointWrite | ( | uint8_t | ep_addr, |
const uint8_t * | buf, | ||
uint32_t | len | ||
) |
Write data to USB Endpoint.
[in] | ep_addr | Endpoint Address
|
[in] | buf | Buffer with data to write to Endpoint |
[in] | len | Buffer length |
ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities | ( | void | ) |
Get driver capabilities.
Retrieves information about capabilities in this driver implementation. The bitfield members of the struct ARM_USBD_CAPABILITIES encode various capabilities, for example if the hardware can create signal events using the ARM_USBD_SignalDeviceEvent callback function.
Example:
uint16_t ARM_USBD_GetFrameNumber | ( | void | ) |
Get current USB Frame Number.
ARM_DRV_VERSION ARM_USBD_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRV_VERSION
Example:
ARM_USBD_STATUS ARM_USBD_Initialize | ( | ARM_USBD_SignalDeviceEvent_t | cb_device_event, |
ARM_USBD_SignalEndpointEvent_t | cb_endpoint_event | ||
) |
Initialize USB Device Interface.
[in] | cb_device_event | Pointer to ARM_USBD_SignalDeviceEvent |
[in] | cb_endpoint_event | Pointer to ARM_USBD_SignalEndpointEvent |
The function initializes the USB Device interface. It is called when the middleware component starts operation.
The function performs the following operations:
The parameter cb_device_event is a pointer to the ARM_USBD_SignalDeviceEvent callback function; use a NULL pointer when no device callback signals are required.
The parameter cb_endpoint_event is a pointer to the ARM_USBD_SignalEndpointEvent callback function; use a NULL pointer when no endpoint callback signals are required.
Example:
ARM_USBD_STATUS ARM_USBD_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control USB Device Interface Power.
[in] | state | Power state |
void ARM_USBD_SignalDeviceEvent | ( | ARM_USBD_EVENT | event | ) |
void ARM_USBD_SignalEndpointEvent | ( | uint8_t | ep_addr, |
ARM_USBD_EP_EVENT | ep_event | ||
) |
Signal USB Endpoint Event. Occurs when Endpoint Read/Write completes.
[in] | ep_addr | Endpoint Address ep_addr.0..3: Address ep_addr.7: Direction |
[in] | ep_event | ARM_USBD_EP_EVENT |
ARM_USBD_STATUS ARM_USBD_Uninitialize | ( | void | ) |
De-initialize USB Device Interface.
The function ARM_USBD_Uninitialize de-initializes the resources of USBD 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.