em_usb.h File Reference

USB protocol stack library API for EFM32/EZR32.

Version
5.5.0

License

(C) Copyright 2014 Silicon Labs, http://www.silabs.com

This file is licensed under the Silabs License Agreement. See the file "Silabs_License_Agreement.txt" for details. Before using this software for any purpose, you must agree to the terms of that agreement.

Definition in file em_usb.h .

#include " em_device.h "
#include " em_assert.h "
#include " usbconfig.h "
#include <string.h>
#include <stddef.h>
#include " em_common.h "
#include <stdio.h>

Data Structures

struct USB_ConfigurationDescriptor_TypeDef
USB Configuration Descriptor.
struct USB_DeviceDescriptor_TypeDef
USB Device Descriptor.
struct USB_EndpointDescriptor_TypeDef
USB Endpoint Descriptor.
struct USB_InterfaceDescriptor_TypeDef
USB Interface Descriptor.
struct USB_Setup_TypeDef
USB Setup request package.
struct USB_StringDescriptor_TypeDef
USB String Descriptor.
struct USBD_Callbacks_TypeDef
USB Device stack callback structure.
struct USBD_Init_TypeDef
USB Device stack initialization structure.
struct USBH_Device_TypeDef
USB HOST device definition.
struct USBH_Ep_TypeDef
USB HOST endpoint status data.
struct USBH_Init_TypeDef
USB Host stack initialization structure.

Macros

