USB Common#

Common parts for both host and device USB stacks.

Modules#

USB_Setup_TypeDef

USB_DeviceDescriptor_TypeDef

USB_ConfigurationDescriptor_TypeDef

USB_InterfaceDescriptor_TypeDef

USB_EndpointDescriptor_TypeDef

USB_StringDescriptor_TypeDef

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.

Typedefs#

typedef unsigned short
char16_t

Data type used for UTF-16LE formatted USB string descriptors.

typedef int(*
USB_XferCompleteCb_TypeDef)(USB_Status_TypeDef status, uint32_t xferred, uint32_t remaining)

USB transfer callback function.

typedef void(*
USBTIMER_Callback_TypeDef)(void)

USBTIMER callback function.

Functions#

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.

int
USB_PRINTF(const char *format,...)

Transmit "printf" formated data on the debug serial port.

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.

void
USBTIMER_DelayMs(uint32_t msec)

Active wait millisecond delay function.

void
USBTIMER_DelayUs(uint32_t usec)

Active wait microsecond delay function.

void
USBTIMER_Init(void)

Activate the hardware timer used to pace the 1 millisecond timer system.

void
USBTIMER_Start(uint32_t id, uint32_t timeout, USBTIMER_Callback_TypeDef callback)

Start a timer.

void
USBTIMER_Stop(uint32_t id)

Stop a timer.

Macros#

#define
SILABS_USB_VID 0x10C4

Silicon Labs Vendor ID, supplied by USB-IF.

#define
USB_SETUP_DIR_OUT 0

Setup request data stage OUT direction value.

#define
USB_SETUP_DIR_IN 1

Setup request data stage IN direction value.

#define
USB_SETUP_DIR_MASK 0x80

Setup request data stage direction mask.

#define
USB_SETUP_DIR_D2H 0x80

Setup request data stage IN direction mask.

#define
USB_SETUP_DIR_H2D 0x00

Setup request data stage OUT direction mask.

#define
USB_SETUP_TYPE_STANDARD 0

Standard setup request value.

#define
USB_SETUP_TYPE_CLASS 1

Class setup request value.

#define
USB_SETUP_TYPE_VENDOR 2

Vendor setup request value.

#define
USB_SETUP_TYPE_STANDARD_MASK 0x00

Standard setup request mask.

#define
USB_SETUP_TYPE_CLASS_MASK 0x20

Class setup request mask.

#define
USB_SETUP_TYPE_VENDOR_MASK 0x40

Vendor setup request mask.

#define
USB_SETUP_RECIPIENT_DEVICE 0

Setup request device recipient value.

#define
USB_SETUP_RECIPIENT_INTERFACE 1

Setup request interface recipient value.

#define
USB_SETUP_RECIPIENT_ENDPOINT 2

Setup request endpoint recipient value.

#define
USB_SETUP_RECIPIENT_OTHER 3

Setup request other recipient value.

#define
GET_STATUS 0

Standard setup request GET_STATUS.

#define
CLEAR_FEATURE 1

Standard setup request CLEAR_FEATURE.

#define
SET_FEATURE 3

Standard setup request SET_FEATURE.

#define
SET_ADDRESS 5

Standard setup request SET_ADDRESS.

#define
GET_DESCRIPTOR 6

Standard setup request GET_DESCRIPTOR.

#define
SET_DESCRIPTOR 7

Standard setup request SET_DESCRIPTOR.

#define
GET_CONFIGURATION 8

Standard setup request GET_CONFIGURATION.

#define
SET_CONFIGURATION 9

Standard setup request SET_CONFIGURATION.

#define
GET_INTERFACE 10

Standard setup request GET_INTERFACE.

#define
SET_INTERFACE 11

Standard setup request SET_INTERFACE.

#define
SYNCH_FRAME 12

Standard setup request SYNCH_FRAME.

#define
USB_HID_GET_REPORT 0x01

HID class setup request GET_REPORT.

#define
USB_HID_GET_IDLE 0x02

HID class setup request GET_IDLE.

