USB Host
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_usbh nnn .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
- Top level control functions
- USB transfer functions
- USB Chapter 9 support functions
- Host port control functions
- Enumeration and query functions
- Utility functions
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_Q
xxx
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 |
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.