USB_HOST
Platform Middleware > USB

Detailed Description

Gecko USB HOST protocol stack, see USB host stack library page for detailed documentation.

Data Structures

struct USBH_Device_TypeDef
USB HOST device definition.
struct USBH_Ep_TypeDef
USB HOST endpoint status data.
struct USBH_Init_TypeDef
USB Host stack initialization structure.

Macros

#define USB_VBUSOVRCUR_POLARITY_HIGH 1
#define USB_VBUSOVRCUR_POLARITY_LOW 0
#define USB_VBUSOVRCUR_PORT_NONE -1
#define USBH_INIT_DEFAULT

Typedefs

typedef struct USBH_Device_TypeDef USBH_Device_TypeDef
USB HOST device definition.

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
}

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.
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.
void USBH_PrintString (const char *pre, const USB_StringDescriptor_TypeDef *s, const char *post)
Print a USB string descriptor on the debug serial port.
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_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.
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.

Macro Definition Documentation

#define USB_VBUSOVRCUR_POLARITY_HIGH   1

Overcurrent flag pin polarity is high.

Definition at line 827 of file em_usb.h .

#define USB_VBUSOVRCUR_POLARITY_LOW   0

Overcurrent flag pin polarity is low.

Definition at line 826 of file em_usb.h .

#define USB_VBUSOVRCUR_PORT_NONE   -1

No overcurrent flag functionality.

Definition at line 825 of file em_usb.h .

#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 893 of file em_usb.h .

Typedef Documentation

typedef struct USBH_Device_TypeDef USBH_Device_TypeDef

USB HOST device definition.

A host application should not manipulate the contents of this struct.

Enumeration Type Documentation

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.

Definition at line 830 of file em_usb.h .

Function Documentation

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 .

Definition at line 199 of file em_usbh.c .

References USBH_Ep_TypeDef::addr , USB_EndpointDescriptor_TypeDef::bEndpointAddress , USB_EndpointDescriptor_TypeDef::bmAttributes , CONFIG_DESC_BM_TRANSFERTYPE , USBH_Ep_TypeDef::epDesc , H_EP_IDLE , USBH_Ep_TypeDef::hcIn , USBH_Ep_TypeDef::hcOut , USBH_Ep_TypeDef::in , USBH_Ep_TypeDef::packetSize , USBH_Ep_TypeDef::state , USBH_Ep_TypeDef::type , USB_SETUP_DIR_MASK , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USB_EndpointDescriptor_TypeDef::wMaxPacketSize .

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 .

Definition at line 281 of file em_usbh.c .

References USB_Setup_TypeDef::bmRequestType , USB_Setup_TypeDef::bRequest , USBH_Ep_TypeDef::buf , CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , CORE_EXIT_ATOMIC , H_EP_IDLE , H_EP_SETUP , USBH_Ep_TypeDef::hcIn , USBH_Ep_TypeDef::hcOut , USBH_Ep_TypeDef::setup , USBH_Ep_TypeDef::setupErrCnt , USBH_Ep_TypeDef::state , USBH_Ep_TypeDef::timeout , USB_STATUS_EP_BUSY , USB_STATUS_HC_BUSY , USB_STATUS_ILLEGAL , USB_STATUS_OK , USBH_DeviceConnected() , USBTIMER_Start() , USB_Setup_TypeDef::wIndex , USB_Setup_TypeDef::wLength , USB_Setup_TypeDef::wValue , USBH_Ep_TypeDef::xferCompleteCb , USBH_Ep_TypeDef::xferCompleted , and USBH_Ep_TypeDef::xferred .

Referenced by 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 .

Definition at line 396 of file em_usbh.c .

References CORE_IN_IRQ_CONTEXT , CORE_IRQ_DISABLED , USB_STATUS_ILLEGAL , USB_STATUS_OK , USBH_ControlMsg() , USBH_Ep_TypeDef::xferCompleted , USBH_Ep_TypeDef::xferred , and USBH_Ep_TypeDef::xferStatus .

