USBLibAPIGuide  1.00.00.01
Data Structures | Macros | Typedefs | Functions | Variables
Device_api

Data Structures

struct  tDeviceInfo
 
struct  tCompositeEntry
 
struct  tCustomHandlers
 
struct  tConfigSection
 
struct  tConfigHeader
 

Macros

#define EP_INFO_IN   0
 
#define EP_INFO_OUT   1
 
#define HALT_EP_IN   0
 
#define HALT_EP_OUT   1
 
#define EP0_MAX_PACKET_SIZE   64
 
#define DEV_ADDR_PENDING   0x80000000
 
#define DEFAULT_CONFIG_ID   1
 
#define REMOTE_WAKEUP_PULSE_MS   10
 
#define REMOTE_WAKEUP_READY_MS   20
 
#define USBLIB_LPM_STATE_DISABLED   0x00000000
 
#define USBLIB_LPM_STATE_AWAKE   0x00000001
 
#define USBLIB_LPM_STATE_SLEEP   0x00000002
 
#define USB_MAX_INTERFACES_PER_DEVICE   8
 

Typedefs

typedef void(* tStdRequest) (void *pvInstance, tUSBRequest *pUSBRequest)
 
typedef void(* tInfoCallback) (void *pvInstance, uint32_t ui32Info)
 
typedef void(* tInterfaceCallback) (void *pvInstance, uint8_t ui8InterfaceNum, uint8_t ui8AlternateSetting)
 
typedef void(* tUSBIntHandler) (void *pvInstance)
 
typedef void(* tUSBEPIntHandler) (void *pvInstance, uint32_t ui32Status)
 
typedef void(* tUSBDeviceHandler) (void *pvInstance, uint32_t ui32Request, void *pvRequestData)
 

Functions

uint32_t USBDCDConfigDescGetSize (const tConfigHeader *psConfig)
 
uint32_t USBDCDConfigDescGetNum (const tConfigHeader *psConfig, uint32_t ui32Type)
 
tDescriptorHeader * USBDCDConfigDescGet (const tConfigHeader *psConfig, uint32_t ui32Type, uint32_t ui32Index, uint32_t *pui32Section)
 
uint32_t USBDCDConfigGetNumAlternateInterfaces (const tConfigHeader *psConfig, uint8_t ui8InterfaceNumber)
 
tInterfaceDescriptor * USBDCDConfigGetInterface (const tConfigHeader *psConfig, uint32_t ui32Index, uint32_t ui32Alt, uint32_t *pui32Section)
 
tEndpointDescriptor * USBDCDConfigGetInterfaceEndpoint (const tConfigHeader *psConfig, uint32_t ui32InterfaceNumber, uint32_t ui32AltCfg, uint32_t ui32Index)
 
bool USBDeviceConfig (tDCDInstance *psDevInst, const tConfigHeader *psConfig)
 
bool USBDeviceConfigAlternate (tDCDInstance *psDevInst, const tConfigHeader *psConfig, uint8_t ui8InterfaceNum, uint8_t ui8AlternateSetting)
 
void USBDCDDeviceInfoInit (uint32_t ui32Index, tDeviceInfo *psDeviceInfo)
 
void USBDCDInit (uint32_t ui32Index, tDeviceInfo *psDevice, void *pvDCDCBData)
 
void USBDCDTerm (uint32_t ui32Index)
 
void USBDCDRequestDataEP0 (uint32_t ui32Index, uint8_t *pui8Data, uint32_t ui32Size)
 
void USBDCDSendDataEP0 (uint32_t ui32Index, uint8_t *pui8Data, uint32_t ui32Size)
 
void USBDCDSetDefaultConfiguration (uint32_t ui32Index, uint32_t ui32DefaultConfig)
 
void USBDCDStallEP0 (uint32_t ui32Index)
 
void USBDCDPowerStatusSet (uint32_t ui32Index, uint8_t ui8Power)
 
bool USBDCDFeatureSet (uint32_t ui32Index, uint32_t ui32Feature, void *pvFeature)
 
bool USBDCDFeatureGet (uint32_t ui32Index, uint32_t ui32Feature, void *pvFeature)
 
bool USBDCDRemoteWakeLPM (uint32_t ui32Index)
 
