CMSIS-Driver  Version 2.7.1
Peripheral Interface for Middleware and Application Code
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
USB Device Interface

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. More...
 
typedef void(* ARM_USBD_SignalEndpointEvent_t )(uint8_t ep_addr, uint32_t event)
 Pointer to ARM_USBD_SignalEndpointEvent : Signal USB Endpoint Event. More...
 

Functions

ARM_DRIVER_VERSION ARM_USBD_GetVersion (void)
 Get driver version. More...
 
ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities (void)
 Get driver capabilities. More...
 
int32_t ARM_USBD_Initialize (ARM_USBD_SignalDeviceEvent_t cb_device_event, ARM_USBD_SignalEndpointEvent_t cb_endpoint_event)
 Initialize USB Device Interface. More...
 
int32_t ARM_USBD_Uninitialize (void)
 De-initialize USB Device Interface. More...
 
int32_t ARM_USBD_PowerControl (ARM_POWER_STATE state)
 Control USB Device Interface Power. More...
 
int32_t ARM_USBD_DeviceConnect (void)
 Connect USB Device. More...
 
int32_t ARM_USBD_DeviceDisconnect (void)
 Disconnect USB Device. More...
 
ARM_USBD_STATE ARM_USBD_DeviceGetState (void)
 Get current USB Device State. More...
 
int32_t ARM_USBD_DeviceRemoteWakeup (void)
 Trigger USB Remote Wakeup. More...
 
int32_t ARM_USBD_DeviceSetAddress (uint8_t dev_addr)
 Set USB Device Address. More...
 
int32_t ARM_USBD_ReadSetupPacket (uint8_t *setup)
 Read setup packet received over Control Endpoint. More...
 
int32_t ARM_USBD_EndpointConfigure (uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size)
 Configure USB Endpoint. More...
 
int32_t ARM_USBD_EndpointUnconfigure (uint8_t ep_addr)
 Unconfigure USB Endpoint. More...
 
int32_t ARM_USBD_EndpointStall (uint8_t ep_addr, bool stall)
 Set/Clear Stall for USB Endpoint. More...
 
int32_t ARM_USBD_EndpointTransfer (uint8_t ep_addr, uint8_t *data, uint32_t num)
 Read data from or Write data to USB Endpoint. More...
 
uint32_t ARM_USBD_EndpointTransferGetResult (uint8_t ep_addr)
 Get result of USB Endpoint transfer. More...
 
int32_t ARM_USBD_EndpointTransferAbort (uint8_t ep_addr)
 Abort current USB Endpoint transfer. More...
 
uint16_t ARM_USBD_GetFrameNumber (void)
 Get current USB Frame Number. More...
 
void ARM_USBD_SignalDeviceEvent (uint32_t event)
 Signal USB Device Event. More...
 
void ARM_USBD_SignalEndpointEvent (uint8_t ep_addr, uint32_t ep_event)
 Signal USB Endpoint Event. More...
 

Description

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:

msc_inline_mscgraph_2

Data Structure Documentation

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 Common 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:

  • Driver_USBD0 is the name of the access struct of the first instance (no. 0).
  • Driver_USBD1 is the name of the access struct of the second instance (no. 1).

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.

Note
The struct must remain unchanged.

Data Fields

ARM_DRIVER_VERSION(* GetVersion )(void)
 Pointer to ARM_USBD_GetVersion : Get driver version. More...
 
ARM_USBD_CAPABILITIES(* GetCapabilities )(void)
 Pointer to ARM_USBD_GetCapabilities : Get driver capabilities. More...
 
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. More...
 
int32_t(* Uninitialize )(void)
 Pointer to ARM_USBD_Uninitialize : De-initialize USB Device Interface. More...
 
int32_t(* PowerControl )(ARM_POWER_STATE state)
 Pointer to ARM_USBD_PowerControl : Control USB Device Interface Power. More...
 
int32_t(* DeviceConnect )(void)
 Pointer to ARM_USBD_DeviceConnect : Connect USB Device. More...
 
