![]() |
CMSIS-Driver
Version 2.02
Peripheral Interface for Middleware and Application Code
|
Driver API for USB Device Peripheral (Driver_USBD.h) More...
Content | |
USBD Device Events | |
The USB Device driver generates Device call back events that are notified via the function ARM_USBD_SignalDeviceEvent. | |
USBD Endpoint Events | |
The USB Device driver generates Endpoint call back events that are notified via the function ARM_USBD_SignalEndpointEvent. | |
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 )(uint32_t event) |
Pointer to ARM_USBD_SignalDeviceEvent : Signal USB Device Event. | |
typedef void(* | ARM_USBD_SignalEndpointEvent_t )(uint8_t ep_addr, uint32_t event) |
Pointer to ARM_USBD_SignalEndpointEvent : Signal USB Endpoint Event. | |
Functions | |
ARM_DRIVER_VERSION | ARM_USBD_GetVersion (void) |
Get driver version. | |
ARM_USBD_CAPABILITIES | ARM_USBD_GetCapabilities (void) |
Get driver capabilities. | |
int32_t | ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event) |
Initialize USB Device Interface. | |
int32_t | ARM_USBD_Uninitialize (void) |
De-initialize USB Device Interface. | |
int32_t | ARM_USBD_PowerControl (ARM_POWER_STATE state) |
Control USB Device Interface Power. | |
int32_t | ARM_USBD_DeviceConnect (void) |
Connect USB Device. | |
int32_t | ARM_USBD_DeviceDisconnect (void) |
Disconnect USB Device. | |
ARM_USBD_STATE | ARM_USBD_DeviceGetState (void) |
Get current USB Device State. | |
int32_t | ARM_USBD_DeviceRemoteWakeup (void) |
Trigger USB Remote Wakeup. | |
int32_t | ARM_USBD_DeviceSetAddress (uint8_t dev_addr) |
Set USB Device Address. | |
int32_t | ARM_USBD_ReadSetupPacket (uint8_t *setup) |
Read setup packet received over Control Endpoint. | |
int32_t | ARM_USBD_EndpointConfigure (uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size) |
Configure USB Endpoint. | |
int32_t | ARM_USBD_EndpointUnconfigure (uint8_t ep_addr) |
Unconfigure USB Endpoint. | |
int32_t | ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall) |
Set/Clear Stall for USB Endpoint. | |
int32_t | ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num) |
Read data from or Write data to USB Endpoint. | |
uint32_t | ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr) |
Get result of USB Endpoint transfer. | |
int32_t | ARM_USBD_EndpointTransferAbort (uint8_t ep_addr) |
Abort current USB Endpoint transfer. | |
uint16_t | ARM_USBD_GetFrameNumber (void) |
Get current USB Frame Number. | |
void | ARM_USBD_SignalDeviceEvent (uint32_t event) |
Signal USB Device Event. | |
void | ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t ep_event) |
Signal USB Endpoint Event. | |
Driver API for USB Device Peripheral (Driver_USBD.h)
USB Device API
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 (USBD Device Events) and endpoint related events (USBD Endpoint Events).
USB Device Function Call Sequence
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 Driver_USBDn. 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_USBD_GetVersion : Get driver version. | |
ARM_USBD_CAPABILITIES(* | GetCapabilities )(void) |
Pointer to ARM_USBD_GetCapabilities : Get driver capabilities. | |
int32_t(* | Initialize )(ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event) |
Pointer to ARM_USBD_Initialize : Initialize USB Device Interface. | |
int32_t(* | Uninitialize )(void) |
Pointer to ARM_USBD_Uninitialize : De-initialize USB Device Interface. | |
int32_t(* | PowerControl )(ARM_POWER_STATE state) |
Pointer to ARM_USBD_PowerControl : Control USB Device Interface Power. | |
int32_t(* | DeviceConnect )(void) |
Pointer to ARM_USBD_DeviceConnect : Connect USB Device. | |
int32_t(* | 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. | |
int32_t(* | DeviceRemoteWakeup )(void) |
Pointer to ARM_USBD_DeviceRemoteWakeup : Trigger USB Remote Wakeup. | |
int32_t(* | DeviceSetAddress )(uint8_t dev_addr) |
Pointer to ARM_USBD_DeviceSetAddress : Set USB Device Address. | |
int32_t(* | ReadSetupPacket )(uint8_t *setup) |
Pointer to ARM_USBD_ReadSetupPacket : Read setup packet received over Control Endpoint. | |
int32_t(* | EndpointConfigure )(uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size) |
Pointer to ARM_USBD_EndpointConfigure : Configure USB Endpoint. | |
int32_t(* | EndpointUnconfigure )(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointUnconfigure : Unconfigure USB Endpoint. | |
int32_t(* | EndpointStall )(uint8_t ep_addr, bool stall) |
Pointer to ARM_USBD_EndpointStall : Set/Clear Stall for USB Endpoint. | |
int32_t(* | EndpointTransfer )(uint8_t ep_addr, uint8_t *data, uint32_t num) |
Pointer to ARM_USBD_EndpointTransfer : Read data from or Write data to USB Endpoint. | |
uint32_t(* | EndpointTransferGetResult )(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointTransferGetResult : Get result of USB Endpoint transfer. | |
int32_t(* | EndpointTransferAbort )(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointTransferAbort : Abort current USB Endpoint transfer. | |
uint16_t(* | GetFrameNumber )(void) |
Pointer to ARM_USBD_GetFrameNumber : Get current USB Frame Number. | |
int32_t(* DeviceConnect)(void) |
Pointer to ARM_USBD_DeviceConnect : Connect USB Device.
int32_t(* 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.
int32_t(* DeviceRemoteWakeup)(void) |
Pointer to ARM_USBD_DeviceRemoteWakeup : Trigger USB Remote Wakeup.
int32_t(* DeviceSetAddress)(uint8_t dev_addr) |
Pointer to ARM_USBD_DeviceSetAddress : Set USB Device Address.
int32_t(* EndpointConfigure)(uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size) |
Pointer to ARM_USBD_EndpointConfigure : Configure USB Endpoint.
int32_t(* EndpointStall)(uint8_t ep_addr, bool stall) |
Pointer to ARM_USBD_EndpointStall : Set/Clear Stall for USB Endpoint.
int32_t(* EndpointTransfer)(uint8_t ep_addr, uint8_t *data, uint32_t num) |
Pointer to ARM_USBD_EndpointTransfer : Read data from or Write data to USB Endpoint.
int32_t(* EndpointTransferAbort)(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointTransferAbort : Abort current USB Endpoint transfer.
uint32_t(* EndpointTransferGetResult)(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointTransferGetResult : Get result of USB Endpoint transfer.
int32_t(* EndpointUnconfigure)(uint8_t ep_addr) |
Pointer to ARM_USBD_EndpointUnconfigure : Unconfigure 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_DRIVER_VERSION(* GetVersion)(void) |
Pointer to ARM_USBD_GetVersion : Get driver version.
int32_t(* Initialize)(ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event) |
Pointer to ARM_USBD_Initialize : Initialize USB Device Interface.
int32_t(* PowerControl)(ARM_POWER_STATE state) |
Pointer to ARM_USBD_PowerControl : Control USB Device Interface Power.
int32_t(* ReadSetupPacket)(uint8_t *setup) |
Pointer to ARM_USBD_ReadSetupPacket : Read setup packet received over Control Endpoint.
int32_t(* 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:
Data Fields | ||
---|---|---|
uint32_t | event_vbus_off: 1 | Signal VBUS Off event. |
uint32_t | event_vbus_on: 1 | Signal VBUS On event. |
uint32_t | vbus_detection: 1 | VBUS detection. |
struct ARM_USBD_STATE |
USB Device State.
This structure stores information about the state of the USB Device. The bitfields encode whether the device is powered, the established speed and if active.
Returned by:
Data Fields | ||
---|---|---|
uint32_t | active: 1 | USB Device active flag. |
uint32_t | speed: 2 | USB Device speed setting (ARM_USB_SPEED_xxx) |
uint32_t | vbus: 1 | USB Device VBUS flag. |
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:
int32_t ARM_USBD_DeviceConnect | ( | void | ) |
int32_t ARM_USBD_DeviceDisconnect | ( | void | ) |
Disconnect USB Device.
Signals to the host that the device is disconnected.
ARM_USBD_STATE ARM_USBD_DeviceGetState | ( | void | ) |
Get current USB Device State.
Retrieves the current USB device state.
int32_t ARM_USBD_DeviceRemoteWakeup | ( | void | ) |
int32_t ARM_USBD_DeviceSetAddress | ( | uint8_t | dev_addr | ) |
Set USB Device Address.
[in] | dev_addr | Device Address |
Assigns an address to the device.
int32_t ARM_USBD_EndpointConfigure | ( | uint8_t | ep_addr, |
uint8_t | ep_type, | ||
uint16_t | ep_max_packet_size | ||
) |
Configure USB Endpoint.
[in] | ep_addr | Endpoint Address
|
[in] | ep_type | Endpoint Type (ARM_USB_ENDPOINT_xxx) |
[in] | ep_max_packet_size | Endpoint Maximum Packet Size |
Configures the specified endpoint for transfers.
int32_t ARM_USBD_EndpointStall | ( | uint8_t | ep_addr, |
bool | stall | ||
) |
Set/Clear Stall for USB Endpoint.
[in] | ep_addr | Endpoint Address
|
[in] | stall | Operation
|
Sets or clears stall condition for the specified endpoint.
int32_t ARM_USBD_EndpointTransfer | ( | uint8_t | ep_addr, |
uint8_t * | data, | ||
uint32_t | num | ||
) |
Read data from or Write data to USB Endpoint.
[in] | ep_addr | Endpoint Address
|
[out] | data | Pointer to buffer for data to read or with data to write |
[in] | num | Number of data bytes to transfer |
This function is used to read data from or to write data to USB Endpoint.
The function specifies the endpoint address, the buffer for data to read or with data to write and the number of bytes to transfer.
The function is non-blocking and returns as soon as the driver starts the operation on the specified endpoint. During the operation it is not allowed to call this function again on the same endpoint. Also the data buffer must stay allocated and the contents of data must not be modified.
Direction in the endpoint address specifies the type of transfer:
Endpoint Read is finished when the requested number of data bytes have been received or when a short packet or ZLP (Zero-Length Packet) has been received. Completion of operation is indicated by ARM_USBD_EVENT_OUT event. Number of successfully received data bytes can be retrieved by calling ARM_USBD_EndpointTransferGetResult.
Endpoint Write is finished when the requested number of data bytes have been sent. Completion of operation is indicated by ARM_USBD_EVENT_IN event. Number of successfully sent data bytes can be retrieved by calling ARM_USBD_EndpointTransferGetResult.
Transfer operation can be aborted by calling ARM_USBD_EndpointTransferAbort.
int32_t ARM_USBD_EndpointTransferAbort | ( | uint8_t | ep_addr | ) |
Abort current USB Endpoint transfer.
[in] | ep_addr | Endpoint Address
|
This function is used to abort active endpoint transfer started by ARM_USBD_EndpointTransfer.
uint32_t ARM_USBD_EndpointTransferGetResult | ( | uint8_t | ep_addr | ) |
Get result of USB Endpoint transfer.
[in] | ep_addr | Endpoint Address
|
Returns the number of successfully transferred data bytes started by ARM_USBD_EndpointTransfer operation.
int32_t ARM_USBD_EndpointUnconfigure | ( | uint8_t | ep_addr | ) |
Unconfigure USB Endpoint.
[in] | ep_addr | Endpoint Address
|
Unconfigures the specified endpoint.
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.
Retrieves the sequential 11-bit frame number of the last Start of Frame (SOF) packet.
ARM_DRIVER_VERSION ARM_USBD_GetVersion | ( | void | ) |
Get driver version.
Returns version information of the driver implementation in ARM_DRIVER_VERSION
Example:
int32_t 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.
Example:
int32_t ARM_USBD_PowerControl | ( | ARM_POWER_STATE | state | ) |
Control USB Device Interface Power.
[in] | state | Power state |
Allows you to control the power modes of the USB Device interface.
int32_t ARM_USBD_ReadSetupPacket | ( | uint8_t * | setup | ) |
Read setup packet received over Control Endpoint.
[out] | setup | Pointer to buffer for setup packet |
Reads last SETUP packet (8 bytes) that was received over Control Endpoint (Endpoint 0) which is indicated by ARM_USBD_EVENT_SETUP event.
void ARM_USBD_SignalDeviceEvent | ( | uint32_t | event | ) |
Signal USB Device Event.
[in] | event | USBD Device Events |
The function ARM_USBD_SignalDeviceEvent notifies the application of the USBD Device Events and it is registered by the function ARM_USBD_Initialize. The function ARM_USBD_GetCapabilities returns information about the implemented optional events in a driver.
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_USBD_EVENT_VBUS_ON | Occurs when valid VBUS voltage is detected. |
1 | ARM_USBD_EVENT_VBUS_OFF | Occurs when VBUS voltage is turned off. |
2 | ARM_USBD_EVENT_RESET | Occurs when USB Reset is detected. |
3 | ARM_USBD_EVENT_HIGH_SPEED | Occurs when USB Device is switched to High-speed. |
4 | ARM_USBD_EVENT_SUSPEND | Occurs when USB Suspend is detected. |
5 | ARM_USBD_EVENT_RESUME | Occurs when USB Resume is detected. |
void ARM_USBD_SignalEndpointEvent | ( | uint8_t | ep_addr, |
uint32_t | event | ||
) |
Signal USB Endpoint Event.
[in] | ep_addr | Endpoint Address
|
[in] | event | USBD Endpoint Events |
The function ARM_USBD_SignalEndpointEvent notifies the application of the USBD Endpoint Events and it is registered by the function ARM_USBD_Initialize.
The argument ep_addr specifies the endpoint that is used.
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_USBD_EVENT_SETUP | Occurs when SETUP packet is received over Control Endpoint. |
1 | ARM_USBD_EVENT_OUT | Occurs when data is received over OUT Endpoint. |
2 | ARM_USBD_EVENT_IN | Occurs when data is sent over IN Endpoint. |
int32_t ARM_USBD_Uninitialize | ( | void | ) |
De-initialize USB Device Interface.
The function ARM_USBD_Uninitialize de-initializes the resources of USBD interface.
It is called when the middleware component stops operation and releases the software resources used by the interface.