EFM32 Giant Gecko Software Documentation  efm32gg-doc-5.1.2
em_usb.h File Reference

Detailed Description

USB protocol stack library API for EFM32/EZR32.

Version
5.1.2

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>

Go to the source code of this file.

Data Structures

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

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_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   1
 
#define USB_USBC_32kHz_CLK_LFXO   0
 
#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. More...
 
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...
 
typedef struct USBH_Device_TypeDef USBH_Device_TypeDef
 USB HOST device definition. More...
 
typedef void(* USBTIMER_Callback_TypeDef) (void)
 USBTIMER callback function. More...
 

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. More...
 
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...
 
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. More...
 
void USB_PrintErrorMsgString (char *pre, int error)
 Format and print a text string given an error code, prepends an optional user supplied leader string. More...
 
int USB_PRINTF (const char *format,...)
 Transmit "printf" formated data on the debug serial port. More...
 
int USB_PUTCHAR (char c)
 Transmit a single char on the debug serial port. More...
 
void USB_PUTS (const char *p)
 Transmit a zero terminated string on the debug serial port. More...
 
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...
 
int USBH_AssignHostChannel (USBH_Ep_TypeDef *ep, uint8_t hcnum)
 Assign a host channel to a given endpoint. More...
 
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. More...
 
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. More...
 
bool USBH_DeviceConnected (void)
 Check if a device is connected. More...
 
int USBH_GetConfigurationDescriptorB (USBH_Device_TypeDef *device, void *buf, int len, uint8_t configIndex)
 Read a configuration descriptor from a device. More...
 
int USBH_GetDeviceDescriptorB (USBH_Device_TypeDef *device, void *buf, int len)
 Read a device descriptor from a device. More...
 
uint8_t USBH_GetPortSpeed (void)
 Get the bus speed of the device attached to the USB port. More...
 
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. More...
 
int USBH_Init (const USBH_Init_TypeDef *p)
 Initialize host protocol stack data structures. More...
 
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. More...
 
int USBH_PortReset (void)
 Drive reset signalling on the USB port. More...
 
int USBH_PortResume (void)
 Drive resume signalling on the USB port. More...
 
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. More...
 
int USBH_PrintDeviceDescriptor (const USB_DeviceDescriptor_TypeDef *device)
 Pretty print a device descriptor on the debug serial port. More...
 
int USBH_PrintEndpointDescriptor (const USB_EndpointDescriptor_TypeDef *endpoint)
 Pretty print an endpoint descriptor on the debug serial port. More...
 
int USBH_PrintInterfaceDescriptor (const USB_InterfaceDescriptor_TypeDef *interface)
 Pretty print an interface descriptor on the debug serial port. More...
 
void USBH_PrintString (const char *pre, const USB_StringDescriptor_TypeDef *s, const char *post)
 Print a USB string descriptor on the debug serial port. More...
 
USB_ConfigurationDescriptor_TypeDefUSBH_QGetConfigurationDescriptor (const uint8_t *buf, int configIndex)
 Return a pointer to a configuration descriptor. More...
 
USB_DeviceDescriptor_TypeDefUSBH_QGetDeviceDescriptor (const uint8_t *buf)
 Return a pointer to the device descriptor. More...
 
USB_EndpointDescriptor_TypeDefUSBH_QGetEndpointDescriptor (const uint8_t *buf, int configIndex, int interfaceIndex, int endpointIndex)
 Return a pointer to an endpoint descriptor. More...
 
USB_InterfaceDescriptor_TypeDefUSBH_QGetInterfaceDescriptor (const uint8_t *buf, int configIndex, int interfaceIndex)
 Return a pointer to an interface descriptor. More...
 
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. More...
 
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. More...
 
int USBH_ReadB (USBH_Ep_TypeDef *ep, void *data, int byteCount, int timeout)
 Read data from device endpoint, blocking version. More...
 
int USBH_SetAddressB (USBH_Device_TypeDef *device, uint8_t deviceAddress)
 Give a device an USB address. More...
 
int USBH_SetAltInterfaceB (USBH_Device_TypeDef *device, uint8_t interfaceIndex, uint8_t alternateSetting)
 Activate a device interface within current device configuration. More...
 
int USBH_SetConfigurationB (USBH_Device_TypeDef *device, uint8_t configValue)
 Activate a device configuration. More...
 
int USBH_StallEpB (USBH_Ep_TypeDef *ep)
 Set an endpoint in the stalled (halted) state. More...
 
void USBH_Stop (void)
 Stop USB host operation. More...
 
int USBH_UnStallEpB (USBH_Ep_TypeDef *ep)
 Reset stall state on a stalled (halted) endpoint. More...
 
int USBH_WaitForDeviceConnectionB (uint8_t *buf, int timeoutInSeconds)
 Wait for device connection. More...
 
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. More...
 
int USBH_WriteB (USBH_Ep_TypeDef *ep, void *data, int byteCount, int timeout)
 Write data to device endpoint, blocking version. More...
 
void USBTIMER_DelayMs (uint32_t msec)
 Active wait millisecond delay function. Can also be used inside interrupt handlers. More...
 
void USBTIMER_DelayUs (uint32_t usec)
 Active wait microsecond delay function. Can also be used inside interrupt handlers. More...
 
void USBTIMER_Init (void)
 Activate the hardware timer used to pace the 1 millisecond timer system. More...