USB Host#

Gecko USB host protocol stack.

The source files for the USB host stack resides in the usb directory and follows the naming convention: em_usbhnnn.c/h.


Introduction#

The USB host protocol stack provides an API which makes it possible to create USB hosts with a minimum of effort. The host stack supports control, bulk and interrupt transfers.

The stack is highly configurable to suit various needs, it does also contain useful debugging features together with several demonstration projects to get you started fast.

We recommend that you read through this documentation, then proceed to build and test a few example projects before you start designing your own USB host applications.


Getting started#

To use an USB device, its pratical to divide the initial steps needed into :


Device connection#

This framework can be used to establish a device connection. 

// Initialize USB host stack
USBH_Init( &is );

for (;;)
{
  // Wait for ever on device attachment

  // The second parameter is timeout in seconds, 0 means for ever
  if ( USBH_WaitForDeviceConnectionB( tmpBuf, 0 ) == USB_STATUS_OK )
  {

    // Device is now connected and ready for enumeration !

  }

  // Wait for disconnection
  while ( USBH_DeviceConnected() ){}

  // Disable USB peripheral, power down USB port.
  USBH_Stop();
}


Device enumeration and configuration#

This framework can be used to enumerate and activate the device. 

  // Enumerate device, retrieve device and configuration descriptors from device
  USBH_QueryDeviceB( tmpBuf, sizeof( tmpBuf ), USBH_GetPortSpeed() );

  // Qualify the device
  if ( ( USBH_QGetDeviceDescriptor( tmpBuf )->idVendor  == 0x10C4               ) &&
       ( USBH_QGetDeviceDescriptor( tmpBuf )->idProduct == 0x0001               ) &&
       ( USBH_QGetDeviceDescriptor( tmpBuf )->bNumConfigurations == 1           ) &&
       ( USBH_QGetConfigurationDescriptor( tmpBuf, 0 )->bNumInterfaces  == 1    ) &&
       ( USBH_QGetInterfaceDescriptor(  tmpBuf, 0, 0 )->bInterfaceClass == 0xFF ) &&
       ( USBH_QGetInterfaceDescriptor(  tmpBuf, 0, 0 )->bNumEndpoints   == 2    )    )
  {
    // After having determined that the device is "our" device, it's time to
    // give it an USB address and activate the configuration.

    // Populate device and endpoint data structures with
    // data retrieved during enumeration.
    USBH_InitDeviceData( &device, tmpBuf, ep, 2, USBH_GetPortSpeed() );

    USBH_SetAddressB( &device, DEV_ADDR );
    USBH_SetConfigurationB( &device, device.confDesc.bConfigurationValue );

    // Assign host channels to device endpoints
    USBH_AssignHostChannel( &ep[ 0 ], 2 );
    USBH_AssignHostChannel( &ep[ 1 ], 3 );

    // We are now ready to use the device !

  }


The host stack API#


Introduction#

This section contains brief descriptions of all functions in the API. You will find detailed information on input and output parameters and return values by clicking on the hyperlinked function names. It is also a good idea to study the code in the USB demonstration projects.

Your application code must include one header file: em_usb.h.

The functions in the API come in two flavours, they are either blocking or non-blocking. The blocking functions have an uppercase letter B at the end of the function name. Blocking functions can not be called when interrupts are disabled. Note that all API callback functions are called from within the USB peripheral interrupt handler with interrupts disabled.

The USB stack use a hardware timer to keep track of time. TIMER0 is the default choice, refer to Configuring the host stack for other possibilities. Your application must not use the selected timer.

Pitfalls:
An USB peripheral will fill host receive buffers in quantities of WORD's (4 bytes). When allocating storage for receive buffers, round size up to next WORD boundary. If it is possible that a device will send more data than host expects, round buffer size up to the next multiple of maxpacket size for the relevant endpoint to avoid buffer overflow.
Transmit and receive buffers must also be WORD aligned. Macros are available for allocating buffers, see UBUF and STATIC_UBUF.

