EFM32 Happy Gecko Software Documentation  efm32hg-doc-5.1.2

Detailed Description

Gecko USB DEVICE protocol stack, see USB device stack library page for detailed documentation.

Data Structures

struct  USBD_Callbacks_TypeDef
 USB Device stack callback structure. More...
 
struct  USBD_Init_TypeDef
 USB Device stack initialization structure. More...
 

Macros

#define USB_PWRSAVE_MODE_ENTEREM2   4
 
#define USB_PWRSAVE_MODE_OFF   0
 
#define USB_PWRSAVE_MODE_ONSUSPEND   1
 
#define USB_PWRSAVE_MODE_ONVBUSOFF   2
 
#define USB_USBC_32kHz_CLK_LFRCO   1
 
#define USB_USBC_32kHz_CLK_LFXO   0
 

Typedefs

typedef struct USBD_Callbacks_TypeDef USBD_Callbacks_TypeDef
 USB Device stack callback structure. More...
 
typedef void(* USBD_DeviceStateChangeCb_TypeDef) (USBD_State_TypeDef oldState, USBD_State_TypeDef newState)
 USB State change callback function. More...
 
typedef bool(* USBD_IsSelfPoweredCb_TypeDef) (void)
 USB power mode callback function. More...
 
typedef int(* USBD_SetupCmdCb_TypeDef) (const USB_Setup_TypeDef *setup)
 USB setup request callback function. More...
 
typedef void(* USBD_SofIntCb_TypeDef) (uint16_t sofNr)
 USB Start Of Frame (SOF) interrupt callback function. More...
 
typedef void(* USBD_UsbResetCb_TypeDef) (void)
 USB Reset callback function. More...
 

Enumerations

enum  USBD_State_TypeDef {
  USBD_STATE_NONE = 0,
  USBD_STATE_ATTACHED = 1,
  USBD_STATE_POWERED = 2,
  USBD_STATE_DEFAULT = 3,
  USBD_STATE_ADDRESSED = 4,
  USBD_STATE_CONFIGURED = 5,
  USBD_STATE_SUSPENDED = 6,
  USBD_STATE_LASTMARKER = 7
}
 USB device state enumerator. More...
 

Functions

void USBD_AbortAllTransfers (void)
 Abort all pending transfers. More...
 
int USBD_AbortTransfer (int epAddr)
 Abort a pending transfer on a specific endpoint. More...
 
void USBD_Connect (void)
 Start USB device operation. More...
 
void USBD_Disconnect (void)
 Stop USB device operation. More...
 
bool USBD_EpIsBusy (int epAddr)
 Check if an endpoint is busy doing a transfer. More...
 
USBD_State_TypeDef USBD_GetUsbState (void)
 Get current USB device state. More...
 
const char * USBD_GetUsbStateName (USBD_State_TypeDef state)
 Get a string naming a device USB state. More...
 
int USBD_Init (const USBD_Init_TypeDef *p)
 Initializes USB device hardware and internal protocol stack data structures, then connects the data-line (D+ or D-) pullup resistor to signal host that enumeration can begin. More...
 
int USBD_Read (int epAddr, void *data, int byteCount, USB_XferCompleteCb_TypeDef callback)
 Start a read (OUT) transfer on an endpoint. More...
 
int USBD_RemoteWakeup (void)
 Perform a remote wakeup signalling sequence. More...
 
bool USBD_SafeToEnterEM2 (void)
 Check if it is ok to enter energy mode EM2. More...
 
int USBD_StallEp (int epAddr)
 Set an endpoint in the stalled (halted) state. More...
 
void USBD_Stop (void)
 Stop USB device stack operation. More...
 
int USBD_UnStallEp (int epAddr)
 Reset stall state on a stalled (halted) endpoint. More...
 
int USBD_Write (int epAddr, void *data, int byteCount, USB_XferCompleteCb_TypeDef callback)
 Start a write (IN) transfer on an endpoint. More...
 

Macro Definition Documentation

#define USB_PWRSAVE_MODE_ENTEREM2   4

Enter EM2 while in power-save mode.

Definition at line 352 of file em_usb.h.

#define USB_PWRSAVE_MODE_OFF   0

No energy saving mode selected.

Definition at line 349 of file em_usb.h.

#define USB_PWRSAVE_MODE_ONSUSPEND   1

Enter USB power-save mode on suspend.

