MAX32655 Peripheral Driver API
Peripheral Driver API for the MAX32655
i2c.h
1 
6 /* ****************************************************************************
7  * Copyright (C) 2018 Maxim Integrated Products, Inc., All Rights Reserved.
8  *
9  * Permission is hereby granted, free of charge, to any person obtaining a
10  * copy of this software and associated documentation files (the "Software"),
11  * to deal in the Software without restriction, including without limitation
12  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
13  * and/or sell copies of the Software, and to permit persons to whom the
14  * Software is furnished to do so, subject to the following conditions:
15  *
16  * The above copyright notice and this permission notice shall be included
17  * in all copies or substantial portions of the Software.
18  *
19  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
20  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
21  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
22  * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES
23  * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
24  * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
25  * OTHER DEALINGS IN THE SOFTWARE.
26  *
27  * Except as contained in this notice, the name of Maxim Integrated
28  * Products, Inc. shall not be used except as stated in the Maxim Integrated
29  * Products, Inc. Branding Policy.
30  *
31  * The mere transfer of this software does not imply any licenses
32  * of trade secrets, proprietary technology, copyrights, patents,
33  * trademarks, maskwork rights, or any other form of intellectual
34  * property whatsoever. Maxim Integrated Products, Inc. retains all
35  * ownership rights.
36  *
37  * $Date: 2019-05-13 16:43:27 -0500 (Mon, 13 May 2019) $
38  * $Revision: 43332 $
39  *
40  *************************************************************************** */
41 
42 /* Define to prevent redundant inclusion */
43 #ifndef _MXC_I2C_H_
44 #define _MXC_I2C_H_
45 
46 #include <stdint.h>
47 #include "mxc_sys.h"
48 #include "i2c_regs.h"
49 /***** Definitions *****/
50 
51 
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
55 
62 typedef struct _i2c_req_t mxc_i2c_req_t;
76 typedef int (*mxc_i2c_getAck_t) (mxc_i2c_regs_t* i2c, unsigned char byte);
77 
87 typedef void (*mxc_i2c_complete_cb_t) (mxc_i2c_req_t* req, int result);
88 
96 typedef void (*mxc_i2c_dma_complete_cb_t) (int len, int result);
97 
106 struct _i2c_req_t {
108  unsigned int addr;
110  unsigned char* tx_buf;
111  unsigned int tx_len;
112  unsigned char* rx_buf;
115  unsigned int rx_len;
116  int restart;
123 };
131 
140 typedef enum {
155 
173  mxc_i2c_slave_event_t event, void* data);
174 
175 /***** Function Prototypes *****/
176 
177 /* ************************************************************************* */
178 /* Control/Configuration functions */
179 /* ************************************************************************* */
180 
195 int MXC_I2C_Init (mxc_i2c_regs_t* i2c, int masterMode, unsigned int slaveAddr);
196 
205 
214 int MXC_I2C_Reset (mxc_i2c_regs_t* i2c);
215 
225 int MXC_I2C_SetFrequency (mxc_i2c_regs_t* i2c, unsigned int hz);
226 
235 
249 
261 int MXC_I2C_SetClockStretching (mxc_i2c_regs_t* i2c, int enable);
262 
271 
272 /* ************************************************************************* */
273 /* Low-level functions */
274 /* ************************************************************************* */
275 
287 int MXC_I2C_Start (mxc_i2c_regs_t* i2c);
288 
296 int MXC_I2C_Stop (mxc_i2c_regs_t* i2c);
297 
313 int MXC_I2C_WriteByte (mxc_i2c_regs_t* i2c, unsigned char byte);
314 
329 int MXC_I2C_ReadByte (mxc_i2c_regs_t* i2c, unsigned char* byte, int ack);
330 
353 int MXC_I2C_ReadByteInteractive (mxc_i2c_regs_t* i2c, unsigned char* byte,
354  mxc_i2c_getAck_t getAck);
355 
373 int MXC_I2C_Write (mxc_i2c_regs_t* i2c, unsigned char* bytes, unsigned int* len);
374 
392 int MXC_I2C_Read (mxc_i2c_regs_t* i2c, unsigned char* bytes, unsigned int* len,
393  int ack);
394 
404 int MXC_I2C_ReadRXFIFO (mxc_i2c_regs_t* i2c, volatile unsigned char* bytes,
405  unsigned int len);
406 
419 int MXC_I2C_ReadRXFIFODMA (mxc_i2c_regs_t* i2c, unsigned char* bytes,
420  unsigned int len, mxc_i2c_dma_complete_cb_t callback);
421 
430 
440 int MXC_I2C_WriteTXFIFO (mxc_i2c_regs_t* i2c, volatile unsigned char* bytes,
441  unsigned int len);
442 
454 int MXC_I2C_WriteTXFIFODMA (mxc_i2c_regs_t* i2c, unsigned char* bytes,
455  unsigned int len, mxc_i2c_dma_complete_cb_t callback);
456 
465 
472 
479 
485 int MXC_I2C_GetFlags (mxc_i2c_regs_t* i2c, unsigned int *flags0, unsigned int *flags1);
486 
492 void MXC_I2C_ClearFlags (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
493 
501 void MXC_I2C_EnableInt (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
502 
510 void MXC_I2C_DisableInt (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
511 
523 
532 
541 
550 
563 void MXC_I2C_SetTimeout (mxc_i2c_regs_t* i2c, unsigned int timeout);
564 
573 
598 int MXC_I2C_Recover (mxc_i2c_regs_t* i2c, unsigned int retries);
599 
600 /* ************************************************************************* */
601 /* Transaction level functions */
602 /* ************************************************************************* */
603 
625 int MXC_I2C_MasterTransaction (mxc_i2c_req_t* req);
626 
652 int MXC_I2C_MasterTransactionAsync (mxc_i2c_req_t* req);
653 
680 int MXC_I2C_MasterTransactionDMA (mxc_i2c_req_t* req);
681 
721 
764 
786 int MXC_I2C_SetRXThreshold (mxc_i2c_regs_t* i2c, unsigned int numBytes);
787 
796 
819 int MXC_I2C_SetTXThreshold (mxc_i2c_regs_t* i2c, unsigned int numBytes);
820 
829 
840 
851 
861 void MXC_I2C_DMACallback (int ch, int error);
862 
863 
867 #ifdef __cplusplus
868 }
869 #endif
870 
871 #endif /* _MXC_I2C_H_ */
requesting a write to the slave.
Definition: i2c.h:141
int MXC_I2C_GetRXFIFOAvailable(mxc_i2c_regs_t *i2c)
Get the number of bytes currently available in the receive FIFO.
void MXC_I2C_DisableGeneralCall(mxc_i2c_regs_t *i2c)
Prevents the slave from responding to the general call address.
int(* mxc_i2c_getAck_t)(mxc_i2c_regs_t *i2c, unsigned char byte)
The callback used by the MXC_I2C_ReadByteInteractive() function.
Definition: i2c.h:76
The information required to perform a complete I2C transaction as the bus master. ...
Definition: i2c.h:106
void MXC_I2C_EnablePreload(mxc_i2c_regs_t *i2c)
Enables the slave preload mode.
void(* mxc_i2c_dma_complete_cb_t)(int len, int result)
The callback routine used by the I2C Read/Write FIFO DMA functions to indicate the transaction has co...
Definition: i2c.h:96
int MXC_I2C_SlaveTransactionAsync(mxc_i2c_regs_t *i2c, mxc_i2c_slave_handler_t callback)
Performs a non-blocking I2C slave transaction.
int MXC_I2C_WriteTXFIFODMA(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int len, mxc_i2c_dma_complete_cb_t callback)
Loads bytes into the transmit FIFO using DMA for longer writes.
void MXC_I2C_DisableInt(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)
Disable Interrupts.
void MXC_I2C_DisablePreload(mxc_i2c_regs_t *i2c)
Disable the slave preload mode.
void MXC_I2C_SetTimeout(mxc_i2c_regs_t *i2c, unsigned int timeout)
Set the I2C Timeout.
void MXC_I2C_ClearFlags(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)
Clears the Interrupt Flags.
int MXC_I2C_SetTXThreshold(mxc_i2c_regs_t *i2c, unsigned int numBytes)
Set the transmit threshold level.
int MXC_I2C_WriteByte(mxc_i2c_regs_t *i2c, unsigned char byte)
Write a single byte to the I2C bus.
int MXC_I2C_SetRXThreshold(mxc_i2c_regs_t *i2c, unsigned int numBytes)
Set the receive threshold level.
void MXC_I2C_ClearTXFIFO(mxc_i2c_regs_t *i2c)
Removes and discards all bytes currently in the transmit FIFO.
FIFO was already full.
Definition: i2c.h:152
The transaction has ended.
Definition: i2c.h:149
void MXC_I2C_AbortAsync(mxc_i2c_regs_t *i2c)
Abort any asynchronous requests in progress.
void MXC_I2C_AsyncHandler(mxc_i2c_regs_t *i2c)
The processing function for asynchronous transactions.
int MXC_I2C_GetTimeout(mxc_i2c_regs_t *i2c)
Get the current I2C timeout.
int MXC_I2C_ReadByteInteractive(mxc_i2c_regs_t *i2c, unsigned char *byte, mxc_i2c_getAck_t getAck)
Read a single byte from the I2C bus.
int MXC_I2C_Stop(mxc_i2c_regs_t *i2c)
Generate a stop condition on the I2C bus.
int MXC_I2C_GetFlags(mxc_i2c_regs_t *i2c, unsigned int *flags0, unsigned int *flags1)
Get the presently set interrupt flags.
int restart
Definition: i2c.h:118
int MXC_I2C_GetClockStretching(mxc_i2c_regs_t *i2c)
Determines if clock stretching has been enabled.
int MXC_I2C_SetClockStretching(mxc_i2c_regs_t *i2c, int enable)
Enables or disables clock stretching by the slave.
void MXC_I2C_DMACallback(int ch, int error)
The processing function for DMA transactions.
int MXC_I2C_MasterTransactionAsync(mxc_i2c_req_t *req)
Performs a non-blocking I2C master transaction.
transmit FIFO was empty.
Definition: i2c.h:150
mxc_i2c_slave_event_t
The list of events reported by the MXC_I2C_SlaveTransaction() and MXC_I2C_SlaveTransactionAsync() fun...
Definition: i2c.h:140
void MXC_I2C_EnableGeneralCall(mxc_i2c_regs_t *i2c)
Enables the slave to respond to the general call address.
int MXC_I2C_MasterTransactionDMA(mxc_i2c_req_t *req)
Performs a non-blocking I2C transaction using DMA for reduced time in the ISR.
threshold level.
Definition: i2c.h:147
int(* mxc_i2c_slave_handler_t)(mxc_i2c_regs_t *i2c, mxc_i2c_slave_event_t event, void *data)
The callback routine used by the MXC_I2C_SlaveTransaction() and MXC_I2C_SlaveTransactionAsync functio...
Definition: i2c.h:172
void MXC_I2C_ClearRXFIFO(mxc_i2c_regs_t *i2c)
Removes and discards all bytes currently in the receive FIFO.
int MXC_I2C_ReadByte(mxc_i2c_regs_t *i2c, unsigned char *byte, int ack)
Read a single byte from the I2C bus.
requesting a read from the slave.
Definition: i2c.h:143
unsigned int rx_len
Definition: i2c.h:115
int MXC_I2C_SetFrequency(mxc_i2c_regs_t *i2c, unsigned int hz)
Set the frequency of the I2C interface.
int MXC_I2C_Read(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int *len, int ack)
Read multiple bytes from the I2C bus.
int MXC_I2C_Shutdown(mxc_i2c_regs_t *i2c)
Disable and shutdown I2C peripheral.
int MXC_I2C_Init(mxc_i2c_regs_t *i2c, int masterMode, unsigned int slaveAddr)
Initialize and enable I2C peripheral.
unsigned char * tx_buf
The buffer containing the bytes to write.
Definition: i2c.h:110
Definition: i2c_regs.h:88
int MXC_I2C_Reset(mxc_i2c_regs_t *i2c)
Reset the I2C peripheral.
int MXC_I2C_GetTXThreshold(mxc_i2c_regs_t *i2c)
Get the current transmit threshold level.
unsigned int addr
The 7-bit or 10-bit address of the slave.
Definition: i2c.h:109
int MXC_I2C_ReadyForSleep(mxc_i2c_regs_t *i2c)
Checks if the given I2C bus can be placed in sleep more.
int MXC_I2C_Start(mxc_i2c_regs_t *i2c)
Generate a start (or repeated start) condition on the I2C bus.
void MXC_I2C_EnableInt(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)
Enable Interrupts.
threshold level.
Definition: i2c.h:145
mxc_i2c_regs_t * i2c
I2C block used.)
Definition: i2c.h:107
int MXC_I2C_Recover(mxc_i2c_regs_t *i2c, unsigned int retries)
Attempts to recover the I2C bus, ensuring the I2C lines are idle.
int MXC_I2C_ReadRXFIFO(mxc_i2c_regs_t *i2c, volatile unsigned char *bytes, unsigned int len)
Unloads bytes from the receive FIFO.
void(* mxc_i2c_complete_cb_t)(mxc_i2c_req_t *req, int result)
The callback routine used by the MXC_I2C_MasterTransactionAsync() function to indicate the transactio...
Definition: i2c.h:87
unsigned int tx_len
Definition: i2c.h:111
int MXC_I2C_WriteTXFIFO(mxc_i2c_regs_t *i2c, volatile unsigned char *bytes, unsigned int len)
Loads bytes into the transmit FIFO.
int MXC_I2C_SlaveTransaction(mxc_i2c_regs_t *i2c, mxc_i2c_slave_handler_t callback)
Performs a blocking I2C slave transaction.
int MXC_I2C_MasterTransaction(mxc_i2c_req_t *req)
Performs a blocking I2C master transaction.
unsigned char * rx_buf
The buffer to read the data into.
Definition: i2c.h:114
mxc_i2c_complete_cb_t callback
Definition: i2c.h:122
int MXC_I2C_GetFrequency(mxc_i2c_regs_t *i2c)
Get the frequency of the I2C interface.
int MXC_I2C_ReadRXFIFODMA(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int len, mxc_i2c_dma_complete_cb_t callback)
Unloads bytes from the receive FIFO using DMA for longer reads.
int MXC_I2C_GetRXThreshold(mxc_i2c_regs_t *i2c)
Get the current receive threshold level.
int MXC_I2C_GetTXFIFOAvailable(mxc_i2c_regs_t *i2c)
Get the amount of free space available in the transmit FIFO.
int MXC_I2C_Write(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int *len)
Write multiple bytes to the I2C bus.