Transmit buffers passed to non-blocking transfer functions must be statically allocated because these functions do not have their own buffers. The data in the transmit buffers must be valid until the transfer completes, times out or fails.


Top level control functions#

USBH_Init()
Initial host stack initialization, call once in start of main().

USBH_Stop()
Terminates host operation, turns off VBUS.

USBH_WaitForDeviceConnectionB()
Wait for device connection with optional timeout.

USBH_AssignHostChannel()
Associate a device endpoint with a host channel.


USB transfer functions#

USBH_ControlMsg(), USBH_ControlMsgB()
Perform a non-blocking or blocking USB control message transfer.

USBH_Read(), USBH_ReadB()
Perform a non-blocking or blocking USB IN data transfer. Data direction is from device to host.

USBH_Write(), USBH_WriteB()
Perform a non-blocking or blocking USB OUT data transfer. Data direction is from host to device.


USB Chapter 9 support functions#

All Chapter 9 support functions are blocking with a timeout of 1 second.

USBH_GetConfigurationDescriptorB()
Read a configuration descriptor from a device.

USBH_GetDeviceDescriptorB()
Read a device descriptor from a device.

USBH_GetStringB()
Read a string descriptor from a device.

USBH_SetAddressB()
Set new USB device address on device currently on USB address 0.

USBH_SetAltInterfaceB()
Set alternate interface on a device.

USBH_SetConfigurationB()
Set device configuration.

USBH_StallEpB(), USBH_UnStallEpB()
These functions stalls or un-stalls an endpoint. Uses USB standard requests SET_FEATURE and CLEAR_FEATURE.


Host port control functions#

USBH_DeviceConnected()
Check if a device is connected on the USB host port.

USBH_GetPortSpeed()
Get the bus speed (low speed or full speed) of the device currently connected to the USB host port.

USBH_PortReset()
Drive reset signalling on the USB host port.

USBH_PortResume()
Drive resume signalling on the USB host port.

USBH_PortSuspend()
Set the USB host port in suspend mode.


Enumeration and query functions#

USBH_QueryDeviceB()
This function will read the device and configuration descriptors from a device at USB address 0. The application must allocate a buffer of sufficent size to hold the data. This data buffer can later be used by all USBH_Qxxx functions to retrieve pointers to any descriptor within any configuration descriptor. Data retrieved by this function must also be passed to USBH_InitDeviceData() before normal device communication can start. Ref. section Device enumeration and configuration.

USBH_QGetConfigurationDescriptor()
Get a pointer to a given configuration descriptor. Parses through a data buffer which must have been previously populated by a call to USBH_QueryDeviceB().

USBH_QGetDeviceDescriptor()
Get a pointer to the device descriptor. Parses through a data buffer which must have been previously populated by a call to USBH_QueryDeviceB().

USBH_QGetEndpointDescriptor()
Get a pointer to a given endpoint descriptor within a given interface within a given configuration. Parses through a data buffer which must have been previously populated by a call to USBH_QueryDeviceB().

USBH_QGetInterfaceDescriptor()
Get a pointer to an interface descriptor within a given configuration. Parses through a data buffer which must have been previously populated by a call to USBH_QueryDeviceB().

USBH_InitDeviceData()
Populates device and endpoint data structures with data which must have been retrieved from a device by a call to USBH_QueryDeviceB() . The application must allocate and provide device and endpoint data structures to the host stack. After this function is called the device and endpoint data structures can be used as parameters (handles) to other API functions as needed.


Utility functions#

USBH_PrintString()
Print an USB string descriptor on the debug serial port with optional leader and trailer strings.

USBH_PrintConfigurationDescriptor(), USBH_PrintDeviceDescriptor(), USBH_PrintEndpointDescriptor(), USBH_PrintInterfaceDescriptor()
Pretty print descriptors on the debug serial port.

USB_PUTCHAR()
Transmit a single char on the debug serial port.

USB_PUTS()
Transmit a zero terminated string on the debug serial port.

USB_PRINTF()
Transmit "printf" formated data on the debug serial port.

USB_GetErrorMsgString()
Return an error message string for a given error code.

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

