1 /*! 2 \file usb_ch9_std.h 3 \brief USB 2.0 standard defines 4 5 \version 2020-08-04, V1.1.0, firmware for GD32VF103 6 */ 7 8 /* 9 Copyright (c) 2020, GigaDevice Semiconductor Inc. 10 11 Redistribution and use in source and binary forms, with or without modification, 12 are permitted provided that the following conditions are met: 13 14 1. Redistributions of source code must retain the above copyright notice, this 15 list of conditions and the following disclaimer. 16 2. Redistributions in binary form must reproduce the above copyright notice, 17 this list of conditions and the following disclaimer in the documentation 18 and/or other materials provided with the distribution. 19 3. Neither the name of the copyright holder nor the names of its contributors 20 may be used to endorse or promote products derived from this software without 21 specific prior written permission. 22 23 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 24 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 25 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 26 IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 27 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 28 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 29 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 30 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 32 OF SUCH DAMAGE. 33 */ 34 35 #ifndef __USB_CH9_STD_H 36 #define __USB_CH9_STD_H 37 38 #include "usb_conf.h" 39 40 #define USB_DEV_QUALIFIER_DESC_LEN 0x0AU /*!< USB device qualifier descriptor length */ 41 #define USB_DEV_DESC_LEN 0x12U /*!< USB device descriptor length */ 42 #define USB_CFG_DESC_LEN 0x09U /*!< USB configuration descriptor length */ 43 #define USB_ITF_DESC_LEN 0x09U /*!< USB interface descriptor length */ 44 #define USB_EP_DESC_LEN 0x07U /*!< USB endpoint descriptor length */ 45 #define USB_IAD_DESC_LEN 0x08U /*!< USB IAD descriptor length */ 46 #define USB_OTG_DESC_LEN 0x03U /*!< USB device OTG descriptor length */ 47 48 #define USB_SETUP_PACKET_LEN 0x08U /*!< USB setup packet length */ 49 50 /* bit 7 of bmRequestType: data phase transfer direction */ 51 #define USB_TRX_MASK 0x80U /*!< USB transfer direction mask */ 52 #define USB_TRX_OUT 0x00U /*!< USB transfer OUT direction */ 53 #define USB_TRX_IN 0x80U /*!< USB transfer IN direction */ 54 55 /* bit 6..5 of bmRequestType: request type */ 56 #define USB_REQTYPE_STRD 0x00U /*!< USB standard request */ 57 #define USB_REQTYPE_CLASS 0x20U /*!< USB class request */ 58 #define USB_REQTYPE_VENDOR 0x40U /*!< USB vendor request */ 59 #define USB_REQTYPE_MASK 0x60U /*!< USB request mask */ 60 61 #define USBD_BUS_POWERED 0x00U /*!< USB bus power supply */ 62 #define USBD_SELF_POWERED 0x01U /*!< USB self power supply */ 63 64 #define USB_STATUS_REMOTE_WAKEUP 2U /*!< USB is in remote wakeup status */ 65 #define USB_STATUS_SELF_POWERED 1U /*!< USB is in self powered status */ 66 67 /* bit 4..0 of bmRequestType: recipient type */ 68 enum _usb_recp_type { 69 USB_RECPTYPE_DEV = 0x0U, /*!< USB device request type */ 70 USB_RECPTYPE_ITF = 0x1U, /*!< USB interface request type */ 71 USB_RECPTYPE_EP = 0x2U, /*!< USB endpoint request type */ 72 USB_RECPTYPE_MASK = 0x3U /*!< USB request type mask */ 73 }; 74 75 /* bRequest value */ 76 enum _usb_request { 77 USB_GET_STATUS = 0x0U, /*!< USB get status request */ 78 USB_CLEAR_FEATURE = 0x1U, /*!< USB clear feature request */ 79 USB_RESERVED2 = 0x2U, 80 USB_SET_FEATURE = 0x3U, /*!< USB set feature request */ 81 USB_RESERVED4 = 0x4U, 82 USB_SET_ADDRESS = 0x5U, /*!< USB set address request */ 83 USB_GET_DESCRIPTOR = 0x6U, /*!< USB get descriptor request */ 84 USB_SET_DESCRIPTOR = 0x7U, /*!< USB set descriptor request */ 85 USB_GET_CONFIGURATION = 0x8U, /*!< USB get configuration request */ 86 USB_SET_CONFIGURATION = 0x9U, /*!< USB set configuration request */ 87 USB_GET_INTERFACE = 0xAU, /*!< USB get interface request */ 88 USB_SET_INTERFACE = 0xBU, /*!< USB set interface request */ 89 USB_SYNCH_FRAME = 0xCU /*!< USB synchronize frame request */ 90 }; 91 92 /* descriptor types of USB specifications */ 93 enum _usb_desctype { 94 USB_DESCTYPE_DEV = 0x1U, /*!< USB device descriptor type */ 95 USB_DESCTYPE_CONFIG = 0x2U, /*!< USB configuration descriptor type */ 96 USB_DESCTYPE_STR = 0x3U, /*!< USB string descriptor type */ 97 USB_DESCTYPE_ITF = 0x4U, /*!< USB interface descriptor type */ 98 USB_DESCTYPE_EP = 0x5U, /*!< USB endpoint descriptor type */ 99 USB_DESCTYPE_DEV_QUALIFIER = 0x6U, /*!< USB device qualifier descriptor type */ 100 USB_DESCTYPE_OTHER_SPD_CONFIG = 0x7U, /*!< USB other speed configuration descriptor type */ 101 USB_DESCTYPE_ITF_POWER = 0x8U, /*!< USB interface power descriptor type */ 102 USB_DESCTYPE_IAD = 0xBU, /*!< USB interface association descriptor type */ 103 USB_DESCTYPE_BOS = 0xFU /*!< USB BOS descriptor type */ 104 }; 105 106 /* USB Endpoint Descriptor bmAttributes bit definitions */ 107 /* bits 1..0 : transfer type */ 108 enum _usbx_type { 109 USB_EP_ATTR_CTL = 0x0U, /*!< USB control transfer type */ 110 USB_EP_ATTR_ISO = 0x1U, /*!< USB Isochronous transfer type */ 111 USB_EP_ATTR_BULK = 0x2U, /*!< USB Bulk transfer type */ 112 USB_EP_ATTR_INT = 0x3U /*!< USB Interrupt transfer type */ 113 }; 114 115 /* bits 3..2 : Sync type (only if ISOCHRONOUS) */ 116 #define USB_EP_ATTR_NOSYNC 0x00U /*!< No Synchronization */ 117 #define USB_EP_ATTR_ASYNC 0x04U /*!< Asynchronous */ 118 #define USB_EP_ATTR_ADAPTIVE 0x08U /*!< Adaptive */ 119 #define USB_EP_ATTR_SYNC 0x0CU /*!< Synchronous */ 120 #define USB_EP_ATTR_SYNCTYPE 0x0CU /*!< Synchronous type */ 121 122 /* bits 5..4 : usage type (only if ISOCHRONOUS) */ 123 #define USB_EP_ATTR_DATA 0x00U /*!< Data endpoint */ 124 #define USB_EP_ATTR_FEEDBACK 0x10U /*!< Feedback endpoint */ 125 #define USB_EP_ATTR_IMPLICIT_FEEDBACK_DATA 0x20U /*!< Implicit feedback Data endpoint */ 126 #define USB_EP_ATTR_USAGETYPE 0x30U /*!< Usage type */ 127 128 /* endpoint max packet size bits12..11 */ 129 #define USB_EP_MPS_ADD_0 (0x00 << 11) /*!< None(1 transaction per microframe */ 130 #define USB_EP_MPS_ADD_1 (0x01 << 11) /*!< 1 additional(2 transaction per microframe */ 131 #define USB_EP_MPS_ADD_2 (0x02 << 11) /*!< 2 additional(3 transaction per microframe */ 132 133 #define FEATURE_SELECTOR_EP 0x00U /*!< USB endpoint feature selector */ 134 #define FEATURE_SELECTOR_DEV 0x01U /*!< USB device feature selector */ 135 #define FEATURE_SELECTOR_REMOTEWAKEUP 0x01U /*!< USB feature selector remote wakeup */ 136 137 #define BYTE_SWAP(addr) (((uint16_t)(*((uint8_t *)(addr)))) + \ 138 (uint16_t)(((uint16_t)(*(((uint8_t *)(addr)) + 1U))) << 8U)) 139 140 #define BYTE_LOW(x) ((uint8_t)((x) & 0x00FFU)) 141 #define BYTE_HIGH(x) ((uint8_t)(((x) & 0xFF00U) >> 8U)) 142 143 #define USB_MIN(a, b) (((a) < (b)) ? (a) : (b)) 144 145 #define USB_DEFAULT_CONFIG 0U 146 147 /* USB classes */ 148 #define USB_CLASS_HID 0x03U /*!< USB HID class */ 149 #define USB_CLASS_MSC 0x08U /*!< USB MSC class */ 150 151 /* use the following values when USB host need to get descriptor */ 152 #define USBH_DESC(x) (((x)<< 8U) & 0xFF00U) 153 154 /* as per USB specs 9.2.6.4 :standard request with data request timeout: 5sec 155 standard request with no data stage timeout : 50ms */ 156 #define DATA_STAGE_TIMEOUT 5000U /*!< USB data stage timeout*/ 157 #define NODATA_STAGE_TIMEOUT 50U /*!< USB no data stage timeout*/ 158 159 #pragma pack(1) 160 161 /* USB standard device request structure */ 162 typedef struct _usb_req { 163 uint8_t bmRequestType; /*!< type of request */ 164 uint8_t bRequest; /*!< request of setup packet */ 165 uint16_t wValue; /*!< value of setup packet */ 166 uint16_t wIndex; /*!< index of setup packet */ 167 uint16_t wLength; /*!< length of setup packet */ 168 } usb_req; 169 170 /* USB setup packet define */ 171 typedef union _usb_setup { 172 uint8_t data[8]; 173 174 usb_req req; 175 } usb_setup; 176 177 /* USB descriptor defines */ 178 179 typedef struct _usb_desc_header { 180 uint8_t bLength; /*!< size of the descriptor */ 181 uint8_t bDescriptorType; /*!< type of the descriptor */ 182 } usb_desc_header; 183 184 typedef struct _usb_desc_dev { 185 usb_desc_header header; /*!< descriptor header, including type and size */ 186 187 uint16_t bcdUSB; /*!< BCD of the supported USB specification */ 188 uint8_t bDeviceClass; /*!< USB device class */ 189 uint8_t bDeviceSubClass; /*!< USB device subclass */ 190 uint8_t bDeviceProtocol; /*!< USB device protocol */ 191 uint8_t bMaxPacketSize0; /*!< size of the control (address 0) endpoint's bank in bytes */ 192 uint16_t idVendor; /*!< vendor ID for the USB product */ 193 uint16_t idProduct; /*!< unique product ID for the USB product */ 194 uint16_t bcdDevice; /*!< product release (version) number */ 195 uint8_t iManufacturer; /*!< string index for the manufacturer's name */ 196 uint8_t iProduct; /*!< string index for the product name/details */ 197 uint8_t iSerialNumber; /*!< string index for the product's globally unique hexadecimal serial number */ 198 uint8_t bNumberConfigurations; /*!< total number of configurations supported by the device */ 199 } usb_desc_dev; 200 201 typedef struct _usb_desc_config { 202 usb_desc_header header; /*!< descriptor header, including type and size */ 203 204 uint16_t wTotalLength; /*!< size of the configuration descriptor header,and all sub descriptors inside the configuration */ 205 uint8_t bNumInterfaces; /*!< total number of interfaces in the configuration */ 206 uint8_t bConfigurationValue; /*!< configuration index of the current configuration */ 207 uint8_t iConfiguration; /*!< index of a string descriptor describing the configuration */ 208 uint8_t bmAttributes; /*!< configuration attributes */ 209 uint8_t bMaxPower; /*!< maximum power consumption of the device while in the current configuration */ 210 } usb_desc_config; 211 212 typedef struct _usb_desc_itf { 213 usb_desc_header header; /*!< descriptor header, including type and size */ 214 215 uint8_t bInterfaceNumber; /*!< index of the interface in the current configuration */ 216 uint8_t bAlternateSetting; /*!< alternate setting for the interface number */ 217 uint8_t bNumEndpoints; /*!< total number of endpoints in the interface */ 218 uint8_t bInterfaceClass; /*!< interface class ID */ 219 uint8_t bInterfaceSubClass; /*!< interface subclass ID */ 220 uint8_t bInterfaceProtocol; /*!< interface protocol ID */ 221 uint8_t iInterface; /*!< index of the string descriptor describing the interface */ 222 } usb_desc_itf; 223 224 typedef struct _usb_desc_ep { 225 usb_desc_header header; /*!< descriptor header, including type and size. */ 226 227 uint8_t bEndpointAddress; /*!< logical address of the endpoint */ 228 uint8_t bmAttributes; /*!< endpoint attributes */ 229 uint16_t wMaxPacketSize; /*!< size of the endpoint bank, in bytes */ 230 uint8_t bInterval; /*!< polling interval in milliseconds for the endpoint if it is an INTERRUPT or ISOCHRONOUS type */ 231 } usb_desc_ep; 232 233 typedef struct _usb_desc_LANGID { 234 usb_desc_header header; /*!< descriptor header, including type and size. */ 235 uint16_t wLANGID; /*!< LANGID code */ 236 } usb_desc_LANGID; 237 238 typedef struct _usb_desc_str { 239 usb_desc_header header; /*!< descriptor header, including type and size. */ 240 uint16_t unicode_string[64]; /*!< unicode string data */ 241 } usb_desc_str; 242 243 #pragma pack() 244 245 /* compute string descriptor length */ 246 #define USB_STRING_LEN(unicode_chars) (sizeof(usb_desc_header) + ((unicode_chars) << 1U)) 247 248 #endif /* __USB_CH9_STD_H */ 249