Description

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.

Data Structures
struct	USBH_Ep_TypeDef
	USB HOST endpoint status data.

struct	USBH_Device_TypeDef
	USB HOST device definition.

struct	USBH_Init_TypeDef
	USB Host stack initialization structure.

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
	Default USBH_Init_TypeDef values, provides reasonable Tx/Rx FIFO partitioning.

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.

Function Documentation

◆ USBH_AssignHostChannel()

int USBH_AssignHostChannel	(	USBH_Ep_TypeDef *	`ep,`
		uint8_t	`hcnum`
	)

Assign a host channel to a given endpoint.

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.

Parameters

[in]	`ep`	Pointer to a USBH_Ep_TypeDef data structure.
[in]	`hcnum`	Host channel number (0..).

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

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

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.

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.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

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

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.

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.

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

◆ USBH_DeviceConnected()

bool USBH_DeviceConnected ( void )

Check if a device is connected.

Returns: True if device connected, false otherwise.

◆ USBH_GetConfigurationDescriptorB()

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

Read a configuration descriptor from a device.

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.

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.

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

◆ USBH_GetDeviceDescriptorB()

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

Read a device descriptor from a device.

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.

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.

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

◆ USBH_GetPortSpeed()

uint8_t USBH_GetPortSpeed ( void )

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

Returns: PORT_FULL_SPEED or PORT_LOW_SPEED.

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

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.

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.

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

◆ USBH_Init()

int USBH_Init ( const USBH_Init_TypeDef * p )

Initialize host protocol stack data structures.

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().

Parameters

[in] p Pointer to initialization structure. See USBH_Init_TypeDef.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

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

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.

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.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_PortReset()

int USBH_PortReset ( void )

Drive reset signalling on the USB port.

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

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_PortResume()

int USBH_PortResume ( void )

Drive resume signalling on the USB port.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_PortSuspend()

void USBH_PortSuspend ( void )

Set the USB port in suspend mode.

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

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.

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.

◆ USBH_PrintConfigurationDescriptor()

int USBH_PrintConfigurationDescriptor	(	const USB_ConfigurationDescriptor_TypeDef *	`config,`
		int	`maxLen`
	)

Pretty print a configuration descriptor on the debug serial port.

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.

Parameters

[in]	`config`	Pointer to a USB_ConfigurationDescriptor_TypeDef data structure.
[in]	`maxLen`	The size of the data buffer passed as input parameter config.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_PrintDeviceDescriptor()

int USBH_PrintDeviceDescriptor ( const USB_DeviceDescriptor_TypeDef * device )

Pretty print a device descriptor on the debug serial port.

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.

Parameters

[in] device Pointer to a USB_DeviceDescriptor_TypeDef data structure.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_PrintEndpointDescriptor()

int USBH_PrintEndpointDescriptor ( const USB_EndpointDescriptor_TypeDef * endpoint )

Pretty print an endpoint descriptor on the debug serial port.

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.

Parameters

[in] endpoint Pointer to a USB_EndpointDescriptor_TypeDef data structure.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_PrintInterfaceDescriptor()

int USBH_PrintInterfaceDescriptor ( const USB_InterfaceDescriptor_TypeDef * interface )

Pretty print an interface descriptor on the debug serial port.

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.

Parameters

[in] interface Pointer to a USB_InterfaceDescriptor_TypeDef data structure.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

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

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.

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.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_QGetConfigurationDescriptor()

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

Return a pointer to a configuration descriptor.

Note: This function search through buf looking for a given 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.

Returns: A pointer to USB_ConfigurationDescriptor_TypeDef. NULL if no descriptor found.

◆ 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: A pointer to USB_DeviceDescriptor_TypeDef. NULL if no descriptor found.

◆ USBH_QGetEndpointDescriptor()

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

Return a pointer to an endpoint descriptor.

Note: This function search through buf looking for a given 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.

Returns: A pointer to USB_EndpointDescriptor_TypeDef. NULL if no descriptor found.

◆ USBH_QGetInterfaceDescriptor()

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

Return a pointer to an interface descriptor.

Note: This function search through buf looking for a given 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.

Returns: A pointer to USB_InterfaceDescriptor_TypeDef. NULL if no descriptor found.

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

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.

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.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_ReadB()

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

Read data from device endpoint, blocking version.

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.

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.

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

◆ USBH_SetAddressB()

int USBH_SetAddressB	(	USBH_Device_TypeDef *	`device,`
		uint8_t	`deviceAddress`
	)

Give a device an USB address.

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.

Parameters

