Macros | Typedefs | Enumerations | Functions
General_usblib_api

Macros

#define USB_DESC_ANY   0xFFFFFFFF
 
#define USB_EVENT_CONNECTED   (USB_EVENT_BASE + 0)
 
#define USB_EVENT_DISCONNECTED   (USB_EVENT_BASE + 1)
 
#define USB_EVENT_RX_AVAILABLE   (USB_EVENT_BASE + 2)
 Data has been received and is in the buffer provided.
 
#define USB_EVENT_DATA_REMAINING   (USB_EVENT_BASE + 3)
 
#define USB_EVENT_REQUEST_BUFFER   (USB_EVENT_BASE + 4)
 
#define USB_EVENT_TX_COMPLETE   (USB_EVENT_BASE + 5)
 
#define USB_EVENT_ERROR   (USB_EVENT_BASE + 6)
 
#define USB_EVENT_SUSPEND   (USB_EVENT_BASE + 7)
 The bus has entered suspend state.
 
#define USB_EVENT_RESUME   (USB_EVENT_BASE + 8)
 The bus has left suspend state.
 
#define USB_EVENT_SCHEDULER   (USB_EVENT_BASE + 9)
 A scheduler event has occurred.
 
#define USB_EVENT_STALL   (USB_EVENT_BASE + 10)
 A device or host has detected a stall condition.
 
#define USB_EVENT_POWER_FAULT   (USB_EVENT_BASE + 11)
 The host detected a power fault condition.
 
#define USB_EVENT_POWER_ENABLE   (USB_EVENT_BASE + 12)
 
#define USB_EVENT_POWER_DISABLE   (USB_EVENT_BASE + 13)
 
#define USB_EVENT_COMP_IFACE_CHANGE   (USB_EVENT_BASE + 14)
 
#define USB_EVENT_COMP_EP_CHANGE   (USB_EVENT_BASE + 15)
 
#define USB_EVENT_COMP_STR_CHANGE   (USB_EVENT_BASE + 16)
 
#define USB_EVENT_COMP_CONFIG   (USB_EVENT_BASE + 17)
 
#define USBERR_HOST_IN_PID_ERROR   0x01000000
 The host received an invalid PID in a transaction.
 
#define USBERR_HOST_IN_NOT_COMP   0x00100000
 The host did not receive a response from a device.
 
#define USBERR_HOST_IN_STALL   0x00400000
 The host received a stall on an IN endpoint.
 
#define USBERR_HOST_IN_DATA_ERROR   0x00080000
 The host detected a CRC or bit-stuffing error (isochronous mode).
 
#define USBERR_HOST_IN_NAK_TO   0x00080000
 
#define USBERR_HOST_IN_ERROR   0x00040000
 The host failed to communicate with a device via an IN endpoint.
 
#define USBERR_HOST_IN_FIFO_FULL   0x00020000
 The host receive FIFO is full.
 
#define USBERR_HOST_OUT_NAK_TO   0x00000080
 
#define USBERR_HOST_OUT_NOT_COMP   0x00000080
 The host did not receive a response from a device (isochronous mode).
 
#define USBERR_HOST_OUT_STALL   0x00000020
 The host received a stall on an OUT endpoint.
 
#define USBERR_HOST_OUT_ERROR   0x00000004
 The host failed to communicate with a device via an OUT endpoint.
 
#define USBERR_HOST_EP0_NAK_TO   0x00000080
 
#define USBERR_HOST_EP0_ERROR   0x00000010
 The host failed to communicate with a device via an endpoint zero.
 
#define USBERR_DEV_RX_DATA_ERROR   0x00080000
 The device detected a CRC error in received data.
 
#define USBERR_DEV_RX_OVERRUN   0x00040000
 
#define USBERR_DEV_RX_FIFO_FULL   0x00020000
 The device receive FIFO is full.
 

Typedefs

typedef uint32_t(* tUSBCallback) (struct usbGadgetObj *pGadgetObject, void *pvCBData, uint32_t ulEvent, uint32_t ulMsgParam, void *pvMsgData)
 

Enumerations

enum  tUSBMode { USB_MODE_DEVICE = 0, USB_MODE_HOST, USB_MODE_OTG, USB_MODE_NONE }
 

Functions

uint32_t USBDescGetNum (tDescriptorHeader *psDesc, uint32_t ulSize, uint32_t ulType)
 
