diff options
Diffstat (limited to 'include/arch/rm46l8lp/halcogen/usblib.h')
| -rw-r--r-- | include/arch/rm46l8lp/halcogen/usblib.h | 1899 |
1 files changed, 1899 insertions, 0 deletions
diff --git a/include/arch/rm46l8lp/halcogen/usblib.h b/include/arch/rm46l8lp/halcogen/usblib.h new file mode 100644 index 0000000..88e7fa5 --- /dev/null +++ b/include/arch/rm46l8lp/halcogen/usblib.h @@ -0,0 +1,1899 @@ +/* +* 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__ */ |