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