1 /** 2 * @file i2c.h 3 * @brief Inter-integrated circuit (I2C) communications interface driver. 4 */ 5 6 /****************************************************************************** 7 * 8 * Copyright (C) 2022-2023 Maxim Integrated Products, Inc. (now owned by 9 * Analog Devices, Inc.), 10 * Copyright (C) 2023-2024 Analog Devices, Inc. 11 * 12 * Licensed under the Apache License, Version 2.0 (the "License"); 13 * you may not use this file except in compliance with the License. 14 * You may obtain a copy of the License at 15 * 16 * http://www.apache.org/licenses/LICENSE-2.0 17 * 18 * Unless required by applicable law or agreed to in writing, software 19 * distributed under the License is distributed on an "AS IS" BASIS, 20 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 21 * See the License for the specific language governing permissions and 22 * limitations under the License. 23 * 24 ******************************************************************************/ 25 26 /* Define to prevent redundant inclusion */ 27 #ifndef LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32690_I2C_H_ 28 #define LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32690_I2C_H_ 29 30 #include <stdint.h> 31 #include <stdbool.h> 32 #include "mxc_sys.h" 33 #include "i2c_regs.h" 34 #include "dma_regs.h" 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * @defgroup i2c I2C 42 * @ingroup periphlibs 43 * @{ 44 */ 45 46 /***** Definitions *****/ 47 #define MXC_I2C_STD_MODE 100000 48 #define MXC_I2C_FAST_SPEED 400000 49 #define MXC_I2C_FASTPLUS_SPEED 1000000 50 #define MXC_I2C_HIGH_SPEED 3400000 51 52 typedef struct _i2c_req_t mxc_i2c_req_t; 53 /** 54 * @brief The callback used by the MXC_I2C_ReadByteInteractive() function. 55 * 56 * The callback routine used by the MXC_I2C_ReadByteInteractive() function. This 57 * function allows the application to determine whether the byte received 58 * should be acknowledged or not. 59 * 60 * @param i2c Pointer to I2C registers (selects the I2C block used.) 61 * @param byte The byte received. 62 * 63 * @return 0 if the byte should not be acknowledged (NACK), non-zero to 64 * acknowledge the byte. 65 */ 66 typedef int (*mxc_i2c_getAck_t)(mxc_i2c_regs_t *i2c, unsigned char byte); 67 68 /** 69 * @brief The callback routine used by the MXC_I2C_MasterTransactionAsync() 70 * function to indicate the transaction has completed. 71 * 72 * @param req The details of the transaction. 73 * @param result 0 if all bytes are acknowledged, 1 if any byte 74 * transmitted is not acknowledged, negative if error. 75 * See \ref MXC_Error_Codes for the list of error codes. 76 */ 77 typedef void (*mxc_i2c_complete_cb_t)(mxc_i2c_req_t *req, int result); 78 79 /** 80 * @brief The callback routine used by the I2C Read/Write FIFO DMA 81 * functions to indicate the transaction has completed. 82 * 83 * @param len The length of data actually read/written 84 * @param result See \ref MXC_Error_Codes for the list of error codes. 85 */ 86 typedef void (*mxc_i2c_dma_complete_cb_t)(int len, int result); 87 88 /** 89 * @brief The information required to perform a complete I2C transaction as 90 * the bus master. 91 * 92 * The information required to perform a complete I2C transaction as the bus 93 * master. This structure is used by the MXC_I2C_MasterTransaction() and 94 * MXC_I2C_MasterTransactionAsync() functions. 95 */ 96 struct _i2c_req_t { 97 mxc_i2c_regs_t *i2c; ///< Pointer to I2C registers (selects the 98 ///< I2C block used.) 99 unsigned int addr; ///< The 7-bit or 10-bit address of the slave. 100 unsigned char *tx_buf; ///< The buffer containing the bytes to write. 101 unsigned int tx_len; ///< The number of bytes to write. On return 102 ///< from the function, this will be set to 103 ///< the number of bytes actually transmitted. 104 unsigned char *rx_buf; ///< The buffer to read the data into. 105 unsigned int rx_len; ///< The number of bytes to read. On return 106 ///< from the function, this will be set to 107 ///< the number of bytes actually received. 108 int restart; ///< Controls whether the transaction is 109 ///< terminated with a stop or repeated start 110 ///< condition. Use 0 for a stop, non-zero 111 ///< for repeated start. 112 mxc_i2c_complete_cb_t callback; ///< The callback used to indicate the 113 ///< transaction is complete or an error has 114 ///< occurred. This field may be set to NULL 115 ///< if no indication is necessary. This 116 ///< field is only used by the 117 ///< MXC_I2C_MasterTransactionAsync() function. 118 ///< MXC_I2C_MasterTransaction() ignores the 119 ///< callback field. 120 }; 121 122 /** 123 * @brief The list of events reported by the MXC_I2C_SlaveTransaction() and 124 * MXC_I2C_SlaveTransactionAsync() functions. 125 * 126 * The list of events reported by the MXC_I2C_SlaveTransaction() and 127 * MXC_I2C_SlaveTransactionAsync() functions. It is up to the calling 128 * application to handle these events. 129 */ 130 typedef enum { 131 MXC_I2C_EVT_MASTER_WR = 0, ///< A slave address match occurred with the master 132 ///< requesting a write to the slave. 133 MXC_I2C_EVT_MASTER_RD, ///< A slave address match occurred with the master 134 ///< requesting a read from the slave. 135 MXC_I2C_EVT_RX_THRESH, ///< The receive FIFO contains more bytes than its 136 ///< threshold level. 137 MXC_I2C_EVT_TX_THRESH, ///< The transmit FIFO contains fewer bytes than its 138 ///< threshold level. 139 MXC_I2C_EVT_TRANS_COMP, ///< The transaction has ended. 140 MXC_I2C_EVT_UNDERFLOW, ///< The master has attempted a read when the 141 ///< transmit FIFO was empty. 142 MXC_I2C_EVT_OVERFLOW, ///< The master has written data when the receive 143 ///< FIFO was already full. 144 } mxc_i2c_slave_event_t; 145 146 /** 147 * @brief The callback routine used by the MXC_I2C_SlaveTransaction() and 148 * MXC_I2C_SlaveTransactionAsync functions to handle the various I2C 149 * slave events. 150 * 151 * @param i2c Pointer to I2C registers (selects the I2C block used.) 152 * @param event The event that occurred to trigger this callback. 153 * @param data This field is used to pass Success/Fail for the 154 * MXC_I2C_EVT_TRANS_COMP event. 155 * 156 * @return The return value is only used in the case of an MXC_I2C_EVT_RX_THRESH 157 * event. In this case, the return specifies if the last byte 158 * received should be acknowledged or not. Return 0 to acknowledge, 159 * non-zero to not acknowledge. The return value is ignored for all 160 * other event types. 161 */ 162 typedef int (*mxc_i2c_slave_handler_t)(mxc_i2c_regs_t *i2c, mxc_i2c_slave_event_t event, 163 void *data); 164 165 /***** Function Prototypes *****/ 166 167 /* ************************************************************************* */ 168 /* Control/Configuration functions */ 169 /* ************************************************************************* */ 170 171 /** 172 * @brief Initialize and enable I2C peripheral. 173 * Note the ME18 assigns the same alternate function to multiple sets 174 * of pins. The drivers will enable both sets so that either can be used. 175 * Users should ensure the unused set is left unconnected. 176 * 177 * See MAX32690 Rev A2 Errata #16: 178 * https://www.analog.com/media/en/technical-documentation/data-sheets/max32690_a2_errata_rev2.pdf 179 * 180 * @note On default this function enables I2C peripheral clock and i2c gpio pins. 181 * if you wish to manage clock and gpio related things in upper level instead of here. 182 * Define MSDK_NO_GPIO_CLK_INIT flag in project.mk file. 183 * By this flag this function will remove clock and gpio related codes from file. 184 * 185 * @param i2c Pointer to I2C registers (selects the I2C block used.) 186 * @param masterMode Whether to put the device in master or slave mode. Use 187 * non-zero 188 * for master mode, and zero for slave mode. 189 * @param slaveAddr 7-bit or 10-bit address to use when in slave mode. 190 * This parameter is ignored when masterMode is non-zero. 191 * 192 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 193 */ 194 int MXC_I2C_Init(mxc_i2c_regs_t *i2c, int masterMode, unsigned int slaveAddr); 195 196 /** 197 * @brief Set slave address for I2C instances acting as slaves on the bus. 198 * @note Set idx to zero, multiple I2C instances acting as slaves on the 199 * bus is not yet supported. 200 * 201 * @param i2c Pointer to I2C registers (selects the I2C block used.) 202 * @param slaveAddr 7-bit or 10-bit address to use when in slave mode. 203 * This parameter is ignored when masterMode is non-zero. 204 * @param idx Index of the I2C slave. 205 * 206 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 207 */ 208 int MXC_I2C_SetSlaveAddr(mxc_i2c_regs_t *i2c, unsigned int slaveAddr, int idx); 209 210 /** 211 * @brief Disable and shutdown I2C peripheral. 212 * 213 * @param i2c Pointer to I2C registers (selects the I2C block used.) 214 * 215 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 216 */ 217 int MXC_I2C_Shutdown(mxc_i2c_regs_t *i2c); 218 219 /** 220 * @brief Reset the I2C peripheral. 221 * @note The peripheral will need to be initialized with MXC_I2C_Init() before use 222 * 223 * @param i2c Pointer to I2C registers (selects the I2C block used.) 224 * 225 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 226 */ 227 int MXC_I2C_Reset(mxc_i2c_regs_t *i2c); 228 229 /** 230 * @brief Set the frequency of the I2C interface. 231 * 232 * @param i2c Pointer to I2C registers (selects the I2C block used.) 233 * @param hz The desired frequency in Hertz. 234 * 235 * @return Negative if error, otherwise actual speed set. See \ref 236 * MXC_Error_Codes for the list of error return codes. 237 */ 238 int MXC_I2C_SetFrequency(mxc_i2c_regs_t *i2c, unsigned int hz); 239 240 /** 241 * @brief Get the frequency of the I2C interface. 242 * 243 * @param i2c Pointer to I2C registers (selects the I2C block used.) 244 * 245 * @return The I2C bus frequency in Hertz 246 */ 247 int MXC_I2C_GetFrequency(mxc_i2c_regs_t *i2c); 248 249 /** 250 * @brief Checks if the given I2C bus can be placed in sleep more. 251 * 252 * This functions checks to see if there are any on-going I2C transactions in 253 * progress. If there are transactions in progress, the application should 254 * wait until the I2C bus is free before entering a low-power state. 255 * 256 * @param i2c Pointer to I2C registers (selects the I2C block used.) 257 * 258 * @return #E_NO_ERROR if ready, and non-zero if busy or error. See \ref 259 * MXC_Error_Codes for the list of error return codes. 260 */ 261 int MXC_I2C_ReadyForSleep(mxc_i2c_regs_t *i2c); 262 263 /** 264 * @brief Enables or disables clock stretching by the slave. 265 * 266 * Enables or disables clock stretching by the slave. This function has no 267 * affect when operating as the master. 268 * 269 * @param i2c Pointer to I2C registers (selects the I2C block used.) 270 * @param enable Enables clock stretching if non-zero, disables if zero. 271 * 272 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 273 */ 274 int MXC_I2C_SetClockStretching(mxc_i2c_regs_t *i2c, int enable); 275 276 /** 277 * @brief Determines if clock stretching has been enabled. 278 * 279 * @param i2c Pointer to I2C registers (selects the I2C block used.) 280 * 281 * @return Zero if clock stretching is disabled, non-zero otherwise 282 */ 283 int MXC_I2C_GetClockStretching(mxc_i2c_regs_t *i2c); 284 285 /** 286 * @brief Initializes the DMA for I2C DMA transactions. 287 * 288 * This function will release any acquired DMA channels before reacquiring and 289 * reconfiguring selected I2C DMA TX or RX channels. 290 * 291 * @param i2c Pointer to I2C registers (selects the I2C block used). 292 * @param dma Pointer to DMA registers (selects the DMA block used). 293 * @param use_dma_tx If true, acquire and configure DMA TX channel, else release any 294 * acquired DMA TX channel. 295 * @param use_dma_rx If true, acquire and configure DMA RX channel, else release any 296 * acquired DMA RX channel. 297 * 298 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 299 */ 300 int MXC_I2C_DMA_Init(mxc_i2c_regs_t *i2c, mxc_dma_regs_t *dma, bool use_dma_tx, bool use_dma_rx); 301 302 /** 303 * @brief Retreive the DMA TX Channel associated with I2C instance. 304 * 305 * @param i2c Pointer to I2C registers (selects the I2C block used). 306 * 307 * @return If successful, the DMA TX Channel number is returned. Otherwise, see 308 * \ref MXC_Error_Codes for a list of return codes. 309 */ 310 int MXC_I2C_DMA_GetTXChannel(mxc_i2c_regs_t *i2c); 311 312 /** 313 * @brief Retreive the DMA RX Channel associated with I2C instance. 314 * 315 * @param i2c Pointer to I2C registers (selects the I2C block used). 316 * 317 * @return If successful, the DMA RX Channel number is returned. Otherwise, see 318 * \ref MXC_Error_Codes for a list of return codes. 319 */ 320 int MXC_I2C_DMA_GetRXChannel(mxc_i2c_regs_t *i2c); 321 322 /** 323 * @brief Sets the I2C instance's DMA TX/RX request select. 324 * 325 * @param i2c Pointer to I2C registers (selects the I2C block used). 326 * @param txData Pointer to transmit buffer. 327 * @param rxData Pointer to receive buffer. 328 * 329 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 330 */ 331 int MXC_I2C_DMA_SetRequestSelect(mxc_i2c_regs_t *i2c, uint8_t *txData, uint8_t *rxData); 332 333 /* ************************************************************************* */ 334 /* Low-level functions */ 335 /* ************************************************************************* */ 336 337 /** 338 * @brief Generate a start (or repeated start) condition on the I2C bus. 339 * 340 * Generate a start (or repeated start) condition on the I2C bus. This 341 * function may opt to delay the actual generation of the start condition 342 * until data is actually transferred. 343 * 344 * @param i2c Pointer to I2C registers (selects the I2C block used.) 345 * 346 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 347 */ 348 int MXC_I2C_Start(mxc_i2c_regs_t *i2c); 349 350 /** 351 * @brief Generate a stop condition on the I2C bus. 352 * 353 * @param i2c Pointer to I2C registers (selects the I2C block used.) 354 * 355 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 356 */ 357 int MXC_I2C_Stop(mxc_i2c_regs_t *i2c); 358 359 /** 360 * @brief Write a single byte to the I2C bus. 361 * 362 * Write a single byte to the I2C bus. This function assumes the I2C bus is 363 * already in the proper state (i.e. a start condition has already been 364 * generated and the bus is in the write phase of an I2C transaction). If any 365 * bytes are pending in the FIFO (i.e. in the case of clock stretching), this 366 * function will return E_OVERFLOW. 367 * 368 * @param i2c Pointer to I2C registers (selects the I2C block used.) 369 * @param byte The byte to transmit. 370 * 371 * @return 0 if byte is acknowledged, 1 if not acknowledged, negative if 372 * error. See \ref MXC_Error_Codes for the list of error return codes. 373 */ 374 int MXC_I2C_WriteByte(mxc_i2c_regs_t *i2c, unsigned char byte); 375 376 /** 377 * @brief Read a single byte from the I2C bus. 378 * 379 * Read a single byte from the I2C bus. This function assumes the I2C bus is 380 * already in the proper state (i.e. a start condition has already been 381 * generated and the bus is in the read phase of an I2C transaction). If the FIFO 382 * is empty, this function will return E_UNDERFLOW. 383 * 384 * @param i2c Pointer to I2C registers (selects the I2C block used.) 385 * @param byte Pointer to the byte to read into. 386 * @param ack Whether or not to acknowledge the byte once received. 387 * 388 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 389 */ 390 int MXC_I2C_ReadByte(mxc_i2c_regs_t *i2c, unsigned char *byte, int ack); 391 392 /** 393 * @brief Read a single byte from the I2C bus. 394 * 395 * Read a single byte from the I2C bus. After the byte is received, the 396 * provided callback will be used to determine if the byte should be 397 * acknowledged or not before continuing with the rest of the transaction. 398 * This function assumes the I2C bus is already in the proper state (i.e. a 399 * start condition has already been generated and the bus is in the read 400 * phase of an I2C transaction). This function must be called with clock 401 * stretching enabled. 402 * 403 * @param i2c Pointer to I2C registers (selects the I2C block used.) 404 * @param byte Pointer to the byte to read into. 405 * @param getAck A function to be called to determine whether or not 406 * to acknowledge the byte once received. A non-zero 407 * return value will acknowledge the byte. If this 408 * parameter is set to NULL or its return value is 0, 409 * the byte received will not be acknowledged (i.e., it 410 * will be NACKed). 411 * 412 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 413 */ 414 int MXC_I2C_ReadByteInteractive(mxc_i2c_regs_t *i2c, unsigned char *byte, mxc_i2c_getAck_t getAck); 415 416 /** 417 * @brief Write multiple bytes to the I2C bus. 418 * 419 * Write multiple bytes to the I2C bus. This function assumes the I2C bus is 420 * already in the proper state (i.e. a start condition has already been 421 * generated and the bus is in the write phase of an I2C transaction). 422 * 423 * @param i2c Pointer to I2C registers (selects the I2C block used.) 424 * @param bytes The buffer containing the bytes to transmit. 425 * @param len The number of bytes to write. On return from the 426 * function, this will be set to the number of bytes 427 * actually transmitted. 428 * 429 * @return 0 if all bytes are acknowledged, 1 if any byte transmitted is not 430 * acknowledged, negative if error. See \ref MXC_Error_Codes for the 431 * list of error return codes. 432 */ 433 int MXC_I2C_Write(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int *len); 434 435 /** 436 * @brief Read multiple bytes from the I2C bus. 437 * 438 * Read multiple byte from the I2C bus. This function assumes the I2C bus is 439 * already in the proper state (i.e. a start condition has already been 440 * generated and the bus is in the read phase of an I2C transaction). 441 * 442 * @param i2c Pointer to I2C registers (selects the I2C block used.) 443 * @param bytes The buffer to read the data into. 444 * @param len The number of bytes to read. On return from the 445 * function, this will be set to the number of bytes 446 * actually received. 447 * @param ack Whether or not to acknowledge the last byte once it is 448 * received. All previous bytes will be acknowledged. 449 * 450 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 451 */ 452 int MXC_I2C_Read(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int *len, int ack); 453 454 /** 455 * @brief Unloads bytes from the receive FIFO. 456 * 457 * @param i2c Pointer to I2C registers (selects the I2C block used.) 458 * @param bytes The buffer to read the data into. 459 * @param len The number of bytes to read. 460 * 461 * @return The number of bytes actually read. 462 */ 463 int MXC_I2C_ReadRXFIFO(mxc_i2c_regs_t *i2c, volatile unsigned char *bytes, unsigned int len); 464 465 /** 466 * @brief Unloads bytes from the receive FIFO using DMA for longer reads. 467 * 468 * @note The operation is not complete until the callback has been called 469 * 470 * @param i2c Pointer to I2C registers (selects the I2C block used.) 471 * @param bytes The buffer to read the data into. 472 * @param len The number of bytes to read. 473 * @param callback The function to call when the read is complete 474 * 475 * @return See \ref MXC_Error_Codes for a list of return values. 476 */ 477 int MXC_I2C_ReadRXFIFODMA(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int len, 478 mxc_i2c_dma_complete_cb_t callback); 479 480 /** 481 * @brief Get the number of bytes currently available in the receive FIFO. 482 * 483 * @param i2c Pointer to I2C registers (selects the I2C block used.) 484 * 485 * @return The number of bytes available. 486 */ 487 int MXC_I2C_GetRXFIFOAvailable(mxc_i2c_regs_t *i2c); 488 489 /** 490 * @brief Loads bytes into the transmit FIFO. 491 * 492 * @param i2c Pointer to I2C registers (selects the I2C block used.) 493 * @param bytes The buffer containing the bytes to write 494 * @param len The number of bytes to write. 495 * 496 * @return The number of bytes actually written. 497 */ 498 int MXC_I2C_WriteTXFIFO(mxc_i2c_regs_t *i2c, volatile unsigned char *bytes, unsigned int len); 499 500 /** 501 * @brief Loads bytes into the transmit FIFO using DMA for longer writes. 502 * 503 * @note The operation is not complete until the callback has been called 504 * @param i2c Pointer to I2C registers (selects the I2C block used.) 505 * @param bytes The buffer containing the bytes to write 506 * @param len The number of bytes to write. 507 * @param callback The function to call when the read is complete 508 * 509 * @return See \ref MXC_Error_Codes for a list of return values 510 */ 511 int MXC_I2C_WriteTXFIFODMA(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int len, 512 mxc_i2c_dma_complete_cb_t callback); 513 514 /** 515 * @brief Get the amount of free space available in the transmit FIFO. 516 * 517 * @param i2c Pointer to I2C registers (selects the I2C block used.) 518 * 519 * @return The number of bytes available. 520 */ 521 int MXC_I2C_GetTXFIFOAvailable(mxc_i2c_regs_t *i2c); 522 523 /** 524 * @brief Removes and discards all bytes currently in the receive FIFO. 525 * 526 * @param i2c Pointer to I2C registers (selects the I2C block used.) 527 */ 528 void MXC_I2C_ClearRXFIFO(mxc_i2c_regs_t *i2c); 529 530 /** 531 * @brief Removes and discards all bytes currently in the transmit FIFO. 532 * 533 * @param i2c Pointer to I2C registers (selects the I2C block used.) 534 */ 535 void MXC_I2C_ClearTXFIFO(mxc_i2c_regs_t *i2c); 536 537 /** 538 * @brief Get the presently set interrupt flags. 539 * 540 * @param i2c Pointer to I2C registers (selects the I2C block used.) 541 * @param flags0 Pointer to variable to store interrupt status for interrupt register intfl0. 542 * @param flags1 Pointer to variable to store interrupt status for interrupt register intfl1. 543 */ 544 int MXC_I2C_GetFlags(mxc_i2c_regs_t *i2c, unsigned int *flags0, unsigned int *flags1); 545 546 /** 547 * @brief Clears the Interrupt Flags. 548 * 549 * @param i2c Pointer to I2C registers (selects the I2C block used.) 550 * @param flags0 Flags to clear in interrupt register intfl0. 551 * @param flags1 Flags to clear in interrupt register intfl1. 552 */ 553 void MXC_I2C_ClearFlags(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1); 554 555 /** 556 * @brief Enable Interrupts. 557 * 558 * @param i2c Pointer to I2C registers (selects the I2C block used.) 559 * @param flags0 Interrupts to be enabled in int->en0 560 * @param flags1 Interrupts to be enabled in int->en1 561 */ 562 void MXC_I2C_EnableInt(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1); 563 564 /** 565 * @brief Disable Interrupts. 566 * 567 * @param i2c Pointer to I2C registers (selects the I2C block used.) 568 * @param flags0 Interrupts to be disabled in int->en0 569 * @param flags1 Interrupts to be disabled in int->en1 570 */ 571 void MXC_I2C_DisableInt(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1); 572 573 /** 574 * @brief Enables the slave preload mode 575 * 576 * Use this mode to preload the slave TX FIFO with data that can be sent when 577 * the slave is addressed for a read operation without software intervention. 578 * 579 * @param i2c Pointer to I2C registers (selects the I2C block used.) 580 */ 581 void MXC_I2C_EnablePreload(mxc_i2c_regs_t *i2c); 582 583 /** 584 * @brief Disable the slave preload mode 585 * 586 * @param i2c Pointer to I2C registers (selects the I2C block used.) 587 */ 588 void MXC_I2C_DisablePreload(mxc_i2c_regs_t *i2c); 589 590 /** 591 * @brief Enables the slave to respond to the general call address 592 * 593 * @param i2c Pointer to I2C registers (selects the I2C block used.) 594 */ 595 void MXC_I2C_EnableGeneralCall(mxc_i2c_regs_t *i2c); 596 597 /** 598 * @brief Prevents the slave from responding to the general call address 599 * 600 * @param i2c Pointer to I2C registers (selects the I2C block used.) 601 */ 602 void MXC_I2C_DisableGeneralCall(mxc_i2c_regs_t *i2c); 603 604 /** 605 * @brief Set the I2C Timeout 606 * 607 * The I2C timeout determines the amount of time the master will wait while the 608 * slave is stretching the clock, and the amount of time the slave will stretch 609 * the clock while waiting for software to unload the fifo. 610 * 611 * @param i2c Pointer to I2C registers (selects the I2C block used.) 612 * @param timeout Timeout in uS 613 */ 614 void MXC_I2C_SetTimeout(mxc_i2c_regs_t *i2c, unsigned int timeout); 615 616 /** 617 * @brief Get the current I2C timeout 618 * 619 * @param i2c Pointer to I2C registers (selects the I2C block used.) 620 * 621 * @return The current timeout in uS 622 */ 623 unsigned int MXC_I2C_GetTimeout(mxc_i2c_regs_t *i2c); 624 625 /** 626 * @brief Attempts to recover the I2C bus, ensuring the I2C lines are idle. 627 * 628 * Attempts to recover and reset an I2C bus by sending I2C clocks. During 629 * each clock cycle, the SDA line is cycled to determine if the master has 630 * control of the line. The following steps are performed to create one SCL 631 * clock cycle: 632 * 1. Drive SCL low 633 * 2. Verify SCL is low 634 * 3. Drive SDA low 635 * 4. Verify SDA is low 636 * 5. Release SDA allowing it to return high 637 * 6. Verify SDA is high 638 * 7. Release SCL allowing it to return high. 639 * 8. Verify SCL is high 640 * If any of the steps fail, the bus is considered to still be busy and the 641 * sequence is repeated up to the requested number of times. If all steps 642 * succeed, a final stop condition is generated on the I2C bus. 643 * 644 * @param i2c Pointer to I2C registers (selects the I2C block used.) 645 * @param retries Number of times to attempt the clock cycle sequence. 646 * 647 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 648 */ 649 int MXC_I2C_Recover(mxc_i2c_regs_t *i2c, unsigned int retries); 650 651 /* ************************************************************************* */ 652 /* Transaction level functions */ 653 /* ************************************************************************* */ 654 655 /** 656 * @brief Performs a blocking I2C master transaction. 657 * 658 * Performs a blocking I2C master transaction. These actions will be performed: 659 * 1. If necessary, generate a start condition on the bus. 660 * 2. Send the slave address with the low bit set to 0 (indicating a write). 661 * 3. Transmit req->tx_len bytes of req->tx_buff. 662 * 4. Generate a repeated start condition on the bus. 663 * 5. Send the slave address with the low bit set to 1 (indicating a read). 664 * 6. Receive req->rx_len bytes into req->rx_buf, acknowledging each byte. 665 * 7. Generate a stop (or repeated start) condition on the bus. 666 * Steps 3-6 will be skipped if req->tx_len and req->rx_len are both 0. 667 * Steps 2-4 will be skipped if req->tx_len equals 0. 668 * Steps 4-6 will be skipped if req->rx_len equals 0. 669 * 670 * @param req Pointer to details of the transaction 671 * 672 * @return 0 if all bytes are acknowledged, 1 if any byte transmitted is not 673 * acknowledged, negative if error. See \ref MXC_Error_Codes for the 674 * list of error return codes. 675 */ 676 int MXC_I2C_MasterTransaction(mxc_i2c_req_t *req); 677 678 /** 679 * @brief Performs a non-blocking I2C master transaction. 680 * 681 * Performs a non-blocking I2C master transaction. These actions will be performed: 682 * 1. If necessary, generate a start condition on the bus. 683 * 2. Send the slave address with the low bit set to 0 (indicating a write). 684 * 3. Transmit req->tx_len bytes of req->tx_buff. 685 * 4. Generate a repeated start condition on the bus. 686 * 5. Send the slave address with the low bit set to 1 (indicating a read). 687 * 6. Receive req->rx_len bytes into req->rx_buf, acknowledging each byte. 688 * 7. Generate a stop (or repeated start) condition on the bus. 689 * 8. Execute req->callback to indicate the transaction is complete. 690 * Steps 3-6 will be skipped if tx_len and rx_len are both 0. 691 * Steps 2-4 will be skipped if tx_len equals 0. 692 * Steps 4-6 will be skipped if rx_len equals 0. 693 * 694 * @note MXC_I2C_AsyncHandler() must be called periodically for this function 695 * to operate properly. Ideally from the I2C ISR. 696 * 697 * @param req Pointer to details of the transaction. The memory 698 * used by this parameter must remain available until 699 * the callback is executed. 700 * 701 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 702 */ 703 int MXC_I2C_MasterTransactionAsync(mxc_i2c_req_t *req); 704 705 /** 706 * @brief Performs a non-blocking I2C Master transaction using DMA for reduced time 707 * in the ISR. This function initializes the DMA and acquires DMA channels 708 * if MXC_I2C_DMA_Init(...) was not called earlier. 709 * 710 * It is recommended to initialize the DMA by calling MXC_I2C_DMA_Init(...) function 711 * before calling MXC_I2C_MasterTransactionDMA(...). This provides flexibility in 712 * setting up generic DMA channel vectors during run-time without knowing what DMA 713 * channels will be acquired beforehand. 714 * 715 * Performs a non-blocking I2C transaction. These actions will be performed: 716 * 1. If necessary, generate a start condition on the bus. 717 * 2. Send the slave address with the low bit set to 0 (indicating a write). 718 * 3. Transmit req->tx_len bytes of req->tx_buff. 719 * 4. Generate a repeated start condition on the bus. 720 * 5. Send the slave address with the low bit set to 1 (indicating a read). 721 * 6. Receive req->rx_len bytes into req->rx_buf, acknowledging each byte. 722 * 7. Generate a stop (or repeated start) condition on the bus. 723 * 8. Execute req->callback to indicate the transaction is complete. 724 * Steps 3-6 will be skipped if tx_len and rx_len are both 0. 725 * Steps 2-4 will be skipped if tx_len equals 0. 726 * Steps 4-6 will be skipped if rx_len equals 0. 727 * 728 * @note MXC_I2C_AsyncHandler() must be called periodically for this function 729 * to operate properly. Ideally from the I2C ISR. 730 * 731 * @param req Pointer to details of the transaction. The memory 732 * used by this parameter must remain available until 733 * the callback is executed. 734 * 735 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 736 */ 737 int MXC_I2C_MasterTransactionDMA(mxc_i2c_req_t *req); 738 739 /** 740 * @brief Performs a blocking I2C slave transaction. 741 * 742 * Performs a blocking I2C slave transaction. This function will block until a 743 * complete transaction with this slave has been performed. A transaction 744 * begins with the master addressing the slave and ends with a repeated start 745 * condition, a stop condition, or a bus error. The provided callback 746 * function will be called for these events: 747 * - A slave address match occurs with the master requesting a write to 748 * the slave. 749 * - A slave address match occurs with the master requesting a read from 750 * the slave. 751 * - The receive FIFO crosses the set threshold (see 752 * MXC_I2C_SetRXThreshold()). The callback code should unload the receive 753 * FIFO (see MXC_I2C_ReadFIFO()) to allow the master to send more data. 754 * The return value of the callback function will determine if the 755 * last byte received should be acknowledged or not. Return 0 to 756 * acknowledge, non-zero to not acknowledge. 757 * - The transmit FIFO crosses the set threshold (see 758 * MXC_I2C_SetTXThreshold()). If the master is expected to read more 759 * data from this slave, the callback code should add data to the 760 * transmit FIFO (see MXC_I2C_WriteFIFO()). 761 * - The transaction ends. If the master was writing to the slave, the 762 * receive FIFO may still contain valid data that needs to be 763 * retreived (see MXC_I2C_ReadFIFO()). 764 * - The transmit FIFO underflows because the master requests data when 765 * the transmit FIFO is empty. 766 * - The receive FIFO overflows because the master writes data while the 767 * receive FIFO was full. 768 * 769 * If clock stretching is disabled, careful attention must be paid to the timing 770 * of the callback to avoid losing data on write or unintentionally nacking a read. 771 * 772 * @param i2c Pointer to I2C registers (selects the I2C block used.) 773 * @param callback The function to be called when an I2C event occurs. 774 * 775 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 776 */ 777 int MXC_I2C_SlaveTransaction(mxc_i2c_regs_t *i2c, mxc_i2c_slave_handler_t callback); 778 779 /** 780 * @brief Performs a non-blocking I2C slave transaction. 781 * 782 * Performs a non-blocking I2C slave transaction. This request will remain active 783 * until a complete transaction with this slave has been performed. A 784 * transaction begins with the master begins with the master addressing the 785 * slave and ends with a repeated start condition, a stop condition, or a bus 786 * error. The provided callback function will be called for these events: 787 * - A slave address match occurs with the master requesting a write to 788 * the slave. 789 * - A slave address match occurs with the master requesting a read from 790 * the slave. 791 * - The receive FIFO crosses the set threshold (see 792 * MXC_I2C_SetRXThreshold()). The callback code should unload the receive 793 * FIFO (see MXC_I2C_ReadFIFO()) to allow the master to send more data. 794 * The return value of the callback function will determine if the 795 * last byte received should be acknowledged or not. Return 0 to 796 * acknowledge, non-zero to not acknowledge. 797 * - The transmit FIFO crosses the set threshold (see 798 * MXC_I2C_SetTXThreshold()). If the master is expected to read more 799 * data from this slave, the callback code should add data to the 800 * transmit FIFO (see MXC_I2C_WriteFIFO()). 801 * - The transaction ends. If the master was writing to the slave, the 802 * receive FIFO may still contain valid data that needs to be 803 * retreived (see MXC_I2C_ReadFIFO()). 804 * - The transmit FIFO underflows because the master requests data when 805 * the transmit FIFO is empty. 806 * - The receive FIFO overflows because the master writes data while the 807 * receive FIFO was full. 808 * 809 * If clock stretching is disabled, careful attention must be paid to the timing 810 * of the callback to avoid losing data on write or unintentionally nacking a read. 811 * 812 * @note MXC_I2C_AsyncHandler() must be called peridocally for this function 813 * to operate properly. 814 * 815 * @param i2c Pointer to I2C registers (selects the I2C block used.) 816 * @param callback The function to be called when an I2C event occurs. 817 * 818 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 819 */ 820 int MXC_I2C_SlaveTransactionAsync(mxc_i2c_regs_t *i2c, mxc_i2c_slave_handler_t callback); 821 822 /** 823 * @brief Set the receive threshold level. 824 * 825 * When operating as a master, the function sets the receive threshold level 826 * for when the master should unload the receive FIFO. Smaller values may 827 * consume more CPU cycles, but decrease the chances of the master delaying 828 * the generation of I2C bus clocks because it has no room in the FIFO to 829 * receive data. Larger values may consume fewer CPU cycles, but risk delays 830 * of the I2C clock. When operating as a slave, this function sets the number 831 * of bytes the slave transaction functions should receive before issuing a 832 * call to their callback function. Smaller values may consume more CPU 833 * cycles, but reduce the risk of missing data from the master due to the 834 * recieve FIFO being full. Larger values may reduce the number of CPU 835 * cycles, but may cause bytes sent from the master to be missed. 836 * 837 * @param i2c Pointer to I2C registers (selects the I2C block used.) 838 * @param numBytes The threshold level to set. This value must be 839 * between 0 and 8 inclusive. 840 * 841 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 842 */ 843 int MXC_I2C_SetRXThreshold(mxc_i2c_regs_t *i2c, unsigned int numBytes); 844 845 /** 846 * @brief Get the current receive threshold level. 847 * 848 * @param i2c Pointer to I2C registers (selects the I2C block used.) 849 * 850 * @return The receive threshold value (in bytes). 851 */ 852 int MXC_I2C_GetRXThreshold(mxc_i2c_regs_t *i2c); 853 854 /** 855 * @brief Set the transmit threshold level. 856 * 857 * When operating as a master, the function sets the transmit threshold level 858 * for when the master should add additional bytes to the transmit FIFO. 859 * Larger values may consume more CPU cycles, but decrease the chances of the 860 * master delaying the generation of I2C bus clocks because it has no data in 861 * the FIFO to transmit. Smaller values may consume fewer CPU cycles, but 862 * risk delays of the I2C clock. When operating as a slave, this function 863 * sets the number of bytes the slave transaction functions should transmit 864 * before issuing a call to their callback function. Larger values may 865 * consume more CPU cycles, but reduce the risk of not having data ready when 866 * the master requests it. Smaller values may reduce the number of CPU 867 * cycles, but may cause the master to read from an empty FIFO. (The master 868 * will read 0xFF in this case.) 869 * 870 * @param i2c Pointer to I2C registers (selects the I2C block used.) 871 * @param numBytes The threshold level to set. This value must be 872 * between 0 and 8 inclusive. 873 * 874 * @return Success/Fail, see \ref MXC_Error_Codes for a list of return codes. 875 */ 876 int MXC_I2C_SetTXThreshold(mxc_i2c_regs_t *i2c, unsigned int numBytes); 877 878 /** 879 * @brief Get the current transmit threshold level. 880 * 881 * @param i2c Pointer to I2C registers (selects the I2C block used.) 882 * 883 * @return The transmit threshold value (in bytes). 884 */ 885 int MXC_I2C_GetTXThreshold(mxc_i2c_regs_t *i2c); 886 887 /** 888 * @brief Stop any asynchronous requests in progress. 889 * 890 * Stop any asynchronous requests in progress. Any callbacks associated with 891 * the active transaction will be NOT executed. 892 * 893 * @param i2c Pointer to I2C registers (selects the I2C block used.) 894 */ 895 void MXC_I2C_AsyncStop(mxc_i2c_regs_t *i2c); 896 897 /** 898 * @brief Abort any asynchronous requests in progress. 899 * 900 * Abort any asynchronous requests in progress. Any callbacks associated with 901 * the active transaction will be executed to indicate when the transaction 902 * has been terminated. 903 * 904 * @param i2c Pointer to I2C registers (selects the I2C block used.) 905 */ 906 void MXC_I2C_AbortAsync(mxc_i2c_regs_t *i2c); 907 908 /** 909 * @brief The processing function for asynchronous transactions. 910 * 911 * When using the asynchronous functions, the application must call this 912 * function periodically. This can be done from within the I2C interrupt 913 * handler or periodically by the application if I2C interrupts are disabled. 914 * 915 * @param i2c Pointer to I2C registers (selects the I2C block used.) 916 */ 917 void MXC_I2C_AsyncHandler(mxc_i2c_regs_t *i2c); 918 919 /** 920 * @brief The processing function for DMA transactions. 921 * 922 * When using the DMA functions, the application must call this 923 * function periodically. This can be done from within the DMA Interrupt Handler. 924 * 925 * @param ch DMA channel 926 * @param error Error status 927 */ 928 void MXC_I2C_DMACallback(int ch, int error); 929 930 /**@} end of group i2c */ 931 932 #ifdef __cplusplus 933 } 934 #endif 935 936 #endif // LIBRARIES_PERIPHDRIVERS_INCLUDE_MAX32690_I2C_H_ 937