USBTIMER_DelayMs()
Active wait millisecond delay function. Can also be used inside interrupt handlers.

USBTIMER_DelayUs()
Active wait microsecond delay function. Can also be used inside interrupt handlers.

USBTIMER_Init()
Initialize the timer system. Called by USBH_Init(), but your application must call it again to reinitialize whenever you change the HFPERCLK frequency.

USBTIMER_Start()
Start a timer. You can configure the USB device stack to provide any number of timers. The timers have 1 ms resolution, your application is notified of timeout by means of a callback.

USBTIMER_Stop()
Stop a timer.


Configuring the host stack#

Your application must provide a header file named usbconfig.h. This file must contain the following #define's:

#define USB_HOST         // Compile the stack for host mode.
#define NUM_HC_USED n    // Your application use 'n' host channels in addition
                         // to channels 0 and 1 which are assigned by the
                         // host stack for device endpoint 0 communication.


usbconfig.h may define the following items: 

#define NUM_APP_TIMERS n // Your application needs 'n' timers

#define DEBUG_USB_API    // Turn on API debug diagnostics.

// Some utility functions in the API needs printf. These
// functions have "print" in their name. This macro enables
// these functions.
#define USB_USE_PRINTF   // Enable utility print functions.

// Define a function for transmitting a single char on the serial port.
extern int RETARGET_WriteChar(char c);
#define USER_PUTCHAR  RETARGET_WriteChar

#define USB_TIMER USB_TIMERn  // Select which hardware timer the USB stack
                              // is allowed to use. Valid values are n=0,1,2...
                              // corresponding to TIMER0, TIMER1, ...
                              // If not specified, TIMER0 is used


You are strongly encouraged to start application development with DEBUG_USB_API turned on. When DEBUG_USB_API is turned on and USER_PUTCHAR is defined, useful debugging information will be output on the development kit serial port. Compiling with the DEBUG_EFM_USER flag will also enable all asserts in both emlib and in the USB stack. If asserts are enabled and USER_PUTCHAR defined, assert texts will be output on the serial port.

You application must include retargetserial.c if DEBUG_USB_API is defined and retargetio.c if USB_USE_PRINTF is defined. These files reside in the drivers directory in the software package for your development board.


The host stack can be configured to monitor a GPIO input pin for detection of VBUS overcurrent or short circuit conditions. The stack will default to settings applicable to DK3750 for Classic Giant or SLSTK3701A for Giant 11. Override by using the following three #define's: 

#define USB_VBUSOVRCUR_PORT       gpioPortB       // The port
#define USB_VBUSOVRCUR_PIN        7               // The pin number within the port
#define USB_VBUSOVRCUR_POLARITY   USB_VBUSOVRCUR_POLARITY_LOW

Select any GPIO port for USB_VBUSOVRCUR_PORT or USB_VBUSOVRCUR_PORT_NONE if no overcurrent circuitry in the hw design. For USB_VBUSOVRCUR_POLARITY use USB_VBUSOVRCUR_POLARITY_LOW or USB_VBUSOVRCUR_POLARITY_HIGH.

Modules#

USBH_Ep_TypeDef

USBH_Device_TypeDef

USBH_Init_TypeDef

Enumerations#

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
}

USB HOST endpoint status enumerator.

Functions#

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.

void
USBH_PrintString(const char *pre, const USB_StringDescriptor_TypeDef *s, const char *post)

Print a USB string descriptor on the debug serial port.

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.

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.

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_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.

Macros#

#define
USB_VBUSOVRCUR_PORT_NONE -1

No overcurrent flag functionality.

#define
USB_VBUSOVRCUR_POLARITY_LOW 0

Overcurrent flag pin polarity is low.

#define
USB_VBUSOVRCUR_POLARITY_HIGH 1

Overcurrent flag pin polarity is high.

#define
USBH_INIT_DEFAULT undefined

Default USBH_Init_TypeDef values, provides reasonable Tx/Rx FIFO partitioning.

Enumeration Documentation#

USBH_EpState_TypeDef#

USBH_EpState_TypeDef

