MAX32665 Peripheral Driver API
Peripheral Driver API for the MAX32665
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 
201 
211 
221 int MXC_I2C_SetFrequency (mxc_i2c_regs_t* i2c, unsigned int hz);
222 
231 
245 
258 
267 
268 /* ************************************************************************* */
269 /* Low-level functions */
270 /* ************************************************************************* */
271 
284 
293 
309 int MXC_I2C_WriteByte (mxc_i2c_regs_t* i2c, unsigned char byte);
310 
325 int MXC_I2C_ReadByte (mxc_i2c_regs_t* i2c, unsigned char* byte, int ack);
326 
349 int MXC_I2C_ReadByteInteractive (mxc_i2c_regs_t* i2c, unsigned char* byte,
350  mxc_i2c_getAck_t getAck);
351 
369 int MXC_I2C_Write (mxc_i2c_regs_t* i2c, unsigned char* bytes, unsigned int* len);
370 
388 int MXC_I2C_Read (mxc_i2c_regs_t* i2c, unsigned char* bytes, unsigned int* len,
389  int ack);
390 
400 int MXC_I2C_ReadRXFIFO (mxc_i2c_regs_t* i2c, volatile unsigned char* bytes,
401  unsigned int len);
402 
415 int MXC_I2C_ReadRXFIFODMA (mxc_i2c_regs_t* i2c, unsigned char* bytes,
416  unsigned int len, mxc_i2c_dma_complete_cb_t callback);
417 
426 
436 int MXC_I2C_WriteTXFIFO (mxc_i2c_regs_t* i2c, volatile unsigned char* bytes,
437  unsigned int len);
438 
450 int MXC_I2C_WriteTXFIFODMA (mxc_i2c_regs_t* i2c, unsigned char* bytes,
451  unsigned int len, mxc_i2c_dma_complete_cb_t callback);
452 
461 
468 
475 
485 int MXC_I2C_GetFlags (mxc_i2c_regs_t* i2c, unsigned int *flags0, unsigned int *flags1);
486 
494 void MXC_I2C_ClearFlags (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
495 
503 void MXC_I2C_EnableInt (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
504 
512 void MXC_I2C_DisableInt (mxc_i2c_regs_t* i2c, unsigned int flags0, unsigned int flags1);
513 
523 
530 
537 
544 
555 void MXC_I2C_SetTimeout (mxc_i2c_regs_t* i2c, unsigned int timeout);
556 
564 unsigned int MXC_I2C_GetTimeout (mxc_i2c_regs_t* i2c);
565 
590 int MXC_I2C_Recover (mxc_i2c_regs_t* i2c, unsigned int retries);
591 
592 /* ************************************************************************* */
593 /* Transaction level functions */
594 /* ************************************************************************* */
595 
617 int MXC_I2C_MasterTransaction (mxc_i2c_req_t* req);
618 
644 int MXC_I2C_MasterTransactionAsync (mxc_i2c_req_t* req);
645 
672 int MXC_I2C_MasterTransactionDMA (mxc_i2c_req_t* req);
673 
713 
756 
778 int MXC_I2C_SetRXThreshold (mxc_i2c_regs_t* i2c, unsigned int numBytes);
779 
788 
811 int MXC_I2C_SetTXThreshold (mxc_i2c_regs_t* i2c, unsigned int numBytes);
812 
821 
832 
843 
853 void MXC_I2C_DMACallback (int ch, int error);
854 
855 int MXC_I2C_SetSlaveAddr (mxc_i2c_regs_t* i2c, unsigned int slaveAddr, int idx);
856 
857 
861 #ifdef __cplusplus
862 }
863 #endif
864 
865 #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
_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.