tDescriptorHeader * USBDescGet (tDescriptorHeader *psDesc, uint32_t ulSize, uint32_t ulType, uint32_t ulIndex)
 
uint32_t USBDescGetNumAlternateInterfaces (tConfigDescriptor *psConfig, unsigned char ucInterfaceNumber)
 
static tInterfaceDescriptor * USBDescGetAlternateInterface (tConfigDescriptor *psConfig, unsigned char ucInterfaceNumber, uint32_t ulIndex)
 
tInterfaceDescriptor * USBDescGetInterface (tConfigDescriptor *psConfig, uint32_t ulIndex, uint32_t ulAlt)
 
tEndpointDescriptor * USBDescGetInterfaceEndpoint (tInterfaceDescriptor *psInterface, uint32_t ulIndex, uint32_t ulSize)
 

Detailed Description

Copyright (c) Texas Instruments Incorporated 2015-2016

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Neither the name of Texas Instruments Incorporated nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Macro Definition Documentation

#define USB_DESC_ANY   0xFFFFFFFF

The USB_DESC_ANY label is used as a wild card in several of the descriptor parsing APIs to determine whether or not particular search criteria should be ignored.

#define USB_EVENT_COMP_CONFIG   (USB_EVENT_BASE + 17)

Used with pfnDeviceHandler handler function is classes to allow the device class to make final adjustments to the configuration descriptor. This is only used when a device class is used in a composite device class is in use.

The pvInstance value should point to an instance of the device being accessed.

The ulRequest should be USB_EVENT_COMP_CONFIG.

The pvRequestData should point to the beginning of the configuration descriptor for the device instance.

#define USB_EVENT_COMP_EP_CHANGE   (USB_EVENT_BASE + 15)

Used with pfnDeviceHandler handler function is classes to indicate changes in endpoint number by a class outside the class being accessed. Typically this is when composite device class is in use.

The pvInstance value should point to an instance of the device being accessed.

The ulRequest should be USB_EVENT_COMP_EP_CHANGE.

The pvRequestData should point to a two byte array where the first value is the old endpoint number and the second is the new endpoint number. The endpoint numbers should be exactly as USB specification defines them and bit 7 set indicates an IN endpoint and bit 7 clear indicates an OUT endpoint.

#define USB_EVENT_COMP_IFACE_CHANGE   (USB_EVENT_BASE + 14)

Used with pfnDeviceHandler handler function is classes to indicate changes in the interface number by a class outside the class being accessed. Typically this is when composite device class is in use.

The pvInstance value should point to an instance of the device being accessed.

The ulRequest should be USB_EVENT_COMP_IFACE_CHANGE.

The pvRequestData should point to a two byte array where the first value is the old interface number and the second is the new interface number.

#define USB_EVENT_COMP_STR_CHANGE   (USB_EVENT_BASE + 16)

Used with pfnDeviceHandler handler function is classes to indicate changes in string index number by a class outside the class being accessed. Typically this is when composite device class is in use.

The pvInstance value should point to an instance of the device being accessed.

The ulRequest should be USB_EVENT_COMP_STR_CHANGE.

The pvRequestData should point to a two byte array where the first value is the old string index and the second is the new string index.

#define USB_EVENT_CONNECTED   (USB_EVENT_BASE + 0)

The device is now attached to a USB host and ready to begin sending and receiving data (used by device classes only).

#define USB_EVENT_DATA_REMAINING   (USB_EVENT_BASE + 3)

This event is sent by a lower layer to inquire about the amount of unprocessed data buffered in the layers above. It is used in cases where a low level driver needs to ensure that all preceding data has been processed prior to performing some action or making some notification. Clients receiving this event should return the number of bytes of data that are unprocessed or 0 if no outstanding data remains.

#define USB_EVENT_DISCONNECTED   (USB_EVENT_BASE + 1)

The device has been disconnected from the USB host (used by device classes only).

Note: Due to a hardware erratum in revision A of LM3S3748, this event is not posted to self-powered USB devices when they are disconnected from the USB host.

#define USB_EVENT_ERROR   (USB_EVENT_BASE + 6)

An error has been reported on the channel or pipe. The ulMsgValue parameter indicates the source(s) of the error and is the logical OR combination of "USBERR_" flags defined below.