USB HOST endpoint status enumerator.

Enumerator
H_EP_IDLE

The endpoint is idle.

H_EP_SETUP

The endpoint is in SETUP stage.

H_EP_DATA_IN

The endpoint is in DATA IN stage.

H_EP_DATA_OUT

The endpoint is in DATA OUT stage.

H_EP_STATUS_IN

The endpoint is in STATUS IN stage.

H_EP_STATUS_OUT

The endpoint is in STATUS OUT stage.


Definition at line 831 of file platform/middleware/usb_gecko/inc/em_usb.h

Function Documentation#

USBH_AssignHostChannel#

int USBH_AssignHostChannel (USBH_Ep_TypeDef * ep, uint8_t hcnum)

Assign a host channel to a given endpoint.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

[in]hcnum

Host channel number (0..).

After assigning a host channel to an endpoint, all subsequent transfers to the endpoint will use the given host channel. Several endpoints can be assigned to the same host channel, but keep in mind that concurrent transfers can only be performed on endpoints assigned to different host channels.
The default endpoint (EP0) is assigned to host channels 0 and 1 by the host stack.

Returns


Definition at line 904 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_ControlMsg#

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.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

[in]bmRequestType

SETUP command request type. A suitable combination of values USB_SETUP_DIR_D2H, USB_SETUP_DIR_H2D, USB_SETUP_TYPE_STANDARD_MASK, USB_SETUP_TYPE_CLASS_MASK, USB_SETUP_TYPE_VENDOR_MASK, USB_SETUP_RECIPIENT_DEVICE, USB_SETUP_RECIPIENT_INTERFACE, USB_SETUP_RECIPIENT_ENDPOINT or USB_SETUP_RECIPIENT_OTHER.
Refer to the USB specification for details.

[in]bRequest

A specific SETUP command request.

[in]wValue

Word sized field that varies according to request.

[in]wIndex

Word sized field that varies according to request. Typically used to pass an index or offset.

[in]wLength

Number of bytes to transfer if there is a data stage.

[in]data

Pointer to transfer data buffer.

[in]timeout

Transfer timeout in milliseconds. The transfer will be terminated if not completed within timeout milliseconds. A value of 0 means infinite.

[in]callback

Function to be called on transfer completion. Supply NULL if no callback is needed. See USB_XferCompleteCb_TypeDef.

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.
    This function is non-blocking and returns immediately.

Returns


Definition at line 905 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_ControlMsgB#

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.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

[in]bmRequestType

SETUP command request type. A suitable combination of values USB_SETUP_DIR_D2H, USB_SETUP_DIR_H2D, USB_SETUP_TYPE_STANDARD_MASK, USB_SETUP_TYPE_CLASS_MASK, USB_SETUP_TYPE_VENDOR_MASK, USB_SETUP_RECIPIENT_DEVICE, USB_SETUP_RECIPIENT_INTERFACE, USB_SETUP_RECIPIENT_ENDPOINT or USB_SETUP_RECIPIENT_OTHER.
Refer to the USB specification for details.

[in]bRequest

A specific SETUP command request.

[in]wValue

Word sized field that varies according to request.

[in]wIndex

Word sized field that varies according to request. Typically used to pass an index or offset.

[in]wLength

Number of bytes to transfer if there is a data stage.

[in]data

Pointer to transfer data buffer.

[in]timeout

Transfer timeout in milliseconds. The transfer will be terminated if not completed within timeout milliseconds. A value of 0 means infinite.

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.
    This function is blocking and will not return before the transfer has completed, timed out or failed.

Returns

  • A positive (or zero) value indicates number of bytes transferred.
    A negative value indicates a transfer error code enumerated in USB_Status_TypeDef.


Definition at line 906 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_DeviceConnected#

bool USBH_DeviceConnected (void )

Check if a device is connected.

Parameters
N/A

Returns

  • True if device connected, false otherwise.


Definition at line 907 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_GetConfigurationDescriptorB#

int USBH_GetConfigurationDescriptorB (USBH_Device_TypeDef * device, void * buf, int len, uint8_t configIndex)