#define
USB_HID_SET_REPORT 0x09

HID class setup request SET_REPORT.

#define
USB_HID_SET_IDLE 0x0A

HID class setup request SET_IDLE.

#define
USB_HID_SET_PROTOCOL 0x0B

HID class setup request SET_PROTOCOL.

#define
USB_CDC_SETLINECODING 0x20

CDC class setup request SET_LINE_CODING.

#define
USB_CDC_GETLINECODING 0x21

CDC class setup request GET_LINE_CODING.

#define
USB_CDC_SETCTRLLINESTATE 0x22

CDC class setup request SET_CONTROL_LINE_STATE.

#define
USB_MSD_BOTRESET 0xFF

MSD class setup request Bulk only transfer reset.

#define
USB_MSD_GETMAXLUN 0xFE

MSD class setup request Get Max LUN.

#define
USB_AUDIO_GET_CUR 0x81

Audio class setup request GET_CUR.

#define
USB_AUDIO_GET_CUR 0x81

Audio class setup request GET_CUR.

#define
USB_AUDIO_SET_CUR 0x01

Audio class setup request SET_CUR.

#define
USB_AUDIO_SET_MIN 0x02

Audio class setup request SET_MIN.

#define
USB_AUDIO_GET_MIN 0x82

Audio class setup request GET_MIN.

#define
USB_AUDIO_SET_MAX 0x03

Audio class setup request SET_MAX.

#define
USB_AUDIO_GET_MAX 0x83

Audio class setup request GET_MAX.

#define
USB_AUDIO_SET_RES 0x04

Audio class setup request SET_RES.

#define
USB_AUDIO_GET_RES 0x84

Audio class setup request GET_RES.

#define
USB_AUDIO_SET_MEM 0x05

Audio class setup request SET_MEM.

#define
USB_AUDIO_GET_MEM 0x85

Audio class setup request GET_MEM.

#define
USB_AUDIO_GET_STAT 0xFF

Audio class setup request GET_STAT.

#define
USB_DEVICE_DESCRIPTOR 1

DEVICE descriptor value.

#define
USB_CONFIG_DESCRIPTOR 2

CONFIGURATION descriptor value.

#define
USB_STRING_DESCRIPTOR 3

STRING descriptor value.

#define
USB_MAX_STRING_DESCRIPTOR_CHARS 126

Maximum STRING descriptor bString length.

#define
USB_INTERFACE_DESCRIPTOR 4

INTERFACE descriptor value.

#define
USB_ENDPOINT_DESCRIPTOR 5

ENDPOINT descriptor value.

#define
USB_DEVICE_QUALIFIER_DESCRIPTOR 6

DEVICE_QUALIFIER descriptor value.

#define
USB_OTHER_SPEED_CONFIG_DESCRIPTOR 7

OTHER_SPEED_CONFIGURATION descriptor value.

#define
USB_INTERFACE_POWER_DESCRIPTOR 8

INTERFACE_POWER descriptor value.

#define
USB_INTERFACE_ASSOCIATION_DESCRIPTOR 11

INTERFACE_ASSOCIATION descriptor value.

#define
USB_HID_DESCRIPTOR 0x21

HID descriptor value.

#define
USB_SMARTCARD_DESCRIPTOR 0x21

Smartcard usb-ccid-specific Descriptor Type.

#define
USB_HID_REPORT_DESCRIPTOR 0x22

HID REPORT descriptor value.

#define
USB_CS_INTERFACE_DESCRIPTOR 0x24

Audio Class-specific interface Descriptor Type.

#define
USB_CS_ENDPOINT_DESCRIPTOR 0x25

Audio Class-specific endpoint Descriptor Type.

#define
USB_HUB_DESCRIPTOR 0x29

HUB descriptor value.

#define
USB_CA_HEADER_DESCRIPTOR 1

Audio Class-Specific AC Interface Header descriptor.

#define
USB_CA_INPUT_TERMINAL_DESCRIPTOR 2

