Bulk_device_class_api

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

Detailed Description

Macro Definition Documentation

USB_RX_ERROR_FLAGS

#define USB_RX_ERROR_FLAGS

Value:

(USBERR_DEV_RX_DATA_ERROR |                   \
                                 USBERR_DEV_RX_OVERRUN |                      \
                                 USBERR_DEV_RX_FIFO_FULL)

BULK_DO_PACKET_RX

#define BULK_DO_PACKET_RX   5

DATA_IN_ENDPOINT

#define DATA_IN_ENDPOINT   USB_EP_1

DATA_OUT_ENDPOINT

#define DATA_OUT_ENDPOINT   USB_EP_1

DATA_IN_EP_MAX_SIZE

#define DATA_IN_EP_MAX_SIZE   USBFIFOSizeToBytes(USB_FIFO_SZ_64)

DATA_OUT_EP_MAX_SIZE

#define DATA_OUT_EP_MAX_SIZE   USBFIFOSizeToBytes(USB_FIFO_SZ_64)

DATA_IN_EP_MAX_SIZE_HS

#define DATA_IN_EP_MAX_SIZE_HS   USBFIFOSizeToBytes(USB_FIFO_SZ_512)

DATA_OUT_EP_MAX_SIZE_HS

#define DATA_OUT_EP_MAX_SIZE_HS   USBFIFOSizeToBytes(USB_FIFO_SZ_512)

NUM_BULK_SECTIONS

#define NUM_BULK_SECTIONS

Value:

(sizeof(g_psBulkSections) /                   \
                                 sizeof(g_psBulkSections[0]))

BULKINTERFACE_SIZE

#define BULKINTERFACE_SIZE   (23)

COMPOSITE_DBULK_SIZE

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

Enumeration Type Documentation

tBulkState

enum tBulkState

Enumerator
eBulkStateUnconfigured
eBulkStateIdle
eBulkStateWaitData
eBulkStateWaitClient

Function Documentation

USBDBulkInit()

void * USBDBulkInit	(	uint32_t	ui32Index,
		tUSBDBulkDevice *	psBulkDevice
	)

Initializes bulk device operation for a given USB controller.

Parameters

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.

Note

The application must not make any calls to the low level USB Device API if interacting with USB via the USB bulk device class API. Doing so will cause unpredictable (though almost certainly unpleasant) behavior.

Returns

Returns NULL on failure or void pointer that should be used with the remaining USB bulk class APSs.

References g_pui8BulkDescriptor, g_pui8BulkDeviceDescriptor, tBulkInstance::sDevInfo, tUSBDBulkDevice::sPrivateData, tUSBDBulkDevice::ui16MaxPowermA, tUSBDBulkDevice::ui16PID, tUSBDBulkDevice::ui16VID, tUSBDBulkDevice::ui8PwrAttributes, USBDBulkCompositeInit(), and USBDCDInit().

USBDBulkCompositeInit()

void * USBDBulkCompositeInit	(	uint32_t	ui32Index,
		tUSBDBulkDevice *	psBulkDevice,
		tCompositeEntry *	psCompEntry
	)

Initializes bulk device operation for a given USB controller.

Parameters

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.

Returns

Returns zero on failure or a non-zero value that should be used with the remaining USB Bulk APIs.

References tUSBDBulkDevice::pfnRxCallback, tUSBDBulkDevice::pfnTxCallback, tUSBDBulkDevice::ppui8StringDescriptors, tCompositeEntry::psDevInfo, tCompositeEntry::pvInstance, tBulkInstance::sDevInfo, tUSBDBulkDevice::sPrivateData, USBDCDFeatureGet(), and USBLIB_FEATURE_USBULPI.

Referenced by USBDBulkInit().

USBDBulkTerm()

void USBDBulkTerm

(

void *

pvBulkDevice

)

Shut down the bulk device.

Parameters

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.

Returns

None.

References tBulkInstance::ui32USBBase, USBBaseToIndex, and USBDCDTerm().

USBDBulkSetRxCBData()

void * USBDBulkSetRxCBData	(	void *	pvBulkDevice,
		void *	pvCBData
	)

Sets the client-specific pointer parameter for the receive channel callback.

Parameters

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.

Returns

Returns the previous callback pointer that was being used for this instance's receive callback.

USBDBulkSetTxCBData()

void * USBDBulkSetTxCBData	(	void *	pvBulkDevice,
		void *	pvCBData
	)

Sets the client-specific pointer parameter for the transmit callback.

Parameters

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.

Returns

Returns the previous callback pointer that was being used for this instance's transmit callback.

USBDBulkPacketWrite()

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.

Parameters

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.