Read a configuration descriptor from a device.

Parameters
[in]device

Pointer to a USBH_Device_TypeDef data structure.

[in]buf

Pointer to transfer data buffer.

[in]len

The number of bytes to request, must not exceed transfer data buffer size.

[in]configIndex

Configuration index, a zero based number indicating which configuration to request.

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.
    This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.

Returns

  • A positive (or zero) value indicates number of bytes transferred.
    A negative value indicates a transfer error code enumerated in USB_Status_TypeDef.


Definition at line 908 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_GetDeviceDescriptorB#

int USBH_GetDeviceDescriptorB (USBH_Device_TypeDef * device, void * buf, int len)

Read a device descriptor from a device.

Parameters
[in]device

Pointer to a USBH_Device_TypeDef data structure.

[in]buf

Pointer to transfer data buffer.

[in]len

The number of bytes to request, must not exceed transfer data buffer size.

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.
    This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.

Returns

  • A positive (or zero) value indicates number of bytes transferred.
    A negative value indicates a transfer error code enumerated in USB_Status_TypeDef.


Definition at line 909 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_GetPortSpeed#

uint8_t USBH_GetPortSpeed (void )

Get the bus speed of the device attached to the USB port.

Parameters
N/A

Returns


Definition at line 910 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_GetStringB#

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.

Parameters
[in]device

Pointer to a USBH_Device_TypeDef data structure.

[in]buf

Pointer to transfer data buffer.

[in]bufLen

Transfer data buffer size.

[in]stringIndex

String index, a zero based number indicating which string to request.

[in]langID

String language ID.

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.
    This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.
    The maximum permitted USB string lenght is 255 bytes.

Returns

  • A positive (or zero) value indicates number of bytes transferred.
    A negative value indicates a transfer error code enumerated in USB_Status_TypeDef.


Definition at line 911 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_Init#

int USBH_Init (const USBH_Init_TypeDef * p)

Initialize host protocol stack data structures.

Parameters
[in]p

Pointer to initialization structure. See USBH_Init_TypeDef.

Host stack internal data structures are initialized, no actions will be performed on the USB port. Use this function once before starting USB host operation. USB operation is initated with USBH_WaitForDeviceConnectionB().

Returns


Definition at line 912 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_InitDeviceData#

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.

Parameters
[in]device

Pointer to a USBH_Device_TypeDef data structure.

[in]buf

A data buffer containing enumeration data retrieved with USBH_QueryDeviceB().

[in]ep

Pointer to an array of USBH_Ep_TypeDef endpoint data structures.

[in]numEp

Number of elements in endpoint array.

[in]deviceSpeed

PORT_FULL_SPEED or PORT_LOW_SPEED.

Use this function prior to moving a device out of default state. The application itself must allocate device and endpoint structures. Data from a prior call to USBH_QueryDeviceB() must be passed in input parameter buf. The device speed can be determined with USBH_GetPortSpeed() for devices directly attached to the USB port. Devices attached via a hub must retrieve this information by querying the hub.

Returns


Definition at line 913 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_PortReset#

int USBH_PortReset (void )

Drive reset signalling on the USB port.

Parameters
N/A

Note

  • This function is primarily meant for debugging a device. When returning the device will appear to be disconnected.

Returns


Definition at line 914 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_PortResume#

int USBH_PortResume (void )

Drive resume signalling on the USB port.

Parameters
N/A

Returns


Definition at line 915 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_PortSuspend#

void USBH_PortSuspend (void )

Set the USB port in suspend mode.

Parameters
N/A

Definition at line 916 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_PrintString#

void USBH_PrintString (const char * pre, const USB_StringDescriptor_TypeDef * s, const char * post)

Print a USB string descriptor on the debug serial port.

Parameters
[in]pre

Optional text string to prepend to the string descriptor. Pass NULL if not needed.

[in]s

Pointer to a USB_StringDescriptor_TypeDef data structure.

[in]post

Optional text string to append to the string descriptor. Pass NULL if not needed.

