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