Referenced by USBH_GetConfigurationDescriptorB() , USBH_GetDeviceDescriptorB() , USBH_GetStringB() , USBH_SetAddressB() , USBH_SetAltInterfaceB() , USBH_SetConfigurationB() , USBH_StallEpB() , and USBH_UnStallEpB() .

bool USBH_DeviceConnected ( void )

Check if a device is connected.

Returns
True if device connected, false otherwise.

Definition at line 634 of file em_usbh.c .

Referenced by USBH_ControlMsg() , USBH_Read() , USBH_WaitForDeviceConnectionB() , and USBH_Write() .

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 .

Definition at line 669 of file em_usbh.c .

References USBH_Device_TypeDef::ep0 , GET_DESCRIPTOR , USB_CONFIG_DESCRIPTOR , USB_SETUP_DIR_D2H , USB_SETUP_RECIPIENT_DEVICE , USB_SETUP_TYPE_STANDARD_MASK , USB_STATUS_ILLEGAL , and USBH_ControlMsgB() .

Referenced by USBH_QueryDeviceB() .

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 .

Definition at line 724 of file em_usbh.c .

References USBH_Device_TypeDef::ep0 , GET_DESCRIPTOR , USB_DEVICE_DESCRIPTOR , USB_SETUP_DIR_D2H , USB_SETUP_RECIPIENT_DEVICE , USB_SETUP_TYPE_STANDARD_MASK , USB_STATUS_ILLEGAL , and USBH_ControlMsgB() .

Referenced by USBH_QueryDeviceB() , and USBH_WaitForDeviceConnectionB() .

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 .

Definition at line 759 of file em_usbh.c .

Referenced by MSDH_Init() , and USBH_WaitForDeviceConnectionB() .

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 .

Definition at line 797 of file em_usbh.c .

References USBH_Device_TypeDef::ep0 , GET_DESCRIPTOR , USB_StringDescriptor_TypeDef::len , USB_StringDescriptor_TypeDef::name , SL_MIN , USB_SETUP_DIR_D2H , USB_SETUP_RECIPIENT_DEVICE , USB_SETUP_TYPE_STANDARD_MASK , USB_STATUS_ILLEGAL , USB_STRING_DESCRIPTOR , and USBH_ControlMsgB() .

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 .

Definition at line 852 of file em_usbh.c .

References CMU_ClockSelectSet() , CMU_OscillatorEnable() , cmuClock_HF , cmuOsc_HFXO , cmuOsc_LFXO , cmuSelect_HFRCO , cmuSelect_HFXO , CORE_ATOMIC_SECTION , USBH_Init_TypeDef::nptxFifoSize , USBH_Init_TypeDef::ptxFifoSize , USBH_Init_TypeDef::rxFifoSize , SystemHFXOClockGet() , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USBTIMER_Init() .

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 .

Definition at line 965 of file em_usbh.c .

References USBH_Device_TypeDef::addr , USBH_Device_TypeDef::confDesc , USBH_Device_TypeDef::devDesc , USBH_Device_TypeDef::ep , USBH_Device_TypeDef::ep0 , USBH_Ep_TypeDef::epDesc , USBH_Ep_TypeDef::hcIn , USBH_Ep_TypeDef::hcOut , USBH_Device_TypeDef::itfDesc , USBH_Device_TypeDef::numEp , USBH_Ep_TypeDef::packetSize , USBH_Ep_TypeDef::parentDevice , USBH_Device_TypeDef::speed , USBH_Ep_TypeDef::toggle , USBH_Ep_TypeDef::type , USB_CONFIG_DESCSIZE , USB_DEVICE_DESCSIZE , USB_ENDPOINT_DESCSIZE , USB_EPTYPE_CTRL , USB_INTERFACE_DESCSIZE , USB_STATUS_ILLEGAL , USB_STATUS_OK , USBH_QGetEndpointDescriptor() , and USBH_QGetInterfaceDescriptor() .

Referenced by USBH_QueryDeviceB() , and USBH_WaitForDeviceConnectionB() .

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 .

Definition at line 1036 of file em_usbh.c .