bool USBDCDRemoteWakeupRequest (uint32_t ui32Index)
 
void USBDeviceResumeTickHandler (tDCDInstance *psDevInst)
 
void USBDeviceEnumHandler (tDCDInstance *pDevInstance)
 
void USBDeviceEnumResetHandler (tDCDInstance *pDevInstance)
 
void USBDeviceIntHandlerInternal (uint32_t ui32Index, uint32_t ui32Status)
 
void USB0_IRQDeviceHandler (void)
 

Variables

tDCDInstance g_psDCDInst [1]
 
tDeviceInfog_ppsDevInfo [1]
 

Detailed Description

Macro Definition Documentation

§ EP_INFO_IN

#define EP_INFO_IN   0

Referenced by USBDeviceConfig().

§ EP_INFO_OUT

#define EP_INFO_OUT   1

Referenced by USBDeviceConfig().

§ HALT_EP_IN

#define HALT_EP_IN   0

§ HALT_EP_OUT

#define HALT_EP_OUT   1

§ EP0_MAX_PACKET_SIZE

#define EP0_MAX_PACKET_SIZE   64

§ DEV_ADDR_PENDING

#define DEV_ADDR_PENDING   0x80000000

Referenced by USBDeviceEnumHandler().

§ DEFAULT_CONFIG_ID

#define DEFAULT_CONFIG_ID   1

Referenced by USBDCDDeviceInfoInit().

§ REMOTE_WAKEUP_PULSE_MS

#define REMOTE_WAKEUP_PULSE_MS   10

§ REMOTE_WAKEUP_READY_MS

#define REMOTE_WAKEUP_READY_MS   20

§ USBLIB_LPM_STATE_DISABLED

#define USBLIB_LPM_STATE_DISABLED   0x00000000

§ USBLIB_LPM_STATE_AWAKE

#define USBLIB_LPM_STATE_AWAKE   0x00000001

§ USBLIB_LPM_STATE_SLEEP

#define USBLIB_LPM_STATE_SLEEP   0x00000002

§ USB_MAX_INTERFACES_PER_DEVICE

#define USB_MAX_INTERFACES_PER_DEVICE   8

The maximum number of independent interfaces that any single device implementation can support. Independent interfaces means interface descriptors with different bInterfaceNumber values - several interface descriptors offering different alternative settings but the same interface number count as a single interface.

Referenced by USBDeviceEnumResetHandler().

Typedef Documentation

§ tStdRequest

typedef void(* tStdRequest) (void *pvInstance, tUSBRequest *pUSBRequest)

§ tInfoCallback

typedef void(* tInfoCallback) (void *pvInstance, uint32_t ui32Info)

§ tInterfaceCallback

typedef void(* tInterfaceCallback) (void *pvInstance, uint8_t ui8InterfaceNum, uint8_t ui8AlternateSetting)

§ tUSBIntHandler

typedef void(* tUSBIntHandler) (void *pvInstance)

§ tUSBEPIntHandler

typedef void(* tUSBEPIntHandler) (void *pvInstance, uint32_t ui32Status)

§ tUSBDeviceHandler

typedef void(* tUSBDeviceHandler) (void *pvInstance, uint32_t ui32Request, void *pvRequestData)

Generic handler callbacks that are used when the callers needs to call into an instance of class.

Function Documentation

§ USBDCDConfigDescGetSize()

uint32_t USBDCDConfigDescGetSize ( const tConfigHeader psConfig)

§ USBDCDConfigDescGetNum()

uint32_t USBDCDConfigDescGetNum ( const tConfigHeader psConfig,
uint32_t  ui32Type 
)

§ USBDCDConfigDescGet()

tDescriptorHeader* USBDCDConfigDescGet ( const tConfigHeader psConfig,
uint32_t  ui32Type,
uint32_t  ui32Index,
uint32_t *  pui32Section 
)

§ USBDCDConfigGetNumAlternateInterfaces()

uint32_t USBDCDConfigGetNumAlternateInterfaces ( const tConfigHeader psConfig,
uint8_t  ui8InterfaceNumber 
)

§ USBDCDConfigGetInterface()

