1 //***************************************************************************** 2 // 3 //! @file am_hal_iom.h 4 //! 5 //! @brief Functions for Interfacing with IO Master Serial (SPI/I2C) Modules. 6 //! 7 //! @addtogroup iom3 IOM - IOM (MASTER SPI/I2C) Functions 8 //! @ingroup apollo3_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 //! Pause the CQ gracefully 402 //! pArgs N/A 403 AM_HAL_IOM_REQ_PAUSE, 404 //! Unpause the CQ 405 //! pArgs N/A 406 AM_HAL_IOM_REQ_UNPAUSE, 407 //! Get in and out of Sequence Mode - which allows building a sequence, which either runs once, or repeats\n 408 //! Pass in bool as pArgs - true/false 409 AM_HAL_IOM_REQ_SET_SEQMODE, 410 //! pArgs N/A 411 AM_HAL_IOM_REQ_SEQ_END, 412 //! Initialize configuration for high priority transactions\n 413 //! These transactions take precedence over existing CQ transactions\n 414 //! Pass am_hal_iom_hiprio_cfg_t * as pArgs 415 AM_HAL_IOM_REQ_INIT_HIPRIO, 416 //! Create a block of transactions which are not paused in between\n 417 //! pArgs N/A 418 AM_HAL_IOM_REQ_START_BLOCK, 419 //! pArgs N/A 420 AM_HAL_IOM_REQ_END_BLOCK, 421 //! Control the DCX line\n 422 //! Pass am_hal_iom_dcx_cfg_t * as pArgs 423 AM_HAL_IOM_REQ_SET_DCX, 424 //! Raw CQ transaction\n 425 //! Pass am_hal_iom_cq_raw_t * as pArgs 426 AM_HAL_IOM_REQ_CQ_RAW, 427 AM_HAL_IOM_REQ_MAX 428 } am_hal_iom_request_e; 429 430 #define am_hal_iom_buffer(A) \ 431 union \ 432 { \ 433 uint32_t words[(A + 3) >> 2]; \ 434 uint8_t bytes[A]; \ 435 } 436 437 //***************************************************************************** 438 // 439 //! @brief Macro definitions for common SPI and I2C clock frequencies. 440 //! 441 //! These macros may be used with the ui32ClockFrequency member of the 442 //! am_hal_iom_config_t structure to set the clock frequency of the serial 443 //! interfaces. 444 //! 445 //! This list of frequencies is not exhaustive by any means. If your desired 446 //! frequency is not in this list, simply set ui32ClockFrequency to the 447 //! desired frequency (in Hz) when calling am_hal_iom_config(). 448 //! @name IOM Clock Frequencies 449 //! @{ 450 // 451 //***************************************************************************** 452 #define AM_HAL_IOM_48MHZ 48000000 453 #define AM_HAL_IOM_24MHZ 24000000 454 #define AM_HAL_IOM_16MHZ 16000000 455 #define AM_HAL_IOM_12MHZ 12000000 456 #define AM_HAL_IOM_8MHZ 8000000 457 #define AM_HAL_IOM_6MHZ 6000000 458 #define AM_HAL_IOM_4MHZ 4000000 459 #define AM_HAL_IOM_3MHZ 3000000 460 #define AM_HAL_IOM_2MHZ 2000000 461 #define AM_HAL_IOM_1_5MHZ 1500000 462 #define AM_HAL_IOM_1MHZ 1000000 463 #define AM_HAL_IOM_750KHZ 750000 464 #define AM_HAL_IOM_500KHZ 500000 465 #define AM_HAL_IOM_400KHZ 400000 466 #define AM_HAL_IOM_375KHZ 375000 467 #define AM_HAL_IOM_250KHZ 250000 468 #define AM_HAL_IOM_125KHZ 125000 469 #define AM_HAL_IOM_100KHZ 100000 470 #define AM_HAL_IOM_50KHZ 50000 471 #define AM_HAL_IOM_10KHZ 10000 472 473 //! Max Frequency supported in HAL 474 #define AM_HAL_IOM_MAX_FREQ AM_HAL_IOM_48MHZ 475 //! @} 476 477 //***************************************************************************** 478 // 479 // IOM Interrupts 480 // 481 //***************************************************************************** 482 #define AM_HAL_IOM_INT_CQERR IOM0_INTEN_CQERR_Msk //!< Error during command queue operations 483 #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. 484 #define AM_HAL_IOM_INT_CQPAUSED IOM0_INTEN_CQPAUSED_Msk //!< Command queue operation paused 485 #define AM_HAL_IOM_INT_DERR IOM0_INTEN_DERR_Msk //!< DMA error received 486 #define AM_HAL_IOM_INT_DCMP IOM0_INTEN_DCMP_Msk //!< DMA transfer complete 487 #define AM_HAL_IOM_INT_ARB IOM0_INTEN_ARB_Msk //!< Arbitration loss 488 #define AM_HAL_IOM_INT_STOP IOM0_INTEN_STOP_Msk //!< STOP command 489 #define AM_HAL_IOM_INT_START IOM0_INTEN_START_Msk //!< START command 490 #define AM_HAL_IOM_INT_ICMD IOM0_INTEN_ICMD_Msk //!< ILLEGAL command 491 #define AM_HAL_IOM_INT_IACC IOM0_INTEN_IACC_Msk //!< Illegal FIFO access 492 #define AM_HAL_IOM_INT_NAK IOM0_INTEN_NAK_Msk //!< I2C NAK 493 #define AM_HAL_IOM_INT_FOVFL IOM0_INTEN_FOVFL_Msk //!< Write FIFO overflow 494 #define AM_HAL_IOM_INT_FUNDFL IOM0_INTEN_FUNDFL_Msk //!< Read FIFO underflow 495 #define AM_HAL_IOM_INT_THR IOM0_INTEN_THR_Msk //!< FIFO threshold interrupt 496 #define AM_HAL_IOM_INT_CMDCMP IOM0_INTEN_CMDCMP_Msk //!< Command complete 497 498 499 #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) 500 #define AM_HAL_IOM_INT_I2CARBERR (AM_HAL_IOM_INT_ARB) 501 #define AM_HAL_IOM_INT_INTERR (AM_HAL_IOM_INT_CQERR | AM_HAL_IOM_INT_DERR) 502 #define AM_HAL_IOM_INT_ALL 0xFFFFFFFF 503 // 504 //! Unsuccessful end of a transaction results in one more more of the following 505 // 506 #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) 507 508 #ifdef __cplusplus 509 extern "C" 510 { 511 #endif 512 513 //***************************************************************************** 514 // 515 //! @brief IOM initialization function 516 //! 517 //! @param ui32Module - module instance. 518 //! @param ppHandle - returns the handle for the module instance. 519 //! 520 //! This function accepts a module instance, allocates the interface and then 521 //! returns a handle to be used by the remaining interface functions. 522 //! 523 //! @return status - generic or interface specific status. 524 // 525 //***************************************************************************** 526 extern uint32_t am_hal_iom_initialize(uint32_t ui32Module, void **ppHandle); 527 528 //***************************************************************************** 529 // 530 //! @brief IOM configuration function 531 //! 532 //! @param pHandle - handle for the IOM. 533 //! @param psConfig - pointer to the IOM specific configuration. 534 //! 535 //! This function configures the interface settings for the IO Master. 536 //! 537 //! @return status - generic or interface specific status. 538 // 539 //***************************************************************************** 540 extern uint32_t am_hal_iom_configure(void *pHandle, am_hal_iom_config_t *psConfig); 541 542 //***************************************************************************** 543 // 544 //! @brief IOM enable function 545 //! 546 //! @param pHandle - handle for the interface. 547 //! 548 //! This function enables the IOM for operation. 549 //! 550 //! @return status - generic or interface specific status. 551 // 552 //***************************************************************************** 553 extern uint32_t am_hal_iom_enable(void *pHandle); 554 555 //***************************************************************************** 556 // 557 //! @brief IOM disable function 558 //! 559 //! @param pHandle - handle for the interface. 560 //! 561 //! This function disables the IOMaster from operation. 562 //! 563 //! @return status - generic or interface specific status. 564 // 565 //***************************************************************************** 566 extern uint32_t am_hal_iom_disable(void *pHandle); 567 568 //***************************************************************************** 569 // 570 //! @brief IOM control function 571 //! 572 //! @param pHandle - handle for the IOM. 573 //! @param eReq - device specific special request code. 574 //! @param pArgs - pointer to the request specific arguments. 575 //! 576 //! This function allows advanced settings 577 //! 578 //! @return status - generic or interface specific status. 579 // 580 //***************************************************************************** 581 extern uint32_t am_hal_iom_control(void *pHandle, am_hal_iom_request_e eReq, void *pArgs); 582 583 //***************************************************************************** 584 // 585 //! @brief IOM status function 586 //! 587 //! @param pHandle - handle for the interface. 588 //! @param psStatus - pointer to an interface specific structure used to 589 //! return the status of the interface. 590 //! 591 //! This function returns the current status of the interface. 592 //! 593 //! @return status - generic or interface specific status. 594 // 595 //***************************************************************************** 596 extern uint32_t am_hal_iom_status_get(void *pHandle, am_hal_iom_status_t *psStatus); 597 598 //***************************************************************************** 599 // 600 //! @brief IOM enable interrupts function 601 //! 602 //! @param pHandle - handle for the interface. 603 //! @param ui32IntMask - interface specific interrupt mask. 604 //! 605 //! This function enables the specific indicated interrupts. 606 //! 607 //! The following are valid enable bits, any of which can be ORed together. 608 //! - AM_REG_IOM_INTEN_CQERR_M // Error during command queue operations 609 //! - AM_REG_IOM_INTEN_CQCMP_M // Command queue operation complete 610 //! - AM_REG_IOM_INTEN_DERR_M // DMA error received 611 //! - AM_REG_IOM_INTEN_DCMP_M // DMA transfer complete 612 //! - AM_REG_IOM_INTEN_ARB_M // Arbitration loss 613 //! - AM_REG_IOM_INTEN_STOP_M // STOP command 614 //! - AM_REG_IOM_INTEN_START_M // START command 615 //! - AM_REG_IOM_INTEN_ICMD // ILLEGAL command 616 //! - AM_REG_IOM_INTEN_IACC_M // Illegal FIFO access 617 //! - AM_REG_IOM_INTEN_NAK_M // I2C NAK 618 //! - AM_REG_IOM_INTEN_FOVFL_M // Write FIFO overflow 619 //! - AM_REG_IOM_INTEN_FUNDFL_M // Read FIFO underflow 620 //! - AM_REG_IOM_INTEN_THR_M // FIFO threshold interrupt 621 //! - AM_REG_IOM_INTEN_CMDCMP_M // Command complete 622 //! 623 //! @return status - generic or interface specific status. 624 // 625 //***************************************************************************** 626 extern uint32_t am_hal_iom_interrupt_enable(void *pHandle, uint32_t ui32IntMask); 627 628 //***************************************************************************** 629 // 630 //! @brief IOM disable interrupts function 631 //! 632 //! @param pHandle - handle for the interface. 633 //! @param ui32IntMask - interface specific interrupt mask. 634 //! 635 //! This function disables the specified interrupts. 636 //! 637 //! @return status - generic or interface specific status. 638 //! 639 //! The following are valid disable bits, any of which can be ORed together. 640 //! - AM_REG_IOM_INTEN_CQERR_M // Error during command queue operations 641 //! - AM_REG_IOM_INTEN_CQCMP_M // Command queue operation complete 642 //! - AM_REG_IOM_INTEN_DERR_M // DMA error received 643 //! - AM_REG_IOM_INTEN_DCMP_M // DMA transfer complete 644 //! - AM_REG_IOM_INTEN_ARB_M // Arbitration loss 645 //! - AM_REG_IOM_INTEN_STOP_M // STOP command 646 //! - AM_REG_IOM_INTEN_START_M // START command 647 //! - AM_REG_IOM_INTEN_ICMD // ILLEGAL command 648 //! - AM_REG_IOM_INTEN_IACC_M // Illegal FIFO access 649 //! - AM_REG_IOM_INTEN_NAK_M // I2C NAK 650 //! - AM_REG_IOM_INTEN_FOVFL_M // Write FIFO overflow 651 //! - AM_REG_IOM_INTEN_FUNDFL_M // Read FIFO underflow 652 //! - AM_REG_IOM_INTEN_THR_M // FIFO threshold interrupt 653 //! - AM_REG_IOM_INTEN_CMDCMP_M // Command complete 654 // 655 //***************************************************************************** 656 extern uint32_t am_hal_iom_interrupt_disable(void *pHandle, uint32_t ui32IntMask); 657 658 //***************************************************************************** 659 // 660 //! @brief IOM get interrupt status 661 //! 662 //! @param pHandle - handle for the interface. 663 //! @param bEnabledOnly - only return enabled interrupts 664 //! @param pui32IntStatus - pointer to a uint32_t to return the interrupt status 665 //! 666 //! This function returns the interrupt status for the given peripheral. 667 //! 668 //! The following are valid status bits. 669 //! - AM_REG_IOM_INTSTAT_CQERR_M // Error during command queue operations 670 //! - AM_REG_IOM_INTSTAT_CQCMP_M // Command queue operation complete 671 //! - AM_REG_IOM_INTSTAT_DERR_M // DMA error received 672 //! - AM_REG_IOM_INTSTAT_DCMP_M // DMA transfer complete 673 //! - AM_REG_IOM_INTSTAT_ARB_M // Arbitration loss 674 //! - AM_REG_IOM_INTSTAT_STOP_M // STOP command 675 //! - AM_REG_IOM_INTSTAT_START_M // START command 676 //! - AM_REG_IOM_INTSTAT_ICMD // ILLEGAL command 677 //! - AM_REG_IOM_INTSTAT_IACC_M // Illegal FIFO access 678 //! - AM_REG_IOM_INTSTAT_NAK_M // I2C NAK 679 //! - AM_REG_IOM_INTSTAT_FOVFL_M // Write FIFO overflow 680 //! - AM_REG_IOM_INTSTAT_FUNDFL_M // Read FIFO underflow 681 //! - AM_REG_IOM_INTSTAT_THR_M // FIFO threshold interrupt 682 //! - AM_REG_IOM_INTSTAT_CMDCMP_M // Command complete 683 //! 684 //! @return status - generic or interface specific status. 685 // 686 //***************************************************************************** 687 extern uint32_t am_hal_iom_interrupt_status_get(void *pHandle, bool bEnabledOnly, 688 uint32_t *pui32IntStatus); 689 690 //***************************************************************************** 691 // 692 //! @brief IOM interrupt clear 693 //! 694 //! @param pHandle - handle for the interface. 695 //! @param ui32IntMask - interface specific interrupt mask. 696 //! 697 //! This function clears the interrupts for the given peripheral. 698 //! 699 //! The following are valid clear bits, any of which can be ORed together. 700 //! - AM_REG_IOM_INTCLR_CQERR_M // Error during command queue operations 701 //! - AM_REG_IOM_INTCLR_CQCMP_M // Command queue operation complete 702 //! - AM_REG_IOM_INTCLR_DERR_M // DMA error received 703 //! - AM_REG_IOM_INTCLR_DCMP_M // DMA transfer complete 704 //! - AM_REG_IOM_INTCLR_ARB_M // Arbitration loss 705 //! - AM_REG_IOM_INTCLR_STOP_M // STOP command 706 //! - AM_REG_IOM_INTCLR_START_M // START command 707 //! - AM_REG_IOM_INTCLR_ICMD // ILLEGAL command 708 //! - AM_REG_IOM_INTCLR_IACC_M // Illegal FIFO access 709 //! - AM_REG_IOM_INTCLR_NAK_M // I2C NAK 710 //! - AM_REG_IOM_INTCLR_FOVFL_M // Write FIFO overflow 711 //! - AM_REG_IOM_INTCLR_FUNDFL_M // Read FIFO underflow 712 //! - AM_REG_IOM_INTCLR_THR_M // FIFO threshold interrupt 713 //! - AM_REG_IOM_INTCLR_CMDCMP_M // Command complete 714 //! 715 //! @return status - generic or interface specific status. 716 // 717 //***************************************************************************** 718 extern uint32_t am_hal_iom_interrupt_clear(void *pHandle, uint32_t ui32IntMask); 719 720 //***************************************************************************** 721 // 722 //! @brief IOM interrupt service routine 723 //! 724 //! @param pHandle - handle for the interface. 725 //! @param ui32IntMask - interface specific interrupt mask indicating 726 //! interrupts to be serviced 727 //! 728 //! This function is designed to be called from within the user defined ISR 729 //! (am_iom_isr) in order to service the non-blocking, queued, or DMA processing 730 //! for a given module instance. 731 //! 732 //! @return status - generic or interface specific status. 733 // 734 //***************************************************************************** 735 extern uint32_t am_hal_iom_interrupt_service(void *pHandle, uint32_t ui32IntMask); 736 737 //***************************************************************************** 738 // 739 //! @brief IOM power control function 740 //! 741 //! @param pHandle - handle for the interface. 742 //! @param ePowerState - the desired power state to move the peripheral to. 743 //! @param retainState - flag (if true) to save/restore perhipheral state upon 744 //! power state change. 745 //! 746 //! This function updates the peripheral to a given power state. 747 //! 748 //! @return status - generic or interface specific status. 749 // 750 //***************************************************************************** 751 extern uint32_t am_hal_iom_power_ctrl(void *pHandle, 752 am_hal_sysctrl_power_state_e ePowerState, 753 bool retainState); 754 755 //***************************************************************************** 756 // 757 //! @brief IOM blocking transfer function 758 //! 759 //! @param pHandle - handle for the interface. 760 //! @param psTransaction - pointer to the transaction control structure. 761 //! 762 //! This function performs a transaction on the IOM in PIO mode. It handles 763 //! half duplex transactions only (TX or RX). 764 //! 765 //! @return status - generic or interface specific status. 766 // 767 //***************************************************************************** 768 extern uint32_t am_hal_iom_blocking_transfer(void *pHandle, 769 am_hal_iom_transfer_t *psTransaction); 770 771 //***************************************************************************** 772 // 773 //! @brief IOM non-blocking transfer function 774 //! 775 //! @param pHandle - handle for the interface. 776 //! @param psTransaction - pointer to the uniform transaction control structure. 777 //! @param pfnCallback - pointer the callback function to be executed when 778 //! transaction is complete can be set to NULL). 779 //! @param pCallbackCtxt- context registered which is passed on to the callback 780 //! function 781 //! 782 //! This function performs a transaction on the interface. It handles half duplex 783 //! transactions. The callback is executed when the transaction is complete. 784 //! 785 //! @return status - generic or interface specific status. 786 // 787 //***************************************************************************** 788 extern uint32_t am_hal_iom_nonblocking_transfer(void *pHandle, 789 am_hal_iom_transfer_t *psTransaction, 790 am_hal_iom_callback_t pfnCallback, 791 void *pCallbackCtxt); 792 793 //***************************************************************************** 794 // 795 //! @brief IOM uninitialize function 796 //! 797 //! @param pHandle - returns the handle for the module instance. 798 //! 799 //! This function accepts a handle to the initialized interface and returns 800 //! the peripheral instance to a known uninitialized state. 801 //! 802 //! @return status - generic or interface specific status. 803 // 804 //***************************************************************************** 805 // 806 // Uninitialize the interface and return the handle to a known state. 807 // 808 extern uint32_t am_hal_iom_uninitialize(void *pHandle); 809 810 //***************************************************************************** 811 // 812 //! @brief Perform a Full Duplex transaction. 813 //! 814 //! @param pHandle - handle for the interface. 815 //! @param psTransaction - pointer to the uniform transaction control structure. 816 //! 817 //! @return HAL status of the operation. 818 // 819 //***************************************************************************** 820 uint32_t 821 am_hal_iom_spi_blocking_fullduplex(void *pHandle, 822 am_hal_iom_transfer_t *psTransaction); 823 824 //***************************************************************************** 825 //! @brief IOM High Priority transfer function 826 //! 827 //! @param pHandle - handle for the interface 828 //! @param psTransaction - pointer to the transaction control structure 829 //! @param pfnCallback - pointer to function executed when 830 //! transaction is complete (can be set to NULL). 831 //! @param pCallbackCtxt - context registered which is passed on to the callback 832 //! function 833 //! @return uint32_t - generic or interface specific status 834 //***************************************************************************** 835 uint32_t am_hal_iom_highprio_transfer(void *pHandle, 836 am_hal_iom_transfer_t *psTransaction, 837 am_hal_iom_callback_t pfnCallback, 838 void *pCallbackCtxt); 839 840 841 #ifdef __cplusplus 842 } 843 #endif 844 845 #endif // AM_HAL_IOM_H 846 //***************************************************************************** 847 // 848 // End Doxygen group. 849 //! @} 850 // 851 //***************************************************************************** 852