References CORE_ATOMIC_SECTION , CORE_IN_IRQ_CONTEXT , CORE_IRQ_DISABLED , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USBTIMER_DelayMs() .

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 .

Definition at line 1068 of file em_usbh.c .

References CORE_ATOMIC_SECTION , CORE_IN_IRQ_CONTEXT , CORE_IRQ_DISABLED , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USBTIMER_DelayMs() .

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 .

Definition at line 1145 of file em_usbh.c .

References USB_ConfigurationDescriptor_TypeDef::bConfigurationValue , USB_ConfigurationDescriptor_TypeDef::bDescriptorType , USB_ConfigurationDescriptor_TypeDef::bLength , USB_ConfigurationDescriptor_TypeDef::bmAttributes , USB_ConfigurationDescriptor_TypeDef::bMaxPower , USB_ConfigurationDescriptor_TypeDef::bNumInterfaces , USB_ConfigurationDescriptor_TypeDef::iConfiguration , SL_MIN , USB_PRINTF() , USB_PUTCHAR() , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USB_ConfigurationDescriptor_TypeDef::wTotalLength .

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 .

Definition at line 1202 of file em_usbh.c .

References USB_DeviceDescriptor_TypeDef::bcdDevice , USB_DeviceDescriptor_TypeDef::bcdUSB , USB_DeviceDescriptor_TypeDef::bDescriptorType , USB_DeviceDescriptor_TypeDef::bDeviceClass , USB_DeviceDescriptor_TypeDef::bDeviceProtocol , USB_DeviceDescriptor_TypeDef::bDeviceSubClass , USB_DeviceDescriptor_TypeDef::bLength , USB_DeviceDescriptor_TypeDef::bMaxPacketSize0 , USB_DeviceDescriptor_TypeDef::bNumConfigurations , USB_DeviceDescriptor_TypeDef::idProduct , USB_DeviceDescriptor_TypeDef::idVendor , USB_DeviceDescriptor_TypeDef::iManufacturer , USB_DeviceDescriptor_TypeDef::iProduct , USB_DeviceDescriptor_TypeDef::iSerialNumber , USB_PRINTF() , USB_STATUS_ILLEGAL , and USB_STATUS_OK .

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 .

Definition at line 1247 of file em_usbh.c .

References USB_EndpointDescriptor_TypeDef::bDescriptorType , USB_EndpointDescriptor_TypeDef::bEndpointAddress , USB_EndpointDescriptor_TypeDef::bInterval , USB_EndpointDescriptor_TypeDef::bLength , USB_EndpointDescriptor_TypeDef::bmAttributes , USB_PRINTF() , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USB_EndpointDescriptor_TypeDef::wMaxPacketSize .

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 .

Definition at line 1285 of file em_usbh.c .

References USB_InterfaceDescriptor_TypeDef::bAlternateSetting , USB_InterfaceDescriptor_TypeDef::bDescriptorType , USB_InterfaceDescriptor_TypeDef::bInterfaceClass , USB_InterfaceDescriptor_TypeDef::bInterfaceNumber , USB_InterfaceDescriptor_TypeDef::bInterfaceProtocol , USB_InterfaceDescriptor_TypeDef::bInterfaceSubClass , USB_InterfaceDescriptor_TypeDef::bLength , USB_InterfaceDescriptor_TypeDef::bNumEndpoints , USB_InterfaceDescriptor_TypeDef::iInterface , USB_PRINTF() , USB_STATUS_ILLEGAL , and USB_STATUS_OK .

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.

Definition at line 1333 of file em_usbh.c .

References USB_StringDescriptor_TypeDef::name , USB_PUTCHAR() , and USB_PUTS() .

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.

Definition at line 1392 of file em_usbh.c .

References SL_MIN , USB_CONFIG_DESCRIPTOR , USB_CONFIG_DESCSIZE , and USBH_QGetDeviceDescriptor() .

Referenced by USBH_QGetInterfaceDescriptor() .

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.

Definition at line 1444 of file em_usbh.c .

References USB_DeviceDescriptor_TypeDef::bDescriptorType , USB_DeviceDescriptor_TypeDef::bLength , USB_DEVICE_DESCRIPTOR , and USB_DEVICE_DESCSIZE .

