1 /* 2 * Copyright 2021 MindMotion Microelectronics Co., Ltd. 3 * All rights reserved. 4 * 5 * SPDX-License-Identifier: BSD-3-Clause 6 */ 7 8 #ifndef __HAL_USB_H__ 9 #define __HAL_USB_H__ 10 11 #include "hal_common.h" 12 #include "hal_usb_bdt.h" 13 14 /*! 15 * @addtogroup USB 16 * @{ 17 */ 18 19 /*! 20 * @brief USB driver version number. 21 */ 22 #define USB_DRIVER_VERSION 0u /*!< USB_0. */ 23 24 25 /*! 26 * @addtogroup USB_INT 27 * @brief USB_INT mask codes 28 * @{ 29 */ 30 #define USB_INT_RESET USB_INTSTAT_USBRST_MASK /*!< USB Interrupt: USB bus reset. */ 31 #define USB_INT_ERROR USB_INTSTAT_ERROR_MASK /*!< USB Interrupt: Error happend. */ 32 #define USB_INT_SOFTOK USB_INTSTAT_SOFTOK_MASK /*!< USB Interrupt: Recv a SOF_Tok. */ 33 #define USB_INT_TOKENDONE USB_INTSTAT_TOKDNE_MASK /*!< USB Interrupt: Token done. */ 34 #define USB_INT_SLEEP USB_INTSTAT_SLEEP_MASK /*!< USB Interrupt: Sleep. */ 35 #define USB_INT_RESUME USB_INTSTAT_RESUME_MASK /*!< USB Interrupt: Resume. */ 36 #define USB_INT_ATTACH USB_INTSTAT_ATTACH_MASK /*!< USB Interrupt: Attach. */ 37 #define USB_INT_STALL USB_INTSTAT_STALL_MASK /*!< USB Interrupt: Stall. */ 38 /*! 39 * @} 40 */ 41 42 /*! 43 * @addtogroup USB_INT_ERR 44 * @brief USB_INT_ERR mask codes 45 * @{ 46 */ 47 #define USB_INT_ERR_PID USB_ERRSTAT_PIDERR_MASK /*!< USB Error: PID check error. */ 48 #define USB_INT_ERR_CRC5 USB_ERRSTAT_CRC5EOF_MASK /*!< USB Error: CRC5 check failed. */ 49 #define USB_INT_ERR_EOF USB_ERRSTAT_CRC5EOF_MASK /*!< USB Error: EOF Error. */ 50 #define USB_INT_ERR_CRC16 USB_ERRSTAT_CRC16_MASK /*!< USB Error: CRC16 check failed. */ 51 #define USB_INT_ERR_DFN8 USB_ERRSTAT_DFN8_MASK /*!< USB Error: Data not 8bit. */ 52 #define USB_INT_ERR_BTO USB_ERRSTAT_BTOERR_MASK /*!< USB Error: BTO error. */ 53 #define USB_INT_ERR_DMA USB_ERRSTAT_DMAERR_MASK /*!< USB Error: DMA error. */ 54 #define USB_INT_ERR_BTS USB_ERRSTAT_BTSERR_MASK /*!< USB Error: Bit stuff error. */ 55 /*! 56 * @} 57 */ 58 59 /*! 60 * @addtogroup USB_EP 61 * @brief USB_EP mask codes 62 * @{ 63 */ 64 #define USB_EP_0 (1u << 0u ) /*!< EndPoint 0. */ 65 #define USB_EP_1 (1u << 1u ) /*!< EndPoint 1. */ 66 #define USB_EP_2 (1u << 2u ) /*!< EndPoint 2. */ 67 #define USB_EP_3 (1u << 3u ) /*!< EndPoint 3. */ 68 #define USB_EP_4 (1u << 4u ) /*!< EndPoint 4. */ 69 #define USB_EP_5 (1u << 5u ) /*!< EndPoint 5. */ 70 #define USB_EP_6 (1u << 6u ) /*!< EndPoint 6. */ 71 #define USB_EP_7 (1u << 7u ) /*!< EndPoint 7. */ 72 #define USB_EP_8 (1u << 8u ) /*!< EndPoint 8. */ 73 #define USB_EP_9 (1u << 9u ) /*!< EndPoint 9. */ 74 #define USB_EP_10 (1u << 10u) /*!< EndPoint 10. */ 75 #define USB_EP_11 (1u << 11u) /*!< EndPoint 11. */ 76 #define USB_EP_12 (1u << 12u) /*!< EndPoint 12. */ 77 #define USB_EP_13 (1u << 13u) /*!< EndPoint 13. */ 78 #define USB_EP_14 (1u << 14u) /*!< EndPoint 14. */ 79 #define USB_EP_15 (1u << 15u) /*!< EndPoint 15. */ 80 /*! 81 * @} 82 */ 83 84 /*! 85 * @brief USB TokenPid type. 86 */ 87 typedef enum 88 { 89 USB_TokenPid_OUT = 0x1u, /*!< USB Token Pid: OUT. */ 90 USB_TokenPid_IN = 0x9u, /*!< USB Token Pid: IN. */ 91 USB_TokenPid_SETUP = 0xDu, /*!< USB Token Pid: SETUP. */ 92 } USB_TokenPid_Type; 93 94 /*! 95 * @brief USB Direction type. 96 */ 97 typedef enum 98 { 99 USB_Direction_OUT = 0x0u, /*!< USB Direstion: IN. */ 100 USB_Direction_IN = 0x1u, /*!< USB Direstion: OUT. */ 101 USB_Direction_NULL, /*!< USB Direstion: NULL. */ 102 } USB_Direction_Type; 103 104 /*! 105 * @brief USB BufDesp OddEven type. 106 */ 107 typedef enum 108 { 109 USB_BufDesp_OddEven_Even = 0x0u, /*!< Buffer Descriptor OddEven: Even. */ 110 USB_BufDesp_OddEven_Odd = 0x1u, /*!< Buffer Descriptor OddEven: Odd. */ 111 } USB_BufDesp_OddEven_Type; 112 113 /*! 114 * @brief USB EndPoint Mode. 115 */ 116 typedef enum 117 { 118 USB_EndPointMode_Control = 1u, /*!< USB EndPoint Mode: Control xfer. */ 119 USB_EndPointMode_Bulk = 2u, /*!< USB EndPoint Mode: Bulk xfer. */ 120 USB_EndPointMode_Interrupt = 3u, /*!< USB EndPoint Mode: Interrupt xfer. */ 121 USB_EndPointMode_Isochronous = 4u, /*!< USB EndPoint Mode: isoch xfer. */ 122 USB_EndPointMode_NULL, /*!< USB EndPoint Mode: NULL. */ 123 } USB_EndPointMode_Type; 124 125 /*! 126 * @brief This type of structure instance is used to keep the settings when calling the @ref USB_InitDevice() to initialize the USB module. 127 */ 128 typedef struct 129 { 130 uint32_t BufDespTable_Addr; /*!< BufDespTable addr. */ 131 } USB_Device_Init_Type; 132 133 /*! 134 * @brief Initialize the USB module. 135 * 136 * @param USBx USB instance. 137 * @param init Pointer to the initialization structure. See to @ref USB_Device_Init_Type. 138 * @return None. 139 */ 140 void USB_InitDevice(USB_Type * USBx, USB_Device_Init_Type * init); 141 142 /*! 143 * @brief Enable interrupts of the USB module. 144 * 145 * @param USBx USB instance. 146 * @param interrupts Interrupt code masks. See to @ref USB_INT. 147 * @param enable 'true' to enable the indicated interrupts, 'false' to disable the indicated interrupts. 148 * @return None. 149 */ 150 void USB_EnableInterrupts(USB_Type * USBx, uint32_t interrupts, bool enable); 151 152 /*! 153 * @brief Get the enabled interrupts status flags of the USB module. 154 * 155 * @param USBx USB instance. 156 * @return Interrupt status flags. See to @ref USB_INT. 157 */ 158 uint32_t USB_GetEnabledInterrupts(USB_Type * USBx); 159 160 /*! 161 * @brief Get the interrupts status flags of the USB module. 162 * 163 * @param USBx USB instance. 164 * @return Interrupt status flags. See to @ref USB_INT. 165 */ 166 uint32_t USB_GetInterruptStatus(USB_Type * USBx); 167 168 /*! 169 * @brief Clear the interrupts status flags of the USB module. 170 171 * @param USBx USB instance. 172 * @param interrupts Interrupt status flags. See to @ref USB_INT. 173 * @return None. 174 */ 175 void USB_ClearInterruptStatus(USB_Type * USBx, uint32_t interrupts); 176 177 /*! 178 * @brief Enable error interrupts of the USB module. 179 * 180 * @param USBx USB instance. 181 * @param interrupts Error Interrupt code masks. See to @ref USB_INT_ERR. 182 * @param enable 'true' to enable the indicated interrupts, 'false' to disable the indicated interrupts. 183 * @return None. 184 */ 185 void USB_EnableErrInterrupts(USB_Type * USBx, uint32_t interrupts, bool enable); 186 187 /*! 188 * @brief Get the enabled error interrupts status flags of the USB module. 189 * 190 * @param USBx USB instance. 191 * @return Interrupt status flags. See to @ref USB_INT_ERR. 192 */ 193 uint32_t USB_GetEnabledErrInterrupts(USB_Type * USBx); 194 195 /*! 196 * @brief Get the error interrupts status flags of the USB module. 197 * 198 * @param USBx USB instance. 199 * @return Interrupt status flags. See to @ref USB_INT_ERR. 200 */ 201 uint32_t USB_GetErrInterruptStatus(USB_Type * USBx); 202 203 /*! 204 * @brief Clear the error interrupts status flags of the USB module. 205 206 * @param USBx USB instance. 207 * @param interrupts Interrupt status flags. See to @ref USB_INT_ERR. 208 * @return None. 209 */ 210 void USB_ClearErrInterruptStatus(USB_Type * USBx, uint32_t interrupts); 211 212 /*! 213 * @brief Enable USB. 214 * 215 * @param USBx USB instance. 216 * @param enable 'true' to enable the module, 'false' to disable the module. 217 * @return None. 218 */ 219 void USB_Enable(USB_Type * USBx, bool enable); 220 221 /*! 222 * @brief Enable USB BufDesp ODD_EVEN Reset, and make only even BufDesp can be used. 223 * 224 * @param USBx USB instance. 225 * @param enable 'true' to enable the feature, 'false' to disable the feature. 226 * @return None. 227 */ 228 void USB_EnableOddEvenReset(USB_Type * USBx, bool enable); 229 230 /*! 231 * @brief Enable USB Resume signal. 232 * 233 * @param USBx USB instance. 234 * @param enable 'true' to enable the resume signal, 'false' to disable the resume signal. 235 * @return None. 236 */ 237 void USB_EnableResumeSignal(USB_Type * USBx, bool enable); 238 239 /*! 240 * @brief Enable USB Suspend. 241 * 242 * @param USBx USB instance. 243 * @param enable 'true' to enable suspend, 'false' to disable suspend. 244 * @return None. 245 */ 246 void USB_EnableSuspend(USB_Type * USBx, bool enable); 247 248 /*! 249 * @brief Set Device address. This address is distribute by host. 250 * 251 * @param USBx USB instance. 252 * @param addr The Device address. 253 * @return None. 254 */ 255 void USB_SetDeviceAddr(USB_Type * USBx, uint8_t addr); 256 257 /*! 258 * @brief Get Device address. 259 * 260 * @param USBx USB instance. 261 * @return The Device address. 262 */ 263 uint8_t USB_GetDeviceAddr(USB_Type * USBx); 264 265 /*! 266 * @brief Get buffer descriptor table address. 267 * 268 * @param USBx USB instance. 269 * @return The BufDespTable address. 270 */ 271 uint32_t USB_GetBufDespTableAddr(USB_Type * USBx); 272 273 /*! 274 * @brief Get the USB Frame Number. 275 * 276 * @param USBx USB instance. 277 * @return The USB Frame Number. 278 */ 279 uint32_t USB_GetFrameNumber(USB_Type * USBx); 280 281 /*! 282 * @brief Get BufDesp after USB_INT_TOKENDONE interrupt happened and before clear USB_INT_TOKENDONE interrupt status. 283 * 284 * @param USBx USB instance. 285 * @return BufDesp address. 286 */ 287 USB_BufDesp_Type * USB_GetBufDesp(USB_Type * USBx); 288 289 /*! 290 * @brief Get Token Pid from BufDesp before the BufDesp Reset. 291 * 292 * @param bd BufDesp addr. 293 * @return Token Pid. 294 */ 295 USB_TokenPid_Type USB_BufDesp_GetTokenPid(USB_BufDesp_Type * bd); 296 297 /*! 298 * @brief Get packet addr from BufDesp before the BufDesp Reset. 299 * 300 * @param bd BufDesp addr. 301 * @return Packet addrress. 302 */ 303 uint32_t USB_BufDesp_GetPacketAddr(USB_BufDesp_Type * bd); 304 305 /*! 306 * @brief Get packet size from BufDesp before the BufDesp Reset. 307 * 308 * @param bd BufDesp addr. 309 * @return Packet size. 310 */ 311 uint32_t USB_BufDesp_GetPacketSize(USB_BufDesp_Type * bd); 312 313 /*! 314 * @brief Reset BufDesp. 315 * 316 * @param bd BufDesp addr. 317 * @return None. 318 */ 319 void USB_BufDesp_Reset(USB_BufDesp_Type * bd); 320 321 /*! 322 * @brief Get EndPoint index after USB_INT_TOKENDONE interrupt happened and before clear USB_INT_TOKENDONE interrupt status. 323 * 324 * @param USBx USB instance. 325 * @return EndPoint index. 326 */ 327 uint32_t USB_GetEndPointIndex(USB_Type * USBx); 328 329 /*! 330 * @brief Get Xfer Direction after USB_INT_TOKENDONE interrupt happened and before clear USB_INT_TOKENDONE interrupt status. 331 * 332 * @param USBx USB instance. 333 * @return Xfer Direction, See to @ref USB_Direction_Type. 334 */ 335 USB_Direction_Type USB_GetXferDirection(USB_Type * USBx); 336 337 /*! 338 * @brief Get BufDesp OddEven after USB_INT_TOKENDONE interrupt happened and before clear USB_INT_TOKENDONE interrupt status. 339 * 340 * @param USBx USB instance. 341 * @return BufDesp OddEven. 342 */ 343 USB_BufDesp_OddEven_Type USB_GetBufDespOddEven(USB_Type * USBx); 344 345 /*! 346 * @brief Enable the end point. 347 * 348 * @param USBx USB instance. 349 * @param index endpoint index. 350 * @param mode End point mode, See to @ref USB_EndPointMode_Type. 351 * @param enable 'true' to enable the EndPoint, 'false' to disable the EndPoint. 352 * @return None. 353 */ 354 void USB_EnableEndPoint(USB_Type * USBx, uint32_t index, USB_EndPointMode_Type mode, bool enable); 355 356 /*! 357 * @brief Stall EndPoint n. 358 * 359 * @param USBx USB instance. 360 * @param ep_mask EndPoint mask, see to @ref USB_EP mask codes. 361 * @param enable 'true' to enable the EndPoint stall, 'false' to disable the EndPoint stall. 362 * @return None. 363 */ 364 void USB_EnableEndPointStall(USB_Type * USBx, uint32_t ep_mask, bool enable); 365 366 /*! 367 * @brief Get Enabled EndPoint stall status. 368 * 369 * @param USBx USB instance. 370 * @return stall status, see to @ref USB_EP mask codes. 371 */ 372 uint32_t USB_GetEnabledEndPointStall(USB_Type * USBx); 373 374 /*! 375 * @brief Xfer data by usb. 376 * 377 * @param bd BufDesp. 378 * @param data_n DATAn packet, n equal 0 or 1. 379 * @param data the address of data. 380 * @param len Data length. 381 * @return 'true': BufDesp can be xfer data, 'false': BufDesp is busy. 382 */ 383 bool USB_BufDesp_Xfer(USB_BufDesp_Type * bd, uint32_t data_n, uint8_t * data, uint32_t len); 384 385 /*! 386 * @brief Check whether BufDesp is busy. 387 * 388 * @param bd BufDesp addr. 389 * @return 'true': BufDesp is busy, 'false': BufDesp is not busy. 390 */ 391 bool USB_BufDesp_IsBusy(USB_BufDesp_Type * bd); 392 393 394 /*! 395 *@} 396 */ 397 398 #endif /* __HAL_USB_H__ */ 399 400