Note

  • This function is enabled when the #define USER_PUTCHAR macro is properly defined when configuring the protocol stack in "usbconfig.h". The function is primarily meant for debugging purposes.


Definition at line 917 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_PrintConfigurationDescriptor#

int USBH_PrintConfigurationDescriptor (const USB_ConfigurationDescriptor_TypeDef * config, int maxLen)

Pretty print a configuration descriptor on the debug serial port.

Parameters
[in]config

Pointer to a USB_ConfigurationDescriptor_TypeDef data structure.

[in]maxLen

The size of the data buffer passed as input parameter config.

Note

  • This function is enabled when #define USB_USE_PRINTF and #define USER_PUTCHAR macros are properly defined when configuring the protocol stack in "usbconfig.h". The function is primarily meant for debugging purposes.

Returns


Definition at line 920 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_PrintDeviceDescriptor#

int USBH_PrintDeviceDescriptor (const USB_DeviceDescriptor_TypeDef * device)

Pretty print a device descriptor on the debug serial port.

Parameters
[in]device

Pointer to a USB_DeviceDescriptor_TypeDef data structure.

Note

  • This function is enabled when #define USB_USE_PRINTF and #define USER_PUTCHAR macros are properly defined when configuring the protocol stack in "usbconfig.h". The function is primarily meant for debugging purposes.

Returns


Definition at line 921 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_PrintEndpointDescriptor#

int USBH_PrintEndpointDescriptor (const USB_EndpointDescriptor_TypeDef * endpoint)

Pretty print an endpoint descriptor on the debug serial port.

Parameters
[in]endpoint

Pointer to a USB_EndpointDescriptor_TypeDef data structure.

Note

  • This function is enabled when #define USB_USE_PRINTF and #define USER_PUTCHAR macros are properly defined when configuring the protocol stack in "usbconfig.h". The function is primarily meant for debugging purposes.

Returns


Definition at line 922 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_PrintInterfaceDescriptor#

int USBH_PrintInterfaceDescriptor (const USB_InterfaceDescriptor_TypeDef * interface)

Pretty print an interface descriptor on the debug serial port.

Parameters
[in]interface

Pointer to a USB_InterfaceDescriptor_TypeDef data structure.

Note

  • This function is enabled when #define USB_USE_PRINTF and #define USER_PUTCHAR macros are properly defined when configuring the protocol stack in "usbconfig.h". The function is primarily meant for debugging purposes.

Returns


Definition at line 923 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_QueryDeviceB#

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.

Parameters
[in]buf

A data buffer with sufficent space for the descriptors. The data buffer size must be sizeof( USBH_Device_TypeDef ) + the anticipated maximum size of the entire configuration descriptor.

[in]bufsize

The size of the data buffer.

[in]deviceSpeed

PORT_FULL_SPEED or PORT_LOW_SPEED.

The device speed can be determined with USBH_GetPortSpeed() for devices directly attached to the USB port. Devices attached via a hub must retrieve this information by querying the hub.

Note

  • This function is normally used to retrieve the data needed by USBH_InitDeviceData().
    This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.

Returns


Definition at line 931 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_QGetConfigurationDescriptor#

USB_ConfigurationDescriptor_TypeDef * USBH_QGetConfigurationDescriptor (const uint8_t * buf, int configIndex)

Return a pointer to a configuration descriptor.

Parameters
[in]buf

A data buffer containing enumeration data retrieved with USBH_QueryDeviceB().

[in]configIndex

Configuration index, a zero based number indicating which configuration descriptor to find.

Note

  • This function search through buf looking for a given configuration descriptor.

Returns


Definition at line 932 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_QGetDeviceDescriptor#

USB_DeviceDescriptor_TypeDef * USBH_QGetDeviceDescriptor (const uint8_t * buf)

Return a pointer to the device descriptor.

Parameters
[in]buf

A data buffer containing enumeration data retrieved with USBH_QueryDeviceB().

Returns


Definition at line 933 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_QGetEndpointDescriptor#

USB_EndpointDescriptor_TypeDef * USBH_QGetEndpointDescriptor (const uint8_t * buf, int configIndex, int interfaceIndex, int endpointIndex)

