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