MAX32675 Peripheral Driver API
Peripheral Driver API for the MAX32675
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  *************************************************************************** */
38 
39 /* Define to prevent redundant inclusion */
40 #ifndef _MXC_I2C_H_
41 #define _MXC_I2C_H_
42 
43 #include <stdint.h>
44 #include "mxc_sys.h"
45 #include "i2c_regs.h"
46 
47 #ifdef __cplusplus
48 extern "C" {
49 #endif
50 
57 typedef struct _i2c_req_t mxc_i2c_req_t;
58 
72 typedef int (*mxc_i2c_getAck_t) (mxc_i2c_regs_t* i2c, unsigned char byte);
73 
83 typedef void (*mxc_i2c_complete_cb_t) (mxc_i2c_req_t* req, int result);
84 
92 typedef void (*mxc_i2c_dma_complete_cb_t) (int len, int result);
93 
102 struct _i2c_req_t {
104  unsigned int addr;
106  unsigned char* tx_buf;
107  unsigned int tx_len;
108  unsigned char* rx_buf;
111  unsigned int rx_len;
112  int restart;
119 };
127 
136 typedef enum {
151 
169  mxc_i2c_slave_event_t event, void* data);
170 
171 /***** Function Prototypes *****/
172 
173 /* ************************************************************************* */
174 /* Control/Configuration functions */
175 /* ************************************************************************* */
176 
191 int MXC_I2C_Init (mxc_i2c_regs_t* i2c, int masterMode, unsigned int slaveAddr);
192 
205 int MXC_I2C_SetSlaveAddr(mxc_i2c_regs_t* i2c, unsigned int slaveAddr, int idx);
206 
215 
224 int MXC_I2C_Reset (mxc_i2c_regs_t* i2c);
225 
235 int MXC_I2C_SetFrequency (mxc_i2c_regs_t* i2c, unsigned int hz);
236 
244 unsigned int MXC_I2C_GetFrequency (mxc_i2c_regs_t* i2c);
245 
259 
271 int MXC_I2C_SetClockStretching (mxc_i2c_regs_t* i2c, int enable);
272 
281 
282 /* ************************************************************************* */
283 /* Low-level functions */
284 /* ************************************************************************* */
285 
297 int MXC_I2C_Start (mxc_i2c_regs_t* i2c);
298 
306 int MXC_I2C_Stop (mxc_i2c_regs_t* i2c);
307 
323 int MXC_I2C_WriteByte (mxc_i2c_regs_t* i2c, unsigned char byte);
324 
339 int MXC_I2C_ReadByte (mxc_i2c_regs_t* i2c, unsigned char* byte, int ack);
340 
363 int MXC_I2C_ReadByteInteractive (mxc_i2c_regs_t* i2c, unsigned char* byte,
364  mxc_i2c_getAck_t getAck);
365 
383 int MXC_I2C_Write (mxc_i2c_regs_t* i2c, unsigned char* bytes, unsigned int* len);
384 
402 int MXC_I2C_Read (mxc_i2c_regs_t* i2c, unsigned char* bytes, unsigned int* len,
403  int ack);
404 
414 int MXC_I2C_ReadRXFIFO (mxc_i2c_regs_t* i2c, volatile unsigned char* bytes,
415  unsigned int len);
416 
429 int MXC_I2C_ReadRXFIFODMA (mxc_i2c_regs_t* i2c, unsigned char* bytes,
430  unsigned int len, mxc_i2c_dma_complete_cb_t callback);
431 
440 
450 int MXC_I2C_WriteTXFIFO (mxc_i2c_regs_t* i2c, volatile unsigned char* bytes,
451  unsigned int len);
452 
464 int MXC_I2C_WriteTXFIFODMA (mxc_i2c_regs_t* i2c, unsigned char* bytes,
465  unsigned int len, mxc_i2c_dma_complete_cb_t callback);
466 
475 
482 
489 
499 int MXC_I2C_GetFlags (mxc_i2c_regs_t* i2c, unsigned int *flags0, unsigned int *flags1);
500 
508 void MXC_I2C_ClearFlags (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
509 
517 void MXC_I2C_EnableInt (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
518 
526 void MXC_I2C_DisableInt (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
527 
537 
544 
551 
558 
571 void MXC_I2C_SetTimeout (mxc_i2c_regs_t* i2c, unsigned int timeout);
572 
580 unsigned int MXC_I2C_GetTimeout (mxc_i2c_regs_t* i2c);
581 
606 int MXC_I2C_Recover (mxc_i2c_regs_t* i2c, unsigned int retries);
607 
608 /* ************************************************************************* */
609 /* Transaction level functions */
610 /* ************************************************************************* */
611 
633 int MXC_I2C_MasterTransaction (mxc_i2c_req_t* req);
634 
660 int MXC_I2C_MasterTransactionAsync (mxc_i2c_req_t* req);
661 
688 int MXC_I2C_MasterTransactionDMA (mxc_i2c_req_t* req);
689 
729 
772 
794 int MXC_I2C_SetRXThreshold (mxc_i2c_regs_t* i2c, unsigned int numBytes);
795 
803 unsigned int MXC_I2C_GetRXThreshold (mxc_i2c_regs_t* i2c);
804 
827 int MXC_I2C_SetTXThreshold (mxc_i2c_regs_t* i2c, unsigned int numBytes);
828 
836 unsigned int MXC_I2C_GetTXThreshold (mxc_i2c_regs_t* i2c);
837 
848 
859 
869 void MXC_I2C_DMACallback (int ch, int error);
870 
871 
875 #ifdef __cplusplus
876 }
877 #endif
878 
879 #endif /* _MXC_I2C_H_ */
MXC_I2C_GetClockStretching
int MXC_I2C_GetClockStretching(mxc_i2c_regs_t *i2c)
Determines if clock stretching has been enabled.
MXC_I2C_DMACallback
void MXC_I2C_DMACallback(int ch, int error)
The processing function for DMA transactions.
MXC_I2C_ReadRXFIFO
int MXC_I2C_ReadRXFIFO(mxc_i2c_regs_t *i2c, volatile unsigned char *bytes, unsigned int len)
Unloads bytes from the receive FIFO.
MXC_I2C_SetTimeout
void MXC_I2C_SetTimeout(mxc_i2c_regs_t *i2c, unsigned int timeout)
Set the I2C Timeout.
MXC_I2C_GetRXFIFOAvailable
int MXC_I2C_GetRXFIFOAvailable(mxc_i2c_regs_t *i2c)
Get the number of bytes currently available in the receive FIFO.
MXC_I2C_SlaveTransaction
int MXC_I2C_SlaveTransaction(mxc_i2c_regs_t *i2c, mxc_i2c_slave_handler_t callback)
Performs a blocking I2C Slave transaction.
MXC_I2C_Start
int MXC_I2C_Start(mxc_i2c_regs_t *i2c)
Generate a start (or repeated start) condition on the I2C bus.
MXC_I2C_SetClockStretching
int MXC_I2C_SetClockStretching(mxc_i2c_regs_t *i2c, int enable)
Enables or disables clock stretching by the slave.
MXC_I2C_WriteTXFIFODMA
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.
MXC_I2C_SlaveTransactionAsync
int MXC_I2C_SlaveTransactionAsync(mxc_i2c_regs_t *i2c, mxc_i2c_slave_handler_t callback)
Performs a non-blocking I2C Slave transaction.
MXC_I2C_ClearFlags
void MXC_I2C_ClearFlags(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)
Clears the Interrupt Flags.
MXC_I2C_ClearRXFIFO
void MXC_I2C_ClearRXFIFO(mxc_i2c_regs_t *i2c)
Removes and discards all bytes currently in the receive FIFO.
MXC_I2C_EVT_UNDERFLOW
@ MXC_I2C_EVT_UNDERFLOW
transmit FIFO was empty.
Definition: i2c.h:146
mxc_i2c_slave_event_t
mxc_i2c_slave_event_t
The list of events reported by the MXC_I2C_SlaveTransaction() and MXC_I2C_SlaveTransactionAsync() fun...
Definition: i2c.h:136
MXC_I2C_GetTXFIFOAvailable
int MXC_I2C_GetTXFIFOAvailable(mxc_i2c_regs_t *i2c)
Get the amount of free space available in the transmit FIFO.
MXC_I2C_DisablePreload
void MXC_I2C_DisablePreload(mxc_i2c_regs_t *i2c)
Disable the slave preload mode.
MXC_I2C_Write
int MXC_I2C_Write(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int *len)
Write multiple bytes to the I2C bus.
MXC_I2C_EnableGeneralCall
void MXC_I2C_EnableGeneralCall(mxc_i2c_regs_t *i2c)
Enables the slave to respond to the general call address.
_i2c_req_t::restart
int restart
Definition: i2c.h:114
MXC_I2C_Shutdown
int MXC_I2C_Shutdown(mxc_i2c_regs_t *i2c)
Disable and shutdown I2C peripheral.
MXC_I2C_AsyncHandler
void MXC_I2C_AsyncHandler(mxc_i2c_regs_t *i2c)
The processing function for asynchronous transactions.
MXC_I2C_DisableInt
void MXC_I2C_DisableInt(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)
Disable Interrupts.
MXC_I2C_DisableGeneralCall
void MXC_I2C_DisableGeneralCall(mxc_i2c_regs_t *i2c)
Prevents the slave from responding to the general call address.
MXC_I2C_SetTXThreshold
int MXC_I2C_SetTXThreshold(mxc_i2c_regs_t *i2c, unsigned int numBytes)
Set the transmit threshold level.
MXC_I2C_GetFrequency
unsigned int MXC_I2C_GetFrequency(mxc_i2c_regs_t *i2c)
Get the frequency of the I2C interface.
MXC_I2C_EnableInt
void MXC_I2C_EnableInt(mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)
Enable Interrupts.
MXC_I2C_EVT_RX_THRESH
@ MXC_I2C_EVT_RX_THRESH
threshold level.
Definition: i2c.h:141
MXC_I2C_ReadByteInteractive
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.
mxc_i2c_slave_handler_t
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:168
MXC_I2C_MasterTransactionAsync
int MXC_I2C_MasterTransactionAsync(mxc_i2c_req_t *req)
Performs a non-blocking I2C Master transaction.
MXC_I2C_ReadyForSleep
int MXC_I2C_ReadyForSleep(mxc_i2c_regs_t *i2c)
Checks if the given I2C bus can be placed in sleep more.
MXC_I2C_EVT_OVERFLOW
@ MXC_I2C_EVT_OVERFLOW
FIFO was already full.
Definition: i2c.h:148
_i2c_req_t
The information required to perform a complete I2C transaction as the bus master.
Definition: i2c.h:102
MXC_I2C_GetFlags
int MXC_I2C_GetFlags(mxc_i2c_regs_t *i2c, unsigned int *flags0, unsigned int *flags1)
Get the presently set interrupt flags.
MXC_I2C_Recover
int MXC_I2C_Recover(mxc_i2c_regs_t *i2c, unsigned int retries)
Attempts to recover the I2C bus, ensuring the I2C lines are idle.
MXC_I2C_EVT_MASTER_WR
@ MXC_I2C_EVT_MASTER_WR
requesting a write to the slave.
Definition: i2c.h:137
_i2c_req_t::tx_buf
unsigned char * tx_buf
The buffer containing the bytes to write.
Definition: i2c.h:106
_i2c_req_t::addr
unsigned int addr
The 7-bit or 10-bit address of the slave.
Definition: i2c.h:105
MXC_I2C_ReadByte
int MXC_I2C_ReadByte(mxc_i2c_regs_t *i2c, unsigned char *byte, int ack)
Read a single byte from the I2C bus.
_i2c_req_t::rx_len
unsigned int rx_len
Definition: i2c.h:111
MXC_I2C_Init
int MXC_I2C_Init(mxc_i2c_regs_t *i2c, int masterMode, unsigned int slaveAddr)
Initialize and enable I2C peripheral.
MXC_I2C_WriteTXFIFO
int MXC_I2C_WriteTXFIFO(mxc_i2c_regs_t *i2c, volatile unsigned char *bytes, unsigned int len)
Loads bytes into the transmit FIFO.
MXC_I2C_ReadRXFIFODMA
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.
MXC_I2C_GetRXThreshold
unsigned int MXC_I2C_GetRXThreshold(mxc_i2c_regs_t *i2c)
Get the current receive threshold level.
MXC_I2C_MasterTransaction
int MXC_I2C_MasterTransaction(mxc_i2c_req_t *req)
Performs a blocking I2C Master transaction.
MXC_I2C_Reset
int MXC_I2C_Reset(mxc_i2c_regs_t *i2c)
Reset the I2C peripheral.
MXC_I2C_Stop
int MXC_I2C_Stop(mxc_i2c_regs_t *i2c)
Generate a stop condition on the I2C bus.
_i2c_req_t::i2c
mxc_i2c_regs_t * i2c
I2C block used.)
Definition: i2c.h:103
MXC_I2C_MasterTransactionDMA
int MXC_I2C_MasterTransactionDMA(mxc_i2c_req_t *req)
Performs a non-blocking I2C Master transaction using DMA for reduced time in the ISR.
MXC_I2C_SetFrequency
int MXC_I2C_SetFrequency(mxc_i2c_regs_t *i2c, unsigned int hz)
Set the frequency of the I2C interface.
MXC_I2C_EnablePreload
void MXC_I2C_EnablePreload(mxc_i2c_regs_t *i2c)
Enables the slave preload mode.
mxc_i2c_complete_cb_t
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:83
mxc_i2c_dma_complete_cb_t
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:92
MXC_I2C_SetSlaveAddr
int MXC_I2C_SetSlaveAddr(mxc_i2c_regs_t *i2c, unsigned int slaveAddr, int idx)
Initialize and enable I2C peripheral.
_i2c_req_t::callback
mxc_i2c_complete_cb_t callback
Definition: i2c.h:118
MXC_I2C_EVT_TX_THRESH
@ MXC_I2C_EVT_TX_THRESH
threshold level.
Definition: i2c.h:143
_i2c_req_t::tx_len
unsigned int tx_len
Definition: i2c.h:107
mxc_i2c_getAck_t
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:72
_i2c_req_t::rx_buf
unsigned char * rx_buf
The buffer to read the data into.
Definition: i2c.h:110
mxc_i2c_regs_t
Definition: i2c_regs.h:88
MXC_I2C_SetRXThreshold
int MXC_I2C_SetRXThreshold(mxc_i2c_regs_t *i2c, unsigned int numBytes)
Set the receive threshold level.
MXC_I2C_EVT_MASTER_RD
@ MXC_I2C_EVT_MASTER_RD
requesting a read from the slave.
Definition: i2c.h:139
MXC_I2C_ClearTXFIFO
void MXC_I2C_ClearTXFIFO(mxc_i2c_regs_t *i2c)
Removes and discards all bytes currently in the transmit FIFO.
MXC_I2C_Read
int MXC_I2C_Read(mxc_i2c_regs_t *i2c, unsigned char *bytes, unsigned int *len, int ack)
Read multiple bytes from the I2C bus.
MXC_I2C_GetTXThreshold
unsigned int MXC_I2C_GetTXThreshold(mxc_i2c_regs_t *i2c)
Get the current transmit threshold level.
MXC_I2C_EVT_TRANS_COMP
@ MXC_I2C_EVT_TRANS_COMP
The transaction has ended.
Definition: i2c.h:145
MXC_I2C_GetTimeout
unsigned int MXC_I2C_GetTimeout(mxc_i2c_regs_t *i2c)
Get the current I2C timeout.
MXC_I2C_AbortAsync
void MXC_I2C_AbortAsync(mxc_i2c_regs_t *i2c)
Abort any asynchronous requests in progress.
MXC_I2C_WriteByte
int MXC_I2C_WriteByte(mxc_i2c_regs_t *i2c, unsigned char byte)
Write a single byte to the I2C bus.