1 /*********************************************************************************************************//** 2 * @file ht32_usbd_core.h 3 * @version $Rev:: 2555 $ 4 * @date $Date:: 2022-03-15 #$ 5 * @brief The header file of standard protocol related function for HT32 USB Device Library. 6 ************************************************************************************************************* 7 * @attention 8 * 9 * Firmware Disclaimer Information 10 * 11 * 1. The customer hereby acknowledges and agrees that the program technical documentation, including the 12 * code, which is supplied by Holtek Semiconductor Inc., (hereinafter referred to as "HOLTEK") is the 13 * proprietary and confidential intellectual property of HOLTEK, and is protected by copyright law and 14 * other intellectual property laws. 15 * 16 * 2. The customer hereby acknowledges and agrees that the program technical documentation, including the 17 * code, is confidential information belonging to HOLTEK, and must not be disclosed to any third parties 18 * other than HOLTEK and the customer. 19 * 20 * 3. The program technical documentation, including the code, is provided "as is" and for customer reference 21 * only. After delivery by HOLTEK, the customer shall use the program technical documentation, including 22 * the code, at their own risk. HOLTEK disclaims any expressed, implied or statutory warranties, including 23 * the warranties of merchantability, satisfactory quality and fitness for a particular purpose. 24 * 25 * <h2><center>Copyright (C) Holtek Semiconductor Inc. All rights reserved</center></h2> 26 ************************************************************************************************************/ 27 // <<< Use Configuration Wizard in Context Menu >>> 28 29 /* Define to prevent recursive inclusion -------------------------------------------------------------------*/ 30 #ifndef __HT32_USBD_CORE_H 31 #define __HT32_USBD_CORE_H 32 33 #ifdef __cplusplus 34 extern "C" { 35 #endif 36 37 /* Includes ------------------------------------------------------------------------------------------------*/ 38 39 /** @addtogroup HT32_USBD_Library 40 * @{ 41 */ 42 43 /** @addtogroup USBDCore 44 * @{ 45 */ 46 47 48 /* Settings ------------------------------------------------------------------------------------------------*/ 49 /** @defgroup USBDCore_Settings USB Device Core settings 50 * @{ 51 */ 52 /* USBD Debug mode */ 53 //<e0.0> Enable USB Debug mode 54 //<o1.0> Dump USB Debug data 55 #ifndef USBDCORE_DEBUG 56 #define USBDCORE_DEBUG (0) /*!< Enable USB Debug mode */ 57 #define USBDCORE_DEBUG_DATA (0) /*!< Dump USB Debug data */ 58 #endif 59 /** 60 * @} 61 */ 62 63 /* Exported types ------------------------------------------------------------------------------------------*/ 64 /** @defgroup USBDCore_Exported_Type USB Device Core exported types 65 * @{ 66 */ 67 /** 68 * @brief USB Device Request. 69 */ 70 typedef __PACKED_H struct 71 { 72 uc8 bmRequestType; 73 uc8 bRequest; 74 uc8 wValueL; 75 uc8 wValueH; 76 uc16 wIndex; 77 uc16 wLength; 78 } __PACKED_F USBDCore_Request_TypeDef; 79 80 /** 81 * @brief USB Descriptor. 82 */ 83 typedef struct 84 { 85 uc8 *pDeviceDesc; /*!< Device Descriptor */ 86 uc8 *pConfnDesc; /*!< Configuration Descriptor */ 87 uc8 **ppStringDesc; /*!< String Descriptor */ 88 u32 uStringDescNumber; /*!< Count of String Descriptor */ 89 } USBDCore_Desc_TypeDef; 90 91 /** 92 * @brief STALL, control IN or control OUT. 93 */ 94 typedef enum 95 { 96 USB_ACTION_STALL = 0, 97 USB_ACTION_DATAIN = 1, 98 USB_ACTION_DATAOUT = 2, 99 } USBDCore_Action_Enum; 100 101 /** 102 * @brief Call back function. 103 */ 104 typedef struct 105 { 106 void (*func) (u32 uPara); /*!< Call back function pointer */ 107 u32 uPara; /*!< Parameter of call back function */ 108 } USBDCore_CallBack_TypeDef; 109 110 /** 111 * @brief Parameter for control IN/OUT Transfer. 112 */ 113 typedef struct 114 { 115 u8 uBuffer[2]; /*!< Temporary buffer */ 116 uc8 *pData; /*!< Pointer of control IN/OUT Data */ 117 s32 sByteLength; /*!< Total length for control IN/OUT Transfer */ 118 USBDCore_Action_Enum Action; /*!< STALL, control IN or control OUT */ 119 USBDCore_CallBack_TypeDef CallBack_OUT; /*!< Call back function pointer for Control OUT */ 120 } USBDCore_Transfer_TypeDef; 121 122 /** 123 * @brief USB Device. 124 */ 125 typedef struct 126 { 127 USBDCore_Request_TypeDef Request; /*!< USB Device Request */ 128 USBDCore_Desc_TypeDef Desc; /*!< USB Descriptor */ 129 USBDCore_Transfer_TypeDef Transfer; /*!< Parameter for control IN/OUT Transfer */ 130 } USBDCore_Device_TypeDef; 131 132 /** 133 * @brief Bit access for CurrentFeature. 134 */ 135 typedef __PACKED_H struct _FEATURE_TYPEBIT 136 { 137 unsigned bSelfPowered :1; /*!< Remote Wakeup feature */ 138 unsigned bRemoteWakeup :1; /*!< Self Powered */ 139 } __PACKED_F USBDCore_Feature_TypeBit; 140 141 /** 142 * @brief For Set/ClearFeature and GetStatus request. 143 */ 144 typedef __PACKED_H union _FEATURE_TYPEDEF 145 { 146 u8 uByte; /*!< Byte access for CurrentFeature */ 147 USBDCore_Feature_TypeBit Bits; /*!< Bit access for CurrentFeature */ 148 } __PACKED_F USBDCore_Feature_TypeDef; 149 150 /** 151 * @brief Device State. 152 */ 153 typedef enum 154 { 155 USER_USER_USB_STATE_UNCONNECTED = 0, 156 USER_USER_USB_STATE_ATTACHED = 1, 157 USER_USER_USB_STATE_POWERED = 2, 158 USER_USER_USB_STATE_SUSPENDED = 3, 159 USER_USER_USB_STATE_DEFAULT = 4, 160 USER_USER_USB_STATE_ADDRESS = 5, 161 USER_USER_USB_STATE_CONFIGURED = 6, 162 } USBDCore_Status_Enum; 163 164 /** 165 * @brief USB Device information. 166 */ 167 typedef struct 168 { 169 u8 uCurrentConfiguration; /*!< For Set/GetConfiguration request */ 170 u8 uCurrentInterface; /*!< For Set/GetInterface request */ 171 volatile USBDCore_Status_Enum CurrentStatus; /*!< Device State */ 172 USBDCore_Status_Enum LastStatus; /*!< Device State before SUSPEND */ 173 USBDCore_Feature_TypeDef CurrentFeature; /*!< For Set/ClearFeature and GetStatus request */ 174 u32 uIsDiscardClearFeature; /*!< Discard ClearFeature flag for Mass Storage */ 175 } USBDCore_Info_TypeDef; 176 177 typedef void (*USBDCore_CallBackClass_Typedef) (USBDCore_Device_TypeDef *pDev); 178 typedef void (*USBDCore_CallBackVendor_Typedef) (USBDCore_Device_TypeDef *pDev); 179 typedef void (*USBDCore_CallBackEPTn_Typedef) (USBD_EPTn_Enum EPTn); 180 181 /** 182 * @brief USB Class call back function. 183 */ 184 typedef struct 185 { 186 USBDCore_CallBack_TypeDef CallBack_MainRoutine; /*!< Class main routine call back function */ 187 USBDCore_CallBack_TypeDef CallBack_Reset; /*!< Class RESET call back function */ 188 USBDCore_CallBack_TypeDef CallBack_StartOfFrame; /*!< Class SOF call back function */ 189 USBDCore_CallBackClass_Typedef CallBack_ClassGetDescriptor; /*!< Class Get Descriptor call back function */ 190 USBDCore_CallBackClass_Typedef CallBack_ClassSetInterface; /*!< Set Interface call back function */ 191 USBDCore_CallBackClass_Typedef CallBack_ClassGetInterface; /*!< Get Interface call back function */ 192 USBDCore_CallBackClass_Typedef CallBack_ClassRequest; /*!< Class Request call back function */ 193 USBDCore_CallBackVendor_Typedef CallBack_VendorRequest; /*!< Vendor Request call back function */ 194 USBDCore_CallBackEPTn_Typedef CallBack_EPTn[MAX_EP_NUM]; /*!< Endpoint n call back function */ 195 } USBDCore_Class_TypeDef; 196 197 /** 198 * @brief USB Device Power related call back function. 199 */ 200 typedef struct 201 { 202 USBDCore_CallBack_TypeDef CallBack_Suspend; 203 } USBDCore_Power_TypeDef; 204 205 /** 206 * @brief Major structure of USB Library. 207 */ 208 typedef struct 209 { 210 USBDCore_Device_TypeDef Device; /*!< USB Device */ 211 USBDCore_Info_TypeDef Info; /*!< USB Device information */ 212 USBDCore_Class_TypeDef Class; /*!< USB Class call back function */ 213 u32 *pDriver; /*!< USB Device Driver initialization structure */ 214 USBDCore_Power_TypeDef Power; /*!< USB Device Power related call back function */ 215 216 void *pdata; /*!< USB User private pointer */ 217 } USBDCore_TypeDef; 218 219 /*----------------------------------------------------------------------------------------------------------*/ 220 /* Variable architecture of USB Library */ 221 /*----------------------------------------------------------------------------------------------------------*/ 222 /* USBCore - USBDCore_TypeDef Major structure of USB Library */ 223 /* USBCore.Device - USBDCore_Device_TypeDef USB Device */ 224 /* USBCore.Device.Request - USBDCore_Request_TypeDef USB Device Request */ 225 /* USBCore.Device.Request.bmRequestType */ 226 /* USBCore.Device.Request.bRequest */ 227 /* USBCore.Device.Request.wValueL */ 228 /* USBCore.Device.Request.wValueH */ 229 /* USBCore.Device.Request.wIndex */ 230 /* USBCore.Device.Request.wLength */ 231 /* USBCore.Device.Desc - USBDCore_Desc_TypeDef USB Descriptor */ 232 /* USBCore.Device.Desc.pDeviceDesc Device Descriptor */ 233 /* USBCore.Device.Desc.pConfnDesc Configuration Descriptor */ 234 /* USBCore.Device.Desc.pStringDesc[DESC_NUM_STRING] String Descriptor */ 235 /* USBCore.Device.Desc.uStringDescNumber Count of String Descriptor */ 236 /* USBCore.Device.Transfer - USBDCore_Transfer_TypeDef Parameter for control IN/OUT Transfer */ 237 /* USBCore.Device.Transfer.uBuffer[2] Temporary buffer */ 238 /* USBCore.Device.Transfer.pData Pointer of control IN/OUT Data */ 239 /* USBCore.Device.Transfer.sByteLength Total length for control IN/OUT Transfer */ 240 /* USBCore.Device.Transfer.Action - USBDCore_Action_Enum STALL, control IN or control OUT */ 241 /* USBCore.Device.Transfer.CallBack_OUT.func(uPara) Call back function pointer for Control OUT */ 242 /* USBCore.Device.Transfer.CallBack_OUT.uPara Parameter of Control OUT call back function */ 243 /* */ 244 /* USBCore.Info - USBDCore_Info_TypeDef USB Device information */ 245 /* USBCore.Info.uCurrentConfiguration For Set/GetConfiguration request */ 246 /* USBCore.Info.uCurrentInterface For Set/GetInterface request */ 247 /* USBCore.Info.CurrentStatus - USBDCore_Status_Enum Device State */ 248 /* USBCore.Info.LastStatus - USBDCore_Status_Enum Device State before SUSPEND */ 249 /* USBCore.Info.CurrentFeature - USBDCore_Feature_TypeDef For Set/ClearFeature and GetStatus request */ 250 /* USBCore.Info.CurrentFeature.uByte Byte access for CurrentFeature */ 251 /* USBCore.Info.CurrentFeature.Bits.bRemoteWakeup Remote Wakeup feature */ 252 /* USBCore.Info.CurrentFeature.Bits.bSelfPowered Self Powered */ 253 /* USBCore.Info.uIsDiscardClearFeature Discard ClearFeature flag for Mass Storage */ 254 /* */ 255 /* USBCore.Class - USBDCore_Class_TypeDef USB Class call back function */ 256 /* USBCore.Class.CallBack_MainRoutine.func(uPara) Class main routine call back function */ 257 /* USBCore.Class.CallBack_MainRoutine.uPara Parameter of class main routine */ 258 /* USBCore.Class.CallBack_Reset.func(uPara) Class RESET call back function */ 259 /* USBCore.Class.CallBack_Reset.uPara Parameter of RESET call back function */ 260 /* USBCore.Class.CallBack_StartOfFrame.func(uPara) Class SOF call back function */ 261 /* USBCore.Class.CallBack_StartOfFrame.uPara Parameter of SOF call back function */ 262 /* USBCore.Class.CallBack_ClassGetDescriptor(pDev) Class Get Descriptor call back function */ 263 /* USBCore.Class.CallBack_ClassSetInterface(pDev) Set Interface call back function */ 264 /* USBCore.Class.CallBack_ClassGetInterface(pDev) Get Interface call back function */ 265 /* USBCore.Class.CallBack_ClassRequest(pDev) Class Request call back function */ 266 /* USBCore.Class.CallBack_EPTn[MAX_EP_NUM](EPTn) Endpoint n call back function */ 267 /* */ 268 /* USBCore.pDriver USB Device Driver initialization structure */ 269 /* */ 270 /* USBCore.Power - USBDCore_Power_TypeDef USB Device Power related call back function */ 271 /* USBCore.Power.CallBack_Suspend.func(uPara) System low power function for SUSPEND */ 272 /* USBCore.Power.CallBack_Suspend.uPara Parameter of system low power function */ 273 /*----------------------------------------------------------------------------------------------------------*/ 274 275 /** 276 * @} 277 */ 278 279 /* Exported constants --------------------------------------------------------------------------------------*/ 280 /** @defgroup USBDCore_Exported_Constant USB Device Core exported constants 281 * @{ 282 */ 283 284 /** @defgroup USBDCore_Descriptor Definitions for USB descriptor 285 * @{ 286 */ 287 #define DESC_TYPE_01_DEV (0x1) 288 #define DESC_TYPE_02_CONFN (0x2) 289 #define DESC_TYPE_03_STR (0x3) 290 #define DESC_TYPE_04_INF (0x4) 291 #define DESC_TYPE_05_EPT (0x5) 292 #define DESC_TYPE_06_DEV_QLF (0x6) 293 #define DESC_TYPE_08_INF_PWR (0x8) 294 295 #define DESC_CLASS_00_BY_INF (0x00) 296 #define DESC_CLASS_01_AUDIO (0x01) 297 #define DESC_CLASS_02_CDC_CTRL (0x02) 298 #define DESC_CLASS_03_HID (0x03) 299 #define DESC_CLASS_05_PHY (0x05) 300 #define DESC_CLASS_06_STILL_IMG (0x06) 301 #define DESC_CLASS_07_PRINTER (0x07) 302 #define DESC_CLASS_08_MASS_STORAGE (0x08) 303 #define DESC_CLASS_09_HUB (0x09) 304 #define DESC_CLASS_0A_CDC_DATA (0x0A) 305 #define DESC_CLASS_0B_SMART_CARD (0x0B) 306 #define DESC_CLASS_0E_VIDEO (0x0E) 307 #define DESC_CLASS_0F_PHD (0x0F) 308 #define DESC_CLASS_FF_VENDOR (0xFF) 309 310 #define DESC_LEN_DEV ((u32)(18)) 311 #define DESC_LEN_CONFN ((u32)(9)) 312 #define DESC_LEN_INF ((u32)(9)) 313 #define DESC_LEN_EPT ((u32)(7)) 314 /** 315 * @} 316 */ 317 318 /** @defgroup USBDCore_Request Definitions for USB Request 319 * @{ 320 */ 321 #define REQ_DIR_00_H2D (0 << 7) 322 #define REQ_DIR_01_D2H (1 << 7) 323 324 #define REQ_TYPE_00_STD (0 << 5) 325 #define REQ_TYPE_01_CLS (1 << 5) 326 #define REQ_TYPE_02_VND (2 << 5) 327 328 #define REQ_REC_00_DEV (0) 329 #define REQ_REC_01_INF (1) 330 #define REQ_REC_02_EPT (2) 331 /** 332 * @} 333 */ 334 335 /** 336 * @brief For USBDCore_EPTReadOUTData function. 337 */ 338 #define USB_DISCARD_OUT_DATA (0) 339 340 /** 341 * @} 342 */ 343 344 /* Exported macro ------------------------------------------------------------------------------------------*/ 345 /** @defgroup USBDCore_Exported_Macro USB Device Core exported macros 346 * @{ 347 */ 348 #define __DBG_USBPrintf(...) 349 #define __DBG_USBDump(a, b) 350 351 #if (USBDCORE_DEBUG == 1) 352 #ifndef RETARGET_IS_USB 353 extern u32 __DBG_USBCount; 354 #undef __DBG_USBPrintf 355 #define __DBG_USBPrintf printf 356 #if (USBDCORE_DEBUG_DATA == 1) 357 #undef __DBG_USBDump 358 void __DBG_USBDump(uc8 *memory, u32 len); 359 #endif 360 #endif 361 #endif 362 363 /** 364 * @brief Convert Half-Word to Byte for descriptor. 365 */ 366 #define DESC_H2B(Val) ((u8)(Val & 0x00FF)), ((u8)((Val & 0xFF00) >> 8)) 367 368 /** 369 * @brief Padding 0 automatically for String descriptor. 370 */ 371 #define DESC_CHAR(c) (c), (0) 372 373 /** 374 * @brief Calculate String length for String descriptor. 375 */ 376 #define DESC_STRLEN(n) (n * 2 + 2) 377 378 /** 379 * @brief Calculate power for Configuration descriptor. 380 */ 381 #define DESC_POWER(mA) (mA / 2) 382 /** 383 * @} 384 */ 385 386 /* Exported functions --------------------------------------------------------------------------------------*/ 387 /** @defgroup USBDCore_Exported_Functions USB Device Core exported functions 388 * @{ 389 */ 390 #define USBDCore_DeInit API_USB_DEINIT 391 #define USBDCore_EPTReset API_USB_EPTn_RESET 392 #define USBDCore_EPTGetBufferLen API_USB_EPTn_GET_BUFFLEN 393 #define USBDCore_EPTGetTransferCount API_USB_EPTn_GET_CNT 394 #define USBDCore_EPTSetSTALL API_USB_EPTn_SET_HALT 395 #define USBDCore_EPTWaitSTALLSent API_USB_EPTn_WAIT_STALL_SENT 396 #define USBDCore_EPTClearDataToggle API_USB_EPTn_CLR_DTG 397 398 #define USBDCore_EPTWriteINData API_USB_EPTn_WRITE_IN 399 #define USBDCore_EPTReadOUTData API_USB_EPTn_READ_OUT 400 #define USBDCore_EPTReadMemory API_USB_EPTn_READ_MEM 401 402 void USBDCore_Init(USBDCore_TypeDef *pCore); 403 void USBDCore_IRQHandler(USBDCore_TypeDef *pCore); 404 void USBDCore_MainRoutine(USBDCore_TypeDef *pCore); 405 u32 USBDCore_IsSuspend(USBDCore_TypeDef *pCore); 406 u32 USBDCore_GetRemoteWakeUpFeature(USBDCore_TypeDef *pCore); 407 void USBDCore_TriggerRemoteWakeup(void); 408 USBDCore_Status_Enum USBDCore_GetStatus(void); 409 410 void USBDCore_EPTReset(USBD_EPTn_Enum USBD_EPTn); 411 u32 USBDCore_EPTGetBufferLen(USBD_EPTn_Enum USBD_EPTn); 412 u32 USBDCore_EPTGetTransferCount(USBD_EPTn_Enum USBD_EPTn, USBD_TCR_Enum type); 413 void USBDCore_EPTSetSTALL(USBD_EPTn_Enum USBD_EPTn); 414 void USBDCore_EPTWaitSTALLSent(USBD_EPTn_Enum USBD_EPTn); 415 void USBDCore_EPTClearDataToggle(USBD_EPTn_Enum USBD_EPTn); 416 417 u32 USBDCore_EPTWriteINData(USBD_EPTn_Enum USBD_EPTn, u32 *pFrom, u32 len); 418 u32 USBDCore_EPTReadOUTData(USBD_EPTn_Enum USBD_EPTn, u32 *pTo, u32 len); 419 u32 USBDCore_EPTReadMemory(USBD_EPTn_Enum USBD_EPTn, u32 *pTo, u32 len); 420 /** 421 * @} 422 */ 423 424 425 /** 426 * @} 427 */ 428 429 /** 430 * @} 431 */ 432 433 #ifdef __cplusplus 434 } 435 #endif 436 437 #endif /* __HT32_USBD_CORE_H -------------------------------------------------------------------------------*/ 438