#define CLEAR_FEATURE 1
#define CONFIG_DESC_BM_REMOTEWAKEUP 0x20
#define CONFIG_DESC_BM_RESERVED_D7 0x80
#define CONFIG_DESC_BM_SELFPOWERED 0x40
#define CONFIG_DESC_BM_TRANSFERTYPE 0x03
#define CONFIG_DESC_MAXPOWER_mA (x)   (((x) + 1) / 2)
#define DEVICE_IS_SELFPOWERED 0x0001
#define GET_CONFIGURATION 8
#define GET_DESCRIPTOR 6
#define GET_INTERFACE 10
#define GET_STATUS 0
#define HUB_FEATURE_C_PORT_CONNECTION 16
#define HUB_FEATURE_C_PORT_RESET 20
#define HUB_FEATURE_PORT_INDICATOR 22
#define HUB_FEATURE_PORT_POWER 8
#define HUB_FEATURE_PORT_RESET 4
#define PORT_FULL_SPEED 1
#define PORT_LOW_SPEED 2
#define REMOTE_WAKEUP_ENABLED 0x0002
#define SET_ADDRESS 5
#define SET_CONFIGURATION 9
#define SET_DESCRIPTOR 7
#define SET_FEATURE 3
#define SET_INTERFACE 11
#define SILABS_USB_VID 0x10C4
#define STATIC_CONST_STRING_DESC (_name, ...)
#define STATIC_CONST_STRING_DESC_LANGID (_name, x, y)
#define STATIC_UBUF (x, y) SL_ALIGN (4) static uint8_t x[((y) + 3) & ~3] SL_ATTRIBUTE_ALIGN (4)
#define SYNCH_FRAME 12
#define UBUF (x, y) SL_ALIGN (4) uint8_t x[((y) + 3) & ~3] SL_ATTRIBUTE_ALIGN (4)
#define USB_AUDIO_GET_CUR 0x81
#define USB_AUDIO_GET_CUR 0x81
#define USB_AUDIO_GET_MAX 0x83
#define USB_AUDIO_GET_MEM 0x85
#define USB_AUDIO_GET_MIN 0x82
#define USB_AUDIO_GET_RES 0x84
#define USB_AUDIO_GET_STAT 0xFF
#define USB_AUDIO_SET_CUR 0x01
#define USB_AUDIO_SET_MAX 0x03
#define USB_AUDIO_SET_MEM 0x05
#define USB_AUDIO_SET_MIN 0x02
#define USB_AUDIO_SET_RES 0x04
#define USB_CA_AS_GENERAL_DESCRIPTOR 1
#define USB_CA_AS_GENERAL_DESCSIZE 7
#define USB_CA_EP_GENERAL_DESCRIPTOR 1
#define USB_CA_EP_GENERAL_DESCSIZE 7
#define USB_CA_EXTENSION_UNIT_DESCRIPTOR 8
#define USB_CA_FEATURE_UNIT_DESCRIPTOR 6
#define USB_CA_FORMAT_TYPE_DESCRIPTOR 2
#define USB_CA_HEADER_DESCRIPTOR 1
#define USB_CA_INPUT_TERMINAL_DESCRIPTOR 2
#define USB_CA_INPUT_TERMINAL_DESCSIZE 12
#define USB_CA_MIXER_UNIT_DESCRIPTOR 4
#define USB_CA_OUTPUT_TERMINAL_DESCRIPTOR 3
#define USB_CA_OUTPUT_TERMINAL_DESCSIZE 9
#define USB_CA_PROCESSING_UNIT_DESCRIPTOR 7
#define USB_CA_SELECTOR_UNIT_DESCRIPTOR 5
#define USB_CA_STD_AS_ENDPOINT_DESCSZIE 9
#define USB_CDC_ACM_FND_DESCSIZE 4
#define USB_CDC_CALLMNG_FND_DESCSIZE 5
#define USB_CDC_GETLINECODING 0x21
#define USB_CDC_HEADER_FND_DESCSIZE 5
#define USB_CDC_SETCTRLLINESTATE 0x22
#define USB_CDC_SETLINECODING 0x20
#define USB_CLASS_AUDIO 1
#define USB_CLASS_AUDIO_CONTROL 1
#define USB_CLASS_AUDIO_MIDISTREAMING 3
#define USB_CLASS_AUDIO_STREAMING 2
#define USB_CLASS_CDC 2
#define USB_CLASS_CDC_ACM 2
#define USB_CLASS_CDC_ACMFN 2
#define USB_CLASS_CDC_CMNGFN 1
#define USB_CLASS_CDC_DATA 0x0A
#define USB_CLASS_CDC_HFN 0
#define USB_CLASS_CDC_UNIONFN 6
#define USB_CLASS_HID 3
#define USB_CLASS_HID_KEYBOARD 1
#define USB_CLASS_HID_MOUSE 2
#define USB_CLASS_HUB 9
#define USB_CLASS_MISC_COMMON_SUBCLASS 2
#define USB_CLASS_MISC_IAD_PROTOCOL 1
#define USB_CLASS_MISCELLANEOUS 0xEF
#define USB_CLASS_MSD 8
#define USB_CLASS_MSD_BOT_TRANSPORT 0x50
#define USB_CLASS_MSD_CSW_CMDFAILED 1
#define USB_CLASS_MSD_CSW_CMDPASSED 0
#define USB_CLASS_MSD_CSW_PHASEERROR 2
#define USB_CLASS_MSD_SCSI_CMDSET 6
#define USB_CONFIG_DESCRIPTOR 2
#define USB_CONFIG_DESCSIZE 9
#define USB_CS_ENDPOINT_DESCRIPTOR 0x25
#define USB_CS_INTERFACE_DESCRIPTOR 0x24
#define USB_DEVICE_DESCRIPTOR 1
#define USB_DEVICE_DESCSIZE 18
#define USB_DEVICE_QUALIFIER_DESCRIPTOR 6
#define USB_DEVICE_QUALIFIER_DESCSIZE 10
#define USB_DPLL_SRC_HFXO 2
#define USB_DPLL_SRC_LFXO 1
#define USB_ENDPOINT_DESCRIPTOR 5
#define USB_ENDPOINT_DESCSIZE 7
#define USB_EP_DIR_IN 0x80
#define USB_EPNUM_MASK 0x0F
#define USB_EPSYNC_ADAPTIVE (2 << 2)
#define USB_EPSYNC_ASYNC (1 << 2)
#define USB_EPSYNC_NO (0 << 2)
#define USB_EPSYNC_SYNC (3 << 2)
#define USB_EPTYPE_BULK 2
#define USB_EPTYPE_CTRL 0
#define USB_EPTYPE_INTR 3
#define USB_EPTYPE_ISOC 1
#define USB_FEATURE_DEVICE_REMOTE_WAKEUP 1
#define USB_FEATURE_ENDPOINT_HALT 0
#define USB_FS_BULK_EP_MAXSIZE 64
#define USB_FS_CTRL_EP_MAXSIZE 64
#define USB_FS_INTR_EP_MAXSIZE 64
#define USB_FS_ISOC_EP_MAXSIZE 1023
#define USB_HID_DESCRIPTOR 0x21
#define USB_HID_DESCSIZE 9
#define USB_HID_GET_IDLE 0x02
#define USB_HID_GET_REPORT 0x01
#define USB_HID_REPORT_DESCRIPTOR 0x22
#define USB_HID_SET_IDLE 0x0A
#define USB_HID_SET_PROTOCOL 0x0B
#define USB_HID_SET_REPORT 0x09
#define USB_HUB_DESCRIPTOR 0x29
#define USB_INTERFACE_ASSOCIATION_DESCRIPTOR 11
#define USB_INTERFACE_ASSOCIATION_DESCSIZE 8
#define USB_INTERFACE_DESCRIPTOR 4
#define USB_INTERFACE_DESCSIZE 9
#define USB_INTERFACE_POWER_DESCRIPTOR 8
#define USB_LANGID_ENUS 0x0409
#define USB_LS_CTRL_EP_MAXSIZE 8
#define USB_LS_INTR_EP_MAXSIZE 8
#define USB_MAX_DEVICE_ADDRESS 127
#define USB_MAX_STRING_DESCRIPTOR_CHARS 126
#define USB_MSD_BOTRESET 0xFF
#define USB_MSD_GETMAXLUN 0xFE
#define USB_OTHER_SPEED_CONFIG_DESCRIPTOR 7
#define USB_OTHER_SPEED_CONFIG_DESCSIZE 9
#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_SETUP_DIR_D2H 0x80
#define USB_SETUP_DIR_H2D 0x00
#define USB_SETUP_DIR_IN 1
#define USB_SETUP_DIR_MASK 0x80
#define USB_SETUP_DIR_OUT 0
#define USB_SETUP_PKT_SIZE 8
#define USB_SETUP_RECIPIENT_DEVICE 0
#define USB_SETUP_RECIPIENT_ENDPOINT 2
#define USB_SETUP_RECIPIENT_INTERFACE 1
#define USB_SETUP_RECIPIENT_OTHER 3
#define USB_SETUP_TYPE_CLASS 1
#define USB_SETUP_TYPE_CLASS_MASK 0x20
#define USB_SETUP_TYPE_STANDARD 0
#define USB_SETUP_TYPE_STANDARD_MASK 0x00
#define USB_SETUP_TYPE_VENDOR 2
#define USB_SETUP_TYPE_VENDOR_MASK 0x40
#define USB_SMARTCARD_DESCRIPTOR 0x21
#define USB_SMARTCARD_DESCSIZE 54
#define USB_STRING_DESCRIPTOR 3
#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
#define USB_VBUSOVRCUR_POLARITY_HIGH 1
#define USB_VBUSOVRCUR_POLARITY_LOW 0
#define USB_VBUSOVRCUR_PORT_NONE -1
#define USBH_INIT_DEFAULT