int32_t(* DeviceDisconnect )(void)
 Pointer to ARM_USBD_DeviceDisconnect : Disconnect USB Device. More...
 
ARM_USBD_STATE(* DeviceGetState )(void)
 Pointer to ARM_USBD_DeviceGetState : Get current USB Device State. More...
 
int32_t(* DeviceRemoteWakeup )(void)
 Pointer to ARM_USBD_DeviceRemoteWakeup : Trigger USB Remote Wakeup. More...
 
int32_t(* DeviceSetAddress )(uint8_t dev_addr)
 Pointer to ARM_USBD_DeviceSetAddress : Set USB Device Address. More...
 
int32_t(* ReadSetupPacket )(uint8_t *setup)
 Pointer to ARM_USBD_ReadSetupPacket : Read setup packet received over Control Endpoint. More...
 
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. More...
 
int32_t(* EndpointUnconfigure )(uint8_t ep_addr)
 Pointer to ARM_USBD_EndpointUnconfigure : Unconfigure USB Endpoint. More...
 
int32_t(* EndpointStall )(uint8_t ep_addr, bool stall)
 Pointer to ARM_USBD_EndpointStall : Set/Clear Stall for USB Endpoint. More...
 
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. More...
 
uint32_t(* EndpointTransferGetResult )(uint8_t ep_addr)
 Pointer to ARM_USBD_EndpointTransferGetResult : Get result of USB Endpoint transfer. More...
 
int32_t(* EndpointTransferAbort )(uint8_t ep_addr)
 Pointer to ARM_USBD_EndpointTransferAbort : Abort current USB Endpoint transfer. More...
 
uint16_t(* GetFrameNumber )(void)
 Pointer to ARM_USBD_GetFrameNumber : Get current USB Frame Number. More...
 

Field Documentation

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.

struct ARM_USBD_CAPABILITIES

USB Device Driver Capabilities.

A USB Device driver can be implemented with different capabilities. The data fields of this structure encode the capabilities implemented by this driver.

Returned by:

Note
The struct must remain unchanged.
Data Fields
uint32_t vbus_detection: 1 VBUS detection.
uint32_t event_vbus_on: 1 Signal VBUS On event.
uint32_t event_vbus_off: 1 Signal VBUS Off event.
uint32_t reserved: 29 Reserved (must be zero)
struct ARM_USBD_STATE

USB Device State.

This structure stores information about the state of the USB Device. The data fields encode the established speed, whether the device is powered and active.

Returned by:

Data Fields
uint32_t vbus: 1 USB Device VBUS flag.
uint32_t speed: 2 USB Device speed setting (ARM_USB_SPEED_xxx)
uint32_t active: 1 USB Device active flag.
uint32_t reserved: 28

Typedef Documentation

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:

Function Documentation

ARM_DRIVER_VERSION ARM_USBD_GetVersion ( void  )

Get driver version.

Returns
ARM_DRIVER_VERSION

The function ARM_USBD_GetVersion returns version information of the driver implementation in ARM_DRIVER_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_USBD Driver_USBD0;
ARM_DRIVER_USBD *drv_info;
void setup_usbd (void) {
drv_info = &Driver_USBD0;
version = drv_info->GetVersion ();
if (version.api < 0x10A) { // requires at minimum API version 1.10 or higher
// error handling
return;
}
}
ARM_USBD_CAPABILITIES ARM_USBD_GetCapabilities ( void  )

Get driver capabilities.

Returns
ARM_USBD_CAPABILITIES

The function ARM_USBD_GetCapabilities returns information about capabilities in this driver implementation. The data fields of the structure ARM_USBD_CAPABILITIES encode various capabilities, for example if the hardware can create signal events using the ARM_USBD_SignalDeviceEvent callback function.

Example:

extern ARM_DRIVER_USBD Driver_USBD0;
ARM_DRIVER_USBD *drv_info;
void read_capabilities (void) {
ARM_USBD_CAPABILITIES drv_capabilities;
drv_info = &Driver_USBD0;
drv_capabilities = drv_info->GetCapabilities ();
// interrogate capabilities
}
int32_t ARM_USBD_Initialize ( ARM_USBD_SignalDeviceEvent_t  cb_device_event,
ARM_USBD_SignalEndpointEvent_t  cb_endpoint_event 
)