Return a pointer to an endpoint descriptor.

Parameters
[in]buf

A data buffer containing enumeration data retrieved with USBH_QueryDeviceB().

[in]configIndex

Configuration index, a zero based number indicating in which configuration descriptor to look for the interface containing the endpoint descriptor.

[in]interfaceIndex

Interface index, a zero based number indicating the interface descriptor to look for the correct endpoint descriptor in.

[in]endpointIndex

Endpoint index, a zero based number indicating which endpoint descriptor to look for.

Note

  • This function search through buf looking for a given endpoint descriptor.

Returns


Definition at line 934 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_QGetInterfaceDescriptor#

USB_InterfaceDescriptor_TypeDef * USBH_QGetInterfaceDescriptor (const uint8_t * buf, int configIndex, int interfaceIndex)

Return a pointer to an interface descriptor.

Parameters
[in]buf

A data buffer containing enumeration data retrieved with USBH_QueryDeviceB().

[in]configIndex

Configuration index, a zero based number indicating in which configuration descriptor to look for the interface descriptor.

[in]interfaceIndex

Interface index, a zero based number indicating which interface descriptor to find.

Note

  • This function search through buf looking for a given interface descriptor.

Returns


Definition at line 935 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_Read#

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.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

[in]data

Pointer to transfer data buffer.

[in]byteCount

Number of bytes to transfer (zero is a valid value).

[in]timeout

Transfer timeout in milliseconds. The transfer will be terminated if not completed within timeout milliseconds. A value of 0 means infinite.

[in]callback

Function to be called on transfer completion. Supply NULL if no callback is needed. See USB_XferCompleteCb_TypeDef.

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.
    This function is non-blocking and returns immediately.

Returns


Definition at line 937 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_ReadB#

int USBH_ReadB (USBH_Ep_TypeDef * ep, void * data, int byteCount, int timeout)

Read data from device endpoint, blocking version.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

[in]data

Pointer to transfer data buffer.

[in]byteCount

Number of bytes to transfer (zero is a valid value).

[in]timeout

Transfer timeout in milliseconds. The transfer will be terminated if not completed within timeout milliseconds. A value of 0 means infinite.

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.
    This function is blocking and will not return before the transfer has completed, timed out or failed.

Returns

  • A positive (or zero) value indicates number of bytes transferred.
    A negative value indicates a transfer error code enumerated in USB_Status_TypeDef.


Definition at line 938 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_SetAddressB#

int USBH_SetAddressB (USBH_Device_TypeDef * device, uint8_t deviceAddress)

Give a device an USB address.

Parameters
[in]device

Pointer to a USBH_Device_TypeDef data structure.

[in]deviceAddress

The new device address. Provide a value between 0 and 127.

Note

  • The device must currently have address 0. This command will move the device to the addressed state.
    This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.

Returns


Definition at line 939 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_SetAltInterfaceB#

int USBH_SetAltInterfaceB (USBH_Device_TypeDef * device, uint8_t interfaceIndex, uint8_t alternateSetting)

Activate a device interface within current device configuration.

Parameters
[in]device

Pointer to a USBH_Device_TypeDef data structure.

[in]interfaceIndex

The interface index. A zero based value.

[in]alternateSetting

The alternate interface setting value.

Note


  • This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.

Returns


Definition at line 940 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_SetConfigurationB#

int USBH_SetConfigurationB (USBH_Device_TypeDef * device, uint8_t configValue)

Activate a device configuration.

Parameters
[in]device

Pointer to a USBH_Device_TypeDef data structure.

[in]configValue

The configuration value. The value can be retrieved from device->confDesc.bConfigurationValue

Note

  • This command will move the device to the configured state.
    This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.

Returns


Definition at line 941 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_StallEpB#

int USBH_StallEpB (USBH_Ep_TypeDef * ep)

Set an endpoint in the stalled (halted) state.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

Note

  • This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.

Returns


Definition at line 942 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_Stop#

void USBH_Stop (void )

Stop USB host operation.