Definition at line 350 of file em_usb.h.

#define USB_PWRSAVE_MODE_ONVBUSOFF   2

Enter USB power-save mode when not attached to host.

Definition at line 351 of file em_usb.h.

#define USB_USBC_32kHz_CLK_LFRCO   1

Use 32kHz LFRCO clock while in powersave mode.

Definition at line 355 of file em_usb.h.

#define USB_USBC_32kHz_CLK_LFXO   0

Use 32kHz LFXO clock while in powersave mode.

Definition at line 354 of file em_usb.h.

Typedef Documentation

USB Device stack callback structure.

Callback functions used by the device stack to signal events or query status to/from the application. See USBD_Init_TypeDef. Assign members to NULL if your application don't need a specific callback.

typedef void(* USBD_DeviceStateChangeCb_TypeDef) (USBD_State_TypeDef oldState, USBD_State_TypeDef newState)

USB State change callback function.

Called whenever the device change state.

Parameters
[in]oldStateThe device USB state just leaved. See USBD_State_TypeDef.
[in]newStateNew (the current) USB device state. See USBD_State_TypeDef.

Definition at line 731 of file em_usb.h.

typedef bool(* USBD_IsSelfPoweredCb_TypeDef) (void)

USB power mode callback function.

Called whenever the device stack needs to query if the device is currently self- or bus-powered. Typically when host has issued an GET_STATUS setup command.

Returns
True if self-powered, false otherwise.

Definition at line 745 of file em_usb.h.

typedef int(* USBD_SetupCmdCb_TypeDef) (const USB_Setup_TypeDef *setup)

USB setup request callback function.

Called on each setup request received from host. This gives the application a possibility to extend or override standard requests, and to implement class or vendor specific requests. Return USB_STATUS_OK if the request is handled, return USB_STATUS_REQ_ERR if it is an illegal request or return USB_STATUS_REQ_UNHANDLED to pass the request on to the default request handler.

Parameters
[in]setupPointer to an USB setup packet. See USB_Setup_TypeDef.
Returns
An appropriate status/error code. See USB_Status_TypeDef.

Definition at line 765 of file em_usb.h.

typedef void(* USBD_SofIntCb_TypeDef) (uint16_t sofNr)

USB Start Of Frame (SOF) interrupt callback function.

Called at each SOF interrupt (if enabled),

Parameters
[in]sofNrCurrent frame number. The value rolls over to 0 after 16383 (0x3FFF).

Definition at line 716 of file em_usb.h.

typedef void(* USBD_UsbResetCb_TypeDef) (void)

USB Reset callback function.

Called whenever USB reset signalling is detected on the USB port.

Definition at line 704 of file em_usb.h.

Enumeration Type Documentation

USB device state enumerator.

Enumerator
USBD_STATE_NONE 

Device state is undefined/unknown.

USBD_STATE_ATTACHED 

Device state is ATTACHED.

USBD_STATE_POWERED 

Device state is POWERED.

USBD_STATE_DEFAULT 

Device state is DEFAULT.

USBD_STATE_ADDRESSED 

Device state is ADDRESSED.

USBD_STATE_CONFIGURED 

Device state is CONFIGURED.

USBD_STATE_SUSPENDED 

Device state is SUSPENDED.

USBD_STATE_LASTMARKER 

Device state enum end marker.

Definition at line 358 of file em_usb.h.

Function Documentation

void USBD_AbortAllTransfers ( void  )

Abort all pending transfers.

Aborts transfers for all endpoints currently in use. Pending transfers on the default endpoint (EP0) are not aborted.

Definition at line 55 of file em_usbd.c.

References CORE_ATOMIC_SECTION, and USB_STATUS_EP_ABORTED.

int USBD_AbortTransfer ( int  epAddr)

Abort a pending transfer on a specific endpoint.

Parameters
[in]epAddrThe address of the endpoint to abort.
Returns
USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

Definition at line 73 of file em_usbd.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, USB_STATUS_EP_ABORTED, USB_STATUS_ILLEGAL, USB_STATUS_OK, USBD_STATE_ADDRESSED, and USBD_STATE_CONFIGURED.

Referenced by USBX_SetupCmdCb().

void USBD_Connect ( void  )

Start USB device operation.

Device operation is started by connecting a pullup resistor on the appropriate USB data line.

Definition at line 130 of file em_usbd.c.