tInterfaceDescriptor* USBDCDConfigGetInterface ( const tConfigHeader psConfig,
uint32_t  ui32Index,
uint32_t  ui32Alt,
uint32_t *  pui32Section 
)

§ USBDCDConfigGetInterfaceEndpoint()

tEndpointDescriptor* USBDCDConfigGetInterfaceEndpoint ( const tConfigHeader psConfig,
uint32_t  ui32InterfaceNumber,
uint32_t  ui32AltCfg,
uint32_t  ui32Index 
)

§ USBDeviceConfig()

bool USBDeviceConfig ( tDCDInstance psDevInst,
const tConfigHeader psConfig 
)

Configure the USB controller appropriately for the device whose configuration descriptor is passed.

Parameters
psDevInstis a pointer to the device instance being configured.
psConfigis a pointer to the configuration descriptor that the USB controller is to be set up to support.

This function may be used to initialize a USB controller to operate as the device whose configuration descriptor is passed. The function enables the USB controller, partitions the FIFO appropriately and configures each endpoint required by the configuration. If the supplied configuration supports multiple alternate settings for any interface, the USB FIFO is set up assuming the worst case use (largest packet size for a given endpoint in any alternate setting using that endpoint) to allow for on-the-fly alternate setting changes later. On return from this function, the USB controller is configured for correct operation of the default configuration of the device described by the descriptor passed.

Returns
Returns true on success or false on failure.

References EP_INFO_IN, EP_INFO_OUT, USB_DESC_ANY, USB_DTYPE_ENDPOINT, USB_DTYPE_INTERFACE, USB_EP_DESC_IN, USB_EP_DESC_NUM_M, USBDCDConfigDescGet(), USBDCDConfigDescGetNum(), USBDCDConfigGetInterface(), and USBDCDConfigGetInterfaceEndpoint().

§ USBDeviceConfigAlternate()

bool USBDeviceConfigAlternate ( tDCDInstance psDevInst,
const tConfigHeader psConfig,
uint8_t  ui8InterfaceNum,
uint8_t  ui8AlternateSetting 
)

Configure the affected USB endpoints appropriately for one alternate interface setting.

Parameters
psDevInstis a pointer to the device instance being configured.
psConfigis a pointer to the configuration descriptor that contains the interface whose alternate settings is to be configured.
ui8InterfaceNumis the number of the interface whose alternate setting is to be configured. This number corresponds to the bInterfaceNumber field in the desired interface descriptor.
ui8AlternateSettingis the alternate setting number for the desired interface. This number corresponds to the bAlternateSetting field in the desired interface descriptor.

This function may be used to reconfigure the endpoints of an interface for operation in one of the interface's alternate settings. Note that this function assumes that the endpoint FIFO settings will not need to change and only the endpoint mode is changed. This assumption is valid if the USB controller was initialized using a previous call to USBDCDConfig().

In reconfiguring the interface endpoints, any additional configuration bits set in the endpoint configuration other than the direction (USB_EP_DEV_IN or USB_EP_DEV_OUT) and mode (USB_EP_MODE_MASK) are preserved.

Returns
Returns true on success or false on failure.

References USB_DESC_ANY, USB_DTYPE_INTERFACE, USBDCDConfigDescGetNum(), USBDCDConfigGetInterface(), and USBDCDConfigGetInterfaceEndpoint().

§ USBDCDDeviceInfoInit()

void USBDCDDeviceInfoInit ( uint32_t  ui32Index,
tDeviceInfo psDeviceInfo 
)

Initialize an instance of the tDeviceInfo structure.

Parameters
ui32Indexis the index of the USB controller which is to be initialized.
psDeviceInfois a pointer to the tDeviceInfo structure that needs to be initialized.

This function must be called by a USB device class instance to initialize the basic tDeviceInfo required for all USB device class modules. This is typically called in the initialization routine for USB device class. For example in usbdaudio.c that supports USB device audio classes, this function is called in the USBDAudioCompositeInit() function which is used for both composite and non-composites instances of the USB audio class.

Note
This function should not be called directly by applications.
Returns
None.

References tDCDInstance::bPwrSrcSet, tDCDInstance::bRemoteWakeup, DEFAULT_CONFIG_ID, eUSBStateIdle, tDCDInstance::iEP0State, tDCDInstance::ui32Configuration, tDCDInstance::ui32DefaultConfiguration, tDCDInstance::ui32IntNum, tDCDInstance::ui32LPMState, and tDCDInstance::ui8Status.

