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