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