USB_DEVICEPlatform Middleware > USB

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.
struct USBD_Init_TypeDef
USB Device stack initialization structure.

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 2
#define USB_USBC_32kHz_CLK_LFXO 1
#define USB_USBLEM_CLK_LFRCO 2
#define USB_USBLEM_CLK_LFXO 1

Typedefs

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

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.

Functions

void USBD_AbortAllTransfers (void)
Abort all pending transfers.
int USBD_AbortTransfer (int epAddr)
Abort a pending transfer on a specific endpoint.
void USBD_Connect (void)
Start USB device operation.
void USBD_Disconnect (void)
Stop USB device operation.
bool USBD_EpIsBusy (int epAddr)
Check if an endpoint is busy doing a transfer.
USBD_State_TypeDef USBD_GetUsbState (void)
Get current USB device state.
const char * USBD_GetUsbStateName ( USBD_State_TypeDef state)
Get a string naming a device USB state.
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.
int USBD_Read (int epAddr, void *data, int byteCount, USB_XferCompleteCb_TypeDef callback)
Start a read (OUT) transfer on an endpoint.
int USBD_RemoteWakeup (void)
Perform a remote wakeup signalling sequence.
bool USBD_SafeToEnterEM2 (void)
Check if it is ok to enter energy mode EM2.
int USBD_StallEp (int epAddr)
Set an endpoint in the stalled (halted) state.
void USBD_Stop (void)
Stop USB device stack operation.
int USBD_UnStallEp (int epAddr)
Reset stall state on a stalled (halted) endpoint.
int USBD_Write (int epAddr, void *data, int byteCount, USB_XferCompleteCb_TypeDef callback)
Start a write (IN) transfer on an endpoint.

Macro Definition Documentation

#define USB_PWRSAVE_MODE_ENTEREM2   4

Enter EM2 while in power-save mode.

Definition at line 354 of file em_usb.h .

#define USB_PWRSAVE_MODE_OFF   0

No energy saving mode selected.

Definition at line 351 of file em_usb.h .

#define USB_PWRSAVE_MODE_ONSUSPEND   1

Enter USB power-save mode on suspend.

Definition at line 352 of file em_usb.h .

#define USB_PWRSAVE_MODE_ONVBUSOFF   2

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

Definition at line 353 of file em_usb.h .

#define USB_USBC_32kHz_CLK_LFRCO   2

Use 32kHz LFRCO clock while in powersave mode.

Definition at line 357 of file em_usb.h .

#define USB_USBC_32kHz_CLK_LFXO   1

Use 32kHz LFXO clock while in powersave mode.

Definition at line 356 of file em_usb.h .

#define USB_USBLEM_CLK_LFRCO   2

Use LFRCO as USB LEM clock.

Definition at line 360 of file em_usb.h .

#define USB_USBLEM_CLK_LFXO   1

Use LFXO as USB LEM clock.

Definition at line 359 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] oldState The device USB state just leaved. See USBD_State_TypeDef .
[in] newState New (the current) USB device state. See USBD_State_TypeDef .

Definition at line 720 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 734 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] setup Pointer to an USB setup packet. See USB_Setup_TypeDef .
Returns
An appropriate status/error code. See USB_Status_TypeDef .

Definition at line 754 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] sofNr Current frame number. The value rolls over to 0 after 16383 (0x3FFF).

Definition at line 705 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 693 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 363 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 57 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] epAddr The 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 75 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 127 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 142 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] epAddr The address of the endpoint to check.
Returns
True if endpoint is busy, false otherwise.

Definition at line 159 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 183 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] state Device USB state. See USBD_State_TypeDef .
Returns
State name string pointer.

Definition at line 198 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] p Pointer 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 224 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::bInterval , 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() , cmuClock_HF , cmuOsc_HFXO , cmuOsc_LFRCO , cmuOsc_LFXO , cmuSelect_HFCLK , cmuSelect_HFRCO , cmuSelect_HFXO , cmuSelect_LFRCO , cmuSelect_LFXO , 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::major , SYSTEM_ChipRevision_TypeDef::minor , USBD_Init_TypeDef::numberOfStrings , USBD_Init_TypeDef::stringDescriptors , SYSTEM_ChipRevisionGet() , SystemHFXOClockGet() , USB , 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] epAddr Endpoint address.
[in] data Pointer to transfer data buffer.
[in] byteCount Transfer length.
[in] callback Function 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 619 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 698 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 729 of file em_usbd.c .

int USBD_StallEp ( int epAddr )

Set an endpoint in the stalled (halted) state.

Parameters
[in] epAddr The 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 771 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 807 of file em_usbd.c .

References CMU , CMU_HFCORECLKEN0_USB , CMU_HFCORECLKEN0_USBC , USB , 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] epAddr The 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 836 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] epAddr Endpoint address.
[in] data Pointer to transfer data buffer. This buffer must be WORD (4 byte) aligned.
[in] byteCount Transfer length.
[in] callback Function 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 885 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() , si114xOutputDebugMessage() , USBX_blockWrite() , USBX_inXferCompleteCb() , and USBX_SetupCmdCb() .