References CORE_ATOMIC_SECTION.

void USBD_Disconnect ( void  )

Stop USB device operation.

Device operation is stopped by disconnecting the pullup resistor from the appropriate USB data line. Often referred to as a "soft" disconnect.

Definition at line 145 of file em_usbd.c.

References CORE_ATOMIC_SECTION.

Referenced by USBD_Stop().

bool USBD_EpIsBusy ( int  epAddr)

Check if an endpoint is busy doing a transfer.

Parameters
[in]epAddrThe address of the endpoint to check.
Returns
True if endpoint is busy, false otherwise.

Definition at line 162 of file em_usbd.c.

References USB_STATUS_ILLEGAL.

USBD_State_TypeDef USBD_GetUsbState ( void  )

Get current USB device state.

Returns
Device USB state. See USBD_State_TypeDef.

Definition at line 186 of file em_usbd.c.

Referenced by USBD_Read(), and USBD_Write().

const char* USBD_GetUsbStateName ( USBD_State_TypeDef  state)

Get a string naming a device USB state.

Parameters
[in]stateDevice USB state. See USBD_State_TypeDef.
Returns
State name string pointer.

Definition at line 201 of file em_usbd.c.

References USBD_STATE_LASTMARKER.

int USBD_Init ( const USBD_Init_TypeDef p)

Initializes USB device hardware and internal protocol stack data structures, then connects the data-line (D+ or D-) pullup resistor to signal host that enumeration can begin.

Note
You may later use USBD_Disconnect() and USBD_Connect() to force reenumeration.
Parameters
[in]pPointer to device initialization struct. See USBD_Init_TypeDef.
Returns
USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

Definition at line 226 of file em_usbd.c.

References _USB_DOEP0CTL_MPS_32B, _USB_DOEP0CTL_MPS_64B, USB_InterfaceDescriptor_TypeDef::bAlternateSetting, USB_EndpointDescriptor_TypeDef::bEndpointAddress, USB_InterfaceDescriptor_TypeDef::bInterfaceNumber, USB_EndpointDescriptor_TypeDef::bmAttributes, USB_DeviceDescriptor_TypeDef::bMaxPacketSize0, USBD_Init_TypeDef::bufferingMultiplier, USBD_Init_TypeDef::callbacks, CMU, CMU_ClockEnable(), CMU_ClockSelectGet(), CMU_ClockSelectSet(), CMU_HFCORECLKEN0_USB, CMU_HFCORECLKEN0_USBC, CMU_OscillatorEnable(), CMU_USBCRCTRL_EN, CMU_USHFRCOCONF_BAND_48MHZ, cmuClock_HF, cmuClock_LFC, cmuClock_USBC, cmuClock_USBLE, cmuOsc_LFRCO, cmuOsc_LFXO, cmuSelect_HFCLK, cmuSelect_HFXO, cmuSelect_LFRCO, cmuSelect_LFXO, cmuSelect_USHFRCO, CONFIG_DESC_BM_TRANSFERTYPE, USBD_Init_TypeDef::configDescriptor, CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, USBD_Init_TypeDef::deviceDescriptor, SYSTEM_ChipRevision_TypeDef::family, SYSTEM_ChipRevision_TypeDef::major, SYSTEM_ChipRevision_TypeDef::minor, USBD_Init_TypeDef::numberOfStrings, USBD_Init_TypeDef::stringDescriptors, SYSTEM_ChipRevisionGet(), USB, USB_CTRL_LEMADDRMEN, USB_CTRL_LEMIDLEEN, USB_CTRL_LEMNAKEN, USB_CTRL_LEMOSCCTRL_GATE, USB_CTRL_LEMPHYCTRL, USB_ENDPOINT_DESCRIPTOR, USB_EPNUM_MASK, USB_EPTYPE_CTRL, USB_INTERFACE_DESCRIPTOR, USB_IRQn, USB_SETUP_DIR_MASK, USB_STATUS_ILLEGAL, USB_STATUS_OK, USBD_STATE_LASTMARKER, USBD_STATE_NONE, USBD_STATE_POWERED, USBTIMER_Init(), and USB_EndpointDescriptor_TypeDef::wMaxPacketSize.

Referenced by USBX_init().

int USBD_Read ( int  epAddr,
void *  data,
int  byteCount,
USB_XferCompleteCb_TypeDef  callback 
)

