/** * @file descriptor.h * @brief Structure of USB Descriptors * @note * * ------------------------------------------------------------------ Copyright (c) 2023 by Lattice Semiconductor Corporation ALL RIGHTS RESERVED ------------------------------------------------------------------ DISCLAIMER: LATTICE MAKES NO WARRANTIES ON THIS FILE OR ITS CONTENTS, WHETHER EXPRESSED, IMPLIED, STATUTORY, OR IN ANY PROVISION OF THE LATTICE PROPEL LICENSE AGREEMENT OR COMMUNICATION WITH LICENSEE, AND LATTICE SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. LATTICE DOES NOT WARRANT THAT THE FUNCTIONS CONTAINED HEREIN WILL MEET LICENSEE 'S REQUIREMENTS, OR THAT LICENSEE' S OPERATION OF ANY DEVICE, SOFTWARE OR SYSTEM USING THIS FILE OR ITS CONTENTS WILL BE UNINTERRUPTED OR ERROR FREE, OR THAT DEFECTS HEREIN WILL BE CORRECTED. LICENSEE ASSUMES RESPONSIBILITY FOR SELECTION OF MATERIALS TO ACHIEVE ITS INTENDED RESULTS, AND FOR THE PROPER INSTALLATION, USE, AND RESULTS OBTAINED THEREFROM. LICENSEE ASSUMES THE ENTIRE RISK OF THE FILE AND ITS CONTENTS PROVING DEFECTIVE OR FAILING TO PERFORM PROPERLY AND IN SUCH EVENT, LICENSEE SHALL ASSUME THE ENTIRE COST AND RISK OF ANY REPAIR, SERVICE, CORRECTION, OR ANY OTHER LIABILITIES OR DAMAGES CAUSED BY OR ASSOCIATED WITH THE SOFTWARE. IN NO EVENT SHALL LATTICE BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS FILE OR ITS CONTENTS, EVEN IF LATTICE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. LATTICE 'S SOLE LIABILITY, AND LICENSEE' S SOLE REMEDY, IS SET FORTH ABOVE. LATTICE DOES NOT WARRANT OR REPRESENT THAT THIS FILE, ITS CONTENTS OR USE THEREOF DOES NOT INFRINGE ON THIRD PARTIES' INTELLECTUAL PROPERTY RIGHTS, INCLUDING ANY PATENT. IT IS THE USER' S RESPONSIBILITY TO VERIFY THE USER SOFTWARE DESIGN FOR CONSISTENCY AND FUNCTIONALITY THROUGH THE USE OF FORMAL SOFTWARE VALIDATION METHODS. ------------------------------------------------------------------ */ #ifndef SRC_DESCRIPTOR_H_ #define SRC_DESCRIPTOR_H_ #include "ltcusb.h" #include /** * @brief Structure of Standard Device Descriptor */ typedef struct ltcusb_device_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief DEVICE Descriptor Type */ uint8_t bDescriptorType; /** * @brief USB Specification Release Number in Binary-Coded Decimal * (i.e., 2.10 is 210H). * This field identifies the release of the USB Specification with * which the device and its descriptors are compliant. */ uint16_t bcdUSB; /**@brief Class code (assigned by the USB-IF). */ uint8_t bDeviceClass; /**@brief Subclass code (assigned by the USB-IF).*/ uint8_t bDeviceSubClass; /**@brief Protocol code (assigned by the USB-IF).*/ uint8_t bDeviceProtocol; /**@brief Maximum packet size for endpoint zero (only 8, 16, 32, or 64 * are valid) */ uint8_t bMaxPacketSize0; /**@brief Vendor ID (assigned by the USB-IF) */ uint16_t idVendor; /**@brief Product ID (assigned by the manufacturer) */ uint16_t idProduct; /**@brief Device release number in binary-coded decimal*/ uint16_t bcdDevice; /**@brief Index of string descriptor describing manufacturer*/ uint8_t iManufacturer; /**@brief Index of string descriptor describing product */ uint8_t iProduct; /**@brief Index of string descriptor describing the device’s serial * number*/ uint8_t iSerialNumber; /**@brief Number of possible configurations*/ uint8_t bNumConfigurations; }device_descriptor; /** *@brief Use this to set device descriptor. */ extern device_descriptor device_descriptor_data; /** * @brief Structure of BOS Descriptor */ typedef struct ltcusb_bos_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief BOS Descriptor Type */ uint8_t bDescriptorType; /** * @brief Length of this descriptor and all of its sub descriptors */ uint16_t wTotalLength; /**@brief The number of separate device capability descriptors in the BOS*/ uint8_t bNumDeviceCaps; }bos_descriptor; /** * @brief Use this to set BOS descriptor */ extern bos_descriptor bos_descriptor_data; /** * @brief Structure of USB 2.0 Extension Descriptor */ typedef struct ltcusb_usb_2_0_extension_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief DEVICE CAPABILITY Descriptor type */ uint8_t bDescriptorType; /** * @brief Capability type: USB 2.0 EXTENSION */ uint8_t bDevCapabilityType; /**@brief Encodings are: * Bit Encoding * 0 Reserved. Shall be set to zero. * 1 LPM. A value of one in this bit location indicates that this * device supports the * Link Power Management protocol. SuperSpeed devices shall set * this bit to one. * 31:2 Reserved. Shall be set to zero.*/ uint32_t bmAttributes; }usb_2_0_extension_descriptor; /** * @brief Use this to set USB 2.0 Extension Descriptor */ extern usb_2_0_extension_descriptor usb_2_0_extension_descriptor_data; /** * @brief Structure of SuperSpeed Device Capabilities Descriptor. */ typedef struct ltcusb_ss_usb_device_capability_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief DEVICE CAPABILITY Descriptor type */ uint8_t bDescriptorType; /** * @brief Capability type: SUPERSPEED_USB */ uint8_t bDevCapabilityType; /**@brief Encodings are: * Bit Encoding * 0 Reserved. Shall be set to zero. * 1 LTM Capable. A value of one in this bit location indicates * that this device has is capable of generating Latency * Tolerance Messages. * 7:2 Reserved. Shall be set to zero.*/ uint8_t bmAttributes; /**@brief Encodings are: * Bit Encoding * 0 If this bit is set, then the device supports operation at l * ow-Speed USB. * 1 If this bit is set, then the device supports operation at * full-Speed USB. * 2 If this bit is set, then the device supports operation at * high-Speed USB. * 3 If this bit is set, then the device supports operation at * 5 Gbps. * 15:4 Reserved. Shall be set to zero.*/ uint16_t wSpeedsSupported; /**@brief The lowest speed at which all the functionality supported by * the device is available to the user.*/ uint8_t bFunctionalitySupport; /**@brief U1 Device Exit Latency. Worst case latency to transition from * U1 to U0, assuming the latency is limited only by the device * and not the device’s link partner.*/ uint8_t bU1DevExitLat; /**@brief U2 Device Exit Latency. Worst case latency to transition from * U2 to U0, assuming the latency is limited only by the device * and not the device’s link partner. * Applies to all ports on a device.*/ uint16_t wU2DevExitLat; }ss_usb_device_capability_descriptor; /** * @brief Use this to set SuperSpeed USB Device Capability Descriptor */ extern ss_usb_device_capability_descriptor \ ss_usb_device_capability_descriptor_data; /** * @brief Structure of Standard Device Qualifier Descriptor */ typedef struct ltcusb_device_qualifier_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief DEVICE Qualifier Descriptor Type */ uint8_t bDescriptorType; /** * @brief USB Specification Release Number in Binary-Coded Decimal * (i.e., 2.10 is 210H). * This field identifies the release of the USB Specification with * which the device and its descriptors are compliant. */ uint16_t bcdUSB; /**@brief Class code (assigned by the USB-IF). */ uint8_t bDeviceClass; /**@brief Subclass code (assigned by the USB-IF).*/ uint8_t bDeviceSubClass; /**@brief Protocol code (assigned by the USB-IF).*/ uint8_t bDeviceProtocol; /**@brief Maximum packet size for endpoint zero (only 8, 16, 32, or 64 * are valid) */ uint8_t bMaxPacketSize0; /**@brief Number of Other-speed Configurations */ uint8_t bNumConfigurations; /**@brief Reserved for future use, must be zero*/ uint8_t bReserved; }device_qualifier_descriptor; /** *@brief Use this to set device descriptor. */ extern device_qualifier_descriptor device_qualifier_descriptor_data; /** * @brief Structure of Other_Speed_Configuration Descriptor */ typedef struct ltcusb_other_speed_configuration_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief Other Speed Configuration Descriptor Type */ uint8_t bDescriptorType; /** * @brief Total length of data returned */ uint16_t wTotalLength; /**@brief Number of interfaces supported by this speed configuration. */ uint8_t bNumInterfaces; /**@brief Value to use to select configuration.*/ uint8_t bConfigurationValue; /**@brief Index of string descriptor.*/ uint8_t iConfiguration; /**@brief Same as Configuration descriptor */ uint8_t bmAttributes; /**@brief Same as Configuration descriptor */ uint8_t bMaxPower; }other_speed_configuration_descriptor; /** *@brief Use this to Other Speed Configuration Descriptor. */ extern other_speed_configuration_descriptor \ other_speed_configuration_descriptor_data; /** * @brief Structure of Standard Configuration Descriptor */ typedef struct ltcusb_config_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief CONFIGURATION Descriptor Type */ uint8_t bDescriptorType; /** * @brief Total length of data returned for this configuration. * Includes the combined length of all descriptors (configuration, * interface, endpoint, and class- or vendor-specific) returned * for this configuration. */ uint16_t wTotalLength; /**@brief Number of interfaces supported by this configuration*/ uint8_t bNumInterfaces; /**@brief Value to use as an argument to the SetConfiguration() request * to select this configuration*/ uint8_t bConfigurationValue; /**@brief Index of string descriptor describing this configuration*/ uint8_t iConfiguration; /**@brief Configuration characteristics * D7:Reserved (set to one) * D6:Self-powered * D5:Remote Wakeup * D4...0:Reserved (reset to zero) */ uint8_t bmAttributes; /**@brief Maximum power consumption of the USB device from the bus in * this specific configuration when the device is fully operational. * Expressed in 2 mA units (i.e., 50 = 100 mA). */ uint8_t bMaxPower; }config_descriptor; /** *@brief Use this to set Configuration descriptor. *@todo remove global varible from here. */ extern config_descriptor config_descriptor_data; /** * @brief Structure of Standard Interface Descriptor */ typedef struct ltcusb_interface_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief INTERFACE Descriptor Type */ uint8_t bDescriptorType; /** * @brief Number of this interface. Zero-based value identifying the * index in the array of concurrent interfaces supported by this * configuration. */ uint8_t bInterfaceNumber; /**@brief Value used to select this alternate setting for the interface * identified in the prior field*/ uint8_t bAlternateSetting; /**@brief Number of endpoints used by this interface (excluding the * Default Control Pipe). If this value is zero, this interface * only uses the Default Control Pipe.*/ uint8_t bNumEndpoints; /**@brief Class code (assigned by the USB-IF).*/ uint8_t bInterfaceClass; /**@brief Subclass code (assigned by the USB-IF). */ uint8_t bInterfaceSubClass; /**@brief Protocol code (assigned by the USB). */ uint8_t bInterfaceProtocol; /**@brief Index of string descriptor describing this interface */ uint8_t iInterface; }interface_descriptor; /** * @brief Structure of Standard Endpoint Descriptor */ typedef struct ltcusb_endpoint_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief ENDPOINT Descriptor Type */ uint8_t bDescriptorType; /** * @brief The address of the endpoint on the device described by this * descriptor. * The address is encoded as follows: * Bit 3...0: The endpoint number * Bit 6...4: Reserved, reset to zero * Bit 7: Direction, ignored for control endpoints * 0 = OUT endpoint * 1 = IN endpoint */ uint8_t bEndpointAddress; /**@brief This field describes the endpoint’s attributes when it is * configured using the bConfigurationValue. * Bits 1..0: Transfer Type * 00 = Control * 01 = Isochronous * 10 = Bulk * 11 = Interrupt */ uint8_t bmAttributes; /**@brief Maximum packet size this endpoint is capable of sending or * receiving when this configuration is selected.*/ uint16_t wMaxPacketSize; /**@brief Interval for servicing the endpoint for data transfers. * Expressed in 125-µs units.*/ uint8_t bInterval; }endpoint_descriptor; /** * @brief Structure of Container ID Descriptor */ typedef struct ltcusb_container_id_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief DEVICE CAPABILITY Descriptor type */ uint8_t bDescriptorType; /** * @brief Capability type: CONTAINER_ID */ uint8_t bDevCapabilityType; /**@brief This field is reserved and shall be set to zero.*/ uint8_t bReserved; /**@todo Implement when USB3.0 development.*/ }container_id_descriptor; /** * @brief Structure of SuperSpeed Endpoint Companion Descriptor. * Each SuperSpeed endpoint described in an interface is followed * by a SuperSpeed Endpoint Companion descriptor. This descriptor contains * additional endpoint characteristics that are only defined for * SuperSpeed endpoints. */ typedef struct ltcusb_ss_endpoint_companion_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief SUPERSPEED_USB_ENDPOINT_COMPANION Descriptor Type */ uint8_t bDescriptorType; /** * @brief The maximum number of packets the endpoint can send or receive * as part of a burst. Valid values are from 0 to 15. A value of * 0 indicates that the endpoint can only burst one packet at a * time and a value of 15 indicates that the endpoint can burst up * to 16 packets at a time. For endpoints of type control this * shall be set to 0. */ uint8_t bMaxBurst; /**@brief This field value depend on Bulk Endpoint,isochronous endpoint, * Control or Interrupt Endpoint as specified in USB 3.0 * Specification. */ uint8_t bmAttributes; /**@brief The total number of bytes this endpoint will transfer every * service interval. This field is only valid for periodic * endpoints. For isochronous endpoints, this value is used to * reserve the bus time in the schedule,required for the frame * data payloads per 125 us.*/ uint16_t wBytesPerInterval; }ss_endpoint_companion_descriptor; /** * @brief Structure of String Language Descriptor */ typedef struct ltcusb_string_language_descriptor_struct { /**@brief Size of this descriptor in bytes */ uint8_t bLength; /**@brief String Descriptor Type */ uint8_t bDescriptorType; /** * @brief USB language ID (LANGID) code zero */ uint16_t wLANGID_0; }string_language_descriptor; /** * @brief Structure of Standard Interface Association Descriptor */ typedef struct ltcusb_interface_association_descriptor_struct { /**@todo USB 3.0 implementation.*/ }interface_association_descriptor; /** *@brief Use this to set string_language_descriptor. */ extern string_language_descriptor string_language_descriptor_data; /** * @brief USB Interface Descriptor. */ extern interface_descriptor interface_descriptor_data; /** * @brief Endpoint 1 descriptor for Bulk IN. */ extern endpoint_descriptor endpoint_descriptor_bin_1_data; /** * @brief Endpoint 1 descriptor for Bulk OUT. */ extern endpoint_descriptor endpoint_descriptor_bout_1_data; /** * @brief Endpoint 5 descriptor for interrupt IN. */ extern endpoint_descriptor endpoint_descriptor_iin_5_data; /** * @brief Endpoint 5 descriptor for interrupt OUT. */ extern endpoint_descriptor endpoint_descriptor_iout_5_data; /** * @brief SuperSpeed Endpoint Companion descriptor for bulk endpoint. */ extern ss_endpoint_companion_descriptor \ ss_endpoint_companion_descriptor_bulk_data; /** * @brief SuperSpeed Endpoint Companion descriptor for interrupt endpoint. */ extern ss_endpoint_companion_descriptor \ ss_endpoint_companion_descriptor_interrupt_data; /** * @brief String to hold the manufacturer id. */ extern uint8_t string_descriptor_manufacturer_id[256]; /** * @brief String to hold the product id. */ extern uint8_t string_descriptor_product_id[256]; /** * @brief String to hold the serial number id. */ extern uint8_t string_descriptor_serial_id[256]; /** * @brief Length of manufacturer id string. */ extern uint32_t string_descriptor_manufacturer_id_len; /** * @brief Length of product id string. */ extern uint32_t string_descriptor_product_id_len; /** * @brief Length of serial number id string. */ extern uint32_t string_descriptor_serial_id_len; /** * @brief Create USB string descriptor from C string. * @param str String to be set into string descriptor. * @param str_len Length of string to be set. * @param str_desc USB string descriptor from str. * @param str_desc_len Length of USB string descriptor. * @return 0 When success. * @retval -1 When Input string is larger than maximum allowed size. * */ extern int create_string_descriptor(uint8_t* str, uint32_t str_len, uint32_t* str_desc, uint32_t* str_desc_len); #endif /* SRC_DESCRIPTOR_H_ */