1 //***************************************************************************** 2 // 3 //! @file am_hal_usb.h 4 //! 5 //! @brief Functions for USB module 6 //! 7 //! @addtogroup usb_4p USB Functionality 8 //! @ingroup apollo4p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2023, Ambiq Micro, Inc. 16 // All rights reserved. 17 // 18 // Redistribution and use in source and binary forms, with or without 19 // modification, are permitted provided that the following conditions are met: 20 // 21 // 1. Redistributions of source code must retain the above copyright notice, 22 // this list of conditions and the following disclaimer. 23 // 24 // 2. Redistributions in binary form must reproduce the above copyright 25 // notice, this list of conditions and the following disclaimer in the 26 // documentation and/or other materials provided with the distribution. 27 // 28 // 3. Neither the name of the copyright holder nor the names of its 29 // contributors may be used to endorse or promote products derived from this 30 // software without specific prior written permission. 31 // 32 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 33 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 34 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 35 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 36 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 37 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 38 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 39 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 40 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 41 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 42 // POSSIBILITY OF SUCH DAMAGE. 43 // 44 // This is part of revision release_sdk_4_4_0-3c5977e664 of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 48 #ifndef AM_HAL_USB_H_ 49 #define AM_HAL_USB_H_ 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 //***************************************************************************** 56 // 57 //! @brief This is Used to select the HFRC2 configuration for HighSpeed USB 58 //! used in function am_hal_usb_setHFRC2 arguments 59 // 60 //***************************************************************************** 61 typedef enum 62 { 63 AM_HAL_USB_HS_CLK_DISABLE, ///< hfrc2 will be disabled, default off method 64 AM_HAL_USB_HS_CLK_DISABLE_HFRC2_ADJ, ///< hfrc2 will be disabled, not default 65 AM_HAL_USB_HS_CLK_HFRC2, ///< default HFRC2 will be enabled 66 AM_HAL_USB_HS_CLK_HFRC2_ADJ, ///< HFRC2 adjust based on the internal 32Mhz 67 AM_HAL_USB_HS_CLK_HFRC2_ADJ_EXTERN_CLK, ///< HFRC2 adjust based on external clock 68 AM_HAL_USB_HS_CLK_X32 = 0x7FFFFFF, ///< force vars derived from this enum to 4 bytes 69 } 70 am_hal_usb_hs_clock_type ; 71 72 //***************************************************************************** 73 // 74 //! @brief Enum for the USB speed type. 75 //! 76 //! These macros correspond to the defintions in the USB specification. 77 //! They may be used with the \e am_hal_usb_set_dev_speed() function. 78 // 79 //***************************************************************************** 80 typedef enum 81 { 82 AM_HAL_USB_SPEED_LOW, 83 AM_HAL_USB_SPEED_FULL, 84 AM_HAL_USB_SPEED_HIGH, 85 AM_HAL_USB_SPEED_UNKNOWN 86 } 87 am_hal_usb_dev_speed_e; 88 89 //***************************************************************************** 90 // 91 //! @brief Enum for the USB device state. 92 //! 93 //! These macros partially correspond to the defintions in the USB specification. 94 //! They may be used with the \e am_hal_usb_set_dev_state() function. 95 //! 96 // 97 //***************************************************************************** 98 typedef enum 99 { 100 AM_HAL_USB_DEV_STATE_INIT, 101 AM_HAL_USB_DEV_STATE_ADDRESSED, 102 AM_HAL_USB_DEV_STATE_CONFIGED, 103 AM_HAL_USB_DEV_STATE_RESUMING, 104 AM_HAL_USB_DEV_STATE_ACTIVE, 105 AM_HAL_USB_DEV_STATE_SUSPENDING, 106 AM_HAL_USB_DEV_STATE_SUSPENDED 107 } 108 am_hal_usb_dev_state_e; 109 110 //***************************************************************************** 111 // 112 //! @brief Enum for the USB device bus event. 113 //! 114 //! These macros correspond to the defintions in the USB specification. 115 //! They may be used with the \e am_hal_usb_dev_evt_callback callback function 116 //! provided by upper layer USB stack. 117 //! 118 // 119 //***************************************************************************** 120 typedef enum 121 { 122 AM_HAL_USB_DEV_EVT_BUS_RESET, 123 AM_HAL_USB_DEV_EVT_SOF, 124 AM_HAL_USB_DEV_EVT_RESUME, 125 AM_HAL_USB_DEV_EVT_SUSPEND, 126 AM_HAL_USB_DEV_EVT_NUM 127 } 128 am_hal_usb_dev_event_e; 129 130 //***************************************************************************** 131 // 132 //! @brief Enum for the USB transfer status. 133 //! 134 //! These macros is used to indicate how the USB transfer is completed. 135 //! They may be used with the \e am_hal_usb_ep_xfer_complete_callback callback 136 //! function provided by upper layer USB stack. 137 //! 138 // 139 //***************************************************************************** 140 typedef enum 141 { 142 // Transfer is done without error, for ctrl it means status packet done 143 USB_XFER_DONE, 144 // For control transfer only, data stage is done without error 145 USB_XFER_DATA, 146 // Endpoint stall is set 147 USB_XFER_STALL, 148 // Endpoint stall is cleared 149 USB_XFER_UNSTALL, 150 // Transfer is aborted 151 USB_XFER_ABORT, 152 // Transfer is aborted because endpoint reset/disable 153 USB_XFER_RESET, 154 // There was an error 155 USB_XFER_ERROR 156 } 157 am_hal_usb_xfer_code_e; 158 159 160 //***************************************************************************** 161 // 162 //! @brief Enum for the USB control call 163 //! 164 //! The macros defined here are used to specify how the void * parameter(s) 165 //! passed into the control function are interpreted. 166 //! 167 // 168 //***************************************************************************** 169 typedef enum 170 { 171 // 172 //! this is used when the XTAL freq is not the default 32mhz and 173 //! high speed USB mode is needed. This will allow the caller to set a 174 //! non 32Mhz HF_XTAL freq. (The default value is 32Mhz) 175 // 176 AM_HAL_CLKGEN_CONTROL_SET_XTAL_FREQ, 177 // 178 //! this is controller by an argument of type am_hal_usb_hs_clock_type 179 //! this is how modules configure the HFRC2 180 AM_HAL_CLKGEN_CONTROL_SET_HFRC2_TYPE, 181 182 183 } am_hal_usb_control_e; 184 185 //***************************************************************************** 186 // 187 //! @brief device event callback function pointer type 188 //! 189 //! Upper layer USB stack uses it to define a callback function to receive the 190 //! the USB bus events and registers it by 'am_hal_usb_register_dev_evt_callback' 191 //! function. 192 // 193 //***************************************************************************** 194 typedef void (*am_hal_usb_dev_evt_callback)(am_hal_usb_dev_event_e eDevState); 195 196 //***************************************************************************** 197 // 198 //! @brief ep0 setup request callback function pointer type 199 //! 200 //! Upper layer USB stack uses it to define a callback function to receive 201 //! setup requst from the USB host and registers it by 202 //! 'am_hal_usb_register_ep0_setup_received_callback' function. 203 // 204 //***************************************************************************** 205 typedef void (*am_hal_usb_ep0_setup_received_callback)(uint8_t *pui8Setup); 206 207 //***************************************************************************** 208 // 209 //! @brief ctrl/bulk/intr/iso transfer callback function pointer type 210 //! 211 //! Upper layer USB stack uses it to define a callback function to receive a 212 //! confirm for the USB HAL driver about how many bytes has been tranfered and 213 //! the transfer status. 214 // 215 //***************************************************************************** 216 typedef void (*am_hal_usb_ep_xfer_complete_callback)(uint8_t ui8EpAddr, uint16_t ui16XferLen, am_hal_usb_xfer_code_e eXferCode, void *param); 217 218 //***************************************************************************** 219 // 220 //! @brief register a USB bus event callback function 221 //! 222 //! @param pHandle - handle for the module instance. 223 //! @param cb - a USB bus event callback function. 224 //! 225 //! This function registers a USB bus event callback function defined in the upper layer 226 //! USB stack. 227 //! 228 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 229 // 230 //***************************************************************************** 231 extern uint32_t am_hal_usb_register_dev_evt_callback(void *pHandle, am_hal_usb_dev_evt_callback cb); 232 233 //***************************************************************************** 234 // 235 //! @brief register a setup requst callback function 236 //! 237 //! @param pHandle - handle for the module instance. 238 //! @param cb - setup request callback function. 239 //! 240 //! This function registers a setup request callback function defined in the upper layer 241 //! USB stack. 242 //! 243 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 244 // 245 //***************************************************************************** 246 extern uint32_t am_hal_usb_register_ep0_setup_received_callback(void *pHandle, am_hal_usb_ep0_setup_received_callback cb); 247 248 //***************************************************************************** 249 // 250 //! @brief register a transfer completion callback function 251 //! 252 //! @param pHandle - handle for the module instance. 253 //! @param cb - transfer completion callback function. 254 //! 255 //! This function registers a bulk/intr/iso transfer completion callback function. 256 //! 257 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 258 // 259 //***************************************************************************** 260 extern uint32_t am_hal_usb_register_ep_xfer_complete_callback(void *pHandle, am_hal_usb_ep_xfer_complete_callback cb); 261 262 //***************************************************************************** 263 // 264 //! @brief set the USB device state 265 //! 266 //! @param pHandle - handle for the module instance. 267 //! @param eDevState - device states like suspended, resuming, etc. 268 //! 269 //! This function is used by upper layer USB stack to set the device state. 270 //! 271 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 272 // 273 //***************************************************************************** 274 extern uint32_t am_hal_usb_set_dev_state(void *pHandle, am_hal_usb_dev_state_e eDevState); 275 276 //***************************************************************************** 277 // 278 //! @brief start the remote wakeup 279 //! 280 //! @param pHandle - handle for the module instance. 281 //! 282 //! This function is used by upper layer USB stack to start a remote wakeup action. 283 //! 284 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 285 // 286 //***************************************************************************** 287 extern uint32_t am_hal_usb_start_remote_wakeup(void *pHandle); 288 289 //***************************************************************************** 290 // 291 //! @brief stop the remote wakeup 292 //! 293 //! @param pHandle - handle for the module instance. 294 //! 295 //! This function is used by upper layer USB stack to end a remote wakeup action. 296 //! 297 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 298 // 299 //***************************************************************************** 300 extern uint32_t am_hal_usb_end_remote_wakeup(void *pHandle); 301 302 //***************************************************************************** 303 // 304 //! @brief set the USB device address 305 //! 306 //! @param pHandle - handle for the module instance. 307 //! @param ui8EpAddr - set the USB device address 308 //! 309 //! This function is used by upper layer USB stack to set the device address allocated 310 //! by the USB host during the enumeration. 311 //! 312 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 313 // 314 //***************************************************************************** 315 extern uint32_t am_hal_usb_set_addr(void *pHandle, uint8_t ui8EpAddr); 316 317 //***************************************************************************** 318 // 319 //! @brief soft connect to the USB host 320 //! 321 //! @param pHandle - handle for the module instance. 322 //! 323 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 324 // 325 //***************************************************************************** 326 extern uint32_t am_hal_usb_attach(void *pHandle); 327 328 //***************************************************************************** 329 // 330 //! @brief soft disconnect to the USB host 331 //! 332 //! @param pHandle - handle for the module instance. 333 //! 334 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 335 // 336 //***************************************************************************** 337 extern uint32_t am_hal_usb_detach(void *pHandle); 338 339 //***************************************************************************** 340 // 341 //! @brief get the USB frame number 342 //! 343 //! @param pHandle - handle for the module instance. 344 //! 345 //! This function is used by upper layer USB stack to get the USB frame number. 346 //! 347 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 348 // 349 //***************************************************************************** 350 extern uint32_t am_hal_get_frame_number(void *pHandle); 351 352 //***************************************************************************** 353 // 354 //! @brief enable the SOF interrupt 355 //! 356 //! @param pHandle - handle for the module instance. 357 //! 358 //! This function is used by upper layer USB stack to enable the SOF interrupt. 359 //! 360 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 361 // 362 //***************************************************************************** 363 extern uint32_t am_hal_usb_enable_sof_intr(void *pHandle); 364 365 //***************************************************************************** 366 // 367 //! @brief disable the SOF interrupt 368 //! 369 //! @param pHandle - handle for the module instance. 370 //! 371 //! This function is used by upper layer USB stack to disable the SOF interrupt. 372 //! 373 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 374 // 375 //***************************************************************************** 376 extern uint32_t am_hal_usb_disable_sof_intr(void *pHandle); 377 378 #define AM_HAL_USB_GET_HW_INFO_ENABLED 379 #ifdef AM_HAL_USB_GET_HW_INFO_ENABLED 380 381 //***************************************************************************** 382 // 383 //! @brief Macro definitions for the USB hardware information. 384 //! 385 //! These macros correspond to the definitions in the datasheet of 386 //! apollo4 USB peripheral. 387 //! They may be used with the \e am_hal_usb_get_hw_infor function. 388 //! 389 // 390 //***************************************************************************** 391 typedef struct 392 { 393 // the major version number 394 uint8_t ui8Major; 395 // the minor version number 396 uint16_t ui16Minor; 397 // the number of OUT endpoints 398 uint8_t ui8OutEpNum; 399 // the number of IN endpoints 400 uint8_t ui8InEpNum; 401 // the width of RAM bus address 402 uint8_t ui8RamBits; 403 } am_hal_usb_hw_info; 404 405 //***************************************************************************** 406 // 407 //! @brief get the hardware information 408 //! 409 //! @param pHandle - handle for the module instance. 410 //! @param sHWInfo - the information about the USB device hardware configuration. 411 //! 412 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 413 // 414 //***************************************************************************** 415 extern uint32_t am_hal_usb_get_hw_infor(void *pHandle, am_hal_usb_hw_info *sHWInfo); 416 417 #endif 418 419 #define AM_HAL_USB_TEST_MODE_ENABLED 420 #ifdef AM_HAL_USB_TEST_MODE_ENABLED 421 422 //***************************************************************************** 423 // 424 //! @brief Macro definitions for the USB devie test mode. 425 //! 426 //! These macros correspond to the defintions in the USB specification. 427 //! They may be used with the \e am_hal_usb_test_mode function. 428 //! 429 // 430 //***************************************************************************** 431 typedef enum 432 { 433 AM_HAL_USB_TEST_SE0_NAK, 434 AM_HAL_USB_TEST_J, 435 AM_HAL_USB_TEST_K, 436 AM_HAL_USB_TEST_PACKET 437 } 438 am_hal_usb_test_mode_e; 439 440 // 441 // Upper layer USB stack should call below functions 442 // when receive TEST_MODE request 443 // 444 //***************************************************************************** 445 // 446 //! @brief set the USB test mode flag 447 //! 448 //! @param pHandle - handle for the module instance. 449 //! 450 //! set a flag in the handle to indicate the current USB device in the test mode. 451 //! 452 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 453 // 454 //***************************************************************************** 455 extern uint32_t am_hal_usb_enter_test_mode(const void *pHandle); 456 457 //***************************************************************************** 458 // 459 //! @brief do the USB test 460 //! 461 //! @param pHandle - handle for the module instance. 462 //! @param eTestMode - one of the test mode like TEST_SE0_NAK, TEST_J, TEST_K and TEST_PACKET. 463 //! 464 //! This function is used by upper layer USB stack to order the USB device controller 465 //! to send the specific USB packet or signals to verify the timing and signal quaility. 466 //! 467 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 468 // 469 //***************************************************************************** 470 extern uint32_t am_hal_usb_test_mode(const void *pHandle, const am_hal_usb_test_mode_e eTestMode); 471 #endif 472 473 //***************************************************************************** 474 // 475 //! @brief initialize the endpoint 476 //! 477 //! @param pHandle - handle for the module instance. 478 //! @param ui8EpAddr - endpoint address including the endpoint direction 479 //! @param ui8EpAttr - the type of endpoint (bulk/intr/iso/control) 480 //! @param ui16MaxPacket - the max packet length of the endpoint 481 //! 482 //! This function is used by upper layer USB stack to initialize the endpoints 483 //! when USB host sets the configuration of the USB device. 484 //! 485 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 486 // 487 //***************************************************************************** 488 extern uint32_t am_hal_usb_ep_init(void *pHandle, uint8_t ui8EpAddr, uint8_t ui8EpAttr, uint16_t ui16MaxPacket); 489 490 //***************************************************************************** 491 // 492 //! @brief stall the endpoint 493 //! 494 //! @param pHandle - handle for the module instance. 495 //! @param ui8EpAddr - endpoint address including the endpoint direction 496 //! 497 //! This function is used by upper layer USB stack to stall the endpoint when 498 //! some unknown requests can't be handled or transfer can't continue. 499 //! 500 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 501 // 502 //***************************************************************************** 503 extern uint32_t am_hal_usb_ep_stall(void *pHandle, uint8_t ui8EpAddr); 504 505 //***************************************************************************** 506 // 507 //! @brief clear the endpoint stall 508 //! 509 //! @param pHandle - handle for the module instance. 510 //! @param ui8EpAddr - endpoint address including the endpoint direction 511 //! 512 //! This function is used by upper layer USB stack to clear the endpoint stall 513 //! when USB device stack can recovry from some error status or USB host sends 514 //! the clear feature request to clear the stall of the endpoint. 515 //! 516 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 517 // 518 //***************************************************************************** 519 extern uint32_t am_hal_usb_ep_clear_stall(void *pHandle, uint8_t ui8EpAddr); 520 521 //***************************************************************************** 522 // 523 //! @brief submit a USB transfer 524 //! 525 //! @param pHandle - handle for the module instance. 526 //! @param ui8EpAddr - endpoint address including the endpoint direction 527 //! @param pui8Buf - the buffer for receiving the data from USB host or 528 //! sending data to the USB host. 529 //! @param ui16Len - the length of the buffer. 530 //! 531 //! This function is used by the upper layer USB stack to submit a transfer requst 532 //! to the USB device controller. 533 //! 534 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 535 // 536 //***************************************************************************** 537 extern uint32_t am_hal_usb_ep_xfer(void *pHandle, uint8_t ui8EpAddr, uint8_t *pui8Buf, uint16_t ui16Len); 538 539 //***************************************************************************** 540 // 541 //! @brief get the current USB speed 542 //! 543 //! @param pHandle - handle for the module instance. 544 //! 545 //! This function is used by the upper layer USB stack to get the current USB 546 //! speed type 547 //! like full-speed or high-speed. 548 //! 549 //! @return one of am_hal_usb_dev_speed_e like 550 //! AM_HAL_USB_SPEED_FULL 551 //! AM_HAL_USB_SPEED_HIGH, etc. 552 // 553 //***************************************************************************** 554 extern am_hal_usb_dev_speed_e am_hal_get_usb_dev_speed(void *pHandle); 555 556 //***************************************************************************** 557 // 558 //! @brief set the USB speed 559 //! 560 //! @param pHandle - handle for the module instance. 561 //! @param eSpeed - speed type of the USB device 562 //! 563 //! This function is used by the upper layer USB stack to force USB device controller 564 //! to run under a certain speed, for example full-speed by ignoring the controller 565 //! high-speed capability. 566 //! 567 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 568 // 569 //***************************************************************************** 570 extern uint32_t am_hal_usb_set_dev_speed(void *pHandle, am_hal_usb_dev_speed_e eSpeed); 571 572 //***************************************************************************** 573 // 574 //! @brief initialize the USB device controller module 575 //! 576 //! @param ui32Module - the index to the USB module 577 //! @param ppHandle - the handle of initialized USB instance 578 //! 579 //! This function should be called firstly before we use any other USB HAL driver 580 //! functions. 581 //! 582 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 583 // 584 //***************************************************************************** 585 extern uint32_t am_hal_usb_initialize(uint32_t ui32Module, void **ppHandle); 586 587 //***************************************************************************** 588 // 589 //! @brief uninitialize the USB device controller module 590 //! 591 //! @param pHandle - the handle of initialized USB instance 592 //! 593 //! This function should be called finally after we want to shutdown the USB 594 //! device controller. 595 //! 596 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 597 // 598 //***************************************************************************** 599 extern uint32_t am_hal_usb_deinitialize(void *pHandle); 600 601 //***************************************************************************** 602 // 603 //! @brief power on/off the USB device controller 604 //! 605 //! @param pHandle - the handle of initialized USB instance 606 //! @param ePowerState - the power state of USB device controller 607 //! @param bRetainState - wether retain the USB registers or not 608 //! 609 //! This function should be called after USB device controller has been initalized 610 //! successfully by 'am_hal_usb_initialize'. 611 //! 612 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 613 // 614 //***************************************************************************** 615 extern uint32_t am_hal_usb_power_control(void *pHandle, am_hal_sysctrl_power_state_e ePowerState, bool bRetainState); 616 617 //***************************************************************************** 618 // 619 //! @brief enable the IN endpoints' interrupt 620 //! 621 //! @param pHandle - the handle of initialized USB instance 622 //! @param ui32IntMask - the bit mask of IN endpoints' interrupt 623 //! 624 //! This function is used to enable the IN endpoints' interrupt. 625 //! 626 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 627 // 628 //***************************************************************************** 629 extern uint32_t am_hal_usb_intr_ep_in_enable(void *pHandle, uint32_t ui32IntMask); 630 631 //***************************************************************************** 632 // 633 //! @brief disable the IN endpoints' interrupt 634 //! 635 //! @param pHandle - the handle of initialized USB instance 636 //! @param ui32IntMask - the bit mask of IN endpoints' interrupt 637 //! 638 //! This function is used to disable the IN endpoints' interrupt. 639 //! 640 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 641 // 642 //***************************************************************************** 643 extern uint32_t am_hal_usb_intr_ep_in_disable(void *pHandle, uint32_t ui32IntMask); 644 645 //***************************************************************************** 646 // 647 //! @brief clear the IN endpoints' interrupt status 648 //! 649 //! @param pHandle - the handle of initialized USB instance 650 //! 651 //! This function is used to clear the IN endpoints' interrupt status. 652 //! 653 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 654 // 655 //***************************************************************************** 656 extern uint32_t am_hal_usb_intr_ep_in_clear(void *pHandle); 657 658 //***************************************************************************** 659 // 660 //! @brief get the IN endpoints' interrupt status 661 //! 662 //! @param pHandle - the handle of initialized USB instance 663 //! @param ui32IntStatus - the IN endpoints' interrupt status 664 //! @param bEnabledOnly - only check enabled IN endpoint interrupt or not 665 //! 666 //! This function is used to get IN endpoints' interrupt status. 667 //! 668 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 669 // 670 //***************************************************************************** 671 extern uint32_t am_hal_usb_intr_ep_in_status_get(void *pHandle, uint32_t *ui32IntStatus, bool bEnabledOnly); 672 673 //***************************************************************************** 674 // 675 //! @brief enable the OUT endpoints' interrupt 676 //! 677 //! @param pHandle - the handle of initialized USB instance 678 //! @param ui32IntMask - the bit mask of OUT endpoints' interrupt 679 //! 680 //! This function is used to enable the OUT endpoints' interrupt. 681 //! 682 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 683 // 684 //***************************************************************************** 685 extern uint32_t am_hal_usb_intr_ep_out_enable(void *pHandle, uint32_t ui32IntMask); 686 687 //***************************************************************************** 688 // 689 //! @brief disable the endpoints' interrupt 690 //! 691 //! @param pHandle - the handle of initialized USB instance 692 //! @param ui32IntMask - the bit mask of OUT endpoints' interrupt 693 //! 694 //! This function is used to disable the OUT endpoints' interrupt. 695 //! 696 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 697 // 698 //***************************************************************************** 699 extern uint32_t am_hal_usb_intr_ep_out_disable(void *pHandle, uint32_t ui32IntMask); 700 701 //***************************************************************************** 702 // 703 //! @brief clear the OUT endpoints' interrupt status 704 //! 705 //! @param pHandle - the handle of initialized USB instance 706 //! 707 //! This function is used to clear the OUT endpoints' interrupt. 708 //! 709 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 710 // 711 //***************************************************************************** 712 extern uint32_t am_hal_usb_intr_ep_out_clear(void *pHandle); 713 714 //***************************************************************************** 715 // 716 //! @brief get the OUT endpoints' interrupt status 717 //! 718 //! @param pHandle - the handle of initialized USB instance 719 //! @param pui32IntStatus - pointer to the OUT endpoints' interrupt status 720 //! @param bEnabledOnly - only check enabled OUT endpoint interrupt or not 721 //! 722 //! This function is used to get the OUT endpoints' interrupt status. 723 //! 724 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 725 // 726 //***************************************************************************** 727 extern uint32_t am_hal_usb_intr_ep_out_status_get(void *pHandle, uint32_t *pui32IntStatus, bool bEnabledOnly); 728 729 //***************************************************************************** 730 // 731 //! @brief enable the USB bus's interrupts 732 //! 733 //! @param pHandle - the handle of initialized USB instance 734 //! @param ui32IntMask - the bit mask of enabled USB bus interrupts 735 //! 736 //! This function is used to enable the USB bus interrupts. 737 //! 738 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 739 // 740 //***************************************************************************** 741 extern uint32_t am_hal_usb_intr_usb_enable(void *pHandle, uint32_t ui32IntMask); 742 743 //***************************************************************************** 744 // 745 //! @brief disable the USB bus's interrupts 746 //! 747 //! @param pHandle - the handle of initialized USB instance 748 //! @param ui32IntMask - the bit mask of USB bus interrupts. 749 //! 750 //! This function is used to disable the USB bus interrupts. 751 //! 752 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 753 // 754 //***************************************************************************** 755 extern uint32_t am_hal_usb_intr_usb_disable(void *pHandle, uint32_t ui32IntMask); 756 757 //***************************************************************************** 758 // 759 //! @brief clear the USB bus interrupts 760 //! 761 //! @param pHandle - the handle of initialized USB instance 762 //! 763 //! This function is used to clear the USB bus interrupt status. 764 //! 765 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 766 // 767 //***************************************************************************** 768 extern uint32_t am_hal_usb_intr_usb_clear(void *pHandle); 769 770 //***************************************************************************** 771 // 772 //! @brief get the USB bus interrupt status 773 //! 774 //! This function is used to get the USB bus interrupt status. 775 //! 776 //! @param pHandle - the handle of initialized USB instance 777 //! @param ui32IntStatus - the USB bus interrupt status 778 //! @param bEnabledOnly - only check enabled USB bus interrupt or not 779 //! 780 //! This function is used to get the USB bus interrupt status. 781 //! 782 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 783 // 784 //***************************************************************************** 785 extern uint32_t am_hal_usb_intr_usb_status_get(void *pHandle, uint32_t *ui32IntStatus, bool bEnabledOnly); 786 787 //***************************************************************************** 788 // 789 //! @brief Enum for the USB device bus event mask bit. 790 //! 791 //! This Enum are just some convenient utility for easing the programming. 792 // 793 //***************************************************************************** 794 enum 795 { 796 USB_INTRUSB_Suspend_Msk = 0x1, 797 USB_INTRUSB_Resume_Msk = 0x2, 798 USB_INTRUSB_Reset_Msk = 0x4, 799 USB_INTRUSB_SOF_Msk = 0x8, 800 USB_INTRIN_EP0_Msk = 0x1, 801 }; 802 803 //***************************************************************************** 804 // 805 //! @brief get all USB related interrupt status 806 //! 807 //! This function is used to get all USB related interrupt status. 808 //! 809 //! @param pHandle - the handle of initialized USB instance 810 //! @param ui32IntrUsbStatus - the USB bus interrupt status 811 //! @param ui32IntrInStatus - the USB IN endpoint interrupt status 812 //! @param ui32IntrOutStatus - the USB OUT endpoint interrupt status 813 //! 814 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 815 // 816 //***************************************************************************** 817 extern uint32_t am_hal_usb_intr_status_get(void *pHandle, uint32_t *ui32IntrUsbStatus, uint32_t *ui32IntrInStatus, uint32_t *ui32IntrOutStatus); 818 819 //***************************************************************************** 820 // 821 //! @brief USB interrupt service routine 822 //! 823 //! This function is USB interrupt service routine function. 824 //! 825 //! @param pHandle - the handle of initialized USB instance 826 //! @param ui32IntrUsbStatus - the USB bus interrupt status 827 //! @param ui32IntrInStatus - the USB IN endpoint interrupt status 828 //! @param ui32IntrOutStatus - the USB OUT endpoint interrupt status 829 //! 830 // 831 //***************************************************************************** 832 extern void am_hal_usb_interrupt_service(void *pHandle, 833 uint32_t ui32IntrUsbStatus, 834 uint32_t ui32IntrInStatus, 835 uint32_t ui32IntrOutStatus); 836 837 838 839 //***************************************************************************** 840 // 841 //! @brief Apply various specific commands / controls to the USB module 842 //! 843 //! @param eControl control enum 844 //! @param pArgs data used. This differs for each enum 845 //! 846 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 847 // 848 //***************************************************************************** 849 extern uint32_t am_hal_usb_control(am_hal_usb_control_e eControl, void *pArgs); 850 851 //***************************************************************************** 852 // 853 //! @brief set and enable HFRC2 FLL for 24Mhz speed usb 854 //! 855 //! @note this is used for HIGH-SPEED usb 856 //! 857 //! @param tUsbHsClockType - enable or disable the HFRC2 858 //! 859 //! @return one of am_hal_status_e like AM_HAL_STATUS_SUCCESS 860 // 861 //***************************************************************************** 862 extern uint32_t am_hal_usb_setHFRC2(am_hal_usb_hs_clock_type tUsbHsClockType); 863 864 865 #ifdef __cplusplus 866 } 867 #endif 868 869 #endif /* AM_HAL_USB_H_ */ 870 871 //***************************************************************************** 872 // 873 // End Doxygen group. 874 //! @} 875 // 876 //***************************************************************************** 877 878