Referenced by USBDCDInit(), and USBDHIDCompositeInit().

§ USBDCDInit()

void USBDCDInit ( uint32_t  ui32Index,
tDeviceInfo psDevice,
void *  pvDCDCBData 
)

Initialize the USB library device control driver for a given hardware controller.

Parameters
ui32Indexis the index of the USB controller which is to be initialized.
psDeviceis a pointer to a structure containing information that the USB library requires to support operation of this application's device. The structure contains event handler callbacks and pointers to the various standard descriptors that the device wishes to publish to the host.
pvDCDCBDatais the callback data for any device callbacks.

This function must be called by a device class which wishes to operate as a USB device and is not typically called by an application. This function initializes the USB device control driver for the given controller and saves the device information for future use. Prior to returning from this function, the device is connected to the USB bus. Following return, the caller can expect to receive a callback to the supplied pfnResetHandler function when a host connects to the device. The pvDCDCBData contains a pointer to data that is returned with the DCD calls back to the function in the psDevice->psCallbacks() functions.

The device information structure passed in psDevice must remain unchanged between this call and any matching call to USBDCDTerm() because it is not copied by the USB library.

The USBStackModeSet() function can be called with eUSBModeForceDevice in order to cause the USB library to force the USB operating mode to a device controller. This allows the application to used the USBVBUS and USBID pins as GPIOs on devices that support forcing OTG to operate as a device only controller. By default the USB library will assume that the USBVBUS and USBID pins are configured as USB pins and not GPIOs.

Returns
None.

References eUSBModeDevice, eUSBModeForceHost, eUSBModeHost, eUSBModeNone, eUSBModeOTG, g_iUSBMode, tDCDInstance::pvCBData, and USBDCDDeviceInfoInit().

Referenced by USBDBulkInit(), USBDCDCInit(), and USBDHIDInit().

§ USBDCDTerm()

void USBDCDTerm ( uint32_t  ui32Index)

Free the USB library device control driver for a given hardware controller.

Parameters
ui32Indexis the index of the USB controller which is to be freed.

This function should be called by an application if it no longer requires the use of a given USB controller to support its operation as a USB device. It frees the controller for use by another client.

It is the caller's responsibility to remove its device from the USB bus prior to calling this function.

Returns
None.

References InternalUSBTickReset().

Referenced by USBDAudioTerm(), USBDBulkTerm(), USBDCDCTerm(), USBDDFUCompositeTerm(), USBDDFUUpdateBegin(), USBDHIDTerm(), and USBDMSCTerm().

§ USBDCDRequestDataEP0()

void USBDCDRequestDataEP0 ( uint32_t  ui32Index,
uint8_t *  pui8Data,
uint32_t  ui32Size 
)

This function starts the request for data from the host on endpoint zero.

Parameters
ui32Indexis the index of the USB controller from which the data is being requested.
pui8Datais a pointer to the buffer to fill with data from the USB host.
ui32Sizeis the size of the buffer or data to return from the USB host.

This function handles retrieving data from the host when a custom command has been issued on endpoint zero. If the application needs notification when the data has been received, psCallbacks->pfnDataReceived() in the tDeviceInfo structure must contain valid function pointer. In nearly all cases this is necessary because the caller of this function would likely need to know that the data requested was received.

Returns
None.

References eUSBStateRx, tDCDInstance::iEP0State, tDCDInstance::pui8EP0Data, tDCDInstance::ui32EP0DataRemain, and tDCDInstance::ui32OUTDataSize.

§ USBDCDSendDataEP0()

void USBDCDSendDataEP0 ( uint32_t  ui32Index,
uint8_t *  pui8Data,
uint32_t  ui32Size 
)

This function requests transfer of data to the host on endpoint zero.

Parameters
ui32Indexis the index of the USB controller which is to be used to send the data.
pui8Datais a pointer to the buffer to send via endpoint zero.
ui32Sizeis the amount of data to send in bytes.