Typedefs

typedef unsigned short char16_t
typedef int(* USB_XferCompleteCb_TypeDef ) ( USB_Status_TypeDef status, uint32_t xferred, uint32_t remaining)
USB transfer callback function.
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.
typedef struct USBH_Device_TypeDef USBH_Device_TypeDef
USB HOST device definition.
typedef void(* USBTIMER_Callback_TypeDef ) (void)
USBTIMER callback function.

Enumerations

enum USB_Status_TypeDef {
USB_STATUS_OK = 0,
USB_STATUS_REQ_ERR = -1,
USB_STATUS_EP_BUSY = -2,
USB_STATUS_REQ_UNHANDLED = -3,
USB_STATUS_ILLEGAL = -4,
USB_STATUS_EP_STALLED = -5,
USB_STATUS_EP_ABORTED = -6,
USB_STATUS_EP_ERROR = -7,
USB_STATUS_EP_NAK = -8,
USB_STATUS_DEVICE_UNCONFIGURED = -9,
USB_STATUS_DEVICE_SUSPENDED = -10,
USB_STATUS_DEVICE_RESET = -11,
USB_STATUS_TIMEOUT = -12,
USB_STATUS_DEVICE_REMOVED = -13,
USB_STATUS_HC_BUSY = -14,
USB_STATUS_DEVICE_MALFUNCTION = -15,
USB_STATUS_PORT_OVERCURRENT = -16
}
USB transfer status enumerator.
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.
enum USBH_EpState_TypeDef {
H_EP_IDLE = 0,
H_EP_SETUP = 1,
H_EP_DATA_IN = 2,
H_EP_DATA_OUT = 3,
H_EP_STATUS_IN = 4,
H_EP_STATUS_OUT = 5
}

Functions