Parameters
N/A

USB host operation is terminated and VBUS on the port is turned off.


Definition at line 943 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_UnStallEpB#

int USBH_UnStallEpB (USBH_Ep_TypeDef * ep)

Reset stall state on a stalled (halted) endpoint.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

Note

  • This function is blocking and will not return before the transfer has completed, timed out (1 second) or failed.

Returns


Definition at line 944 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_WaitForDeviceConnectionB#

int USBH_WaitForDeviceConnectionB (uint8_t * buf, int timeoutInSeconds)

Wait for device connection.

Parameters
[in]buf

A data buffer with sufficent space for retrieving the first 8 bytes of a device descriptor. The data buffer size must be sizeof( USBH_Device_TypeDef ) + 8.

[in]timeoutInSeconds

Timeout in seconds. A value of 0 means infinite.

This function will wait for device connection and try to read the 8 first bytes of the device descriptor.
First the USB peripheral is initializet (reset) and VBUS is turned on. When a device is connected, an USB reset will be signalled on the USB port, and then a USB GetDescriptor command is performed.
This procedure is repeated until success or timeout. On each iteration the duration of USB reset signalling is varied.

Returns


Definition at line 945 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_Write#

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.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

[in]data

Pointer to transfer data buffer.

[in]byteCount

Number of bytes to transfer (zero is a valid value).

[in]timeout

Transfer timeout in milliseconds. The transfer will be terminated if not completed within timeout milliseconds. A value of 0 means infinite.

[in]callback

Function to be called on transfer completion. Supply NULL if no callback is needed. See USB_XferCompleteCb_TypeDef.

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.
    This function is non-blocking and returns immediately.

Returns


Definition at line 946 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_WriteB#

int USBH_WriteB (USBH_Ep_TypeDef * ep, void * data, int byteCount, int timeout)

Write data to device endpoint, blocking version.

Parameters
[in]ep

Pointer to a USBH_Ep_TypeDef data structure.

[in]data

Pointer to transfer data buffer.

[in]byteCount

Number of bytes to transfer (zero is a valid value).

[in]timeout

Transfer timeout in milliseconds. The transfer will be terminated if not completed within timeout milliseconds. A value of 0 means infinite.

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.
    This function is blocking and will not return before the transfer has completed, timed out or failed.

Returns

  • A positive (or zero) value indicates number of bytes transferred.
    A negative value indicates a transfer error code enumerated in USB_Status_TypeDef.


Definition at line 947 of file platform/middleware/usb_gecko/inc/em_usb.h

Macro Definition Documentation#

USB_VBUSOVRCUR_PORT_NONE#

#define USB_VBUSOVRCUR_PORT_NONE
Value:
-1

No overcurrent flag functionality.



Definition at line 826 of file platform/middleware/usb_gecko/inc/em_usb.h

USB_VBUSOVRCUR_POLARITY_LOW#

#define USB_VBUSOVRCUR_POLARITY_LOW
Value:
0

Overcurrent flag pin polarity is low.



Definition at line 827 of file platform/middleware/usb_gecko/inc/em_usb.h

USB_VBUSOVRCUR_POLARITY_HIGH#

#define USB_VBUSOVRCUR_POLARITY_HIGH
Value:
1

Overcurrent flag pin polarity is high.



Definition at line 828 of file platform/middleware/usb_gecko/inc/em_usb.h

USBH_INIT_DEFAULT#

#define USBH_INIT_DEFAULT
Value:
{ \
(MAX_HOST_FIFO_SIZE_INWORDS * 2), /* 1024 bytes Rx FIFO size. */ \
MAX_HOST_FIFO_SIZE_INWORDS, /* 512 bytes non-periodic Tx FIFO size. */ \
MAX_HOST_FIFO_SIZE_INWORDS, /* 512 bytes periodic Tx FIFO size. */ \
0 /* Reserved. */ \
}

Default USBH_Init_TypeDef values, provides reasonable Tx/Rx FIFO partitioning.



Definition at line 894 of file platform/middleware/usb_gecko/inc/em_usb.h