This function handles sending data to the host when a custom command is issued or non-standard descriptor has been requested on endpoint zero. If the application needs notification when this is complete, psCallbacks->pfnDataSent in the tDeviceInfo structure must contain a valid function pointer. This callback could be used to free up the buffer passed into this function in the pui8Data parameter. The contents of the pui8Data buffer must remain unchanged until the pfnDataSent callback is received.

Returns
None.

References tDCDInstance::pui8EP0Data, tDCDInstance::ui32EP0DataRemain, and tDCDInstance::ui32OUTDataSize.

§ USBDCDSetDefaultConfiguration()

void USBDCDSetDefaultConfiguration ( uint32_t  ui32Index,
uint32_t  ui32DefaultConfig 
)

This function sets the default configuration for the device.

Parameters
ui32Indexis the index of the USB controller whose default configuration is to be set.
ui32DefaultConfigis the configuration identifier (byte 6 of the standard configuration descriptor) which is to be presented to the host as the default configuration in cases where the configuration descriptor is queried prior to any specific configuration being set.

This function allows a device to override the default configuration descriptor that will be returned to a host whenever it is queried prior to a specific configuration having been set. The parameter passed must equal one of the configuration identifiers found in the ppsConfigDescriptors array for the device.

If this function is not called, the USB library will return the first configuration in the ppsConfigDescriptors array as the default configuration.

Note
The USB device stack assumes that the configuration IDs (byte 6 of the configuration descriptor, bConfigurationValue) stored within the configuration descriptor array, ppsConfigDescriptors, are equal to the array index + 1. In other words, the first entry in the array must contain a descriptor with bConfigurationValue 1, the second must have bConfigurationValue 2 and so on.
Returns
None.

References tDCDInstance::ui32DefaultConfiguration.

§ USBDCDStallEP0()

void USBDCDStallEP0 ( uint32_t  ui32Index)

This function generates a stall condition on endpoint zero.

Parameters
ui32Indexis the index of the USB controller whose endpoint zero is to be stalled.

This function is typically called to signal an error condition to the host when an unsupported request is received by the device. It should be called from within the callback itself (in interrupt context) and not deferred until later since it affects the operation of the endpoint zero state machine in the USB library.

Returns
None.

References eUSBStateStall, and tDCDInstance::iEP0State.

§ USBDCDPowerStatusSet()

void USBDCDPowerStatusSet ( uint32_t  ui32Index,
uint8_t  ui8Power 
)

Reports the device power status (bus- or self-powered) to the library.

Parameters
ui32Indexis the index of the USB controller whose device power status is being reported.
ui8Powerindicates the current power status, either USB_STATUS_SELF_PWR or USB_STATUS_BUS_PWR.

Applications which support switching between bus- or self-powered operation should call this function whenever the power source changes to indicate the current power status to the USB library. This information is required by the library to allow correct responses to be provided when the host requests status from the device.

Returns
None.

References tDCDInstance::bPwrSrcSet, tDCDInstance::ui8Status, USB_STATUS_BUS_PWR, USB_STATUS_PWR_M, and USB_STATUS_SELF_PWR.

Referenced by USBDBulkPowerStatusSet(), USBDCDCPowerStatusSet(), and USBDHIDPowerStatusSet().

§ USBDCDFeatureSet()

bool USBDCDFeatureSet ( uint32_t  ui32Index,
uint32_t  ui32Feature,
void *  pvFeature 
)

This function is used to enable/disable features of the USB library.

Parameters
ui32Indexis the index of the USB controller whose device power status is being reported.
ui32Featureindicates which feature is being changed.
pvFeatureholds the data that controls the feature request.

Applications can change the support levels of some USB library features by calling this function to enable/disable certain features. This function should normally be called before class initialization functions since the settings need to be in place before enumeration starts. This allows the USB library to properly respond to all enumeration requests. The ui32Feature value is one of the USBLIB_FEATURE_* defines which controls the type of request being made. The pvFeature is a feature specific data structure that is determined by the value passed in the ui32Feature parameter.

Returns
Returns true if the feature was successfully changed and returns false if the feature was not able to be changed or is not supported.

References tDCDInstance::ui32Features, tLPMFeature::ui32Features, USBLIB_FEATURE_LPM, USBLIB_FEATURE_LPM_EN, and USBLIB_FEATURE_USBPLL.