char * USB_GetErrorMsgString (int error)
Return an error message string for a given error code.
void USB_PrintErrorMsgString (char *pre, int error)
Format and print a text string given an error code, prepends an optional user supplied leader string.
int USB_PRINTF (const char *format,...)
Transmit "printf" formated data on the debug serial port.
int USB_PUTCHAR (char c)
Transmit a single char on the debug serial port.
void USB_PUTS (const char *p)
Transmit a zero terminated string on the debug serial port.
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.
int USBH_AssignHostChannel ( USBH_Ep_TypeDef *ep, uint8_t hcnum)
Assign a host channel to a given endpoint.
int USBH_ControlMsg ( USBH_Ep_TypeDef *ep, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength, void *data, int timeout, USB_XferCompleteCb_TypeDef callback)
Send a SETUP command to a device, non-blocking version.
int USBH_ControlMsgB ( USBH_Ep_TypeDef *ep, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength, void *data, int timeout)
Send a SETUP command to a device, blocking version.
bool USBH_DeviceConnected (void)
Check if a device is connected.
int USBH_GetConfigurationDescriptorB ( USBH_Device_TypeDef *device, void *buf, int len, uint8_t configIndex)
Read a configuration descriptor from a device.
int USBH_GetDeviceDescriptorB ( USBH_Device_TypeDef *device, void *buf, int len)
Read a device descriptor from a device.
uint8_t USBH_GetPortSpeed (void)
Get the bus speed of the device attached to the USB port.
int USBH_GetStringB ( USBH_Device_TypeDef *device, uint8_t *buf, int bufLen, uint8_t stringIndex, uint16_t langID)
Read a string descriptor from a device.
int USBH_Init (const USBH_Init_TypeDef *p)
Initialize host protocol stack data structures.
int USBH_InitDeviceData ( USBH_Device_TypeDef *device, const uint8_t *buf, USBH_Ep_TypeDef *ep, int numEp, uint8_t deviceSpeed)
Populate device and endpoint data structures with data retrieved during device enumeration.
int USBH_PortReset (void)
Drive reset signalling on the USB port.
int USBH_PortResume (void)
Drive resume signalling on the USB port.
void USBH_PortSuspend (void)
Set the USB port in suspend mode.
int USBH_PrintConfigurationDescriptor (const USB_ConfigurationDescriptor_TypeDef *config, int maxLen)
Pretty print a configuration descriptor on the debug serial port.
int USBH_PrintDeviceDescriptor (const USB_DeviceDescriptor_TypeDef *device)
Pretty print a device descriptor on the debug serial port.
int USBH_PrintEndpointDescriptor (const USB_EndpointDescriptor_TypeDef *endpoint)
Pretty print an endpoint descriptor on the debug serial port.
int USBH_PrintInterfaceDescriptor (const USB_InterfaceDescriptor_TypeDef *interface)
Pretty print an interface descriptor on the debug serial port.
void USBH_PrintString (const char *pre, const USB_StringDescriptor_TypeDef *s, const char *post)
Print a USB string descriptor on the debug serial port.
USB_ConfigurationDescriptor_TypeDef * USBH_QGetConfigurationDescriptor (const uint8_t *buf, int configIndex)
Return a pointer to a configuration descriptor.
USB_DeviceDescriptor_TypeDef * USBH_QGetDeviceDescriptor (const uint8_t *buf)
Return a pointer to the device descriptor.
USB_EndpointDescriptor_TypeDef * USBH_QGetEndpointDescriptor (const uint8_t *buf, int configIndex, int interfaceIndex, int endpointIndex)
Return a pointer to an endpoint descriptor.
USB_InterfaceDescriptor_TypeDef * USBH_QGetInterfaceDescriptor (const uint8_t *buf, int configIndex, int interfaceIndex)
Return a pointer to an interface descriptor.
int USBH_QueryDeviceB (uint8_t *buf, size_t bufsize, uint8_t deviceSpeed)
Will request both the device descriptor and the entire configuration descriptor from the device at USB address 0.
int USBH_Read ( USBH_Ep_TypeDef *ep, void *data, int byteCount, int timeout, USB_XferCompleteCb_TypeDef callback)
Read data from device endpoint, non-blocking version.
int USBH_ReadB ( USBH_Ep_TypeDef *ep, void *data, int byteCount, int timeout)
Read data from device endpoint, blocking version.
int USBH_SetAddressB ( USBH_Device_TypeDef *device, uint8_t deviceAddress)
Give a device an USB address.
int USBH_SetAltInterfaceB ( USBH_Device_TypeDef *device, uint8_t interfaceIndex, uint8_t alternateSetting)
Activate a device interface within current device configuration.
int USBH_SetConfigurationB ( USBH_Device_TypeDef *device, uint8_t configValue)
Activate a device configuration.
int USBH_StallEpB ( USBH_Ep_TypeDef *ep)
Set an endpoint in the stalled (halted) state.
void USBH_Stop (void)
Stop USB host operation.
int USBH_UnStallEpB ( USBH_Ep_TypeDef *ep)
Reset stall state on a stalled (halted) endpoint.
int USBH_WaitForDeviceConnectionB (uint8_t *buf, int timeoutInSeconds)
Wait for device connection.
int USBH_Write ( USBH_Ep_TypeDef *ep, void *data, int byteCount, int timeout, USB_XferCompleteCb_TypeDef callback)
Write data to device endpoint, non-blocking version.
int USBH_WriteB ( USBH_Ep_TypeDef *ep, void *data, int byteCount, int timeout)
Write data to device endpoint, blocking version.
void USBTIMER_DelayMs (uint32_t msec)
Active wait millisecond delay function. Can also be used inside interrupt handlers.
void USBTIMER_DelayUs (uint32_t usec)
Active wait microsecond delay function. Can also be used inside interrupt handlers.
void USBTIMER_Init (void)
Activate the hardware timer used to pace the 1 millisecond timer system.