Audio Class-Specific AC Interface Input Terminal desc.

#define
USB_CA_OUTPUT_TERMINAL_DESCRIPTOR 3

Audio Class-Specific AC Interface Output Terminal desc.

#define
USB_CA_MIXER_UNIT_DESCRIPTOR 4

Audio Class-Specific AC Interface Mixer descriptor.

#define
USB_CA_SELECTOR_UNIT_DESCRIPTOR 5

Audio Class-Specific AC Interface Selector desc.

#define
USB_CA_FEATURE_UNIT_DESCRIPTOR 6

Audio Class-Specific AC Interface Feature desc.

#define
USB_CA_PROCESSING_UNIT_DESCRIPTOR 7

Audio Class-Specific AC Interface Processing desc.

#define
USB_CA_EXTENSION_UNIT_DESCRIPTOR 8

Audio Class-Specific AC Interface Extension desc.

#define
USB_CA_EP_GENERAL_DESCRIPTOR 1

Audio Class-Specific general descriptor subtype code.

#define
USB_CA_AS_GENERAL_DESCRIPTOR 1

Audio Class-Specific AS Interface General descriptor.

#define
USB_CA_FORMAT_TYPE_DESCRIPTOR 2

Audio Class-Specific AS Interface Format Type desc.

#define
USB_DEVICE_DESCSIZE 18

Device descriptor size.

#define
USB_CONFIG_DESCSIZE 9

Configuration descriptor size.

#define
USB_INTERFACE_DESCSIZE 9

Interface descriptor size.

#define
USB_ENDPOINT_DESCSIZE 7

Endpoint descriptor size.

#define
USB_DEVICE_QUALIFIER_DESCSIZE 10

Device qualifier descriptor size.

#define
USB_OTHER_SPEED_CONFIG_DESCSIZE 9

Device other speed configuration descriptor size.

#define
USB_INTERFACE_ASSOCIATION_DESCSIZE 8

INTERFACE_ASSOCIATION descriptor size.

#define
USB_HID_DESCSIZE 9

HID descriptor size.

#define
USB_SMARTCARD_DESCSIZE 54

CCID descriptor size.

#define
USB_CDC_HEADER_FND_DESCSIZE 5

CDC Header functional descriptor size.

#define
USB_CDC_CALLMNG_FND_DESCSIZE 5

CDC Call Management functional descriptor size.

#define
USB_CDC_ACM_FND_DESCSIZE 4

CDC Abstract Control Management functional descriptor size.

#define
USB_CA_INPUT_TERMINAL_DESCSIZE 12

Audio Input Terminal descriptor size.

#define
USB_CA_OUTPUT_TERMINAL_DESCSIZE 9

Audio Output Terminal descriptor size.

#define
USB_CA_EP_GENERAL_DESCSIZE 7

Audio Class-Specific general descriptor subtype size.

#define
USB_CA_AS_GENERAL_DESCSIZE 7

Audio Class-Specific AS Interface General desc size.

#define
USB_CA_STD_AS_ENDPOINT_DESCSZIE 9

Audio-class standard audio stream descriptor size.

#define
USB_LS_CTRL_EP_MAXSIZE 8

The max size of low speed control endpoints.

#define
USB_LS_INTR_EP_MAXSIZE 8

The max size of low speed interrupt endpoints.

#define
USB_FS_CTRL_EP_MAXSIZE 64

The max size of full speed control endpoints.

#define
USB_FS_INTR_EP_MAXSIZE 64

The max size of full speed interrupt endpoints.

#define
USB_FS_BULK_EP_MAXSIZE 64

The max size of full speed bulk endpoints.

#define
USB_FS_ISOC_EP_MAXSIZE 1023

The max size of full speed isochronous endpoints.

#define
USB_EPTYPE_CTRL 0

Endpoint type control.

#define
USB_EPTYPE_ISOC 1

Endpoint type isochron.

#define
USB_EPTYPE_BULK 2

Endpoint type bulk.

#define
USB_EPTYPE_INTR 3