Start a read (OUT) transfer on an endpoint.

Note
The transfer buffer length must be a multiple of 4 bytes in length and WORD (4 byte) aligned. When allocating the buffer, round buffer length up. If it is possible that the host will send more data than your device expects, round buffer size up to the next multiple of maxpacket size.
Parameters
[in]epAddrEndpoint address.
[in]dataPointer to transfer data buffer.
[in]byteCountTransfer length.
[in]callbackFunction to be called on transfer completion. Supply NULL if no callback is needed. See USB_XferCompleteCb_TypeDef.
Returns
USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

Definition at line 573 of file em_usbd.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, USB_STATUS_DEVICE_UNCONFIGURED, USB_STATUS_EP_BUSY, USB_STATUS_EP_STALLED, USB_STATUS_ILLEGAL, USB_STATUS_OK, USBD_GetUsbState(), and USBD_STATE_CONFIGURED.

Referenced by CDC_SetupCmd(), CDC_StateChangeEvent(), HIDKBD_SetupCmd(), USBX_blockRead(), and USBX_outXferCompleteCb().

int USBD_RemoteWakeup ( void  )

Perform a remote wakeup signalling sequence.

Note
It is the responsibility of the application to ensure that remote wakeup is not attempted before the device has been suspended for at least 5 miliseconds. This function should not be called from within an interrupt handler.
Returns
USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

Definition at line 661 of file em_usbd.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, USB_STATUS_ILLEGAL, USB_STATUS_OK, and USBD_STATE_SUSPENDED.

bool USBD_SafeToEnterEM2 ( void  )

Check if it is ok to enter energy mode EM2.

Note
Before entering EM2 both the USB hardware and the USB stack must be in a certain state, this function checks if all conditions for entering EM2 is met. Refer to the Energy-saving modes section for more information.
Returns
True if ok to enter EM2, false otherwise.

Definition at line 693 of file em_usbd.c.

int USBD_StallEp ( int  epAddr)

Set an endpoint in the stalled (halted) state.

Parameters
[in]epAddrThe address of the endpoint to stall.
Returns
USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

Definition at line 737 of file em_usbd.c.

References CORE_ATOMIC_SECTION, USB_STATUS_ILLEGAL, and USB_STATUS_OK.

Referenced by MSDD_Handler().

void USBD_Stop ( void  )

Stop USB device stack operation.

The data-line pullup resistor is turned off, USB interrupts are disabled, and finally the USB pins are disabled.

Definition at line 776 of file em_usbd.c.

References CMU, CMU_HFCORECLKEN0_USB, CMU_HFCORECLKEN0_USBC, USB_IRQn, USBD_Disconnect(), and USBD_STATE_NONE.

Referenced by USBX_disable().

int USBD_UnStallEp ( int  epAddr)

Reset stall state on a stalled (halted) endpoint.

Parameters
[in]epAddrThe address of the endpoint to un-stall.
Returns
USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

Definition at line 799 of file em_usbd.c.

References CORE_ATOMIC_SECTION, USB_STATUS_ILLEGAL, and USB_STATUS_OK.

Referenced by MSDD_SetupCmd().

int USBD_Write ( int  epAddr,
void *  data,
int  byteCount,
USB_XferCompleteCb_TypeDef  callback 
)

Start a write (IN) transfer on an endpoint.

Parameters
[in]epAddrEndpoint address.
[in]dataPointer to transfer data buffer. This buffer must be WORD (4 byte) aligned.
[in]byteCountTransfer length.
[in]callbackFunction to be called on transfer completion. Supply NULL if no callback is needed. See USB_XferCompleteCb_TypeDef.
Returns
USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

Definition at line 851 of file em_usbd.c.

References CORE_DECLARE_IRQ_STATE, CORE_ENTER_ATOMIC, CORE_EXIT_ATOMIC, USB_STATUS_DEVICE_UNCONFIGURED, USB_STATUS_EP_BUSY, USB_STATUS_EP_STALLED, USB_STATUS_ILLEGAL, USB_STATUS_OK, USBD_GetUsbState(), and USBD_STATE_CONFIGURED.

Referenced by CDC_SetupCmd(), HIDKBD_KeyboardEvent(), HIDKBD_SetupCmd(), MSDD_SetupCmd(), USBX_blockWrite(), USBX_inXferCompleteCb(), and USBX_SetupCmdCb().