1 //***************************************************************************** 2 // 3 //! @file am_hal_mspi.h 4 //! 5 //! @brief Functions for Interfacing with the MSPI. 6 //! 7 //! @addtogroup mspi3 MSPI - Multi-bit SPI 8 //! @ingroup apollo3_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 //***************************************************************************** 13 // 14 // Copyright (c) 2024, Ambiq Micro, Inc. 15 // All rights reserved. 16 // 17 // Redistribution and use in source and binary forms, with or without 18 // modification, are permitted provided that the following conditions are met: 19 // 20 // 1. Redistributions of source code must retain the above copyright notice, 21 // this list of conditions and the following disclaimer. 22 // 23 // 2. Redistributions in binary form must reproduce the above copyright 24 // notice, this list of conditions and the following disclaimer in the 25 // documentation and/or other materials provided with the distribution. 26 // 27 // 3. Neither the name of the copyright holder nor the names of its 28 // contributors may be used to endorse or promote products derived from this 29 // software without specific prior written permission. 30 // 31 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 32 // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 33 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 34 // ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 35 // LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 36 // CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 37 // SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 38 // INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 39 // CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 40 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 41 // POSSIBILITY OF SUCH DAMAGE. 42 // 43 // This is part of revision release_sdk_3_2_0-dd5f40c14b of the AmbiqSuite Development Package. 44 // 45 //***************************************************************************** 46 #ifndef AM_HAL_MSPI_H 47 #define AM_HAL_MSPI_H 48 49 #ifdef __cplusplus 50 extern "C" 51 { 52 #endif 53 54 //***************************************************************************** 55 // 56 //! CMSIS-Style macro for handling a variable MSPI module number. 57 // 58 //***************************************************************************** 59 #define MSPIn(n) ((MSPI_Type*)(MSPI_BASE + (n * (MSPI_BASE - MSPI_BASE)))) 60 61 // 62 // USE_CQ=1 will use the Command Queue in nonblocking transfers. 63 // 0 uses plain DMA (w/o CQ) in nonblocking transfers. 64 // 65 #define MSPI_USE_CQ 1 66 67 #define AM_HAL_MSPI_MAX_TRANS_SIZE 65535 // 2^16-1 68 #define AM_HAL_MSPI_MAX_FIFO_SIZE 16 69 #define AM_HAL_MSPI_DEFAULT_BURST_COUNT 32 70 71 // Size guideline for allocation of application supplied buffers 72 #define AM_HAL_MSPI_CQ_ENTRY_SIZE (18 * sizeof(uint32_t)) 73 #define AM_HAL_MSPI_HIPRIO_ENTRY_SIZE (6 * sizeof(uint32_t)) 74 75 #define AM_HAL_MSPI_SC_CLEAR(flag) ((flag) << 16) 76 #define AM_HAL_MSPI_SC_SET(flag) ((flag)) 77 78 //! For MSPI - Need to Set the flag for unpausing 79 #define AM_HAL_MSPI_SC_UNPAUSE(flag) AM_HAL_MSPI_SC_SET(flag) 80 #define AM_HAL_MSPI_SC_PAUSE(flag) AM_HAL_MSPI_SC_CLEAR(flag) 81 82 //! Use this macro to directly control the flags 83 #define AM_HAL_MSPI_SETCLR(module, scVal) \ 84 do { \ 85 MSPIn(module)->CQSETCLEAR = (scVal); \ 86 } while (0); 87 88 //! Flags 5, 7 & 6 are reserved by HAL 89 #define AM_HAL_MSPI_PAUSE_FLAG_RESV (MSPI_CQFLAGS_CQFLAGS_SWFLAG7 | MSPI_CQFLAGS_CQFLAGS_SWFLAG6 | MSPI_CQFLAGS_CQFLAGS_SWFLAG5) 90 #define AM_HAL_MSPI_SC_RESV_MASK (AM_HAL_MSPI_PAUSE_FLAG_RESV | (AM_HAL_MSPI_PAUSE_FLAG_RESV << 8) | (AM_HAL_MSPI_PAUSE_FLAG_RESV << 16)) 91 92 //! We use SWFLAGEN7 to control SW pausing Command Queue - default unPause 93 //! We use SWFLAGEN6 to pause on the sequece loopback - default Pause 94 //! We use SWFLAGEN5 to pause CQ while a block is building 95 #define AM_HAL_MSPI_PAUSE_FLAG_IDX (_VAL2FLD(MSPI_CQFLAGS_CQFLAGS, MSPI_CQFLAGS_CQFLAGS_CQIDX)) 96 #define AM_HAL_MSPI_PAUSE_FLAG_CQ (_VAL2FLD(MSPI_CQFLAGS_CQFLAGS, MSPI_CQFLAGS_CQFLAGS_SWFLAG7)) 97 #define AM_HAL_MSPI_PAUSE_FLAG_SEQLOOP (_VAL2FLD(MSPI_CQFLAGS_CQFLAGS, MSPI_CQFLAGS_CQFLAGS_SWFLAG6)) 98 #define AM_HAL_MSPI_PAUSE_FLAG_BLOCK (_VAL2FLD(MSPI_CQFLAGS_CQFLAGS, MSPI_CQFLAGS_CQFLAGS_SWFLAG5)) 99 100 //! By default - we Pause CQ for no more entries, or force pause from SW 101 #define AM_HAL_MSPI_PAUSE_DEFAULT (AM_HAL_MSPI_PAUSE_FLAG_IDX) 102 #define AM_HAL_MSPI_CQP_PAUSE_DEFAULT (AM_HAL_MSPI_PAUSE_FLAG_IDX | AM_HAL_MSPI_PAUSE_FLAG_CQ) 103 104 //***************************************************************************** 105 // 106 //! @brief Macro definitions for MSPI interrupt status bits. 107 //! 108 //! These macros correspond to the bits in the MSPI interrupt status register. 109 //! 110 //! @name MSPI Interrupts 111 //! @{ 112 // 113 //***************************************************************************** 114 #define AM_HAL_MSPI_INT_SCRERR MSPI_INTEN_SCRERR_Msk 115 #define AM_HAL_MSPI_INT_CQERR MSPI_INTEN_CQERR_Msk 116 #define AM_HAL_MSPI_INT_CQPAUSED MSPI_INTEN_CQPAUSED_Msk 117 #define AM_HAL_MSPI_INT_CQUPD MSPI_INTEN_CQUPD_Msk 118 #define AM_HAL_MSPI_INT_CQCMP MSPI_INTEN_CQCMP_Msk 119 #define AM_HAL_MSPI_INT_DMAERR MSPI_INTEN_DERR_Msk 120 #define AM_HAL_MSPI_INT_DMACMP MSPI_INTEN_DCMP_Msk 121 #define AM_HAL_MSPI_INT_RX_FIFO_FULL MSPI_INTEN_RXF_Msk 122 #define AM_HAL_MSPI_INT_RX_FIFO_OVFL MSPI_INTEN_RXO_Msk 123 #define AM_HAL_MSPI_INT_RX_FIFO_UNFL MSPI_INTEN_RXU_Msk 124 #define AM_HAL_MSPI_INT_TX_FIFO_OVFL MSPI_INTEN_TXO_Msk 125 #define AM_HAL_MSPI_INT_TX_FIFO_EMPTY MSPI_INTEN_TXE_Msk 126 #define AM_HAL_MSPI_INT_CMDCMP MSPI_INTEN_CMDCMP_Msk 127 #define AM_HAL_MSPI_INT_ALL 0xFFFFFFFF 128 129 #define AM_HAL_MSPI_INT_ERR (AM_HAL_MSPI_INT_DMAERR | AM_HAL_MSPI_INT_CQERR | AM_HAL_MSPI_INT_SCRERR) 130 131 132 #define AM_HAL_MSPI_LINK_IOM_NONE 0x7 133 //! @} MSPI Interrupts 134 //***************************************************************************** 135 // 136 //! @brief Configuration structure for the MSPI. 137 // 138 //***************************************************************************** 139 140 // 141 //! Number of bytes in the address 142 // 143 typedef enum 144 { 145 AM_HAL_MSPI_ADDR_1_BYTE, 146 AM_HAL_MSPI_ADDR_2_BYTE, 147 AM_HAL_MSPI_ADDR_3_BYTE, 148 AM_HAL_MSPI_ADDR_4_BYTE 149 } am_hal_mspi_addr_e; 150 151 // 152 //! Number of bytes in the instruction 153 // 154 typedef enum 155 { 156 AM_HAL_MSPI_INSTR_1_BYTE, 157 AM_HAL_MSPI_INSTR_2_BYTE 158 } am_hal_mspi_instr_e; 159 160 // 161 //! Transmit or receive 162 // 163 typedef enum 164 { 165 AM_HAL_MSPI_RX = 0, 166 AM_HAL_MSPI_TX = 1 167 } am_hal_mspi_dir_e; 168 169 // 170 //! Mode of Transfer. 171 // 172 typedef enum 173 { 174 AM_HAL_MSPI_TRANS_PIO, 175 AM_HAL_MSPI_TRANS_DMA 176 } am_hal_mspi_trans_e; 177 178 // 179 //! MSPI interface mode and chip enable selection 180 // 181 typedef enum 182 { 183 AM_HAL_MSPI_FLASH_SERIAL_CE0, 184 AM_HAL_MSPI_FLASH_SERIAL_CE1, 185 AM_HAL_MSPI_FLASH_DUAL_CE0, 186 AM_HAL_MSPI_FLASH_DUAL_CE1, 187 AM_HAL_MSPI_FLASH_QUAD_CE0, 188 AM_HAL_MSPI_FLASH_QUAD_CE1, 189 AM_HAL_MSPI_FLASH_OCTAL_CE0, 190 AM_HAL_MSPI_FLASH_OCTAL_CE1, 191 AM_HAL_MSPI_FLASH_QUADPAIRED, 192 AM_HAL_MSPI_FLASH_QUADPAIRED_SERIAL, 193 AM_HAL_MSPI_FLASH_DUAL_CE0_1_1_2, 194 AM_HAL_MSPI_FLASH_DUAL_CE1_1_1_2, 195 AM_HAL_MSPI_FLASH_DUAL_CE0_1_2_2, 196 AM_HAL_MSPI_FLASH_DUAL_CE1_1_2_2, 197 AM_HAL_MSPI_FLASH_QUAD_CE0_1_1_4, 198 AM_HAL_MSPI_FLASH_QUAD_CE1_1_1_4, 199 AM_HAL_MSPI_FLASH_QUAD_CE0_1_4_4, 200 AM_HAL_MSPI_FLASH_QUAD_CE1_1_4_4, 201 AM_HAL_MSPI_FLASH_SERIAL_CE0_3WIRE, 202 AM_HAL_MSPI_FLASH_SERIAL_CE1_3WIRE, 203 AM_HAL_MSPI_FLASH_MAX = AM_HAL_MSPI_FLASH_SERIAL_CE1_3WIRE 204 } am_hal_mspi_device_e; 205 206 // 207 //! Enumerate the SPI modes. Note that these are arranged per the ordering of 208 //! SPHA (bit1) and SPOL (bit0) in the IOM.MSPICFG register. 209 // 210 typedef enum 211 { 212 AM_HAL_MSPI_SPI_MODE_0, // CPOL = 0; CPHA = 0 213 AM_HAL_MSPI_SPI_MODE_2, // CPOL = 1; CPHA = 0 214 AM_HAL_MSPI_SPI_MODE_1, // CPOL = 0; CPHA = 1 215 AM_HAL_MSPI_SPI_MODE_3, // CPOL = 1; CPHA = 1 216 } am_hal_mspi_spi_mode_e; 217 218 typedef enum 219 { 220 AM_HAL_MSPI_CLK_48MHZ = 1, 221 AM_HAL_MSPI_CLK_24MHZ = 2, 222 AM_HAL_MSPI_CLK_16MHZ = 3, 223 AM_HAL_MSPI_CLK_12MHZ = 4, 224 AM_HAL_MSPI_CLK_8MHZ = 6, 225 AM_HAL_MSPI_CLK_6MHZ = 8, 226 AM_HAL_MSPI_CLK_4P8MHZ = 10, 227 AM_HAL_MSPI_CLK_4MHZ = 12, 228 AM_HAL_MSPI_CLK_3P2MHZ = 15, 229 AM_HAL_MSPI_CLK_3MHZ = 16, 230 AM_HAL_MSPI_CLK_1P5MHZ = 32 231 } am_hal_mspi_clock_e; 232 233 // 234 //! Transfer callback function prototype 235 // 236 typedef void (*am_hal_mspi_callback_t)(void *pCallbackCtxt, uint32_t status); 237 238 typedef struct 239 { 240 bool bLoop; 241 //! Command Queue Transaction Gating 242 uint32_t ui32PauseCondition; 243 //! Command Queue Post-Transaction status setting 244 uint32_t ui32StatusSetClr; 245 } am_hal_mspi_seq_end_t; 246 247 typedef struct 248 { 249 uint8_t *pBuf; //!< Buffer provided to store the high priority transaction context 250 uint32_t size; //!< Size of buffer in bytes 251 } am_hal_mspi_hiprio_cfg_t; 252 253 typedef struct 254 { 255 //! Command Queue Advanced control on gating conditions for transaction to start 256 uint32_t ui32PauseCondition; 257 //! Command Queue Advanced Post-Transaction status setting 258 uint32_t ui32StatusSetClr; 259 am_hal_cmdq_entry_t *pCQEntry; 260 uint32_t numEntries; 261 am_hal_mspi_callback_t pfnCallback; 262 void *pCallbackCtxt; 263 uint32_t *pJmpAddr; 264 } am_hal_mspi_cq_raw_t; 265 266 typedef enum 267 { 268 //! Pass uint32_t * as pConfig 269 AM_HAL_MSPI_REQ_APBCLK, 270 //! Used to set/clear 8 CQ Pause flags - reserved flags are defined as AM_HAL_MSPI_PAUSE_FLAG_RESV 271 AM_HAL_MSPI_REQ_FLAG_SETCLR, 272 //! Pass uint32_t * as pConfig indicating the IOM# to link to. AM_HAL_MSPI_LINK_IOM_NONE indicates no IOM linked 273 AM_HAL_MSPI_REQ_LINK_IOM, 274 //! pConfig N/A 275 AM_HAL_MSPI_REQ_SCRAMB_DIS, 276 //! pConfig N/A 277 AM_HAL_MSPI_REQ_SCRAMB_EN, 278 //! Pass uint32_t * as pConfig 279 AM_HAL_MSPI_REQ_XIPACK, 280 //! pConfig N/A 281 AM_HAL_MSPI_REQ_XIP_DIS, 282 //! pConfig N/A 283 AM_HAL_MSPI_REQ_XIP_EN, 284 //! Pass am_hal_mspi_device_e * as pConfig 285 AM_HAL_MSPI_REQ_DEVICE_CONFIG, 286 //! Pass am_hal_mspi_clock_e * as pConfig 287 AM_HAL_MSPI_REQ_CLOCK_CONFIG, 288 //! Pause the CQ gracefully 289 AM_HAL_MSPI_REQ_PAUSE, 290 //! Unpause the CQ 291 AM_HAL_MSPI_REQ_UNPAUSE, 292 //! Get in and out of Sequence Mode - which allows building a sequence, which either runs once, or repeats 293 //! Pass in bool * as pConfig - true/false 294 AM_HAL_MSPI_REQ_SET_SEQMODE, 295 //! Pass am_hal_mspi_seq_end_t * as pConfig 296 AM_HAL_MSPI_REQ_SEQ_END, 297 //! Initialize configuration for high priority trasactions 298 //! These transactions take precedence over existing CQ transactions 299 //! Pass am_hal_mspi_hiprio_cfg_t * as pConfig 300 AM_HAL_MSPI_REQ_INIT_HIPRIO, 301 //! Create a block of transactions which are not paused in between 302 //! pConfig N/A 303 AM_HAL_MSPI_REQ_START_BLOCK, 304 //! pConfig N/A 305 AM_HAL_MSPI_REQ_END_BLOCK, 306 //! Raw CQ transaction 307 //! Pass am_hal_mspi_cq_raw_t * as pConfig 308 AM_HAL_MSPI_REQ_CQ_RAW, 309 AM_HAL_MSPI_REQ_MAX 310 311 } am_hal_mspi_request_e; 312 313 // 314 //! Device configuration structure 315 // 316 typedef struct 317 { 318 // 319 //! MSPI device configuration for Polling I/O (PIO) Operation. 320 // 321 322 //! Number of turn around cycles between an Address write and Data read. 323 uint8_t ui8TurnAround; 324 325 //! Address Configuration 326 am_hal_mspi_addr_e eAddrCfg; 327 328 //! Instruction Configuration 329 am_hal_mspi_instr_e eInstrCfg; 330 331 //! Read instruction sent to flash device 332 uint8_t ui8ReadInstr; 333 334 //! Write instruction sent to flash device 335 uint8_t ui8WriteInstr; 336 337 //! External Flash Device configuration 338 am_hal_mspi_device_e eDeviceConfig; 339 340 // 341 //! MSPI clock configuration. 342 // 343 344 //! SPI Mode. 345 am_hal_mspi_spi_mode_e eSpiMode; 346 347 //! Clock frequency 348 am_hal_mspi_clock_e eClockFreq; 349 350 // 351 //! MSPI device configuration for XIP/DMA/Scrambling operations. 352 // 353 354 //! Send Device Address 355 bool bSendAddr; 356 357 //! Send Device Instruction 358 bool bSendInstr; 359 360 //! Enable Turnaround between Address write and Data read. 361 bool bTurnaround; 362 363 // 364 //! MSPI DMA TCB/Command Queue memory allocation. 365 // 366 367 //! DMA Transfer Control Buffer size in words. 368 uint32_t ui32TCBSize; 369 370 //! DMA Transfer Control Buffer 371 uint32_t *pTCB; 372 373 // 374 //! MSPI Scrambling configuration. 375 // 376 377 //! Scrambling Start Address 378 uint32_t scramblingStartAddr; 379 380 //! Scrambling End Address 381 uint32_t scramblingEndAddr; 382 383 } am_hal_mspi_dev_config_t; 384 385 // 386 //! MSPI Capabilities structure 387 // 388 typedef struct 389 { 390 am_hal_mspi_device_e eDeviceConfig; 391 } am_hal_mspi_capabilities_t; 392 393 // 394 //! Device PIO transfer structure 395 // 396 typedef struct 397 { 398 //! Number of bytes to transfer 399 uint32_t ui32NumBytes; 400 401 //! Enable scrambling. 402 bool bScrambling; 403 404 //! Transfer Direction (Transmit/Receive) 405 am_hal_mspi_dir_e eDirection; 406 407 //! Send Device Address 408 bool bSendAddr; 409 410 //! Device Address 411 uint32_t ui32DeviceAddr; 412 413 //! Send Device Instruction 414 bool bSendInstr; 415 416 //! Device Instruction 417 uint16_t ui16DeviceInstr; 418 419 //! Enable Turnaround between Address write and Data read. 420 bool bTurnaround; 421 422 //! Paired-Quad 423 bool bQuadCmd; 424 425 //! Buffer 426 uint32_t *pui32Buffer; 427 428 } am_hal_mspi_pio_transfer_t; 429 430 // 431 //! DMA transfer structure 432 // 433 typedef struct 434 { 435 //! Address Configuration 436 am_hal_mspi_addr_e eAddrCfg; 437 438 //! Priority 0 = Low (best effort); 1 = High (service immediately) 439 uint8_t ui8Priority; 440 441 //! Direction RX: 0 = Peripheral to Memory; TX: 1 = Memory to Peripheral 442 am_hal_mspi_dir_e eDirection; 443 444 //! Transfer Count 445 uint32_t ui32TransferCount; 446 447 //! External Flash Device Address 448 uint32_t ui32DeviceAddress; 449 450 //! Internal SRAM Address 451 uint32_t ui32SRAMAddress; 452 453 //! Command Queue Transaction Gating 454 uint32_t ui32PauseCondition; 455 //! Command Queue Post-Transaction status setting 456 uint32_t ui32StatusSetClr; 457 458 } am_hal_mspi_dma_transfer_t; 459 460 461 // 462 //! MSPI status structure. 463 // 464 typedef struct 465 { 466 uint32_t ui32NumCQEntries; 467 468 // 469 //! DMA status. 470 // 471 bool bErr; 472 bool bCmp; 473 bool bTIP; 474 475 // 476 //! This is true when the current command queue index matches the end index. 477 //! A DMA transfer will be complete when this is true. 478 // 479 bool bCQEndMatch; 480 481 // 482 //! This mirrors the CMDCMP bit. Transfer complete 483 // 484 bool bTransferComplete; 485 486 487 } 488 am_hal_mspi_status_t; 489 490 491 #define am_hal_mspi_buffer(A) \ 492 union \ 493 { \ 494 uint32_t words[(A + 3) >> 2]; \ 495 uint8_t bytes[A]; \ 496 } 497 498 //***************************************************************************** 499 // 500 //! @brief MSPI initialization function 501 //! 502 //! @param ui32Module - Module instance. 503 //! @param ppHandle - Returns the handle for the module instance. 504 //! 505 //! This function accepts a module instance, allocates the interface and then 506 //! returns a handle to be used by the remaining interface functions. 507 //! 508 //! @return status - Generic or interface specific status. 509 // 510 //***************************************************************************** 511 extern uint32_t am_hal_mspi_initialize(uint32_t ui32Module, 512 void **ppHandle); 513 514 //***************************************************************************** 515 // 516 //! @brief MSPI deinitialization function 517 //! 518 //! @param pHandle - The handle for the module instance. 519 //! 520 //! This function accepts a handle to an instance and de-initializes the 521 //! interface. 522 //! 523 //! @return status - Generic or interface specific status. 524 // 525 //***************************************************************************** 526 extern uint32_t am_hal_mspi_deinitialize(void *pHandle); 527 528 //***************************************************************************** 529 // 530 //! @brief MSPI device configuration function 531 //! 532 //! @param pHandle - Handle for the interface. 533 //! @param pConfig - Pointer to the configuration structure. 534 //! 535 //! This function configures the MSPI settings for a particular external flash device. 536 //! 537 //! @return status - Generic or interface specific status. 538 // 539 //***************************************************************************** 540 extern uint32_t am_hal_mspi_device_configure(void *pHandle, 541 am_hal_mspi_dev_config_t *pConfig); 542 543 //***************************************************************************** 544 // 545 //! @brief MSPI enable function 546 //! 547 //! @param pHandle - The handle for the module instance. 548 //! 549 //! This function accepts a handle to an instance and enables the 550 //! interface. 551 //! 552 //! @return status - Generic or interface specific status. 553 // 554 //***************************************************************************** 555 extern uint32_t am_hal_mspi_enable(void *pHandle); 556 557 //***************************************************************************** 558 // 559 //! @brief MSPI disable function 560 //! 561 //! @param pHandle - The handle for the module instance. 562 //! 563 //! This function accepts a handle to an instance and disables the 564 //! interface. 565 //! 566 //! @return status - Generic or interface specific status. 567 // 568 //***************************************************************************** 569 extern uint32_t am_hal_mspi_disable(void *pHandle); 570 571 //***************************************************************************** 572 // 573 //! @brief MSPI device specific control function. 574 //! 575 //! @param pHandle - Handle for the interface. 576 //! @param eRequest - Device specific special request code. 577 //! @param pConfig - Pointer to the request specific configuration. 578 //! 579 //! @note This function configures the MSPI settings for XIP or DMA operation. 580 //! 581 //! @return status - Generic or interface specific status. 582 // 583 //***************************************************************************** 584 extern uint32_t am_hal_mspi_control(void *pHandle, 585 am_hal_mspi_request_e eRequest, 586 void *pConfig); 587 588 //***************************************************************************** 589 // 590 //! @brief MSPI capability interrogation function 591 //! 592 //! @param pHandle - Handle for the interface. 593 //! @param pCapabilities - Pointer to an interface specific structure used to 594 //! return the capabilities of the interface. 595 //! 596 //! This function returns the specific capabilities of the MSPI. In some 597 //! cases the capabilities may be instance specific (e.g. maximum data rate). 598 //! 599 //! @return status - Generic or interface specific status. 600 // 601 //***************************************************************************** 602 extern uint32_t am_hal_mspi_capabilities_get(void *pHandle, 603 am_hal_mspi_capabilities_t **pCapabilities); 604 605 //***************************************************************************** 606 // 607 //! @brief MSPI blocking transfer function 608 //! 609 //! @param pHandle - Handle for the interface. 610 //! @param pTransaction - Pointer to the transaction control structure. 611 //! @param ui32Timeout - Timeout in usecs. 612 //! 613 //! This function performs a transaction on the MSPI in PIO mode. It handles 614 //! half duplex transactions only (TX or RX). 615 //! 616 //! @return status - Generic or interface specific status. 617 // 618 //***************************************************************************** 619 extern uint32_t am_hal_mspi_blocking_transfer(void *pHandle, 620 am_hal_mspi_pio_transfer_t *pTransaction, 621 uint32_t ui32Timeout); 622 //***************************************************************************** 623 // 624 //! @brief MSPI Non-Blocking transfer function 625 //! 626 //! @param pHandle - Handle for the interface. 627 //! @param pTransfer - Pointer to the transaction control structure. 628 //! @param eMode - Mode 629 //! @param pfnCallback - Pointer the callback function to be executed when 630 //! transaction is complete. 631 //! @param pCallbackCtxt - Passed to callback function 632 //! 633 //! This function performs a transaction on the MSPI using either DMA or the 634 //! Command Queue with DMA. It handles half duplex transactions. 635 //! 636 //! @return status - Generic or interface specific status. 637 // 638 //***************************************************************************** 639 extern uint32_t am_hal_mspi_nonblocking_transfer(void *pHandle, 640 void *pTransfer, 641 am_hal_mspi_trans_e eMode, 642 am_hal_mspi_callback_t pfnCallback, 643 void *pCallbackCtxt); 644 645 //***************************************************************************** 646 // 647 //! @brief MSPI status function 648 //! 649 //! @param pHandle - Handle for the interface. 650 //! @param pStatus - Returned mspi status 651 //! 652 //! This function returns the current status of the DMA operation. 653 //! 654 //! @return status - DMA status flags. 655 // 656 //***************************************************************************** 657 extern uint32_t am_hal_mspi_status_get(void *pHandle, 658 am_hal_mspi_status_t *pStatus ); 659 660 //***************************************************************************** 661 // 662 //! @brief MSPI enable interrupts function 663 //! 664 //! @param pHandle - Handle for the interface. 665 //! @param ui32IntMask - MSPI interrupt mask. 666 //! 667 //! This function enables the specific indicated interrupts. 668 //! 669 //! @return status - Generic or interface specific status. 670 // 671 //***************************************************************************** 672 extern uint32_t am_hal_mspi_interrupt_enable(void *pHandle, 673 uint32_t ui32IntMask); 674 675 //***************************************************************************** 676 // 677 //! @brief MSPI disable interrupts function 678 //! 679 //! @param pHandle - Handle for the interface. 680 //! @param ui32IntMask - MSPI interrupt mask. 681 //! 682 //! This function disable the specific indicated interrupts. 683 //! 684 //! @return status - Generic or interface specific status. 685 // 686 //***************************************************************************** 687 extern uint32_t am_hal_mspi_interrupt_disable(void *pHandle, 688 uint32_t ui32IntMask); 689 690 //***************************************************************************** 691 // 692 //! @brief MSPI interrupt status function 693 //! 694 //! @param pHandle - Handle for the interface. 695 //! @param pui32Status - Returns the interrupt status value. 696 //! @param bEnabledOnly - TRUE: only report interrupt status for enalbed ints. 697 //! FALSE: report all interrupt status values. 698 //! 699 //! This function returns the specific indicated interrupt status. 700 //! 701 //! @return status - Interrupt status. 702 // 703 //***************************************************************************** 704 extern uint32_t am_hal_mspi_interrupt_status_get(void *pHandle, 705 uint32_t *pui32Status, 706 bool bEnabledOnly); 707 708 //***************************************************************************** 709 // 710 //! @brief MSPI interrupt clear 711 //! 712 //! @param pHandle - Handle for the interface. 713 //! @param ui32IntMask - uint32_t for interrupts to clear 714 //! 715 //! This function clears the interrupts for the given peripheral. 716 //! 717 //! @return status - Generic or interface specific status. 718 // 719 //***************************************************************************** 720 extern uint32_t am_hal_mspi_interrupt_clear(void *pHandle, 721 uint32_t ui32IntMask); 722 723 //***************************************************************************** 724 // 725 //! @brief MSPI interrupt service routine 726 //! 727 //! @param pHandle - Handle for the interface. 728 //! @param ui32IntStatus - Interrupt status. 729 //! 730 //! This function is designed to be called from within the user defined ISR 731 //! in order to service the non-blocking, queued, or DMA processing for a given 732 //! module instance. 733 //! 734 //! @return status - Generic or interface specific status. 735 // 736 //***************************************************************************** 737 extern uint32_t am_hal_mspi_interrupt_service(void *pHandle, 738 uint32_t ui32IntStatus); 739 740 //***************************************************************************** 741 // 742 //! @brief MSPI power control function 743 //! 744 //! @param pHandle - Handle for the interface. 745 //! @param ePowerState - The desired power state to move the peripheral to. 746 //! @param bRetainState - Flag (if true) to save/restore peripheral state upon 747 //! power state change. 748 //! 749 //! This function updates the peripheral to a given power state. 750 //! 751 //! @return status - Generic or interface specific status. 752 // 753 //***************************************************************************** 754 extern uint32_t am_hal_mspi_power_control(void *pHandle, 755 am_hal_sysctrl_power_state_e ePowerState, 756 bool bRetainState); 757 //***************************************************************************** 758 // 759 //! @brief MSPI High Priority transfer function 760 //! 761 //! @param pHandle - Handle for the interface 762 //! @param pTransfer - Pointer to the transaction control structure 763 //! @param eMode - PIO or DMA 764 //! - AM_HAL_MSPI_TRANS_PIO 765 //! - AM_HAL_MSPI_TRANS_DMA 766 //! @param pfnCallback - Pointer to function executed when 767 //! transaction is complete (can be set to NULL). 768 //! @param pCallbackCtxt - Context registered which is passed on to the callback 769 //! function 770 //! @return uint32_t - Generic or interface specific status 771 // 772 //***************************************************************************** 773 extern uint32_t am_hal_mspi_highprio_transfer(void *pHandle, 774 am_hal_mspi_dma_transfer_t *pTransfer, 775 am_hal_mspi_trans_e eMode, 776 am_hal_mspi_callback_t pfnCallback, 777 void *pCallbackCtxt); 778 779 #ifdef __cplusplus 780 } 781 #endif 782 783 #endif // AM_HAL_MSPI_H 784 785 //***************************************************************************** 786 // 787 // End Doxygen group. 788 //! @} 789 // 790 //***************************************************************************** 791