Endpoint type interrupt.

#define
USB_EPSYNC_NO (0 << 2)

Endpoint synchronization type, none.

#define
USB_EPSYNC_ASYNC (1 << 2)

Endpoint synchronization type, asynchronous.

#define
USB_EPSYNC_ADAPTIVE (2 << 2)

Endpoint synchronization type, adaptive.

#define
USB_EPSYNC_SYNC (3 << 2)

Endpoint synchronization type, synchronous.

#define
USB_EP_DIR_IN 0x80

Endpoint direction mask.

#define
USB_SETUP_PKT_SIZE 8

Setup request packet size.

#define
USB_EPNUM_MASK 0x0F

Endpoint number mask.

#define
USB_LANGID_ENUS 0x0409

English-United States language id.

#define
USB_MAX_DEVICE_ADDRESS 127

Maximum allowable device address.

#define
CONFIG_DESC_BM_REMOTEWAKEUP 0x20

Configuration descriptor attribute macro.

#define
CONFIG_DESC_BM_SELFPOWERED 0x40

Configuration descriptor attribute macro.

#define
CONFIG_DESC_BM_RESERVED_D7 0x80

Configuration descriptor attribute macro.

#define
CONFIG_DESC_BM_TRANSFERTYPE 0x03

Configuration descriptor transfer type bitmask.

#define
CONFIG_DESC_MAXPOWER_mA (x)

Configuration descriptor power macro.

#define
DEVICE_IS_SELFPOWERED 0x0001

Standard request GET_STATUS bitmask.

#define
REMOTE_WAKEUP_ENABLED 0x0002

Standard request GET_STATUS bitmask.

#define
USB_FEATURE_ENDPOINT_HALT 0

Standard request CLEAR/SET_FEATURE bitmask.

#define
USB_FEATURE_DEVICE_REMOTE_WAKEUP 1

Standard request CLEAR/SET_FEATURE bitmask.

#define
HUB_FEATURE_PORT_RESET 4

HUB class request CLEAR/SET_PORT_FEATURE feature selector.

#define
HUB_FEATURE_PORT_POWER 8

HUB class request CLEAR/SET_PORT_FEATURE feature selector.

#define
HUB_FEATURE_C_PORT_CONNECTION 16

HUB class request CLEAR/SET_PORT_FEATURE feature selector.

#define
HUB_FEATURE_C_PORT_RESET 20

HUB class request CLEAR/SET_PORT_FEATURE feature selector.

#define
HUB_FEATURE_PORT_INDICATOR 22

HUB class request CLEAR/SET_PORT_FEATURE feature selector.

#define
USB_CLASS_CDC 2

CDC device/interface class code.

#define
USB_CLASS_CDC_DATA 0x0A

CDC Data interface class code.

#define
USB_CLASS_CDC_ACM 2

CDC Abstract Control Model interface subclass code.

#define
USB_CLASS_CDC_HFN 0

CDC class Header Functional Descriptor subtype.

#define
USB_CLASS_CDC_CMNGFN 1

CDC class Call Management Functional Descriptor subtype.

#define
USB_CLASS_CDC_ACMFN 2

CDC class Abstract Control Management Functional Descriptor subtype.

#define
USB_CLASS_CDC_UNIONFN 6

CDC class Union Functional Descriptor subtype.

#define
USB_CLASS_HID 3

HID device/interface class code.

#define
USB_CLASS_HID_KEYBOARD 1

HID keyboard interface protocol code.

#define
USB_CLASS_HID_MOUSE 2

HID mouse interface protocol code.

#define
USB_CLASS_HUB 9

HUB device/interface class code.

#define
USB_CLASS_MSD 8

MSD device/interface class code.

#define
USB_CLASS_MSD_BOT_TRANSPORT 0x50

MSD Bulk Only Transport protocol.

#define
USB_CLASS_MSD_SCSI_CMDSET 6

MSD Subclass SCSI transparent command set.

#define
USB_CLASS_MSD_CSW_CMDPASSED 0