Initialize USB Device Interface.

Parameters
[in]cb_device_eventPointer to ARM_USBD_SignalDeviceEvent
[in]cb_endpoint_eventPointer to ARM_USBD_SignalEndpointEvent
Returns
Status Error Codes

The function ARM_USBD_Initialize 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_Uninitialize ( void  )

De-initialize USB Device Interface.

Returns
Status Error Codes

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.

int32_t ARM_USBD_PowerControl ( ARM_POWER_STATE  state)

Control USB Device Interface Power.

Parameters
[in]statePower state
Returns
Status Error Codes

The function ARM_USBD_PowerControl operates the power modes of the USB Device interface.

The parameter state sets the operation and can have the following values:

  • ARM_POWER_FULL : set-up peripheral for data transfers, enable interrupts (NVIC) and optionally DMA. Can be called multiple times. If the peripheral is already in this mode the function performs no operation and returns with ARM_DRIVER_OK.
  • ARM_POWER_LOW : may use power saving. Returns ARM_DRIVER_ERROR_UNSUPPORTED when not implemented.
  • ARM_POWER_OFF : terminates any pending data transfers, disables peripheral, disables related interrupts and DMA.

Refer to Function Call Sequence for more information.

int32_t ARM_USBD_DeviceConnect ( void  )

Connect USB Device.

Returns
Status Error Codes

The function ARM_USBD_DeviceConnect signals to the host that the device is connected.

int32_t ARM_USBD_DeviceDisconnect ( void  )

Disconnect USB Device.

Returns
Status Error Codes

The function ARM_USBD_DeviceDisconnect signals to the host that the device is disconnected.

ARM_USBD_STATE ARM_USBD_DeviceGetState ( void  )

Get current USB Device State.

Returns
Device State ARM_USBD_STATE

Retrieves the current USB device state.

int32_t ARM_USBD_DeviceRemoteWakeup ( void  )

Trigger USB Remote Wakeup.

Returns
Status Error Codes

The function ARM_USBD_DeviceRemoteWakeup signals remote wakeup to the host.

int32_t ARM_USBD_DeviceSetAddress ( uint8_t  dev_addr)

Set USB Device Address.

Parameters
[in]dev_addrDevice Address
Returns
Status Error Codes

Assigns an address to the device.

int32_t ARM_USBD_ReadSetupPacket ( uint8_t *  setup)

Read setup packet received over Control Endpoint.

Parameters
[out]setupPointer to buffer for setup packet
Returns
Status Error Codes

The function ARM_USBD_ReadSetupPacket reads the last SETUP packet (8 bytes) that was received over Control Endpoint (Endpoint 0) which is indicated by ARM_USBD_EVENT_SETUP event.

See also:

int32_t ARM_USBD_EndpointConfigure ( uint8_t  ep_addr,
uint8_t  ep_type,
uint16_t  ep_max_packet_size 
)

Configure USB Endpoint.

Parameters
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
[in]ep_typeEndpoint Type (ARM_USB_ENDPOINT_xxx)
[in]ep_max_packet_sizeEndpoint Maximum Packet Size
Returns
Status Error Codes

The function ARM_USBD_EndpointConfigure configures an endpoint for transfers.

int32_t ARM_USBD_EndpointUnconfigure ( uint8_t  ep_addr)

Unconfigure USB Endpoint.

Parameters
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
Returns
Status Error Codes

The function ARM_USBD_EndpointUnconfigure de-configures the specified endpoint.

The parameter ep_addr specifies the endpoint address.

int32_t ARM_USBD_EndpointStall ( uint8_t  ep_addr,
bool  stall 
)

Set/Clear Stall for USB Endpoint.

Parameters
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
[in]stallOperation
  • false Clear
  • true Set
Returns
Status Error Codes

The function ARM_USBD_EndpointStall sets or clears stall condition for the specified endpoint.

