1 //***************************************************************************** 2 // 3 //! @file am_hal_iom.h 4 //! 5 //! @brief Functions for Interfacing with IO Master Serial (SPI/I2C) Modules. 6 //! 7 //! @addtogroup iom3p IOM - IOM (MASTER SPI/I2C) Functions 8 //! @ingroup apollo3p_hal 9 //! @{ 10 // 11 //***************************************************************************** 12 13 //***************************************************************************** 14 // 15 // Copyright (c) 2024, 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_3_2_0-dd5f40c14b of the AmbiqSuite Development Package. 45 // 46 //***************************************************************************** 47 48 #ifndef AM_HAL_IOM_H 49 #define AM_HAL_IOM_H 50 51 #include "am_hal_status.h" 52 #include "am_hal_sysctrl.h" 53 54 55 //***************************************************************************** 56 // 57 //! CMSIS-Style macro for handling a variable IOM module number. 58 // 59 //***************************************************************************** 60 #define IOMn(n) ((IOM0_Type*)(IOM0_BASE + (n * (IOM1_BASE - IOM0_BASE)))) 61 62 // 63 // Maximum time to wait for hardware to finish a blocking transaction 64 // This is an escape to allow for bailing out in case of faulty peripheral 65 // (e.g. a device pulling the I2C clock low) 66 // 67 #define AM_HAL_IOM_MAX_BLOCKING_WAIT 500000 // 0.5 sec 68 69 // 70 // AM_HAL_IOM_CQ=1 will use the Command Queue in nonblocking transfers. 71 // 0 uses plain DMA (w/o CQ) in nonblocking transfers. 72 // This should be enabled only for A1 silicon. 73 // 74 #define AM_HAL_IOM_CQ 1 75 76 // Size guideline for allocation of application supploed buffers 77 #define AM_HAL_IOM_CQ_ENTRY_SIZE (24 * sizeof(uint32_t)) 78 #define AM_HAL_IOM_HIPRIO_ENTRY_SIZE (8 * sizeof(uint32_t)) 79 80 #define AM_HAL_IOM_SC_CLEAR(flag) ((flag) << 16) 81 #define AM_HAL_IOM_SC_SET(flag) ((flag)) 82 83 // For IOM - Need to Clear the flag for unpausing 84 #define AM_HAL_IOM_SC_UNPAUSE(flag) AM_HAL_IOM_SC_CLEAR(flag) 85 #define AM_HAL_IOM_SC_PAUSE(flag) AM_HAL_IOM_SC_SET(flag) 86 87 // Use this macro to directly control the flags 88 #define AM_HAL_IOM_SETCLR(iom, scVal) \ 89 do { \ 90 IOMn((iom))->CQSETCLEAR = (scVal); \ 91 } while (0); 92 93 // Flags 5, 7 & 6 are reserved by HAL 94 #define AM_HAL_IOM_PAUSE_FLAG_RESV (IOM0_CQPAUSEEN_CQPEN_SWFLAGEN7 | IOM0_CQPAUSEEN_CQPEN_SWFLAGEN6 | IOM0_CQPAUSEEN_CQPEN_SWFLAGEN5) 95 #define AM_HAL_IOM_SC_RESV_MASK (AM_HAL_IOM_PAUSE_FLAG_RESV | (AM_HAL_IOM_PAUSE_FLAG_RESV << 8) | (AM_HAL_IOM_PAUSE_FLAG_RESV << 16)) 96 97 98 // We use SWFLAGEN7 to control SW pausing Command Queue - default unPause 99 // We use SWFLAGEN6 to pause on the sequece loopback - default Pause 100 #define AM_HAL_IOM_PAUSE_FLAG_IDX (_VAL2FLD(IOM0_CQPAUSEEN_CQPEN, IOM0_CQPAUSEEN_CQPEN_IDXEQ)) 101 #define AM_HAL_IOM_PAUSE_FLAG_CQ (_VAL2FLD(IOM0_CQPAUSEEN_CQPEN, IOM0_CQPAUSEEN_CQPEN_SWFLAGEN7)) 102 #define AM_HAL_IOM_PAUSE_FLAG_SEQLOOP (_VAL2FLD(IOM0_CQPAUSEEN_CQPEN, IOM0_CQPAUSEEN_CQPEN_SWFLAGEN6)) 103 #define AM_HAL_IOM_PAUSE_FLAG_BLOCK (_VAL2FLD(IOM0_CQPAUSEEN_CQPEN, IOM0_CQPAUSEEN_CQPEN_SWFLAGEN5)) 104 105 // By default - we Pause CQ for no more entries, or force pause from SW 106 #define AM_HAL_IOM_PAUSE_DEFAULT AM_HAL_IOM_PAUSE_FLAG_IDX 107 #define AM_HAL_IOM_CQP_PAUSE_DEFAULT (AM_HAL_IOM_PAUSE_FLAG_IDX | AM_HAL_IOM_PAUSE_FLAG_CQ) 108 109 //***************************************************************************** 110 // 111 //! IOM Specific status codes 112 // 113 //***************************************************************************** 114 typedef enum 115 { 116 //! Error in hardware command issued or illegal access by SW 117 AM_HAL_IOM_ERR_INVALID_OPER = AM_HAL_STATUS_MODULE_SPECIFIC_START, 118 //! Loss of I2C multi-master arbitration 119 AM_HAL_IOM_ERR_I2C_ARB, 120 //! I2C NAK 121 AM_HAL_IOM_ERR_I2C_NAK, 122 } am_hal_iom_err_e; 123 124 //***************************************************************************** 125 // 126 //! General defines 127 // 128 //***************************************************************************** 129 #define AM_HAL_IOM_FIFO_SIZE_MAX 32 130 #define AM_HAL_IOM_MAX_OFFSETSIZE 3 131 #define AM_HAL_IOM_MAX_TXNSIZE_SPI 4095 132 #define AM_HAL_IOM_MAX_TXNSIZE_I2C 512 133 #define AM_HAL_IOM_MAX_CS_SPI 3 134 135 //***************************************************************************** 136 // 137 //! @brief enumeration types for the IOM. 138 // 139 //***************************************************************************** 140 141 // 142 //! IOM mode enumerations 143 // 144 typedef enum 145 { 146 AM_HAL_IOM_SPI_MODE, 147 AM_HAL_IOM_I2C_MODE, 148 AM_HAL_IOM_NUM_MODES 149 } am_hal_iom_mode_e; 150 151 // 152 //! Transmit or receive enumerations.\n 153 //! Make these enums consistent with the IOM CMD register values. 154 // 155 typedef enum 156 { 157 AM_HAL_IOM_TX, 158 AM_HAL_IOM_RX, 159 AM_HAL_IOM_FULLDUPLEX, //!< Only supported for blocking transactions 160 } am_hal_iom_dir_e; 161 162 // 163 //! Enumerate the SPI modes. Note that these are arranged per the ordering of 164 //! SPHA (bit1) and SPOL (bit0) in the IOM.MSPICFG register. 165 // 166 typedef enum 167 { 168 AM_HAL_IOM_SPI_MODE_0, //!< CPOL = 0; CPHA = 0 169 AM_HAL_IOM_SPI_MODE_2, //!< CPOL = 1; CPHA = 0 170 AM_HAL_IOM_SPI_MODE_1, //!< CPOL = 0; CPHA = 1 171 AM_HAL_IOM_SPI_MODE_3, //!< CPOL = 1; CPHA = 1 172 } am_hal_iom_spi_mode_e; 173 174 175 //***************************************************************************** 176 // 177 //! @brief Transfer callback function prototype 178 // 179 //***************************************************************************** 180 typedef void (*am_hal_iom_callback_t)(void *pCallbackCtxt, uint32_t transactionStatus); 181 // 182 //***************************************************************************** 183 // 184 //! @brief Configuration structure for the IOM. 185 // 186 //***************************************************************************** 187 typedef struct 188 { 189 // 190 //! Select the interface mode, SPI or I2C 191 // 192 am_hal_iom_mode_e eInterfaceMode; 193 194 // 195 //! Select the interface clock frequency 196 // 197 uint32_t ui32ClockFreq; 198 199 // 200 //! Select the SPI clock mode (polarity/phase). Ignored for I2C operation. 201 // 202 am_hal_iom_spi_mode_e eSpiMode; 203 204 // 205 //! Non-Blocking transaction memory configuration\n 206 //! Set length and pointer to Transfer Control Buffer.\n 207 //! Length is in 4 byte multiples 208 // 209 uint32_t *pNBTxnBuf; 210 uint32_t ui32NBTxnBufLength; 211 } 212 am_hal_iom_config_t; 213 214 //***************************************************************************** 215 // 216 //! Configuration structure for an individual SPI device. 217 // 218 //***************************************************************************** 219 typedef struct 220 { 221 // 222 //! IOM module to use for communicating with this device. 223 // 224 uint32_t ui32Module; 225 226 // 227 //! Chip select signal that should be used for this device. 228 // 229 uint32_t ui32ChipSelect; 230 231 // 232 //! Additional options that will ALWAYS be ORed into the command word. 233 // 234 uint32_t ui32Options; 235 } 236 am_hal_iom_spi_device_t; 237 238 //***************************************************************************** 239 // 240 //! Configuration structure for an individual I2C device. 241 // 242 //***************************************************************************** 243 typedef struct 244 { 245 // 246 //! IOM module to use for communicating with this device. 247 // 248 uint32_t ui32Module; 249 250 // 251 //! I2C address associated with this device. 252 // 253 uint32_t ui32BusAddress; 254 255 // 256 //! Additional options that will ALWAYS be ORed into the command word. 257 // 258 uint32_t ui32Options; 259 } 260 am_hal_iom_i2c_device_t; 261 262 //***************************************************************************** 263 // 264 //! @brief Status structure for the IOM. 265 // 266 //***************************************************************************** 267 typedef struct 268 { 269 // 270 //! IOM status. 271 // 272 bool bStatIdle; 273 bool bStatCmdAct; 274 bool bStatErr; 275 276 // 277 //! DMA status\n 278 //! One of: 279 //! - AM_HAL_IOM_STATUS_DMA_IN_PROGRESS 280 //! - AM_HAL_IOM_STATUS_XFER_COMPLETE 281 //! - AM_HAL_IOM_STATUS_DMAERR 282 // 283 uint32_t ui32DmaStat; 284 285 uint32_t ui32MaxTransactions; 286 uint32_t ui32NumPendTransactions; 287 } 288 am_hal_iom_status_t; 289 290 // 291 // transfer structure 292 // 293 typedef struct 294 { 295 union 296 { 297 // 298 //! Chip enable (chip select) for this transaction on this device. 299 // 300 uint32_t ui32SpiChipSelect; 301 uint32_t ui32I2CDevAddr; 302 } uPeerInfo; 303 304 // 305 //! Instruction length (0,1,2, or 3). 306 // 307 uint32_t ui32InstrLen; 308 309 // 310 //! Device Instruction (aka Command). Often used as the offset. 311 // 312 uint32_t ui32Instr; 313 314 // 315 //! Number of bytes to transfer 316 // 317 uint32_t ui32NumBytes; 318 319 // 320 //! Transfer Direction (Transmit/Receive) 321 // 322 am_hal_iom_dir_e eDirection; 323 324 // 325 //! Buffer 326 // 327 uint32_t *pui32TxBuffer; 328 uint32_t *pui32RxBuffer; 329 330 // 331 //! Continue - holds the SPI or I2C bus for multiple transactions. 332 // 333 bool bContinue; 334 335 // 336 //! Repeat Count 337 // 338 uint8_t ui8RepeatCount; 339 340 // 341 //! DMA: Priority 0 = Low (best effort); 1 = High (service immediately) 342 // 343 uint8_t ui8Priority; 344 345 //! Command Queue Advanced control on gating conditions for transaction to start 346 // 347 uint32_t ui32PauseCondition; 348 //! Command Queue Advanced Post-Transaction status setting 349 uint32_t ui32StatusSetClr; 350 351 } am_hal_iom_transfer_t; 352 353 typedef struct 354 { 355 bool bLoop; 356 //! Command Queue Transaction Gating 357 uint32_t ui32PauseCondition; 358 //! Command Queue Post-Transaction status setting 359 uint32_t ui32StatusSetClr; 360 } am_hal_iom_seq_end_t; 361 362 typedef struct 363 { 364 uint8_t *pBuf; //!< Buffer provided to store the high priority transaction context 365 uint32_t size; //!< Size of buffer in bytes 366 } am_hal_iom_hiprio_cfg_t; 367 368 #define AM_HAL_IOM_DCX_INVALID 0xFF 369 typedef struct 370 { 371 uint8_t cs; //!< CS for which this configuration applies 372 uint8_t dcx; //!< alternate CS line used for DCX - AM_HAL_IOM_DCX_INVALID indicates DCX is not used 373 } am_hal_iom_dcx_cfg_t; 374 375 typedef struct 376 { 377 //! Command Queue Advanced control on gating conditions for transaction to start 378 uint32_t ui32PauseCondition; 379 //! Command Queue Advanced Post-Transaction status setting 380 uint32_t ui32StatusSetClr; 381 am_hal_cmdq_entry_t *pCQEntry; 382 uint32_t numEntries; 383 am_hal_iom_callback_t pfnCallback; 384 void *pCallbackCtxt; 385 uint32_t *pJmpAddr; 386 } am_hal_iom_cq_raw_t; 387 388 typedef enum 389 { 390 //! Used to set/clear 8 CQ Pause flags - reserved flags are defined as AM_HAL_IOM_PAUSE_FLAG_RESV\n 391 //! Pass uint32_t as pArgs 392 AM_HAL_IOM_REQ_FLAG_SETCLR = 0, 393 //! Pass uint32_t as pArgs 394 AM_HAL_IOM_REQ_SPI_LSB, 395 //! Pass uint32_t as pArgs 396 AM_HAL_IOM_REQ_RESV1, 397 //! Pass uint32_t as pArgs 398 AM_HAL_IOM_REQ_SPI_RDTHRESH, 399 //! Pass uint32_t as pArgs 400 AM_HAL_IOM_REQ_SPI_WRTHRESH, 401 //! Pass uint32_t as pArgs 402 AM_HAL_IOM_REQ_LINK_MSPI, 403 //! Pause the CQ gracefully 404 //! pArgs N/A 405 AM_HAL_IOM_REQ_PAUSE, 406 //! Unpause the CQ 407 //! pArgs N/A 408 AM_HAL_IOM_REQ_UNPAUSE, 409 //! Get in and out of Sequence Mode - which allows building a sequence, which either runs once, or repeats\n 410 //! Pass in bool as pArgs - true/false 411 AM_HAL_IOM_REQ_SET_SEQMODE, 412 //! pArgs N/A 413 AM_HAL_IOM_REQ_SEQ_END, 414 //! Initialize configuration for high priority transactions\n 415 //! These transactions take precedence over existing CQ transactions\n 416 //! Pass am_hal_iom_hiprio_cfg_t * as pArgs 417 AM_HAL_IOM_REQ_INIT_HIPRIO, 418 //! Create a block of transactions which are not paused in between\n 419 //! pArgs N/A 420 AM_HAL_IOM_REQ_START_BLOCK, 421 //! pArgs N/A 422 AM_HAL_IOM_REQ_END_BLOCK, 423 //! Control the DCX line\n 424 //! Pass am_hal_iom_dcx_cfg_t * as pArgs 425 AM_HAL_IOM_REQ_SET_DCX, 426 //! Raw CQ transaction\n 427 //! Pass am_hal_iom_cq_raw_t * as pArgs 428 AM_HAL_IOM_REQ_CQ_RAW, 429 AM_HAL_IOM_REQ_MAX 430 } am_hal_iom_request_e; 431 432 #define am_hal_iom_buffer(A) \ 433 union \ 434 { \ 435 uint32_t words[(A + 3) >> 2]; \ 436 uint8_t bytes[A]; \ 437 } 438 439 //***************************************************************************** 440 // 441 //! @brief Macro definitions for common SPI and I2C clock frequencies. 442 //! 443 //! These macros may be used with the ui32ClockFrequency member of the 444 //! am_hal_iom_config_t structure to set the clock frequency of the serial 445 //! interfaces. 446 //! 447 //! This list of frequencies is not exhaustive by any means. If your desired 448 //! frequency is not in this list, simply set ui32ClockFrequency to the 449 //! desired frequency (in Hz) when calling am_hal_iom_config(). 450 //! @name IOM3p Clock Frequencies 451 //! @{ 452 // 453 //***************************************************************************** 454 #define AM_HAL_IOM_48MHZ 48000000 455 #define AM_HAL_IOM_24MHZ 24000000 456 #define AM_HAL_IOM_16MHZ 16000000 457 #define AM_HAL_IOM_12MHZ 12000000 458 #define AM_HAL_IOM_8MHZ 8000000 459 #define AM_HAL_IOM_6MHZ 6000000 460 #define AM_HAL_IOM_4MHZ 4000000 461 #define AM_HAL_IOM_3MHZ 3000000 462 #define AM_HAL_IOM_2MHZ 2000000 463 #define AM_HAL_IOM_1_5MHZ 1500000 464 #define AM_HAL_IOM_1MHZ 1000000 465 #define AM_HAL_IOM_750KHZ 750000 466 #define AM_HAL_IOM_500KHZ 500000 467 #define AM_HAL_IOM_400KHZ 400000 468 #define AM_HAL_IOM_375KHZ 375000 469 #define AM_HAL_IOM_250KHZ 250000 470 #define AM_HAL_IOM_125KHZ 125000 471 #define AM_HAL_IOM_100KHZ 100000 472 #define AM_HAL_IOM_50KHZ 50000 473 #define AM_HAL_IOM_10KHZ 10000 474 475 //! Max Frequency supported in HAL 476 #define AM_HAL_IOM_MAX_FREQ AM_HAL_IOM_48MHZ 477 //! @} 478 479 //***************************************************************************** 480 // 481 // IOM Interrupts 482 // 483 //***************************************************************************** 484 #define AM_HAL_IOM_INT_CQERR IOM0_INTEN_CQERR_Msk //!< Error during command queue operations 485 #define AM_HAL_IOM_INT_CQUPD IOM0_INTEN_CQUPD_Msk //!< Command queue operation performed a register write with the register address bit 0 set to 1. 486 #define AM_HAL_IOM_INT_CQPAUSED IOM0_INTEN_CQPAUSED_Msk //!< Command queue operation paused 487 #define AM_HAL_IOM_INT_DERR IOM0_INTEN_DERR_Msk //!< DMA error received 488 #define AM_HAL_IOM_INT_DCMP IOM0_INTEN_DCMP_Msk //!< DMA transfer complete 489 #define AM_HAL_IOM_INT_ARB IOM0_INTEN_ARB_Msk //!< Arbitration loss 490 #define AM_HAL_IOM_INT_STOP IOM0_INTEN_STOP_Msk //!< STOP command 491 #define AM_HAL_IOM_INT_START IOM0_INTEN_START_Msk //!< START command 492 #define AM_HAL_IOM_INT_ICMD IOM0_INTEN_ICMD_Msk //!< ILLEGAL command 493 #define AM_HAL_IOM_INT_IACC IOM0_INTEN_IACC_Msk //!< Illegal FIFO access 494 #define AM_HAL_IOM_INT_NAK IOM0_INTEN_NAK_Msk //!< I2C NAK 495 #define AM_HAL_IOM_INT_FOVFL IOM0_INTEN_FOVFL_Msk //!< Write FIFO overflow 496 #define AM_HAL_IOM_INT_FUNDFL IOM0_INTEN_FUNDFL_Msk //!< Read FIFO underflow 497 #define AM_HAL_IOM_INT_THR IOM0_INTEN_THR_Msk //!< FIFO threshold interrupt 498 #define AM_HAL_IOM_INT_CMDCMP IOM0_INTEN_CMDCMP_Msk //!< Command complete 499 500 501 #define AM_HAL_IOM_INT_SWERR (AM_HAL_IOM_INT_ICMD | AM_HAL_IOM_INT_IACC | AM_HAL_IOM_INT_FOVFL | AM_HAL_IOM_INT_FUNDFL) 502 #define AM_HAL_IOM_INT_I2CARBERR (AM_HAL_IOM_INT_ARB) 503 #define AM_HAL_IOM_INT_INTERR (AM_HAL_IOM_INT_CQERR | AM_HAL_IOM_INT_DERR) 504 #define AM_HAL_IOM_INT_ALL 0xFFFFFFFF 505 // 506 //! Unsuccessful end of a transaction results in one more more of the following 507 // 508 #define AM_HAL_IOM_INT_ERR (AM_HAL_IOM_INT_SWERR | AM_HAL_IOM_INT_I2CARBERR | AM_HAL_IOM_INT_INTERR | AM_HAL_IOM_INT_NAK) 509 510 #ifdef __cplusplus 511 extern "C" 512 { 513 #endif 514 515 //***************************************************************************** 516 // 517 //! @brief IOM initialization function 518 //! 519 //! @param ui32Module - module instance. 520 //! @param ppHandle - returns the handle for the module instance. 521 //! 522 //! This function accepts a module instance, allocates the interface and then 523 //! returns a handle to be used by the remaining interface functions. 524 //! 525 //! @return status - generic or interface specific status. 526 // 527 //***************************************************************************** 528 extern uint32_t am_hal_iom_initialize(uint32_t ui32Module, void **ppHandle); 529 530 //***************************************************************************** 531 // 532 //! @brief IOM configuration function 533 //! 534 //! @param pHandle - handle for the IOM. 535 //! @param psConfig - pointer to the IOM specific configuration. 536 //! 537 //! This function configures the interface settings for the IO Master. 538 //! 539 //! @return status - generic or interface specific status. 540 // 541 //***************************************************************************** 542 extern uint32_t am_hal_iom_configure(void *pHandle, am_hal_iom_config_t *psConfig); 543 544 //***************************************************************************** 545 // 546 //! @brief IOM enable function 547 //! 548 //! @param pHandle - handle for the interface. 549 //! 550 //! This function enables the IOM for operation. 551 //! 552 //! @return status - generic or interface specific status. 553 // 554 //***************************************************************************** 555 extern uint32_t am_hal_iom_enable(void *pHandle); 556 557 //***************************************************************************** 558 // 559 //! @brief IOM disable function 560 //! 561 //! @param pHandle - handle for the interface. 562 //! 563 //! This function disables the IOMaster from operation. 564 //! 565 //! @return status - generic or interface specific status. 566 // 567 //***************************************************************************** 568 extern uint32_t am_hal_iom_disable(void *pHandle); 569 570 //***************************************************************************** 571 // 572 //! @brief IOM control function 573 //! 574 //! @param pHandle - handle for the IOM. 575 //! @param eReq - device specific special request code. 576 //! @param pArgs - pointer to the request specific arguments. 577 //! 578 //! This function allows advanced settings 579 //! 580 //! @return status - generic or interface specific status. 581 // 582 //***************************************************************************** 583 extern uint32_t am_hal_iom_control(void *pHandle, am_hal_iom_request_e eReq, void *pArgs); 584 585 //***************************************************************************** 586 // 587 //! @brief IOM status function 588 //! 589 //! @param pHandle - handle for the interface. 590 //! @param psStatus - pointer to an interface specific structure used to 591 //! return the status of the interface. 592 //! 593 //! This function returns the current status of the interface. 594 //! 595 //! @return status - generic or interface specific status. 596 // 597 //***************************************************************************** 598 extern uint32_t am_hal_iom_status_get(void *pHandle, am_hal_iom_status_t *psStatus); 599 600 //***************************************************************************** 601 // 602 //! @brief IOM enable interrupts function 603 //! 604 //! @param pHandle - handle for the interface. 605 //! @param ui32IntMask - interface specific interrupt mask. 606 //! 607 //! This function enables the specific indicated interrupts. 608 //! 609 //! The following are valid enable bits, any of which can be ORed together. 610 //! - AM_REG_IOM_INTEN_CQERR_M // Error during command queue operations 611 //! - AM_REG_IOM_INTEN_CQCMP_M // Command queue operation complete 612 //! - AM_REG_IOM_INTEN_DERR_M // DMA error received 613 //! - AM_REG_IOM_INTEN_DCMP_M // DMA transfer complete 614 //! - AM_REG_IOM_INTEN_ARB_M // Arbitration loss 615 //! - AM_REG_IOM_INTEN_STOP_M // STOP command 616 //! - AM_REG_IOM_INTEN_START_M // START command 617 //! - AM_REG_IOM_INTEN_ICMD // ILLEGAL command 618 //! - AM_REG_IOM_INTEN_IACC_M // Illegal FIFO access 619 //! - AM_REG_IOM_INTEN_NAK_M // I2C NAK 620 //! - AM_REG_IOM_INTEN_FOVFL_M // Write FIFO overflow 621 //! - AM_REG_IOM_INTEN_FUNDFL_M // Read FIFO underflow 622 //! - AM_REG_IOM_INTEN_THR_M // FIFO threshold interrupt 623 //! - AM_REG_IOM_INTEN_CMDCMP_M // Command complete 624 //! 625 //! @return status - generic or interface specific status. 626 // 627 //***************************************************************************** 628 extern uint32_t am_hal_iom_interrupt_enable(void *pHandle, uint32_t ui32IntMask); 629 630 //***************************************************************************** 631 // 632 //! @brief IOM disable interrupts function 633 //! 634 //! @param pHandle - handle for the interface. 635 //! @param ui32IntMask - interface specific interrupt mask. 636 //! 637 //! This function disables the specified interrupts. 638 //! 639 //! @return status - generic or interface specific status. 640 //! 641 //! The following are valid disable bits, any of which can be ORed together. 642 //! - AM_REG_IOM_INTEN_CQERR_M // Error during command queue operations 643 //! - AM_REG_IOM_INTEN_CQCMP_M // Command queue operation complete 644 //! - AM_REG_IOM_INTEN_DERR_M // DMA error received 645 //! - AM_REG_IOM_INTEN_DCMP_M // DMA transfer complete 646 //! - AM_REG_IOM_INTEN_ARB_M // Arbitration loss 647 //! - AM_REG_IOM_INTEN_STOP_M // STOP command 648 //! - AM_REG_IOM_INTEN_START_M // START command 649 //! - AM_REG_IOM_INTEN_ICMD // ILLEGAL command 650 //! - AM_REG_IOM_INTEN_IACC_M // Illegal FIFO access 651 //! - AM_REG_IOM_INTEN_NAK_M // I2C NAK 652 //! - AM_REG_IOM_INTEN_FOVFL_M // Write FIFO overflow 653 //! - AM_REG_IOM_INTEN_FUNDFL_M // Read FIFO underflow 654 //! - AM_REG_IOM_INTEN_THR_M // FIFO threshold interrupt 655 //! - AM_REG_IOM_INTEN_CMDCMP_M // Command complete 656 // 657 //***************************************************************************** 658 extern uint32_t am_hal_iom_interrupt_disable(void *pHandle, uint32_t ui32IntMask); 659 660 //***************************************************************************** 661 // 662 //! @brief IOM get interrupt status 663 //! 664 //! @param pHandle - handle for the interface. 665 //! @param bEnabledOnly - only return enabled interrupts 666 //! @param pui32IntStatus - pointer to a uint32_t to return the interrupt status 667 //! 668 //! This function returns the interrupt status for the given peripheral. 669 //! 670 //! The following are valid status bits. 671 //! - AM_REG_IOM_INTSTAT_CQERR_M // Error during command queue operations 672 //! - AM_REG_IOM_INTSTAT_CQCMP_M // Command queue operation complete 673 //! - AM_REG_IOM_INTSTAT_DERR_M // DMA error received 674 //! - AM_REG_IOM_INTSTAT_DCMP_M // DMA transfer complete 675 //! - AM_REG_IOM_INTSTAT_ARB_M // Arbitration loss 676 //! - AM_REG_IOM_INTSTAT_STOP_M // STOP command 677 //! - AM_REG_IOM_INTSTAT_START_M // START command 678 //! - AM_REG_IOM_INTSTAT_ICMD // ILLEGAL command 679 //! - AM_REG_IOM_INTSTAT_IACC_M // Illegal FIFO access 680 //! - AM_REG_IOM_INTSTAT_NAK_M // I2C NAK 681 //! - AM_REG_IOM_INTSTAT_FOVFL_M // Write FIFO overflow 682 //! - AM_REG_IOM_INTSTAT_FUNDFL_M // Read FIFO underflow 683 //! - AM_REG_IOM_INTSTAT_THR_M // FIFO threshold interrupt 684 //! - AM_REG_IOM_INTSTAT_CMDCMP_M // Command complete 685 //! 686 //! @return status - generic or interface specific status. 687 // 688 //***************************************************************************** 689 extern uint32_t am_hal_iom_interrupt_status_get(void *pHandle, bool bEnabledOnly, 690 uint32_t *pui32IntStatus); 691 692 //***************************************************************************** 693 // 694 //! @brief IOM interrupt clear 695 //! 696 //! @param pHandle - handle for the interface. 697 //! @param ui32IntMask - interface specific interrupt mask. 698 //! 699 //! This function clears the interrupts for the given peripheral. 700 //! 701 //! The following are valid clear bits, any of which can be ORed together. 702 //! - AM_REG_IOM_INTCLR_CQERR_M // Error during command queue operations 703 //! - AM_REG_IOM_INTCLR_CQCMP_M // Command queue operation complete 704 //! - AM_REG_IOM_INTCLR_DERR_M // DMA error received 705 //! - AM_REG_IOM_INTCLR_DCMP_M // DMA transfer complete 706 //! - AM_REG_IOM_INTCLR_ARB_M // Arbitration loss 707 //! - AM_REG_IOM_INTCLR_STOP_M // STOP command 708 //! - AM_REG_IOM_INTCLR_START_M // START command 709 //! - AM_REG_IOM_INTCLR_ICMD // ILLEGAL command 710 //! - AM_REG_IOM_INTCLR_IACC_M // Illegal FIFO access 711 //! - AM_REG_IOM_INTCLR_NAK_M // I2C NAK 712 //! - AM_REG_IOM_INTCLR_FOVFL_M // Write FIFO overflow 713 //! - AM_REG_IOM_INTCLR_FUNDFL_M // Read FIFO underflow 714 //! - AM_REG_IOM_INTCLR_THR_M // FIFO threshold interrupt 715 //! - AM_REG_IOM_INTCLR_CMDCMP_M // Command complete 716 //! 717 //! @return status - generic or interface specific status. 718 // 719 //***************************************************************************** 720 extern uint32_t am_hal_iom_interrupt_clear(void *pHandle, uint32_t ui32IntMask); 721 722 //***************************************************************************** 723 // 724 //! @brief IOM interrupt service routine 725 //! 726 //! @param pHandle - handle for the interface. 727 //! @param ui32IntMask - interface specific interrupt mask indicating 728 //! interrupts to be serviced 729 //! 730 //! This function is designed to be called from within the user defined ISR 731 //! (am_iom_isr) in order to service the non-blocking, queued, or DMA processing 732 //! for a given module instance. 733 //! 734 //! @return status - generic or interface specific status. 735 // 736 //***************************************************************************** 737 extern uint32_t am_hal_iom_interrupt_service(void *pHandle, uint32_t ui32IntMask); 738 739 //***************************************************************************** 740 // 741 //! @brief IOM power control function 742 //! 743 //! @param pHandle - handle for the interface. 744 //! @param ePowerState - the desired power state to move the peripheral to. 745 //! @param retainState - flag (if true) to save/restore perhipheral state upon 746 //! power state change. 747 //! 748 //! This function updates the peripheral to a given power state. 749 //! 750 //! @return status - generic or interface specific status. 751 // 752 //***************************************************************************** 753 extern uint32_t am_hal_iom_power_ctrl(void *pHandle, 754 am_hal_sysctrl_power_state_e ePowerState, 755 bool retainState); 756 757 //***************************************************************************** 758 // 759 //! @brief IOM blocking transfer function 760 //! 761 //! @param pHandle - handle for the interface. 762 //! @param psTransaction - pointer to the transaction control structure. 763 //! 764 //! This function performs a transaction on the IOM in PIO mode. It handles 765 //! half duplex transactions only (TX or RX). 766 //! 767 //! @return status - generic or interface specific status. 768 // 769 //***************************************************************************** 770 extern uint32_t am_hal_iom_blocking_transfer(void *pHandle, 771 am_hal_iom_transfer_t *psTransaction); 772 773 //***************************************************************************** 774 // 775 //! @brief IOM non-blocking transfer function 776 //! 777 //! @param pHandle - handle for the interface. 778 //! @param psTransaction - pointer to the uniform transaction control structure. 779 //! @param pfnCallback - pointer the callback function to be executed when 780 //! transaction is complete can be set to NULL). 781 //! @param pCallbackCtxt- context registered which is passed on to the callback 782 //! function 783 //! 784 //! This function performs a transaction on the interface. It handles half duplex 785 //! transactions. The callback is executed when the transaction is complete. 786 //! 787 //! @return status - generic or interface specific status. 788 // 789 //***************************************************************************** 790 extern uint32_t am_hal_iom_nonblocking_transfer(void *pHandle, 791 am_hal_iom_transfer_t *psTransaction, 792 am_hal_iom_callback_t pfnCallback, 793 void *pCallbackCtxt); 794 795 //***************************************************************************** 796 // 797 //! @brief IOM uninitialize function 798 //! 799 //! @param pHandle - returns the handle for the module instance. 800 //! 801 //! This function accepts a handle to the initialized interface and returns 802 //! the peripheral instance to a known uninitialized state. 803 //! 804 //! @return status - generic or interface specific status. 805 // 806 //***************************************************************************** 807 // 808 // Uninitialize the interface and return the handle to a known state. 809 // 810 extern uint32_t am_hal_iom_uninitialize(void *pHandle); 811 812 //***************************************************************************** 813 // 814 //! @brief Perform a Full Duplex transaction. 815 //! 816 //! @param pHandle - handle for the interface. 817 //! @param psTransaction - pointer to the uniform transaction control structure. 818 //! 819 //! @return HAL status of the operation. 820 // 821 //***************************************************************************** 822 uint32_t 823 am_hal_iom_spi_blocking_fullduplex(void *pHandle, 824 am_hal_iom_transfer_t *psTransaction); 825 826 //***************************************************************************** 827 //! @brief IOM High Priority transfer function 828 //! 829 //! @param pHandle - handle for the interface 830 //! @param psTransaction - pointer to the transaction control structure 831 //! @param pfnCallback - pointer to function executed when 832 //! transaction is complete (can be set to NULL). 833 //! @param pCallbackCtxt - context registered which is passed on to the callback 834 //! function 835 //! @return uint32_t - generic or interface specific status 836 //***************************************************************************** 837 uint32_t am_hal_iom_highprio_transfer(void *pHandle, 838 am_hal_iom_transfer_t *psTransaction, 839 am_hal_iom_callback_t pfnCallback, 840 void *pCallbackCtxt); 841 842 843 #ifdef __cplusplus 844 } 845 #endif 846 847 #endif // AM_HAL_IOM_H 848 //***************************************************************************** 849 // 850 // End Doxygen group. 851 //! @} 852 // 853 //***************************************************************************** 854