MSD BOT Command status wrapper command passed code.

#define
USB_CLASS_MSD_CSW_CMDFAILED 1

MSD BOT Command status wrapper command failed code.

#define
USB_CLASS_MSD_CSW_PHASEERROR 2

MSD BOT Command status wrapper cmd phase error code.

#define
USB_CLASS_AUDIO 1

Audio interface class code.

#define
USB_CLASS_AUDIO_CONTROL 1

Audio subclass code for control interface.

#define
USB_CLASS_AUDIO_STREAMING 2

Audio subclass code for streaming interface.

#define
USB_CLASS_AUDIO_MIDISTREAMING 3

Audio subclass code for midi streaming interface.

#define
USB_CLASS_MISCELLANEOUS 0xEF

MISCELLANEOUS device class code.

#define
USB_CLASS_MISC_COMMON_SUBCLASS 2

MISCELLANEOUS Common sub class code.

#define
USB_CLASS_MISC_IAD_PROTOCOL 1

MISCELLANEOUS Interface Association Descriptor protocol code.

#define
PORT_FULL_SPEED 1

Full speed return value for USBH_GetPortSpeed().

#define
PORT_LOW_SPEED 2

Low speed return value for USBH_GetPortSpeed().

#define
USB_DPLL_SRC_LFXO 1

Use LFXO as DPLL clock source.

#define
USB_DPLL_SRC_HFXO 2

Use HFXO as DPLL clock source.

#define
STATIC_CONST_STRING_DESC (_name, ...)

Macro for creating USB compliant UTF-16LE UNICODE string descriptors.

#define
STATIC_CONST_STRING_DESC_LANGID (_name, x, y)

Macro for creating USB compliant language string descriptors.

#define
UBUF (x, y)

Macro for creating WORD (4 byte) aligned uint8_t array with size which is a multiple of WORD size.

#define
STATIC_UBUF (x, y)

Macro for creating WORD (4 byte) aligned static uint8_t arrays with size which is a multiple of WORD size.

Enumeration Documentation#

USB_Status_TypeDef#

USB_Status_TypeDef

USB transfer status enumerator.

Enumerator
USB_STATUS_OK

No errors detected.

USB_STATUS_REQ_ERR

Setup request error.

USB_STATUS_EP_BUSY

Endpoint is busy.

USB_STATUS_REQ_UNHANDLED

Setup request not handled.

USB_STATUS_ILLEGAL

Illegal operation attempted.

USB_STATUS_EP_STALLED

Endpoint is stalled.

USB_STATUS_EP_ABORTED

Endpoint transfer was aborted.

USB_STATUS_EP_ERROR

Endpoint transfer error.

USB_STATUS_EP_NAK

Endpoint NAK'ed transfer request.

USB_STATUS_DEVICE_UNCONFIGURED

Device is unconfigured.

USB_STATUS_DEVICE_SUSPENDED

Device is suspended.

USB_STATUS_DEVICE_RESET

Device is/was reset.

USB_STATUS_TIMEOUT

Transfer timeout.

USB_STATUS_DEVICE_REMOVED

Device was removed.

USB_STATUS_HC_BUSY

Host channel is busy.

USB_STATUS_DEVICE_MALFUNCTION

Malfunctioning device attached.

USB_STATUS_PORT_OVERCURRENT

VBUS shortcircuit/overcurrent failure.


Typedef Documentation#

char16_t#

typedef unsigned short char16_t

Data type used for UTF-16LE formatted USB string descriptors.


USB_XferCompleteCb_TypeDef#

typedef int(* USB_XferCompleteCb_TypeDef) (USB_Status_TypeDef status, uint32_t xferred, uint32_t remaining) )(USB_Status_TypeDef status, uint32_t xferred, uint32_t remaining)

USB transfer callback function.

Parameters
TypeDirectionArgument NameDescription
[in]status

The transfer status. See USB_Status_TypeDef.

[in]xferred

Number of bytes actually transferred.

[in]remaining

Number of bytes not transferred.