#define USB_EVENT_POWER_DISABLE   (USB_EVENT_BASE + 13)

The controller needs power removed, This is only generated on OTG parts if automatic power control is disabled.

#define USB_EVENT_POWER_ENABLE   (USB_EVENT_BASE + 12)

The controller has detected a A-Side cable and needs power applied This is only generated on OTG parts if automatic power control is disabled.

#define USB_EVENT_REQUEST_BUFFER   (USB_EVENT_BASE + 4)

This event is sent by a lower layer supporting DMA to request a buffer in which the next received packet may be stored. The ulMsgValue parameter indicates the maximum size of packet that can be received in this channel and pvMsgData points to storage which should be written with the returned buffer pointer. The return value from the callback should be the size of the buffer allocated (which may be less than the maximum size passed in ulMsgValue if the client knows that fewer bytes are expected to be received) or 0 if no buffer is being returned.

#define USB_EVENT_TX_COMPLETE   (USB_EVENT_BASE + 5)

Data has been sent and acknowledged. If this event is received via the USB buffer callback, the ulMsgValue parameter indicates the number of bytes from the transmit buffer that have been successfully transmitted and acknowledged.

#define USBERR_DEV_RX_OVERRUN   0x00040000

The device was unable to receive a packet from the host since the receive FIFO is full.

#define USBERR_HOST_EP0_NAK_TO   0x00000080

The host received NAK on endpoint 0 for longer than the configured timeout.

#define USBERR_HOST_IN_NAK_TO   0x00080000

The host received NAK on an IN endpoint for longer than the specified timeout period (interrupt, bulk and control modes).

#define USBERR_HOST_OUT_NAK_TO   0x00000080

The host received NAK on an OUT endpoint for longer than the specified timeout period (bulk, interrupt and control modes).

Typedef Documentation

typedef uint32_t(* tUSBCallback) (struct usbGadgetObj *pGadgetObject, void *pvCBData, uint32_t ulEvent, uint32_t ulMsgParam, void *pvMsgData)

USB callback function.

Parameters
pvCBDatais the callback pointer associated with the instance generating the callback. This is a value provided by the client during initialization of the instance making the callback.
ulEventis the identifier of the asynchronous event which is being notified to the client.
ulMsgParamis an event-specific parameter.
pvMsgDatais an event-specific data pointer.

A function pointer provided to the USB layer by the application which will be called to notify it of all asynchronous events relating to data transmission or reception. This callback is used by device class drivers and host pipe functions.

Returns
Returns an event-dependent value.

Enumeration Type Documentation

enum tUSBMode

The operating mode required by the USB library client. This type is used by applications which wish to be able to switch between host and device modes by calling the USBStackModeSet() API.

Enumerator
USB_MODE_DEVICE 

The application wishes to operate as a USB device.

USB_MODE_HOST 

The application wishes to operate as a USB host.

USB_MODE_OTG 

The application wishes to operate as both a host and device using On-The-Go protocols to negotiate.

USB_MODE_NONE 

A marker indicating that no USB mode has yet been set by the application.

Function Documentation

tDescriptorHeader * USBDescGet ( tDescriptorHeader *  psDesc,
uint32_t  ulSize,
uint32_t  ulType,
uint32_t  ulIndex 
)

Determines the number of individual descriptors of a particular type within a supplied buffer.

Parameters
psDescpoints to the first byte of a block of standard USB descriptors.
ulSizeis the number of bytes of descriptor data found at pointer psDesc.
ulTypeidentifies the type of descriptor that is to be found. If the value is USB_DESC_ANY, the function returns a pointer to the n-th descriptor regardless of type.
ulIndexis the zero based index of the descriptor whose pointer is to be returned. For example, passing value 1 in ulIndex returns the second matching descriptor.

Return a pointer to the n-th descriptor of a particular type found in the block of ulSize bytes starting at psDesc.

Returns
Returns a pointer to the header of the required descriptor if found or NULL otherwise.
static tInterfaceDescriptor* USBDescGetAlternateInterface ( tConfigDescriptor *  psConfig,
unsigned char  ucInterfaceNumber,
uint32_t  ulIndex 
)
static

Returns a pointer to the n-th interface descriptor in a config descriptor with the supplied interface number.

Parameters
psConfigpoints to the first byte of a standard USB configuration descriptor.
ucInterfaceNumberis the interface number of the descriptor that is being queried.
ulIndexis the zero based index of the descriptor to return.