Returns

Returns the number of bytes actually sent. At this level, this will either be the number of bytes passed (if less than or equal to the maximum packet size for the USB endpoint in use and no outstanding transmission ongoing) or 0 to indicate a failure.

USBDBulkPacketRead()

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.

Parameters

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.

Returns

Returns the number of bytes of data read.

References tBulkInstance::ui32USBBase, and tBulkInstance::ui8OUTEndpoint.

USBDBulkTxPacketAvailable()

uint32_t USBDBulkTxPacketAvailable

(

void *

pvBulkDevice

)

Returns the number of free bytes in the transmit buffer.

Parameters

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.

Returns

Returns the number of bytes available in the transmit buffer.

References eBulkStateIdle, and tBulkInstance::iBulkTxState.

USBDBulkRxPacketAvailable()

uint32_t USBDBulkRxPacketAvailable

(

void *

pvBulkDevice

)

Determines whether a packet is available and, if so, the size of the buffer required to read it.

Parameters

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.

Returns

Returns 0 if no received packet remains unprocessed or the size of the packet if a packet is waiting to be read.

References tBulkInstance::ui32USBBase, and tBulkInstance::ui8OUTEndpoint.

USBDBulkPowerStatusSet()

void USBDBulkPowerStatusSet	(	void *	pvBulkDevice,
		uint8_t	ui8Power
	)

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

Parameters

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.

Returns

None.

References USBDCDPowerStatusSet().

USBDBulkRemoteWakeupRequest()

bool USBDBulkRemoteWakeupRequest

(

void *

pvBulkDevice

)

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

Parameters

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.

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

Variable Documentation

g_pui8BulkDeviceDescriptor

uint8_t g_pui8BulkDeviceDescriptor[]

Initial value:

=
{
    18,                         
    USB_DTYPE_DEVICE,           
    USBShort(0x110),            
                                
    USB_CLASS_VEND_SPECIFIC,    
    0,                          
    0,                          
    64,                         
    USBShort(0),                
    USBShort(0),                
    USBShort(0x100),            
    1,                          
    2,                          
    3,                          
    1                           
}

Referenced by USBDBulkInit().

g_pui8BulkDescriptor

uint8_t g_pui8BulkDescriptor[]

Initial value:

=
{
    
    
    
    9,                          
    USB_DTYPE_CONFIGURATION,    
    USBShort(32),               
    1,                          
                                
    1,                          
    5,                          
                                
    USB_CONF_ATTR_SELF_PWR,     
    250,                        
}

Referenced by USBDBulkInit().

g_pui8BulkInterface

const uint8_t g_pui8BulkInterface[BULKINTERFACE_SIZE]

g_pui8BulkInterfaceHS

const uint8_t g_pui8BulkInterfaceHS[BULKINTERFACE_SIZE]

g_sBulkConfigSection

const tConfigSection g_sBulkConfigSection

Initial value:

=
{
    sizeof(g_pui8BulkDescriptor),
    g_pui8BulkDescriptor
}

g_sBulkInterfaceSection

const tConfigSection g_sBulkInterfaceSection

Initial value:

=
{
    sizeof(g_pui8BulkInterface),
    g_pui8BulkInterface
}

g_sBulkInterfaceSectionHS

const tConfigSection g_sBulkInterfaceSectionHS

Initial value:

=
{
    sizeof(g_pui8BulkInterfaceHS),
    g_pui8BulkInterfaceHS
}

g_psBulkSections

const tConfigSection* g_psBulkSections[]

Initial value:

=
{
    &g_sBulkConfigSection,
    &g_sBulkInterfaceSection
}

g_psBulkSectionsHS

const tConfigSection* g_psBulkSectionsHS[]

Initial value:

=
{
    &g_sBulkConfigSection,
    &g_sBulkInterfaceSectionHS
}

g_sBulkConfigHeader

const tConfigHeader g_sBulkConfigHeader

Initial value:

=
{
    NUM_BULK_SECTIONS,
    g_psBulkSections
}

g_sBulkConfigHeaderHS

const tConfigHeader g_sBulkConfigHeaderHS

Initial value:

=
{
    NUM_BULK_SECTIONS,
    g_psBulkSectionsHS
}

g_ppBulkConfigDescriptors

const tConfigHeader* const g_ppBulkConfigDescriptors[]

Initial value:

=
{
    &g_sBulkConfigHeader
}

g_ppBulkConfigDescriptorsHS

const tConfigHeader* const g_ppBulkConfigDescriptorsHS[]

Initial value:

=
{
    &g_sBulkConfigHeaderHS
}

g_sBulkHandlers

const tCustomHandlers g_sBulkHandlers