USBLib API Guide
1.00.00.01
|
Data Structures | |
struct | tBulkInstance |
struct | tUSBDBulkDevice |
Macros | |
#define | USB_RX_ERROR_FLAGS |
#define | BULK_DO_PACKET_RX 5 |
#define | DATA_IN_ENDPOINT USB_EP_1 |
#define | DATA_OUT_ENDPOINT USB_EP_1 |
#define | DATA_IN_EP_MAX_SIZE USBFIFOSizeToBytes(USB_FIFO_SZ_64) |
#define | DATA_OUT_EP_MAX_SIZE USBFIFOSizeToBytes(USB_FIFO_SZ_64) |
#define | DATA_IN_EP_MAX_SIZE_HS USBFIFOSizeToBytes(USB_FIFO_SZ_512) |
#define | DATA_OUT_EP_MAX_SIZE_HS USBFIFOSizeToBytes(USB_FIFO_SZ_512) |
#define | NUM_BULK_SECTIONS |
#define | BULKINTERFACE_SIZE (23) |
#define | COMPOSITE_DBULK_SIZE (BULKINTERFACE_SIZE) |
Enumerations | |
enum | tBulkState { eBulkStateUnconfigured, eBulkStateIdle, eBulkStateWaitData, eBulkStateWaitClient } |
Functions | |
void * | USBDBulkInit (uint32_t ui32Index, tUSBDBulkDevice *psBulkDevice) |
void * | USBDBulkCompositeInit (uint32_t ui32Index, tUSBDBulkDevice *psBulkDevice, tCompositeEntry *psCompEntry) |
void | USBDBulkTerm (void *pvBulkDevice) |
void * | USBDBulkSetRxCBData (void *pvBulkDevice, void *pvCBData) |
void * | USBDBulkSetTxCBData (void *pvBulkDevice, void *pvCBData) |
uint32_t | USBDBulkPacketWrite (void *pvBulkDevice, uint8_t *pi8Data, uint32_t ui32Length, bool bLast) |
uint32_t | USBDBulkPacketRead (void *pvBulkDevice, uint8_t *pi8Data, uint32_t ui32Length, bool bLast) |
uint32_t | USBDBulkTxPacketAvailable (void *pvBulkDevice) |
uint32_t | USBDBulkRxPacketAvailable (void *pvBulkDevice) |
void | USBDBulkPowerStatusSet (void *pvBulkDevice, uint8_t ui8Power) |
bool | USBDBulkRemoteWakeupRequest (void *pvBulkDevice) |
Variables | |
uint8_t | g_pui8BulkDeviceDescriptor [] |
uint8_t | g_pui8BulkDescriptor [] |
const uint8_t | g_pui8BulkInterface [BULKINTERFACE_SIZE] |
const uint8_t | g_pui8BulkInterfaceHS [BULKINTERFACE_SIZE] |
const tConfigSection | g_sBulkConfigSection |
const tConfigSection | g_sBulkInterfaceSection |
const tConfigSection | g_sBulkInterfaceSectionHS |
const tConfigSection * | g_psBulkSections [] |
const tConfigSection * | g_psBulkSectionsHS [] |
const tConfigHeader | g_sBulkConfigHeader |
const tConfigHeader | g_sBulkConfigHeaderHS |
const tConfigHeader *const | g_ppBulkConfigDescriptors [] |
const tConfigHeader *const | g_ppBulkConfigDescriptorsHS [] |
const tCustomHandlers | g_sBulkHandlers |
#define USB_RX_ERROR_FLAGS |
#define BULK_DO_PACKET_RX 5 |
#define DATA_IN_ENDPOINT USB_EP_1 |
#define DATA_OUT_ENDPOINT USB_EP_1 |
#define DATA_IN_EP_MAX_SIZE USBFIFOSizeToBytes(USB_FIFO_SZ_64) |
#define DATA_OUT_EP_MAX_SIZE USBFIFOSizeToBytes(USB_FIFO_SZ_64) |
#define DATA_IN_EP_MAX_SIZE_HS USBFIFOSizeToBytes(USB_FIFO_SZ_512) |
#define DATA_OUT_EP_MAX_SIZE_HS USBFIFOSizeToBytes(USB_FIFO_SZ_512) |
#define NUM_BULK_SECTIONS |
#define BULKINTERFACE_SIZE (23) |
#define COMPOSITE_DBULK_SIZE (BULKINTERFACE_SIZE) |
The size of the memory that should be allocated to create a configuration descriptor for a single instance of the USB Bulk Device. This does not include the configuration descriptor which is automatically ignored by the composite device class.
enum tBulkState |
void * USBDBulkInit | ( | uint32_t | ui32Index, |
tUSBDBulkDevice * | psBulkDevice | ||
) |
Initializes bulk device operation for a given USB controller.
ui32Index | is the index of the USB controller which is to be initialized for bulk device operation. |
psBulkDevice | points to a structure containing parameters customizing the operation of the bulk device. |
An application wishing to make use of a USB bulk communication channel must call this function to initialize the USB controller and attach the device to the USB bus. This function performs all required USB initialization.
On successful completion, this function will return the psBulkDevice pointer passed to it. This must be passed on all future calls to the device driver related to this device.
The USBDBulk interface offers packet-based transmit and receive operation. If the application would rather use block based communication with transmit and receive buffers, USB buffers may be used above the bulk transmit and receive channels to offer this functionality.
Transmit Operation:
Calls to USBDBulkPacketWrite() must send no more than 64 bytes of data for FS USB and 512 bytes for HS USB at a time and may only be made when no other transmission is currently outstanding.
Once a packet of data has been acknowledged by the USB host, a USB_EVENT_TX_COMPLETE event is sent to the application callback to inform it that another packet may be transmitted.
Receive Operation:
An incoming USB data packet will result in a call to the application callback with event USBD_EVENT_RX_AVAILABLE. The application must then call USBDBulkPacketRead(), passing a buffer capable of holding 64 bytes for FS USB and 512 bytes for HS USB, to retrieve the data and acknowledge reception to the USB host.
References g_pui8BulkDescriptor, g_pui8BulkDeviceDescriptor, tBulkInstance::sDevInfo, tUSBDBulkDevice::sPrivateData, tUSBDBulkDevice::ui16MaxPowermA, tUSBDBulkDevice::ui16PID, tUSBDBulkDevice::ui16VID, tUSBDBulkDevice::ui8PwrAttributes, USBDBulkCompositeInit(), and USBDCDInit().
void * USBDBulkCompositeInit | ( | uint32_t | ui32Index, |
tUSBDBulkDevice * | psBulkDevice, | ||
tCompositeEntry * | psCompEntry | ||
) |
Initializes bulk device operation for a given USB controller.
ui32Index | is the index of the USB controller which is to be initialized for bulk device operation. |
psBulkDevice | points to a structure containing parameters customizing the operation of the bulk device. |
psCompEntry | is the composite device entry to initialize when creating a composite device. |
This call is very similar to USBDBulkInit() except that it is used for initializing an instance of the bulk device for use in a composite device. When this bulk device is part of a composite device, then the psCompEntry should point to the composite device entry to initialize. This is part of the array that is passed to the USBDCompositeInit() function.
References tUSBDBulkDevice::pfnRxCallback, tUSBDBulkDevice::pfnTxCallback, tUSBDBulkDevice::ppui8StringDescriptors, tCompositeEntry::psDevInfo, tCompositeEntry::pvInstance, tBulkInstance::sDevInfo, tUSBDBulkDevice::sPrivateData, USBDCDFeatureGet(), and USBLIB_FEATURE_USBULPI.
Referenced by USBDBulkInit().
void USBDBulkTerm | ( | void * | pvBulkDevice | ) |
Shut down the bulk device.
pvBulkDevice | is the pointer to the device instance structure as returned by USBDBulkInit(). |
This function terminates device operation for the instance supplied and removes the device from the USB bus. This function should not be called if the bulk device is part of a composite device and instead the USBDCompositeTerm() function should be called for the full composite device.
Following this call, the pvBulkDevice instance should not me used in any other calls.
References tBulkInstance::ui32USBBase, USBBaseToIndex, and USBDCDTerm().
void * USBDBulkSetRxCBData | ( | void * | pvBulkDevice, |
void * | pvCBData | ||
) |
Sets the client-specific pointer parameter for the receive channel callback.
pvBulkDevice | is the pointer to the device instance structure as returned by USBDBulkInit(). |
pvCBData | is the pointer that client wishes to be provided on each event sent to the receive channel callback function. |
The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnRxCallback function passed on USBDBulkInit().
If a client wants to make runtime changes in the callback pointer, it must ensure that the pvBulkDevice structure passed to USBDBulkInit() resides in RAM. If this structure is in flash, callback pointer changes are not possible.
void * USBDBulkSetTxCBData | ( | void * | pvBulkDevice, |
void * | pvCBData | ||
) |
Sets the client-specific pointer parameter for the transmit callback.
pvBulkDevice | is the pointer to the device instance structure as returned by USBDBulkInit(). |
pvCBData | is the pointer that client wishes to be provided on each event sent to the transmit channel callback function. |
The client uses this function to change the callback pointer passed in the first parameter on all callbacks to the pfnTxCallback function passed on USBDBulkInit().
If a client wants to make runtime changes in the callback pointer, it must ensure that the pvBulkDevice structure passed to USBDBulkInit() resides in RAM. If this structure is in flash, callback pointer changes are not possible.
uint32_t USBDBulkPacketWrite | ( | void * | pvBulkDevice, |
uint8_t * | pi8Data, | ||
uint32_t | ui32Length, | ||
bool | bLast | ||
) |
Transmits a packet of data to the USB host via the bulk data interface.
pvBulkDevice | is the pointer to the device instance structure as returned by USBDBulkInit(). |
pi8Data | points to the first byte of data which is to be transmitted. |
ui32Length | is the number of bytes of data to transmit. |
bLast | indicates whether more data is to be written before a packet should be scheduled for transmission. If true, the client will make a further call to this function. If false, no further call will be made and the driver should schedule transmission of a short packet. |
This function schedules the supplied data for transmission to the USB host in a single USB packet. If no transmission is currently ongoing, the data is immediately copied to the relevant USB endpoint FIFO for transmission. Whenever a USB packet is acknowledged by the host, a USB_EVENT_TX_COMPLETE event will be sent to the transmit channel callback indicating that more data can now be transmitted.
The maximum value for ui32Length is 64 bytes (the maximum USB packet size for the bulk endpoints in use by the device). Attempts to send more data than this will result in a return code of 0 indicating that the data cannot be sent.
The bLast parameter allows a client to make multiple calls to this function before scheduling transmission of the packet to the host. This can be helpful if, for example, constructing a packet on the fly or writing a packet which spans the wrap point in a ring buffer.
uint32_t USBDBulkPacketRead | ( | void * | pvBulkDevice, |
uint8_t * | pi8Data, | ||
uint32_t | ui32Length, | ||
bool | bLast | ||
) |
Reads a packet of data received from the USB host via the bulk data interface.
pvBulkDevice | is the pointer to the device instance structure as returned by USBDBulkInit(). |
pi8Data | points to a buffer into which the received data will be written. |
ui32Length | is the size of the buffer pointed to by pi8Data. |
bLast | indicates whether the client will make a further call to read additional data from the packet. |
This function reads up to ui32Length bytes of data received from the USB host into the supplied application buffer. If the driver detects that the entire packet has been read, it is acknowledged to the host.
The bLast parameter is ignored in this implementation since the end of a packet can be determined without relying upon the client to provide this information.
References tBulkInstance::ui32USBBase, and tBulkInstance::ui8OUTEndpoint.
uint32_t USBDBulkTxPacketAvailable | ( | void * | pvBulkDevice | ) |
Returns the number of free bytes in the transmit buffer.
pvBulkDevice | is the pointer to the device instance structure as returned by USBDBulkInit(). |
This function returns the maximum number of bytes that can be passed on a call to USBDBulkPacketWrite() and accepted for transmission. The value returned will be the maximum USB packet size (64) if no transmission is currently outstanding or 0 if a transmission is in progress.
References eBulkStateIdle, and tBulkInstance::iBulkTxState.
uint32_t USBDBulkRxPacketAvailable | ( | void * | pvBulkDevice | ) |
Determines whether a packet is available and, if so, the size of the buffer required to read it.
pvBulkDevice | is the pointer to the device instance structure as returned by USBDBulkInit(). |
This function may be used to determine if a received packet remains to be read and allows the application to determine the buffer size needed to read the data.
References tBulkInstance::ui32USBBase, and tBulkInstance::ui8OUTEndpoint.
void USBDBulkPowerStatusSet | ( | void * | pvBulkDevice, |
uint8_t | ui8Power | ||
) |
Reports the device power status (bus- or self-powered) to the USB library.
pvBulkDevice | is the pointer to the bulk device instance structure. |
ui8Power | indicates 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 USB library to allow correct responses to be provided when the host requests status from the device.
References USBDCDPowerStatusSet().
bool USBDBulkRemoteWakeupRequest | ( | void * | pvBulkDevice | ) |
Requests a remote wake up to resume communication when in suspended state.
pvBulkDevice | is the pointer to the bulk device instance structure. |
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.
References USBDCDRemoteWakeupRequest().
uint8_t g_pui8BulkDeviceDescriptor[] |
Referenced by USBDBulkInit().
uint8_t g_pui8BulkDescriptor[] |
Referenced by USBDBulkInit().
const uint8_t g_pui8BulkInterface[BULKINTERFACE_SIZE] |
const uint8_t g_pui8BulkInterfaceHS[BULKINTERFACE_SIZE] |
const tConfigSection g_sBulkConfigSection |
const tConfigSection g_sBulkInterfaceSection |
const tConfigSection g_sBulkInterfaceSectionHS |
const tConfigSection* g_psBulkSections[] |
const tConfigSection* g_psBulkSectionsHS[] |
const tConfigHeader g_sBulkConfigHeader |
const tConfigHeader g_sBulkConfigHeaderHS |
const tConfigHeader* const g_ppBulkConfigDescriptors[] |
const tConfigHeader* const g_ppBulkConfigDescriptorsHS[] |
const tCustomHandlers g_sBulkHandlers |