Referenced by USBOTGFeatureSet().

§ USBDCDFeatureGet()

bool USBDCDFeatureGet ( uint32_t  ui32Index,
uint32_t  ui32Feature,
void *  pvFeature 
)

This function is used to get the features of the USB library.

Parameters
ui32Indexis the index of the USB controller whose device power status is being reported.
ui32Featureindicates which feature is being requested.
pvFeatureholds the data that will be reported for the feature request.

Applications can query the support levels of some USB library features by calling this function to get values of the features. This function should normally be called before class initialization functions since the settings need to be in place during enumeration. This allows the USB library to properly respond to all enumeration requests. The ui32Feature value is one of the USBLIB_FEATURE_* defines which controls the type of request being made. The pvFeature is a feature specific data structure that is determined by the value passed in the ui32Feature parameter.

Returns
Returns true if the feature was requested for ULPI and returns false if the feature was not for ULPI interface.

References USBLIB_FEATURE_USBULPI.

Referenced by USBDBulkCompositeInit(), and USBDCDCCompositeInit().

§ USBDCDRemoteWakeLPM()

bool USBDCDRemoteWakeLPM ( uint32_t  ui32Index)

Requests an LPM remote wake up to resume communication when in an LPM sleep state.

Parameters
ui32Indexis the index of the USB controller that will request a bus wake up.

When the host controller puts the device into an LPM sleep state, the device can call this function to initiate LPM remote wake up signaling to the host. If the remote wake up feature has been enabled by the host, this will cause the host to respond to the LPM remote wake request and resume normal operation. If the host has disabled remote wake up, false is returned to indicate that the wake up request was not successful.

Returns
Returns true if the remote wake up request has been sent or false if LPM remote wake up is disabled.

§ USBDCDRemoteWakeupRequest()

bool USBDCDRemoteWakeupRequest ( uint32_t  ui32Index)

Requests a remote wake up to resume communication when in suspended state.

Parameters
ui32Indexis the index of the USB controller that will request a bus wake up.

When the bus is suspended, an application which supports remote wake up (advertised to the host via the configuration descriptor) may call this function to initiate remote wake up signaling to the host. If the remote wake up feature has not been disabled by the host, this will cause the bus to resume operation within 20mS. If the host has disabled remote wake up, false will be returned to indicate that the wake up request was not successful.

Returns
Returns true if the remote wake up is not disabled and the signaling was started or false if remote wake up is disabled or if signaling is currently ongoing following a previous call to this function.

References tDCDInstance::bRemoteWakeup, tDCDInstance::ui8RemoteWakeupCount, and USB_STATUS_REMOTE_WAKE.

Referenced by USBDBulkRemoteWakeupRequest(), USBDCDCRemoteWakeupRequest(), and USBDHIDRemoteWakeupRequest().

§ USBDeviceResumeTickHandler()

void USBDeviceResumeTickHandler ( tDCDInstance psDevInst)

§ USBDeviceEnumHandler()

void USBDeviceEnumHandler ( tDCDInstance pDevInstance)

§ USBDeviceEnumResetHandler()

void USBDeviceEnumResetHandler ( tDCDInstance pDevInstance)

§ USBDeviceIntHandlerInternal()

void USBDeviceIntHandlerInternal ( uint32_t  ui32Index,
uint32_t  ui32Status 
)

§ USB0_IRQDeviceHandler()

void USB0_IRQDeviceHandler ( void  )

The USB device interrupt handler.

This the main USB interrupt handler entry point for use in USB device applications. This top-level handler will branch the interrupt off to the appropriate application or stack handlers depending on the current status of the USB controller.

Applications which operate purely as USB devices (rather than dual mode applications which can operate in either device or host mode at different times) must ensure that a pointer to this function is installed in the interrupt vector table entry for the USB0 interrupt. For dual mode operation, the vector should be set to point to USB0DualModeIntHandler() instead.

Returns
None.

References USBDeviceIntHandlerInternal().

Variable Documentation

§ g_psDCDInst

tDCDInstance g_psDCDInst[1]

§ g_ppsDevInfo

tDeviceInfo* g_ppsDevInfo[1]
© Copyright 1995-2020, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale