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