[in]	`device`	Pointer to a USBH_Device_TypeDef data structure.
[in]	`deviceAddress`	The new device address. Provide a value between 0 and 127.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_SetAltInterfaceB()

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

Activate a device interface within current device configuration.

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

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.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_SetConfigurationB()

int USBH_SetConfigurationB	(	USBH_Device_TypeDef *	`device,`
		uint8_t	`configValue`
	)

Activate a device configuration.

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.

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

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_StallEpB()

int USBH_StallEpB ( USBH_Ep_TypeDef * ep )

Set an endpoint in the stalled (halted) state.

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

Parameters

[in] ep Pointer to a USBH_Ep_TypeDef data structure.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_Stop()

void USBH_Stop ( void )

Stop USB host operation.

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

◆ USBH_UnStallEpB()

int USBH_UnStallEpB ( USBH_Ep_TypeDef * ep )

Reset stall state on a stalled (halted) endpoint.

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

Parameters

[in] ep Pointer to a USBH_Ep_TypeDef data structure.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_WaitForDeviceConnectionB()

int USBH_WaitForDeviceConnectionB	(	uint8_t *	`buf,`
		int	`timeoutInSeconds`
	)

Wait for device connection.

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.

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.

Returns: Returns USB_STATUS_OK on success, USB_STATUS_TIMEOUT on timeout, USB_STATUS_DEVICE_MALFUNCTION if a device was attached but USB communications could not be succesfully established with the device, or USB_STATUS_PORT_OVERCURRENT if a VBUS overcurrent condition exist.

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

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.

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.

Returns: USB_STATUS_OK on success, else an appropriate error code enumerated in USB_Status_TypeDef.

◆ USBH_WriteB()

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

Write data to device endpoint, blocking version.

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.

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.

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

Macro Definition Documentation

◆ USB_VBUSOVRCUR_PORT_NONE

#define USB_VBUSOVRCUR_PORT_NONE -1

No overcurrent flag functionality.

◆ USB_VBUSOVRCUR_POLARITY_LOW

#define USB_VBUSOVRCUR_POLARITY_LOW 0

Overcurrent flag pin polarity is low.

◆ USB_VBUSOVRCUR_POLARITY_HIGH

#define USB_VBUSOVRCUR_POLARITY_HIGH 1

Overcurrent flag pin polarity is high.

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

Enumeration Type Documentation

◆ USBH_EpState_TypeDef

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

USB HostUSB Stacks

Description

Introduction

Getting started

Device connection

Device enumeration and configuration

The host stack API

Introduction

Top level control functions

USB transfer functions

USB Chapter 9 support functions

Host port control functions

Enumeration and query functions

Utility functions

Configuring the host stack

Data Structures

Functions

Macros

Enumerations

Function Documentation

◆ USBH_AssignHostChannel()

◆ USBH_ControlMsg()

◆ USBH_ControlMsgB()

◆ USBH_DeviceConnected()

◆ USBH_GetConfigurationDescriptorB()

◆ USBH_GetDeviceDescriptorB()

◆ USBH_GetPortSpeed()

◆ USBH_GetStringB()

◆ USBH_Init()

◆ USBH_InitDeviceData()

◆ USBH_PortReset()

◆ USBH_PortResume()

◆ USBH_PortSuspend()

◆ USBH_PrintString()

◆ USBH_PrintConfigurationDescriptor()

◆ USBH_PrintDeviceDescriptor()

◆ USBH_PrintEndpointDescriptor()

◆ USBH_PrintInterfaceDescriptor()

◆ USBH_QueryDeviceB()

◆ USBH_QGetConfigurationDescriptor()

◆ USBH_QGetDeviceDescriptor()

◆ USBH_QGetEndpointDescriptor()

◆ USBH_QGetInterfaceDescriptor()

◆ USBH_Read()

◆ USBH_ReadB()

◆ USBH_SetAddressB()

◆ USBH_SetAltInterfaceB()

◆ USBH_SetConfigurationB()

◆ USBH_StallEpB()

◆ USBH_Stop()

◆ USBH_UnStallEpB()

◆ USBH_WaitForDeviceConnectionB()

◆ USBH_Write()

◆ USBH_WriteB()

Macro Definition Documentation

◆ USB_VBUSOVRCUR_PORT_NONE

◆ USB_VBUSOVRCUR_POLARITY_LOW

◆ USB_VBUSOVRCUR_POLARITY_HIGH

◆ USBH_INIT_DEFAULT

Enumeration Type Documentation

◆ USBH_EpState_TypeDef

USB Host
USB Stacks