Referenced by USBH_QGetConfigurationDescriptor() .

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.

Definition at line 1489 of file em_usbh.c .

References USB_ENDPOINT_DESCRIPTOR , USB_ENDPOINT_DESCSIZE , USB_INTERFACE_DESCSIZE , and USBH_QGetInterfaceDescriptor() .

Referenced by USBH_InitDeviceData() .

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.

Definition at line 1556 of file em_usbh.c .

References USB_CONFIG_DESCSIZE , USB_INTERFACE_DESCRIPTOR , USB_INTERFACE_DESCSIZE , and USBH_QGetConfigurationDescriptor() .

Referenced by USBH_InitDeviceData() , and USBH_QGetEndpointDescriptor() .

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 .

Definition at line 1631 of file em_usbh.c .

References USB_DeviceDescriptor_TypeDef::bMaxPacketSize0 , USBH_Device_TypeDef::confDesc , USBH_Device_TypeDef::devDesc , USBH_Device_TypeDef::ep , USBH_Device_TypeDef::ep0 , USBH_Ep_TypeDef::packetSize , SL_MIN , USBH_Device_TypeDef::speed , USB_CONFIG_DESCSIZE , USB_DEVICE_DESCSIZE , USB_INTERFACE_DESCSIZE , USB_STATUS_OK , USB_STATUS_REQ_ERR , USBH_GetConfigurationDescriptorB() , USBH_GetDeviceDescriptorB() , USBH_InitDeviceData() , and USB_ConfigurationDescriptor_TypeDef::wTotalLength .

Referenced by MSDH_Init() .

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 .

Definition at line 1717 of file em_usbh.c .

References USB_EndpointDescriptor_TypeDef::bInterval , USBH_Ep_TypeDef::buf , CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , CORE_EXIT_ATOMIC , USBH_Ep_TypeDef::epDesc , H_EP_DATA_IN , H_EP_IDLE , USBH_Ep_TypeDef::hcIn , USBH_Ep_TypeDef::in , USBH_Ep_TypeDef::packetSize , USBH_Ep_TypeDef::remaining , SL_MIN , USBH_Ep_TypeDef::state , USBH_Ep_TypeDef::timeout , USBH_Ep_TypeDef::type , USB_EPTYPE_INTR , USB_STATUS_EP_BUSY , USB_STATUS_HC_BUSY , USB_STATUS_ILLEGAL , USB_STATUS_OK , USBH_DeviceConnected() , USBTIMER_Start() , USBH_Ep_TypeDef::xferCompleteCb , USBH_Ep_TypeDef::xferCompleted , and USBH_Ep_TypeDef::xferred .

Referenced by 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 .

Definition at line 1830 of file em_usbh.c .

References CORE_IN_IRQ_CONTEXT , CORE_IRQ_DISABLED , USB_STATUS_ILLEGAL , USB_STATUS_OK , USBH_Read() , USBH_Ep_TypeDef::xferCompleted , USBH_Ep_TypeDef::xferred , and USBH_Ep_TypeDef::xferStatus .

Referenced by MSDBOT_Xfer() .

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 .

Definition at line 1873 of file em_usbh.c .

References USBH_Device_TypeDef::addr , USBH_Device_TypeDef::ep0 , SET_ADDRESS , USB_MAX_DEVICE_ADDRESS , USB_SETUP_DIR_H2D , USB_SETUP_RECIPIENT_DEVICE , USB_SETUP_TYPE_STANDARD_MASK , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USBH_ControlMsgB() .

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 .

Definition at line 1927 of file em_usbh.c .

References USBH_Device_TypeDef::ep , USBH_Device_TypeDef::ep0 , USBH_Device_TypeDef::numEp , SET_INTERFACE , USBH_Ep_TypeDef::toggle , USB_SETUP_DIR_H2D , USB_SETUP_RECIPIENT_INTERFACE , USB_SETUP_TYPE_STANDARD_MASK , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USBH_ControlMsgB() .

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 .