The parameter ep_addr specifies the endpoint address.
The parameter stall is a boolean parameter.

int32_t ARM_USBD_EndpointTransfer ( uint8_t  ep_addr,
uint8_t *  data,
uint32_t  num 
)

Read data from or Write data to USB Endpoint.

Parameters
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
[out]dataPointer to buffer for data to read or with data to write
[in]numNumber of data bytes to transfer
Returns
Status Error Codes

The function ARM_USBD_EndpointTransfer reads from or writes data to an USB Endpoint.

The parameter ep_addr specifies the endpoint address.
The parameter data is a buffer for data to read or data to write.
The parameter num is the number of bytes to transfer (must be multiple of endpoint maximum packet size for Read transfers).

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 for OUT endpoint (direction = 0)
  • Endpoint Write for IN endpoint (direction = 1)

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.

uint32_t ARM_USBD_EndpointTransferGetResult ( uint8_t  ep_addr)

Get result of USB Endpoint transfer.

Parameters
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
Returns
number of successfully transferred data bytes

The function ARM_USBD_EndpointTransferGetResult returns the number of successfully transferred data bytes started by ARM_USBD_EndpointTransfer.

The parameter ep_addr specifies the endpoint address.

int32_t ARM_USBD_EndpointTransferAbort ( uint8_t  ep_addr)

Abort current USB Endpoint transfer.

Parameters
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
Returns
Status Error Codes

The function ARM_USBD_EndpointTransferAbort aborts the transfer to an endpoint started by ARM_USBD_EndpointTransfer.

The parameter ep_addr specifies the endpoint address.

uint16_t ARM_USBD_GetFrameNumber ( void  )

Get current USB Frame Number.

Returns
Frame Number

Retrieves the sequential 11-bit frame number of the last Start of Frame (SOF) packet.

void ARM_USBD_SignalDeviceEvent ( uint32_t  event)

Signal USB Device Event.

Parameters
[in]eventUSBD Device Events
Returns
none

The function ARM_USBD_SignalDeviceEvent is a callback function registered by the function ARM_USBD_Initialize.

The parameter event indicates one or more events that occurred during driver operation. Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.

Not every event is necessarily generated by the driver. This depends on the implemented capabilities stored in the data fields of the structure ARM_USBD_CAPABILITIES, which can be retrieved with the function ARM_USBD_GetCapabilities.

The following events can be generated:

Event BitDescription supported when ARM_USBD_CAPABILITIES
ARM_USBD_EVENT_VBUS_ON 0 Occurs when valid VBUS voltage is detected. data field event_vbus_on = 1
ARM_USBD_EVENT_VBUS_OFF 1 Occurs when VBUS voltage is turned off. data field event_vbus_off = 1
ARM_USBD_EVENT_RESET 2 Occurs when USB Reset is detected. always supported
ARM_USBD_EVENT_HIGH_SPEED 3 Occurs when USB Device is switched to High-speed. always supported
ARM_USBD_EVENT_SUSPEND 4 Occurs when USB Suspend is detected. always supported
ARM_USBD_EVENT_RESUME 5 Occurs when USB Resume is detected. always supported
void ARM_USBD_SignalEndpointEvent ( uint8_t  ep_addr,
uint32_t  event 
)

Signal USB Endpoint Event.

Parameters
[in]ep_addrEndpoint Address
  • ep_addr.0..3: Address
  • ep_addr.7: Direction
[in]eventUSBD Endpoint Events
Returns
none

The function ARM_USBD_SignalEndpointEvent is a callback function registered by the function ARM_USBD_Initialize.

The argument ep_addr specifies the endpoint.
The parameter event indicates one or more events that occurred during driver operation. Each event is encoded in a separate bit and therefore it is possible to signal multiple events within the same call.

The following events can be generated:

Event Bit Description
ARM_USBD_EVENT_SETUP 0 Occurs when SETUP packet is received over Control Endpoint.
ARM_USBD_EVENT_OUT 1 Occurs when data is received over OUT Endpoint.
ARM_USBD_EVENT_IN 2 Occurs when data is sent over IN Endpoint.