The callback function is called when a transfer has completed. An application should check the status, xferred and optionally the remaining parameters before deciding if the transfer is usable. In the case where the transfer is part of a control request data stage, the callback function should return an appropriate USB_Status_TypeDef status.

Returns


USBTIMER_Callback_TypeDef#

typedef void(* USBTIMER_Callback_TypeDef) (void) )(void)

USBTIMER callback function.

The callback function is called when an USBTIMER has expired. The callback is done with interrupts disabled.


Function Documentation#

USB_PUTCHAR#

int USB_PUTCHAR (char c)

Transmit a single char on the debug serial port.

Parameters
TypeDirectionArgument NameDescription
char[in]c

Char to transmit.

Note

  • This function is enabled with #define DEBUG_USB_API when configuring the protocol stack in "usbconfig.h". This is convenient when debugging code, no need to remove use of this function when debugging has completed.

Returns

  • The char transmitted.


USB_PUTS#

void USB_PUTS (const char * p)

Transmit a zero terminated string on the debug serial port.

Parameters
TypeDirectionArgument NameDescription
const char *[in]p

Pointer to string to transmit.

Note

  • This function is enabled with #define DEBUG_USB_API when configuring the protocol stack in "usbconfig.h". This is convenient when debugging code, no need to remove use of this function when debugging has completed.


USB_PRINTF#

int USB_PRINTF (const char * format, ... )

Transmit "printf" formated data on the debug serial port.

Parameters
TypeDirectionArgument NameDescription
const char *[in]format

Format string (as in printf). No floating point format support.

...N/A

Note

  • This function is enabled with #define USB_USE_PRINTF when configuring the protocol stack in "usbconfig.h". This is convenient when debugging code, no need to remove use of this function when debugging has completed.

Returns

  • Number of chars transmitted.


USB_GetErrorMsgString#

char * USB_GetErrorMsgString (int error)

Return an error message string for a given error code.

Parameters
TypeDirectionArgument NameDescription
int[in]error

Error code, see USB_Status_TypeDef.

Returns

  • Error message string pointer.


USB_PrintErrorMsgString#

void USB_PrintErrorMsgString (char * pre, int error)

Format and print a text string given an error code, prepends an optional user supplied leader string.

Parameters
TypeDirectionArgument NameDescription
char *[in]pre

Optional leader string to prepend to error message string.

int[in]error

Error code, see USB_Status_TypeDef.


USBTIMER_DelayMs#

void USBTIMER_DelayMs (uint32_t msec)

Active wait millisecond delay function.

Parameters
TypeDirectionArgument NameDescription
uint32_t[in]msec

Number of milliseconds to wait.

Can also be used inside interrupt handlers.


USBTIMER_DelayUs#

void USBTIMER_DelayUs (uint32_t usec)

Active wait microsecond delay function.

Parameters
TypeDirectionArgument NameDescription
uint32_t[in]usec

Number of microseconds to wait.

Can also be used inside interrupt handlers.


USBTIMER_Init#

void USBTIMER_Init (void )

Activate the hardware timer used to pace the 1 millisecond timer system.

Parameters
TypeDirectionArgument NameDescription
voidN/A

Call this function whenever the HFPERCLK frequency is changed. This function is initially called by HOST and DEVICE stack xxxx_Init() functions.


USBTIMER_Start#

void USBTIMER_Start (uint32_t id, uint32_t timeout, USBTIMER_Callback_TypeDef callback)

Start a timer.

Parameters
TypeDirectionArgument NameDescription
uint32_t[in]id

Timer id (0..).

uint32_t[in]timeout

Number of milliseconds before timer will elapse.

USBTIMER_Callback_TypeDef[in]callback

Function to be called on timer elapse, ref. USBTIMER_Callback_TypeDef.

If the timer is already running, it will be restarted with new timeout.


USBTIMER_Stop#

void USBTIMER_Stop (uint32_t id)

Stop a timer.

Parameters
TypeDirectionArgument NameDescription
uint32_t[in]id

Timer id (0..).