This function returns a pointer to the n-th interface descriptor in the supplied configuration which has the requested interface number. It may be used by a client to retrieve the descriptors for each alternate setting of a given interface within the configuration passed.

Returns
Returns a pointer to the n-th interface descriptor with interface number as specified or NULL of this descriptor does not exist.
tInterfaceDescriptor * USBDescGetInterface ( tConfigDescriptor *  psConfig,
uint32_t  ulIndex,
uint32_t  ulAlt 
)

Returns a pointer to the n-th interface descriptor in a configuration descriptor that applies to the supplied alternate setting number.

Parameters
psConfigpoints to the first byte of a standard USB configuration descriptor.
ulIndexis the zero based index of the interface that is to be found. If ulAlt is set to a value other than USB_DESC_ANY, this will be equivalent to the interface number being searched for.
ulAltis the alternate setting number which is to be searched for. If this value is USB_DESC_ANY, the alternate setting is ignored and all interface descriptors are considered in the search.

Return a pointer to the n-th interface descriptor found in the supplied configuration descriptor. If ulAlt is not USB_DESC_ANY, only interface descriptors which are part of the supplied alternate setting are considered in the search otherwise all interface descriptors are considered.

Note that, although alternate settings can be applied on an interface-by- interface basis, the number of interfaces offered is fixed for a given config descriptor. Hence, this function will correctly find the unique interface descriptor for that interface's alternate setting number ulAlt if ulIndex is set to the required interface number and ulAlt is set to a valid alternate setting number for that interface.

Returns
Returns a pointer to the required interface descriptor if found or NULL otherwise.
tEndpointDescriptor * USBDescGetInterfaceEndpoint ( tInterfaceDescriptor *  psInterface,
uint32_t  ulIndex,
uint32_t  ulSize 
)

Return a pointer to the n-th endpoint descriptor in the supplied interface descriptor.

Parameters
psInterfacepoints to the first byte of a standard USB interface descriptor.
ulIndexis the zero based index of the endpoint that is to be found.
ulSizecontains the maximum number of bytes that the function may search beyond psInterface while looking for the requested endpoint descriptor.

Return a pointer to the n-th endpoint descriptor found in the supplied interface descriptor. If the ulIndex parameter is invalid (greater than or equal to the bNumEndpoints field of the interface descriptor) or the endpoint cannot be found within ulSize bytes of the interface descriptor pointer, the function will return NULL.

Note that, although the USB 2.0 specification states that endpoint descriptors must follow the interface descriptor that they relate to, it also states that device specific descriptors should follow any standard descriptor that they relate to. As a result, we cannot assume that each interface descriptor will be followed by nothing but an ordered list of its own endpoints and, hence, the function needs to be provided ulSize to limit the search range.

Returns
Returns a pointer to the requested endpoint descriptor if found or NULL otherwise.
uint32_t USBDescGetNum ( tDescriptorHeader *  psDesc,
uint32_t  ulSize,
uint32_t  ulType 
)

Determines the number of individual descriptors of a particular type within a supplied buffer.

Parameters
psDescpoints to the first byte of a block of standard USB descriptors.
ulSizeis the number of bytes of descriptor data found at pointer psDesc.
ulTypeidentifies the type of descriptor that is to be counted. If the value is USB_DESC_ANY, the function returns the total number of descriptors regardless of type.

This function can be used to count the number of descriptors of a particular type within a block of descriptors. The caller can provide a specific type value which the function matches against the second byte of each descriptor or, alternatively, can specify USB_DESC_ANY to have the function count all descriptors regardless of their type.

Returns
Returns the number of descriptors found in the supplied block of data.
uint32_t USBDescGetNumAlternateInterfaces ( tConfigDescriptor *  psConfig,
unsigned char  ucInterfaceNumber 
)

Determines the number of different alternate configurations for a given interface within a configuration descriptor.

Parameters
psConfigpoints to the first byte of a standard USB configuration descriptor.
ucInterfaceNumberis the interface number for which the number of alternate configurations is to be counted.

This function can be used to count the number of alternate settings for a specific interface within a configuration.

Returns
Returns the number of alternate versions of the specified interface or 0 if the interface number supplied cannot be found in the config descriptor.

Copyright 2016, Texas Instruments Incorporated