Definition at line 1984 of file em_usbh.c .

References USBH_Device_TypeDef::ep , USBH_Device_TypeDef::ep0 , USBH_Device_TypeDef::numEp , SET_CONFIGURATION , USBH_Ep_TypeDef::toggle , USB_SETUP_DIR_H2D , USB_SETUP_RECIPIENT_DEVICE , USB_SETUP_TYPE_STANDARD_MASK , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USBH_ControlMsgB() .

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 .

Definition at line 2035 of file em_usbh.c .

References USBH_Ep_TypeDef::addr , USBH_Device_TypeDef::ep0 , USBH_Ep_TypeDef::parentDevice , SET_FEATURE , USB_FEATURE_ENDPOINT_HALT , USB_SETUP_DIR_H2D , USB_SETUP_RECIPIENT_ENDPOINT , USB_SETUP_TYPE_STANDARD_MASK , USB_STATUS_ILLEGAL , and USBH_ControlMsgB() .

void USBH_Stop ( void )

Stop USB host operation.

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

Definition at line 2061 of file em_usbh.c .

References CORE_ATOMIC_SECTION , and USBTIMER_Stop() .

Referenced by USBH_WaitForDeviceConnectionB() .

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 .

Definition at line 2098 of file em_usbh.c .

References USBH_Ep_TypeDef::addr , CLEAR_FEATURE , USBH_Device_TypeDef::ep0 , USBH_Ep_TypeDef::parentDevice , USBH_Ep_TypeDef::toggle , USB_FEATURE_ENDPOINT_HALT , USB_SETUP_DIR_H2D , USB_SETUP_RECIPIENT_ENDPOINT , USB_SETUP_TYPE_STANDARD_MASK , USB_STATUS_ILLEGAL , USB_STATUS_OK , and USBH_ControlMsgB() .

Referenced by MSDBOT_Xfer() .

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.

Definition at line 2172 of file em_usbh.c .

References CORE_ATOMIC_SECTION , USBH_Device_TypeDef::devDesc , GPIO_PinInGet() , USB_STATUS_DEVICE_MALFUNCTION , USB_STATUS_ILLEGAL , USB_STATUS_OK , USB_STATUS_PORT_OVERCURRENT , USB_STATUS_TIMEOUT , USBH_DeviceConnected() , USBH_GetDeviceDescriptorB() , USBH_GetPortSpeed() , USBH_InitDeviceData() , USBH_Stop() , USBTIMER_DelayMs() , and USBTIMER_Stop() .

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 .

Definition at line 2330 of file em_usbh.c .

References USB_EndpointDescriptor_TypeDef::bInterval , USBH_Ep_TypeDef::buf , CORE_DECLARE_IRQ_STATE , CORE_ENTER_ATOMIC , CORE_EXIT_ATOMIC , USBH_Ep_TypeDef::epDesc , H_EP_DATA_OUT , H_EP_IDLE , USBH_Ep_TypeDef::hcOut , USBH_Ep_TypeDef::in , USBH_Ep_TypeDef::packetSize , USBH_Ep_TypeDef::remaining , SL_MIN , USBH_Ep_TypeDef::state , USBH_Ep_TypeDef::timeout , USBH_Ep_TypeDef::type , USB_EPTYPE_INTR , USB_STATUS_EP_BUSY , USB_STATUS_HC_BUSY , USB_STATUS_ILLEGAL , USB_STATUS_OK , USBH_DeviceConnected() , USBTIMER_Start() , USBH_Ep_TypeDef::xferCompleteCb , USBH_Ep_TypeDef::xferCompleted , and USBH_Ep_TypeDef::xferred .

Referenced by 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 .

Definition at line 2441 of file em_usbh.c .

References CORE_IN_IRQ_CONTEXT , CORE_IRQ_DISABLED , USB_STATUS_ILLEGAL , USB_STATUS_OK , USBH_Write() , USBH_Ep_TypeDef::xferCompleted , USBH_Ep_TypeDef::xferred , and USBH_Ep_TypeDef::xferStatus .

Referenced by MSDBOT_Xfer() .