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