/*
* Copyright (C) 2009-2018 Texas Instruments Incorporated - www.ti.com
*
*
* 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.
*
*/
/**
* @file usblib.h
*
* @brief Main header file for the USB Library.
*
*/
#ifndef __USBLIB_H__
#define __USBLIB_H__
/******************************************************************************
*
* If building with a C++ compiler, make all of the definitions in this header
* have a C binding.
*
*****************************************************************************/
#ifdef __cplusplus
extern "C"
{
#endif
/* standard device requests -- USB_SetupDataPacket::bRequest */
#define USB_REQUEST_GETSTATUS (0u)
#define USB_REQUEST_CLEARFEATURE (1u)
#define USB_REQUEST_SETFEATURE (3u)
#define USB_REQUEST_SETADDRESS (5u)
#define USB_REQUEST_GETDESCRIPTOR (6u)
#define USB_REQUEST_SETDESCRIPTOR (7u)
#define USB_REQUEST_GETCONFIGURATION (8u)
#define USB_REQUEST_SETCONFIGURATION (9u)
#define USB_REQUEST_GETINTERFACE (10u)
#define USB_REQUEST_SETINTERFACE (11u)
#define USB_REQUEST_SYNCHFRAME (12u)
/** ***************************************************************************
*
* This is the maximum number of endpoints supported by the usblib.
*
*****************************************************************************/
#define USBLIB_NUM_EP 16u /* Number of supported endpoints. */
/******************************************************************************
*
* The following macro allows compiler-independent syntax to be used to
* define packed structures. A typical structure definition using these
* macros will look similar to the following example:
*
* #ifdef ewarm
* #pragma pack(1)
* #endif
*
* typedef struct _PackedStructName
* {
* uint32 ulFirstField;
* char cCharMember;
* uint16 usShort;
* }
* PACKED tPackedStructName;
*
* #ifdef ewarm
* #pragma pack()
* #endif
*
* The conditional blocks related to ewarm include the #pragma pack() lines
* only if the IAR Embedded Workbench compiler is being used. Unfortunately,
* it is not possible to emit a #pragma from within a macro definition so this
* must be done explicitly.
*
*****************************************************************************/
#if defined(ccs) || \
defined(codered) || \
defined(gcc) || \
defined(rvmdk) || \
defined(__ARMCC_VERSION) || \
defined(sourcerygxx)
#define PACKED __attribute__ ((packed))
#elif defined(ewarm) || defined(__IAR_SYSTEMS_ICC__)
#define PACKED
#elif (__TMS470__)
#define PACKED __attribute__ ((packed))
#else
#error Unrecognized COMPILER!
#endif
/******************************************************************************
*
* Assorted language IDs from the document "USB_LANGIDs.pdf" provided by the
* USB Implementers' Forum (Version 1.0).
*
*****************************************************************************/
#define USB_LANG_CHINESE_PRC 0x0804u /**< Chinese (PRC) */
#define USB_LANG_CHINESE_TAIWAN 0x0404u /**< Chinese (Taiwan) */
#define USB_LANG_EN_US 0x0409u /**< English (United States) */
#define USB_LANG_EN_UK 0x0809u /**< English (United Kingdom) */
#define USB_LANG_EN_AUS 0x0C09u /**< English (Australia) */
#define USB_LANG_EN_CA 0x1009u /**< English (Canada) */
#define USB_LANG_EN_NZ 0x1409u /**< English (New Zealand) */
#define USB_LANG_FRENCH 0x040Cu /**< French (Standard) */
#define USB_LANG_GERMAN 0x0407u /**< German (Standard) */
#define USB_LANG_HINDI 0x0439u /**< Hindi */
#define USB_LANG_ITALIAN 0x0410u /**< Italian (Standard) */
#define USB_LANG_JAPANESE 0x0411u /**< Japanese */
#define USB_LANG_KOREAN 0x0412u /**< Korean */
#define USB_LANG_ES_TRAD 0x040Au /**< Spanish (Traditional) */
#define USB_LANG_ES_MODERN 0x0C0Au /**< Spanish (Modern) */
#define USB_LANG_SWAHILI 0x0441u /**< Swahili (Kenya) */
#define USB_LANG_URDU_IN 0x0820u /**< Urdu (India) */
#define USB_LANG_URDU_PK 0x0420u /**< Urdu (Pakistan) */
/** ***************************************************************************
*
* @ingroup usbchap9_src
* @{
*
*****************************************************************************/
/******************************************************************************
*
* Note:
*
* Structure definitions which are derived directly from the USB specification
* use field names from the specification. Since a somewhat different version
* of Hungarian prefix notation is used from the Stellaris standard, beware of
* making assumptions about field sizes based on the field prefix when using
* these structures. Of particular note is the difference in the meaning of
* the 'i' prefix. In USB structures, this indicates a single byte index
* whereas in Stellaris code, this is a 32 bit integer.
*
*****************************************************************************/
/******************************************************************************
*
* All structures defined in this section of the header require byte packing of
* fields. This is usually accomplished using the PACKED macro but, for IAR
* Embedded Workbench, this requires a pragma.
*
*****************************************************************************/
#if defined(ewarm) || defined(__IAR_SYSTEMS_ICC__)
#pragma pack(1)
#endif
/******************************************************************************
*
* Definitions related to standard USB device requests (sections 9.3 & 9.4)
*
*****************************************************************************/
/** ***************************************************************************
*
* @brief The standard USB request header as defined in section 9.3 of the
* USB 2.0 specification.
*
*****************************************************************************/
typedef struct
{
/**
* @brief Determines the type and direction of the request.
*/
uint8 bmRequestType;
/**
* @brief Identifies the specific request being made.
*/
uint8 bRequest;
/**
* @brief Word-sized field that varies according to the request.
*/
uint16 wValue;
/**
* @brief Word-sized field that varies according to the request; typically used
* to pass an index or offset.
*/
uint16 wIndex;
/**
* @brief The number of bytes to transfer if there is a data stage to the
* request.
*/
uint16 wLength;
}
PACKED tUSBRequest;
/******************************************************************************
*
* The following defines are used with the bmRequestType member of tUSBRequest.
*
* Request types have 3 bit fields:
* 4:0 - Is the recipient type.
* 6:5 - Is the request type.
* 7 - Is the direction of the request.
*
*****************************************************************************/
#define USB_RTYPE_DIR_IN 0x80u
#define USB_RTYPE_DIR_OUT 0x00u
#define USB_RTYPE_TYPE_M 0x60u
#define USB_RTYPE_VENDOR 0x40u
#define USB_RTYPE_CLASS 0x20u
#define USB_RTYPE_STANDARD 0x00u
#define USB_RTYPE_RECIPIENT_M 0x1fu
#define USB_RTYPE_OTHER 0x03u
#define USB_RTYPE_ENDPOINT 0x02u
#define USB_RTYPE_INTERFACE 0x01u
#define USB_RTYPE_DEVICE 0x00u
/******************************************************************************
*
* Standard USB requests IDs used in the bRequest field of tUSBRequest.
*
*****************************************************************************/
#define USBREQ_GET_STATUS 0x00u
#define USBREQ_CLEAR_FEATURE 0x01u
#define USBREQ_SET_FEATURE 0x03u
#define USBREQ_SET_ADDRESS 0x05u
#define USBREQ_GET_DESCRIPTOR 0x06u
#define USBREQ_SET_DESCRIPTOR 0x07u
#define USBREQ_GET_CONFIG 0x08u
#define USBREQ_SET_CONFIG 0x09u
#define USBREQ_GET_INTERFACE 0x0au
#define USBREQ_SET_INTERFACE 0x0bu
#define USBREQ_SYNC_FRAME 0x0cu
#define USBREQ_COUNT (USBREQ_SYNC_FRAME + 1u)
/******************************************************************************
*
* Data returned from a USBREQ_GET_STATUS request to a device.
*
*****************************************************************************/
#define USB_STATUS_SELF_PWR 0x0001u /**< Currently self powered. */
#define USB_STATUS_BUS_PWR 0x0000u /**< Currently bus-powered. */
#define USB_STATUS_PWR_M 0x0001u /**< Mask for power mode. */
#define USB_STATUS_REMOTE_WAKE 0x0002u /**< Remote wake-up is currently
enabled. */
/******************************************************************************
*
* Feature Selectors (tUSBRequest.wValue) passed on USBREQ_CLEAR_FEATURE and
* USBREQ_SET_FEATURE.
*
*****************************************************************************/
#define USB_FEATURE_EP_HALT 0x0000u /**< Endpoint halt feature. */
#define USB_FEATURE_REMOTE_WAKE 0x0001u /**< Remote wake feature, device only. */
#define USB_FEATURE_TEST_MODE 0x0002u /**< Test mode */
/******************************************************************************
*
* Endpoint Selectors (tUSBRequest.wIndex) passed on USBREQ_CLEAR_FEATURE,
* USBREQ_SET_FEATURE and USBREQ_GET_STATUS.
*
*****************************************************************************/
#define USB_REQ_EP_NUM_M 0x007Fu
#define USB_REQ_EP_DIR_M 0x0080u
#define USB_REQ_EP_DIR_IN 0x0080u
#define USB_REQ_EP_DIR_OUT 0x0000u
/******************************************************************************
*
* Standard USB descriptor types. These values are passed in the upper bytes
* of tUSBRequest.wValue on USBREQ_GET_DESCRIPTOR and also appear in the
* bDescriptorType field of standard USB descriptors.
*
*****************************************************************************/
#define USB_DTYPE_DEVICE 1u
#define USB_DTYPE_CONFIGURATION 2u
#define USB_DTYPE_STRING 3u
#define USB_DTYPE_INTERFACE 4u
#define USB_DTYPE_ENDPOINT 5u
#define USB_DTYPE_DEVICE_QUAL 6u
#define USB_DTYPE_OSPEED_CONF 7u
#define USB_DTYPE_INTERFACE_PWR 8u
#define USB_DTYPE_OTG 9u
#define USB_DTYPE_INTERFACE_ASC 11u
#define USB_DTYPE_CS_INTERFACE 36u
/******************************************************************************
*
* Definitions related to USB descriptors (sections 9.5 & 9.6)
*
*****************************************************************************/
/** ***************************************************************************
*
* @brief This structure describes a generic descriptor header. These
* fields are to be found at the beginning of all valid USB
* descriptors.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The length of this descriptor (including this length byte) expressed
* in bytes.
*/
uint8 bLength;
/**
* @brief The type identifier of the descriptor whose information follows.
* For standard descriptors, this field could contain, for example,
* USB_DTYPE_DEVICE to identify a device descriptor or
* USB_DTYPE_ENDPOINT to identify an endpoint descriptor.
*/
uint8 bDescriptorType;
}
PACKED tDescriptorHeader;
/** ***************************************************************************
*
* @brief This structure describes the USB device descriptor as defined in USB
* 2.0 specification section 9.6.1.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The length of this descriptor in bytes. All device descriptors
* are 18 bytes long.
*/
uint8 bLength;
/**
* @brief The type of the descriptor. For a device descriptor, this will
* be USB_DTYPE_DEVICE (1).
*/
uint8 bDescriptorType;
/**
* @brief The USB Specification Release Number in BCD format.
* For USB 2.0, this will be 0x0200.
*/
uint16 bcdUSB;
/**
* @brief The device class code.
*/
uint8 bDeviceClass;
/**
* @brief The device subclass code. This value qualifies the value
* found in the bDeviceClass field.
*/
uint8 bDeviceSubClass;
/**
* @brief The device protocol code. This value is qualified by the
* values of bDeviceClass and bDeviceSubClass.
*/
uint8 bDeviceProtocol;
/**
* @brief The maximum packet size for endpoint zero. Valid values
* are 8, 16, 32 and 64.
*/
uint8 bMaxPacketSize0;
/**
* @brief The device Vendor ID (VID) as assigned by the USB-IF.
*/
uint16 idVendor;
/**
* @brief The device Product ID (PID) as assigned by the manufacturer.
*/
uint16 idProduct;
/**
* @brief The device release number in BCD format.
*/
uint16 bcdDevice;
/**
* @brief The index of a string descriptor describing the manufacturer.
*/
uint8 iManufacturer;
/**
* @brief The index of a string descriptor describing the product.
*/
uint8 iProduct;
/**
* @brief The index of a string descriptor describing the device's serial
* number.
*/
uint8 iSerialNumber;
/**
* @brief The number of possible configurations offered by the device.
* This field indicates the number of distinct configuration
* descriptors that the device offers.
*/
uint8 bNumConfigurations;
}
PACKED tDeviceDescriptor;
/******************************************************************************
*
* USB Device Class codes used in the tDeviceDescriptor.bDeviceClass field.
* Definitions for the bDeviceSubClass and bDeviceProtocol fields are device
* specific and can be found in the appropriate device class header files.
*
*****************************************************************************/
#define USB_CLASS_DEVICE 0x00u
#define USB_CLASS_AUDIO 0x01u
#define USB_CLASS_CDC 0x02u
#define USB_CLASS_HID 0x03u
#define USB_CLASS_PHYSICAL 0x05u
#define USB_CLASS_IMAGE 0x06u
#define USB_CLASS_PRINTER 0x07u
#define USB_CLASS_MASS_STORAGE 0x08u
#define USB_CLASS_HUB 0x09u
#define USB_CLASS_CDC_DATA 0x0au
#define USB_CLASS_SMART_CARD 0x0bu
#define USB_CLASS_SECURITY 0x0du
#define USB_CLASS_VIDEO 0x0eu
#define USB_CLASS_HEALTHCARE 0x0fu
#define USB_CLASS_DIAG_DEVICE 0xdcu
#define USB_CLASS_WIRELESS 0xe0u
#define USB_CLASS_MISC 0xefu
#define USB_CLASS_APP_SPECIFIC 0xfeu
#define USB_CLASS_VEND_SPECIFIC 0xffu
#define USB_CLASS_EVENTS 0xffffffffU
/******************************************************************************
*
* Generic values for undefined subclass and protocol.
*
*****************************************************************************/
#define USB_SUBCLASS_UNDEFINED 0x00u
#define USB_PROTOCOL_UNDEFINED 0x00u
/******************************************************************************
*
* The following are the miscellaneous subclass values.
*
*****************************************************************************/
#define USB_MISC_SUBCLASS_SYNC 0x01u
#define USB_MISC_SUBCLASS_COMMON 0x02u
/******************************************************************************
*
* These following are miscellaneous protocol values.
*
*****************************************************************************/
#define USB_MISC_PROTOCOL_IAD 0x01u
/** ***************************************************************************
*
* @brief This structure describes the USB device qualifier descriptor as
* defined in the USB 2.0 specification, section 9.6.2.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The length of this descriptor in bytes. All device qualifier
* descriptors are 10 bytes long.
*/
uint8 bLength;
/**
* @brief The type of the descriptor. For a device descriptor, this will
* be USB_DTYPE_DEVICE_QUAL (6).
*/
uint8 bDescriptorType;
/**
* @brief The USB Specification Release Number in BCD format.
* For USB 2.0, this will be 0x0200.
*/
uint16 bcdUSB;
/**
* @brief The device class code.
*/
uint8 bDeviceClass;
/**
* @brief The device subclass code. This value qualifies the value
* found in the bDeviceClass field.
*/
uint8 bDeviceSubClass;
/**
* @brief The device protocol code. This value is qualified by the
* values of bDeviceClass and bDeviceSubClass.
*/
uint8 bDeviceProtocol;
/**
* @brief The maximum packet size for endpoint zero when operating at
* a speed other than high speed.
*/
uint8 bMaxPacketSize0;
/**
* @brief The number of other-speed configurations supported.
*/
uint8 bNumConfigurations;
/**
* @brief Reserved for future use. Must be set to zero.
*/
uint8 bReserved;
}
PACKED tDeviceQualifierDescriptor;
/** ***************************************************************************
*
* This structure describes the USB configuration descriptor as defined in
* USB 2.0 specification section 9.6.3. This structure also applies to the
* USB other speed configuration descriptor defined in section 9.6.4.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The length of this descriptor in bytes. All configuration
* descriptors are 9 bytes long.
*/
uint8 bLength;
/**
* @brief The type of the descriptor. For a configuration descriptor,
* this will be USB_DTYPE_CONFIGURATION (2).
*/
uint8 bDescriptorType;
/**
* @brief The total length of data returned for this configuration.
* This includes the combined length of all descriptors
* (configuration, interface, endpoint and class- or
* vendor-specific) returned for this configuration.
*/
uint16 wTotalLength;
/**
* @brief The number of interface supported by this configuration.
*/
uint8 bNumInterfaces;
/**
* @brief The value used as an argument to the SetConfiguration standard
* request to select this configuration.
*/
uint8 bConfigurationValue;
/**
* @brief The index of a string descriptor describing this configuration.
*/
uint8 iConfiguration;
/**
* @brief Attributes of this configuration.
*/
uint8 bmAttributes;
/**
* @brief The maximum power consumption of the USB device from the bus
* in this configuration when the device is fully operational.
* This is expressed in units of 2mA so, for example,
* 100 represents 200mA.
*/
uint8 bMaxPower;
}
PACKED tConfigDescriptor;
/******************************************************************************
*
* Flags used in constructing the value assigned to the field
* tConfigDescriptor.bmAttributes. Note that bit 7 is reserved and must be set
* to 1.
*
*****************************************************************************/
#define USB_CONF_ATTR_PWR_M 0xC0u
#define USB_CONF_ATTR_SELF_PWR 0xC0u
#define USB_CONF_ATTR_BUS_PWR 0x80u
#define USB_CONF_ATTR_RWAKE 0xA0u
/** ***************************************************************************
*
* This structure describes the USB interface descriptor as defined in USB
* 2.0 specification section 9.6.5.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The length of this descriptor in bytes. All interface
* descriptors are 9 bytes long.
*/
uint8 bLength;
/**
* @brief The type of the descriptor. For an interface descriptor, this
* will be USB_DTYPE_INTERFACE (4).
*/
uint8 bDescriptorType;
/**
* @brief The number of this interface. This is a zero based index into
* the array of concurrent interfaces supported by this
* configuration.
*/
uint8 bInterfaceNumber;
/**
* @brief The value used to select this alternate setting for the
* interface defined in bInterfaceNumber.
*/
uint8 bAlternateSetting;
/**
* @brief The number of endpoints used by this interface (excluding
* endpoint zero).
*/
uint8 bNumEndpoints;
/**
* @brief The interface class code as assigned by the USB-IF.
*/
uint8 bInterfaceClass;
/**
* @brief The interface subclass code as assigned by the USB-IF.
*/
uint8 bInterfaceSubClass;
/**
* @brief The interface protocol code as assigned by the USB-IF.
*/
uint8 bInterfaceProtocol;
/**
* @brief The index of a string descriptor describing this interface.
*/
uint8 iInterface;
}
PACKED tInterfaceDescriptor;
/** ***************************************************************************
*
* This structure describes the USB endpoint descriptor as defined in USB
* 2.0 specification section 9.6.6.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The length of this descriptor in bytes. All endpoint
* descriptors are 7 bytes long.
*/
uint8 bLength;
/**
* @brief The type of the descriptor. For an endpoint descriptor, this
* will be USB_DTYPE_ENDPOINT (5).
*/
uint8 bDescriptorType;
/**
* @brief The address of the endpoint. This field contains the endpoint
* number ORed with flag USB_EP_DESC_OUT or USB_EP_DESC_IN to
* indicate the endpoint direction.
*/
uint8 bEndpointAddress;
/**
* @brief The endpoint transfer type, USB_EP_ATTR_CONTROL,
* USB_EP_ATTR_ISOC, USB_EP_ATTR_BULK or USB_EP_ATTR_INT and,
* if isochronous, additional flags indicating usage type and
* synchronization method.
*/
uint8 bmAttributes;
/**
* @brief The maximum packet size this endpoint is capable of sending or
* receiving when this configuration is selected. For high speed
* isochronous or interrupt endpoints, bits 11 and 12 are used to
* pass additional information.
*/
uint16 wMaxPacketSize;
/**
* @brief The polling interval for data transfers expressed in frames or
* micro frames depending upon the operating speed.
*/
uint8 bInterval;
}
PACKED tEndpointDescriptor;
/******************************************************************************
*
* Flags used in constructing the value assigned to the field
* tEndpointDescriptor.bEndpointAddress.
*
*****************************************************************************/
#define USB_EP_DESC_OUT 0x00u
#define USB_EP_DESC_IN 0x80u
#define USB_EP_DESC_NUM_M 0x0fu
/******************************************************************************
*
* Mask used to extract the maximum packet size (in bytes) from the
* wMaxPacketSize field of the endpoint descriptor.
*
*****************************************************************************/
#define USB_EP_MAX_PACKET_COUNT_M 0x07FFu
/******************************************************************************
*
* Endpoint attributes used in tEndpointDescriptor.bmAttributes.
*
*****************************************************************************/
#define USB_EP_ATTR_CONTROL 0x00u
#define USB_EP_ATTR_ISOC 0x01u
#define USB_EP_ATTR_BULK 0x02u
#define USB_EP_ATTR_INT 0x03u
#define USB_EP_ATTR_TYPE_M 0x03u
#define USB_EP_ATTR_ISOC_M 0x0cu
#define USB_EP_ATTR_ISOC_NOSYNC 0x00u
#define USB_EP_ATTR_ISOC_ASYNC 0x04u
#define USB_EP_ATTR_ISOC_ADAPT 0x08u
#define USB_EP_ATTR_ISOC_SYNC 0x0cu
#define USB_EP_ATTR_USAGE_M 0x30u
#define USB_EP_ATTR_USAGE_DATA 0x00u
#define USB_EP_ATTR_USAGE_FEEDBACK 0x10u
#define USB_EP_ATTR_USAGE_IMPFEEDBACK 0x20u
/** ***************************************************************************
*
* @brief This structure describes the USB string descriptor for index 0 as
* defined in USB 2.0 specification section 9.6.7. Note that the
* number of language IDs is variable and can be determined by
* examining bLength. The number of language IDs present in the
* descriptor is given by ((bLength - 2) / 2).
*
*****************************************************************************/
typedef struct
{
/**
* @brief The length of this descriptor in bytes. This value will vary
* depending upon the number of language codes provided in the
* descriptor.
*/
uint8 bLength;
/**
* @brief The type of the descriptor. For a string descriptor, this will
* be USB_DTYPE_STRING (3).
*/
uint8 bDescriptorType;
/**
* @brief The language code (LANGID) for the first supported language.
* Note that this descriptor may support multiple languages, in
* which case, the number of elements in the wLANGID array will
* increase and bLength will be updated accordingly.
*/
uint16 wLANGID[1];
}
PACKED tString0Descriptor;
/** ***************************************************************************
*
* @brief This structure describes the USB string descriptor for all string
* indexes other than 0 as defined in USB 2.0 specification
* section 9.6.7.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The length of this descriptor in bytes. This value will be
* 2 greater than the number of bytes comprising the UNICODE
* string that the descriptor contains.
*/
uint8 bLength;
/**
* @brief The type of the descriptor. For a string descriptor, this will
* be USB_DTYPE_STRING (3).
*/
uint8 bDescriptorType;
/**
* @brief The first byte of the UNICODE string. This string is not NULL
* terminated. Its length (in bytes) can be computed by
* subtracting 2 from the value in the bLength field.
*/
uint8 bString;
}
PACKED tStringDescriptor;
/** ***************************************************************************
*
* Write a 2 byte uint16 value to a USB descriptor block.
*
* @param usValue is the two byte uint16 that is to be written to
* the descriptor.
*
* This helper macro is used in descriptor definitions to write two-byte
* values. Since the configuration descriptor contains all interface and
* endpoint descriptors in a contiguous block of memory, these descriptors are
* typically defined using an array of bytes rather than as packed structures.
*
* @return Not a function.
*
*****************************************************************************/
#define USBShort(usValue) (uint8_t)((uint16_t)(usValue) & (uint16_t)0x00ffU), (uint8_t)((uint16_t)(usValue) >> 8U)
/** ***************************************************************************
*
* Write a 3 byte uint32 value to a USB descriptor block.
*
* @param ulValue is the three byte unsigned value that is to be written to the
* descriptor.
*
* This helper macro is used in descriptor definitions to write three-byte
* values. Since the configuration descriptor contains all interface and
* endpoint descriptors in a contiguous block of memory, these descriptors are
* typically defined using an array of bytes rather than as packed structures.
*
* @return Not a function.
*
*****************************************************************************/
#define USB3Byte(ulValue) (ulValue & 0xff), \
((ulValue >> 8) & 0xff), \
((ulValue >> 16) & 0xff)
/** ***************************************************************************
*
* Write a 4 byte uint32 value to a USB descriptor block.
*
* @param ulValue is the four byte uint32 that is to be written to the
* descriptor.
*
* This helper macro is used in descriptor definitions to write four-byte
* values. Since the configuration descriptor contains all interface and
* endpoint descriptors in a contiguous block of memory, these descriptors are
* typically defined using an array of bytes rather than as packed structures.
*
* @return Not a function.
*
*****************************************************************************/
#define USBLong(ulValue) (ulValue & 0xff), \
((ulValue >> 8) & 0xff), \
((ulValue >> 16) & 0xff), \
((ulValue >> 24) & 0xff)
/** ***************************************************************************
*
* Traverse to the next USB descriptor in a block.
*
* @param ptr points to the first byte of a descriptor in a block of
* USB descriptors.
*
* This macro aids in traversing lists of descriptors by returning a pointer
* to the next descriptor in the list given a pointer to the current one.
*
* @return Returns a pointer to the next descriptor in the block following
* @e ptr.
*
*****************************************************************************/
#define NEXT_USB_DESCRIPTOR(ptr) \
(tDescriptorHeader *)(((uint8 *)(ptr)) + \
(ptr)->bLength)
/******************************************************************************
*
* Return to default packing when using the IAR Embedded Workbench compiler.
*
*****************************************************************************/
#if defined(ewarm) || defined(__IAR_SYSTEMS_ICC__)
#pragma pack()
#endif
/** ***************************************************************************
*
* Close the usbchap9_src Doxygen group.
* @}
*
*****************************************************************************/
/** ***************************************************************************
*
* @ingroup device_api
* @{
*
*****************************************************************************/
/** ***************************************************************************
*
* @brief Function prototype for any standard USB request.
*
*****************************************************************************/
typedef void (* tStdRequest)(void * pvInstance, tUSBRequest * pUSBRequest);
/** ***************************************************************************
*
* @brief Data callback for receiving data from an endpoint.
*
*****************************************************************************/
typedef void (* tInfoCallback)(void * pvInstance, uint32 ulInfo);
/** ***************************************************************************
*
* @brief Callback made to indicate that an interface alternate setting
* change has occurred.
*
*****************************************************************************/
typedef void (* tInterfaceCallback)(void * pvInstance,
uint8 ucInterfaceNum,
uint8 ucAlternateSetting);
/** ***************************************************************************
*
* @brief Generic interrupt handler callbacks.
*
*****************************************************************************/
typedef void (* tUSBIntHandler)(void * pvInstance);
/** ***************************************************************************
*
* @brief Interrupt handler callbacks that have status information.
*
*****************************************************************************/
typedef void (* tUSBEPIntHandler)(void * pvInstance,
uint32 ulStatus);
/** ***************************************************************************
*
* @brief Generic handler callbacks that are used when the callers needs to
* call into an instance of class.
*
*****************************************************************************/
typedef void (* tUSBDeviceHandler)(void * pvInstance,
uint32 ulRequest,
void * pvRequestData);
/** ***************************************************************************
*
* @brief USB event handler functions used during enumeration and operation
* of the device stack.
*
*****************************************************************************/
typedef struct
{
/**
* @brief This callback is made whenever the USB host requests a
* non-standard descriptor from the device.
*/
tStdRequest pfnGetDescriptor;
/**
* @brief This callback is made whenever the USB host makes a
* non-standard request.
*/
tStdRequest pfnRequestHandler;
/**
* @brief This callback is made in response to a SetInterface request
* from the host.
*/
tInterfaceCallback pfnInterfaceChange;
/**
* @brief This callback is made in response to a SetConfiguration
* request from the host.
*/
tInfoCallback pfnConfigChange;
/**
* @brief This callback is made when data has been received following
* to a call to USBDCDRequestDataEP0.
*/
tInfoCallback pfnDataReceived;
/**
* @brief This callback is made when data has been transmitted following
* a call to USBDCDSendDataEP0.
*/
tInfoCallback pfnDataSent;
/**
* @brief This callback is made when a USB reset is detected.
*/
tUSBIntHandler pfnResetHandler;
/**
* @brief This callback is made when the bus has been inactive long
* enough to trigger a suspend condition.
*/
tUSBIntHandler pfnSuspendHandler;
/**
* @brief This is called when resume signaling is detected.
*/
tUSBIntHandler pfnResumeHandler;
/**
* @brief This callback is made when the device is disconnected from
* the USB bus.
*/
tUSBIntHandler pfnDisconnectHandler;
/**
* @brief This callback is made to inform the device of activity on
* all endpoints other than endpoint zero.
*/
tUSBEPIntHandler pfnEndpointHandler;
/**
* @brief This generic handler is provided to allow requests based on
* a given instance to be passed into a device. This is commonly
* used by a top level composite device that is using multiple
* instances of a class.
*/
tUSBDeviceHandler pfnDeviceHandler;
}
tCustomHandlers;
/** ***************************************************************************
*
* @brief This structure defines how a given endpoint's FIFO is configured in
* relation to the maximum packet size for the endpoint as specified
* in the endpoint descriptor.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The multiplier to apply to an endpoint's maximum packet size
* when configuring the FIFO for that endpoint. For example,
* setting this value to 2 will result in a 128 byte FIFO being
* configured if bDoubleBuffer is FALSE and the associated
* endpoint is set to use a 64 byte maximum packet size.
*/
uint8 cMultiplier;
/**
* @brief This field indicates whether to configure an endpoint's FIFO
* to be double- or single-buffered. If TRUE, a double-buffered
* FIFO is created and the amount of required FIFO storage is
* multiplied by two.
*/
tBoolean bDoubleBuffer;
/**
* @brief This field defines endpoint mode flags which cannot be deduced
* from the configuration descriptor, namely any in the set
* USB_EP_AUTO_xxx or USB_EP_DMA_MODE_x. USBDCDConfig adds these
* flags to the endpoint mode and direction determined from the
* config descriptor before it configures the endpoint using a
* call to USBDevEndpointConfigSet().
*/
uint16 usEPFlags;
}
tFIFOEntry;
/** ***************************************************************************
*
* @brief This structure defines endpoint and FIFO configuration information
* for all endpoints that the device wishes to use. This information
* cannot be determined by examining the USB configuration descriptor
* and is provided to USBDCDConfig by the application to allow the USB
* controller endpoints to be correctly configured.
*
*****************************************************************************/
typedef struct
{
/**
* @brief An array containing one FIFO entry for each of the IN
* endpoints. Note that endpoint 0 is configured and managed by
* the USB device stack so is excluded from this array. The
* index 0 entry of the array corresponds to endpoint 1,
* index 1 to endpoint 2, etc.
*/
tFIFOEntry sIn[USBLIB_NUM_EP - 1];
/**
* @brief An array containing one FIFO entry for each of the OUT
* endpoints. Note that endpoint 0 is configured and managed by
* the USB device stack so is excluded from this array.
* The index 0 entry of the array corresponds to endpoint 1,
* index 1 to endpoint 2, etc.
*/
tFIFOEntry sOut[USBLIB_NUM_EP - 1];
}
tFIFOConfig;
/** ***************************************************************************
*
* @brief This structure defines a contiguous block of data which contains a
* group of descriptors that form part of a configuration descriptor
* for a device. It is assumed that a config section contains only
* whole descriptors. It is not valid to split a single descriptor
* across multiple sections.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The number of bytes of descriptor data pointed to by pucData.
*/
uint8 ucSize;
/**
* @brief A pointer to a block of data containing an integral number of
* SB descriptors which form part of a larger configuration
* descriptor.
*/
const uint8 * pucData;
}
tConfigSection;
/** ***************************************************************************
*
* @brief This is the top level structure defining a USB device configuration
* descriptor. A configuration descriptor contains a collection of
* device-specific descriptors in addition to the basic config,
* interface and endpoint descriptors. To allow flexibility in
* constructing the configuration, the descriptor is described in
* terms of a list of data blocks. The first block must contain the
* configuration descriptor itself and the following blocks are
* appended to this in order to produce the full descriptor sent to
* the host in response to a GetDescriptor request for the
* configuration descriptor.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The number of sections comprising the full descriptor for this
* configuration.
*/
uint8 ucNumSections;
/**
* @brief A pointer to an array of ucNumSections section pointers which
* must be concatenated to form the configuration descriptor.
*/
const tConfigSection * const * psSections;
}
tConfigHeader;
/** ***************************************************************************
*
* @brief This structure is passed to the USB library on a call to USBDCDInit
* and provides the library with information about the device that the
* application is implementing. It contains functions pointers for
* the various USB event handlers and pointers to each of the standard
* device descriptors.
*
*****************************************************************************/
typedef struct
{
/**
* @brief A pointer to a structure containing pointers to event handler
* functions provided by the client to support the operation of
* this device.
*/
tCustomHandlers sCallbacks;
/**
* @brief A pointer to the device descriptor for this device.
*/
const uint8 * pDeviceDescriptor;
/**
* @brief A pointer to an array of configuration descriptor pointers.
* Each entry in the array corresponds to one configuration that
* the device may be set to use by the USB host. The number of
* entries in the array must match the bNumConfigurations value
* in the device descriptor array, pDeviceDescriptor.
*/
const tConfigHeader * const * ppConfigDescriptors;
/**
* @brief A pointer to the string descriptor array for this device.
* This array must be arranged as follows:
*
* - [0] - Standard descriptor containing supported language codes.
* - [1] - String 1 for the first language listed in descriptor 0.
* - [2] - String 2 for the first language listed in descriptor 0.
* - ...
* - [n] - String n for the first language listed in descriptor 0.
* - [n+1] - String 1 for the second language listed in descriptor 0.
* - ...
* - [2n] - String n for the second language listed in descriptor 0.
* - [2n+1]- String 1 for the third language listed in descriptor 0.
* - ...
* - [3n] - String n for the third language listed in descriptor 0.
*
* and so on.
*/
const uint8 * const * ppStringDescriptors;
/**
* @brief The total number of descriptors provided in the ppStringDescriptors
* array.
*/
uint32 ulNumStringDescriptors;
/**
* @brief A structure defining how the USB controller FIFO is to be
* partitioned between the various endpoints. This member can be
* set to point to g_sUSBDefaultFIFOConfig if the default FIFO
* configuration is acceptable. This configuration sets each
* endpoint FIFO to be single buffered and sized to hold the
* maximum packet size for the endpoint.
*/
const tFIFOConfig * psFIFOConfig;
/**
* @brief This value will be passed back to all call back functions so
* that they have access to individual instance data based on the
* this pointer.
*/
void * pvInstance;
}
tDeviceInfo;
/** ***************************************************************************
*
* Close the Doxygen group.
* @}
*
*****************************************************************************/
/** ***************************************************************************
*
* @ingroup general_usblib_api
* @{
*
*****************************************************************************/
/******************************************************************************
*
* USB descriptor parsing functions found in usbdesc.c
*
*****************************************************************************/
/** ***************************************************************************
*
* @brief 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_DESC_ANY 0xFFFFFFFFu
extern uint32 USBDescGetNum(tDescriptorHeader * psDesc,
uint32 ulSize, uint32 ulType);
extern tDescriptorHeader * USBDescGet(tDescriptorHeader * psDesc,
uint32 ulSize,
uint32 ulType,
uint32 ulIndex);
extern uint32
USBDescGetNumAlternateInterfaces(tConfigDescriptor * psConfig,
uint8 ucInterfaceNumber);
extern tInterfaceDescriptor * USBDescGetInterface(tConfigDescriptor * psConfig,
uint32 ulIndex,
uint32 ulAltCfg);
extern tEndpointDescriptor *
USBDescGetInterfaceEndpoint(tInterfaceDescriptor * psInterface,
uint32 ulIndex,
uint32 ulSize);
/** ***************************************************************************
*
* 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.
*
*****************************************************************************/
typedef enum
{
/**
* @brief The application wishes to operate as a USB device.
*/
USB_MODE_DEVICE = 0,
/**
* @brief The application wishes to operate as a USB host.
*/
USB_MODE_HOST,
/**
* @brief The application wishes to operate as both a host and device
* using On-The-Go protocols to negotiate.
*/
USB_MODE_OTG,
/**
* @brief A marker indicating that no USB mode has yet been set by the
* application.
*/
USB_MODE_NONE
} tUSBMode;
/** ***************************************************************************
*
* A pointer to a USB mode callback function. This function is called by the
* USB library to indicate to the application which operating mode it should
* use, host or device.
*
*****************************************************************************/
typedef void (* tUSBModeCallback)(uint32 ulIndex, tUSBMode eMode);
/** ***************************************************************************
*
* Mode selection and dual mode interrupt steering functions.
*
*****************************************************************************/
extern void USBStackModeSet(uint32 ulIndex, tUSBMode eUSBMode,
tUSBModeCallback pfnCallback);
extern void USBDualModeInit(uint32 ulIndex);
extern void USBDualModeTerm(uint32 ulIndex);
extern void USBOTGMain(uint32 ulMsTicks);
extern void USBOTGPollRate(uint32 ulIndex, uint32 ulPollRate);
extern void USBOTGModeInit(uint32 ulIndex, uint32 ulPollRate,
void * pHostData, uint32 ulHostDataSize);
extern void USBOTGModeTerm(uint32 ulIndex);
extern void USB0OTGModeIntHandler(void);
extern void USB0DualModeIntHandler(void);
/** ***************************************************************************
*
* USB callback function.
*
* @param pvCBData is 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.
* @param ulEvent is the identifier of the asynchronous event which is being
* notified to the client.
* @param ulMsgParam is an event-specific parameter.
* @param pvMsgData is 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.
*
* @return Returns an event-dependent value.
*
*****************************************************************************/
typedef uint32 (* tUSBCallback)(void * pvCBData, uint32 ulEvent,
uint32 ulMsgParam,
void * pvMsgData);
/** ***************************************************************************
*
* Base identifiers for groups of USB events. These are used by both the
* device class drivers and host layer.
*
* USB_CLASS_EVENT_BASE is the lowest identifier that should be used for
* a class-specific event. Individual event bases are defined for each
* of the supported device class drivers. Events with IDs between
* USB_EVENT_BASE and USB_CLASS_EVENT_BASE are reserved for stack use.
*
*****************************************************************************/
#define USB_EVENT_BASE 0x0000u
#define USB_CLASS_EVENT_BASE 0x8000u
/** ***************************************************************************
*
* Event base identifiers for the various device classes supported in host
* and device modes.
* The first 0x800 values of a range are reserved for the device specific
* messages and the second 0x800 values of a range are used for the host
* specific messages for a given class.
*
*****************************************************************************/
#define USBD_CDC_EVENT_BASE (USB_CLASS_EVENT_BASE + 0u)
#define USBD_HID_EVENT_BASE (USB_CLASS_EVENT_BASE + 0x1000u)
#define USBD_HID_KEYB_EVENT_BASE (USBD_HID_EVENT_BASE + 0x100u)
#define USBD_BULK_EVENT_BASE (USB_CLASS_EVENT_BASE + 0x2000u)
#define USBD_MSC_EVENT_BASE (USB_CLASS_EVENT_BASE + 0x3000u)
#define USBD_AUDIO_EVENT_BASE (USB_CLASS_EVENT_BASE + 0x4000u)
#define USBH_CDC_EVENT_BASE (USBD_CDC_EVENT_BASE + 0x800u)
#define USBH_HID_EVENT_BASE (USBD_HID_EVENT_BASE + 0x800u)
#define USBH_BULK_EVENT_BASE (USBD_BULK_EVENT_BASE + 0x800u)
#define USBH_MSC_EVENT_BASE (USBD_MSC_EVENT_BASE + 0x800u)
#define USBH_AUDIO_EVENT_BASE (USBD_AUDIO_EVENT_BASE + 0x800u)
/** ***************************************************************************
*
* General events supported by device classes and host pipes.
*
*****************************************************************************/
/**
* @brief 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_CONNECTED (USB_EVENT_BASE + 0u)
/**
* @brief 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_DISCONNECTED (USB_EVENT_BASE + 1u)
/**
* @brief Data has been received and is in the buffer provided.
*/
#define USB_EVENT_RX_AVAILABLE (USB_EVENT_BASE + 2u)
/**
* @brief 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_DATA_REMAINING (USB_EVENT_BASE + 3u)
/**
* @brief This event is sent by a lower layer supporting DMA to request a
* buffer in which the next received packet may be stored.
* The \e ulMsgValue parameter indicates the maximum size of packet
* that can be received in this channel and \e 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
* \e ulMsgValue if the client knows that fewer bytes are expected
* to be received) or 0 if no buffer is being returned.
*/
#define USB_EVENT_REQUEST_BUFFER (USB_EVENT_BASE + 4u)
/**
* @brief Data has been sent and acknowledged. If this event is received via
* the USB buffer callback, the \e ulMsgValue parameter indicates the
* number of bytes from the transmit buffer that have been successfully
* transmitted and acknowledged.
*/
#define USB_EVENT_TX_COMPLETE (USB_EVENT_BASE + 5u)
/**
* @brief An error has been reported on the channel or pipe. The
* \e ulMsgValue parameter indicates the source(s) of the error and
* is the logical OR combination of "USBERR_" flags defined below.
*/
#define USB_EVENT_ERROR (USB_EVENT_BASE + 6u)
/**
* @brief The bus has entered suspend state.
*/
#define USB_EVENT_SUSPEND (USB_EVENT_BASE + 7u)
/**
* @brief The bus has left suspend state.
*/
#define USB_EVENT_RESUME (USB_EVENT_BASE + 8u)
/**
* @brief A scheduler event has occurred.
*/
#define USB_EVENT_SCHEDULER (USB_EVENT_BASE + 9u)
/**
* @brief A device or host has detected a stall condition.
*/
#define USB_EVENT_STALL (USB_EVENT_BASE + 10u)
/**
* @brief The host detected a power fault condition.
*/
#define USB_EVENT_POWER_FAULT (USB_EVENT_BASE + 11u)
/**
* @brief 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_POWER_ENABLE (USB_EVENT_BASE + 12u)
/**
* @brief The controller needs power removed, This is only generated on OTG
* parts if automatic power control is disabled.
*/
#define USB_EVENT_POWER_DISABLE (USB_EVENT_BASE + 13u)
/**
* @brief 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 \e pvInstance value should point to an instance of the device being
* accessed.
*
* The \e ulRequest should be USB_EVENT_COMP_IFACE_CHANGE.
*
* The \e 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_IFACE_CHANGE (USB_EVENT_BASE + 14u)
/**
* @brief 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 \e pvInstance value should point to an instance of the device being
* accessed.
*
* The \e ulRequest should be USB_EVENT_COMP_EP_CHANGE.
*
* The \e 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_EP_CHANGE (USB_EVENT_BASE + 15u)
/**
* @brief 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 \e pvInstance value should point to an instance of the device being
* accessed.
*
* The \e ulRequest should be USB_EVENT_COMP_STR_CHANGE.
*
* The \e 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_COMP_STR_CHANGE (USB_EVENT_BASE + 16u)
/**
* @brief 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 \e pvInstance value should point to an instance of the device being
* accessed.
*
* The \e ulRequest should be USB_EVENT_COMP_CONFIG.
*
* The \e pvRequestData should point to the beginning of the configuration
* descriptor for the device instance.
*/
#define USB_EVENT_COMP_CONFIG (USB_EVENT_BASE + 17u)
/** ***************************************************************************
*
* Error sources reported via USB_EVENT_ERROR.
*
*****************************************************************************/
/**
* @brief The host received an invalid PID in a transaction.
*/
#define USBERR_HOST_IN_PID_ERROR 0x01000000u
/**
* @brief The host did not receive a response from a device.
*/
#define USBERR_HOST_IN_NOT_COMP 0x00100000u
/**
* @brief The host received a stall on an IN endpoint.
*/
#define USBERR_HOST_IN_STALL 0x00400000u
/**
* @brief The host detected a CRC or bit-stuffing error (isochronous mode).
*/
#define USBERR_HOST_IN_DATA_ERROR 0x00080000u
/**
* @brief The host received NAK on an IN endpoint for longer than the
* specified timeout period (interrupt, bulk and control modes).
*/
#define USBERR_HOST_IN_NAK_TO 0x00080000u
/**
* @brief The host failed to communicate with a device via an IN endpoint.
*/
#define USBERR_HOST_IN_ERROR 0x00040000u
/**
* @brief The host receive FIFO is full.
*/
#define USBERR_HOST_IN_FIFO_FULL 0x00020000u /* RX FIFO full */
/**
* @brief The host received NAK on an OUT endpoint for longer than the
* specified timeout period (bulk, interrupt and control modes).
*/
#define USBERR_HOST_OUT_NAK_TO 0x00000080u
/**
* @brief The host did not receive a response from a device (isochronous mode).
*/
#define USBERR_HOST_OUT_NOT_COMP 0x00000080u
/**
* @brief The host received a stall on an OUT endpoint.
*/
#define USBERR_HOST_OUT_STALL 0x00000020u
/**
* @brief The host failed to communicate with a device via an OUT endpoint.
*/
#define USBERR_HOST_OUT_ERROR 0x00000004u
/**
* @brief The host received NAK on endpoint 0 for longer than the configured
* timeout.
*/
#define USBERR_HOST_EP0_NAK_TO 0x00000080u
/**
* @brief The host failed to communicate with a device via an endpoint zero.
*/
#define USBERR_HOST_EP0_ERROR 0x00000010u
/**
* @brief The device detected a CRC error in received data.
*/
#define USBERR_DEV_RX_DATA_ERROR 0x00080000u
/**
* @brief The device was unable to receive a packet from the host since the
* receive FIFO is full.
*/
#define USBERR_DEV_RX_OVERRUN 0x00040000u
/**
* @brief The device receive FIFO is full.
*/
#define USBERR_DEV_RX_FIFO_FULL 0x00020000u /* RX FIFO full */
/** ***************************************************************************
*
* Close the general_usblib_api Doxygen group.
* @}
*
*****************************************************************************/
/** ***************************************************************************
*
* @ingroup usblib_buffer_api
* @{
*
*****************************************************************************/
/** ***************************************************************************
*
* @brief A function pointer type which describes either a class driver
* packet read or packet write function (both have the same prototype)
* to the USB buffer object.
*
*****************************************************************************/
typedef uint32 (* tUSBPacketTransfer)(void * pvHandle,
uint8 * pcData,
uint32 ulLength,
tBoolean bLast);
/** ***************************************************************************
*
* @brief A function pointer type which describes either a class driver
* transmit or receive packet available function (both have the same
* prototype) to the USB buffer object.
*
*****************************************************************************/
typedef uint32 (* tUSBPacketAvailable)(void * pvHandle);
/** ***************************************************************************
*
* @brief The number of bytes of workspace that each USB buffer object
* requires. This workspace memory is provided to the buffer on
* USBBufferInit() in the \e pvWorkspace field of the \e tUSBBuffer
* structure.
*
*****************************************************************************/
#define USB_BUFFER_WORKSPACE_SIZE 16
/** ***************************************************************************
*
* @brief The structure used by the application to initialize a buffer object
* that will provide buffered access to either a transmit or receive
* channel.
*
*****************************************************************************/
typedef struct
{
/**
* @brief This field sets the mode of the buffer. If TRUE, the buffer
* operates as a transmit buffer and supports calls to
* USBBufferWrite by the client. If FALSE, the buffer operates
* as a receive buffer and supports calls to USBBufferRead.
*/
tBoolean bTransmitBuffer;
/**
* @brief A pointer to the callback function which will be called to
* notify the application of all asynchronous events related to
* the operation of the buffer.
*/
tUSBCallback pfnCBack;
/**
* @brief A pointer that the buffer will pass back to the client in the
* first parameter of all callbacks related to this instance.
*/
void * pvCBData;
/**
* @brief The function which should be called to transmit a packet of
* data in transmit mode or receive a packet in receive mode.
*/
tUSBPacketTransfer pfnTransfer;
/**
* @brief The function which should be called to determine if the
* endpoint is ready to accept a new packet for transmission in
* transmit mode or to determine the size of the buffer required
* to read a packet in receive mode.
*/
tUSBPacketAvailable pfnAvailable;
/**
* @brief The handle to pass to the low level function pointers provided
* in the pfnTransfer and pfnAvailable members. For USB device
* use, this is the psDevice parameter required by the relevant
* device class driver APIs. For USB host use, this is the pipe
* identifier returned by USBHCDPipeAlloc.
*/
void * pvHandle;
/**
* @brief A pointer to memory to be used as the ring buffer for this
* instance.
*/
uint8 * pcBuffer;
/**
* @brief The size, in bytes, of the buffer pointed to by pcBuffer.
*/
uint32 ulBufferSize;
/**
* @brief A pointer to USB_BUFFER_WORKSPACE_SIZE bytes of RAM that the
* buffer object can use for workspace.
*/
void * pvWorkspace;
}
tUSBBuffer;
/** ***************************************************************************
*
* @brief The structure used for encapsulating all the items associated with
* a ring buffer.
*
*****************************************************************************/
typedef struct
{
/**
* @brief The ring buffer size.
*/
uint32 ulSize;
/**
* @brief The ring buffer write index.
*/
volatile uint32 ulWriteIndex;
/**
* @brief The ring buffer read index.
*/
volatile uint32 ulReadIndex;
/**
* @brief The ring buffer.
*/
uint8 * pucBuf;
}
tUSBRingBufObject;
/** ***************************************************************************
*
* USB buffer API function prototypes.
*
*****************************************************************************/
extern const tUSBBuffer * USBBufferInit(const tUSBBuffer * psBuffer);
extern void USBBufferInfoGet(const tUSBBuffer * psBuffer,
tUSBRingBufObject * psRingBuf);
extern void * USBBufferCallbackDataSet(tUSBBuffer * psBuffer, void * pvCBData);
extern uint32 USBBufferWrite(const tUSBBuffer * psBuffer,
const uint8 * pucData,
uint32 ulLength);
extern void USBBufferDataWritten(const tUSBBuffer * psBuffer,
uint32 ulLength);
extern void USBBufferDataRemoved(const tUSBBuffer * psBuffer,
uint32 ulLength);
extern void USBBufferFlush(const tUSBBuffer * psBuffer);
extern uint32 USBBufferRead(const tUSBBuffer * psBuffer,
uint8 * pucData,
uint32 ulLength);
extern uint32 USBBufferDataAvailable(const tUSBBuffer * psBuffer);
extern uint32 USBBufferSpaceAvailable(const tUSBBuffer * psBuffer);
extern uint32 USBBufferEventCallback(void * pvCBData,
uint32 ulEvent,
uint32 ulMsgValue,
void * pvMsgData);
extern tBoolean USBRingBufFull(tUSBRingBufObject * ptUSBRingBuf);
extern tBoolean USBRingBufEmpty(tUSBRingBufObject * ptUSBRingBuf);
extern void USBRingBufFlush(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufUsed(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufFree(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufContigUsed(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufContigFree(tUSBRingBufObject * ptUSBRingBuf);
extern uint32 USBRingBufSize(tUSBRingBufObject * ptUSBRingBuf);
extern uint8 USBRingBufReadOne(tUSBRingBufObject * ptUSBRingBuf);
extern void USBRingBufRead(tUSBRingBufObject * ptUSBRingBuf,
uint8 * pucData, uint32 ulLength);
extern void USBRingBufWriteOne(tUSBRingBufObject * ptUSBRingBuf,
uint8 ucData);
extern void USBRingBufWrite(tUSBRingBufObject * ptUSBRingBuf,
const uint8 pucData[],
uint32 ulLength);
extern void USBRingBufAdvanceWrite(tUSBRingBufObject * ptUSBRingBuf,
uint32 ulNumBytes);
extern void USBRingBufAdvanceRead(tUSBRingBufObject * ptUSBRingBuf,
uint32 ulNumBytes);
extern void USBRingBufInit(tUSBRingBufObject * ptUSBRingBuf,
uint8 * pucBuf, uint32 ulSize);
/** ***************************************************************************
*
* Close the Doxygen group.
* @}
*
*****************************************************************************/
/******************************************************************************
*
* Mark the end of the C bindings section for C++ compilers.
*
*****************************************************************************/
#ifdef __cplusplus
}
#endif
#endif /* __USBLIB_H__ */