Modules
	I2C_Registers

Data Structures
struct	mxc_i2c_req_t

Typedefs
typedef int(*	mxc_i2c_getAck_t) (mxc_i2c_regs_t *i2c, unsigned char byte)

typedef void(*	mxc_i2c_complete_cb_t) (mxc_i2c_req_t *req, int result)

typedef void(*	mxc_i2c_dma_complete_cb_t) (int len, int result)

typedef int(*	mxc_i2c_slave_handler_t) (mxc_i2c_regs_t i2c, mxc_i2c_slave_event_t event, void data)

Enumerations
enum	mxc_i2c_slave_event_t

Functions
int	MXC_I2C_Init (mxc_i2c_regs_t *i2c, int masterMode, unsigned int slaveAddr)

int	MXC_I2C_SetSlaveAddr (mxc_i2c_regs_t *i2c, unsigned int slaveAddr, int idx)

int	MXC_I2C_Shutdown (mxc_i2c_regs_t *i2c)

int	MXC_I2C_SetFrequency (mxc_i2c_regs_t *i2c, unsigned int hz)

unsigned int	MXC_I2C_GetFrequency (mxc_i2c_regs_t *i2c)

int	MXC_I2C_ReadyForSleep (mxc_i2c_regs_t *i2c)

int	MXC_I2C_SetClockStretching (mxc_i2c_regs_t *i2c, int enable)

int	MXC_I2C_GetClockStretching (mxc_i2c_regs_t *i2c)

int	MXC_I2C_DMA_Init (mxc_i2c_regs_t i2c, mxc_dma_regs_t dma, bool use_dma_tx, bool use_dma_rx)

int	MXC_I2C_DMA_GetTXChannel (mxc_i2c_regs_t *i2c)

int	MXC_I2C_DMA_GetRXChannel (mxc_i2c_regs_t *i2c)

int	MXC_I2C_DMA_SetRequestSelect (mxc_i2c_regs_t i2c, uint8_t txData, uint8_t *rxData)

int	MXC_I2C_Start (mxc_i2c_regs_t *i2c)

int	MXC_I2C_Stop (mxc_i2c_regs_t *i2c)

int	MXC_I2C_WriteByte (mxc_i2c_regs_t *i2c, unsigned char byte)

int	MXC_I2C_ReadByte (mxc_i2c_regs_t i2c, unsigned char byte, int ack)

int	MXC_I2C_ReadByteInteractive (mxc_i2c_regs_t i2c, unsigned char byte, mxc_i2c_getAck_t getAck)

int	MXC_I2C_Write (mxc_i2c_regs_t i2c, unsigned char bytes, unsigned int *len)

int	MXC_I2C_Read (mxc_i2c_regs_t i2c, unsigned char bytes, unsigned int *len, int ack)

int	MXC_I2C_ReadRXFIFO (mxc_i2c_regs_t i2c, volatile unsigned char bytes, unsigned int len)

int	MXC_I2C_ReadRXFIFODMA (mxc_i2c_regs_t i2c, unsigned char bytes, unsigned int len, mxc_i2c_dma_complete_cb_t callback)

int	MXC_I2C_GetRXFIFOAvailable (mxc_i2c_regs_t *i2c)

int	MXC_I2C_WriteTXFIFO (mxc_i2c_regs_t i2c, volatile unsigned char bytes, unsigned int len)

int	MXC_I2C_WriteTXFIFODMA (mxc_i2c_regs_t i2c, unsigned char bytes, unsigned int len, mxc_i2c_dma_complete_cb_t callback)

int	MXC_I2C_GetTXFIFOAvailable (mxc_i2c_regs_t *i2c)

void	MXC_I2C_ClearRXFIFO (mxc_i2c_regs_t *i2c)

void	MXC_I2C_ClearTXFIFO (mxc_i2c_regs_t *i2c)

int	MXC_I2C_GetFlags (mxc_i2c_regs_t i2c, unsigned int flags0, unsigned int *flags1)

void	MXC_I2C_ClearFlags (mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)

void	MXC_I2C_EnableInt (mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)

void	MXC_I2C_DisableInt (mxc_i2c_regs_t *i2c, unsigned int flags0, unsigned int flags1)

void	MXC_I2C_EnablePreload (mxc_i2c_regs_t *i2c)

void	MXC_I2C_DisablePreload (mxc_i2c_regs_t *i2c)

void	MXC_I2C_EnableGeneralCall (mxc_i2c_regs_t *i2c)

void	MXC_I2C_DisableGeneralCall (mxc_i2c_regs_t *i2c)

void	MXC_I2C_SetTimeout (mxc_i2c_regs_t *i2c, unsigned int timeout)

unsigned int	MXC_I2C_GetTimeout (mxc_i2c_regs_t *i2c)

int	MXC_I2C_Recover (mxc_i2c_regs_t *i2c, unsigned int retries)

int	MXC_I2C_MasterTransaction (mxc_i2c_req_t *req)

int	MXC_I2C_MasterTransactionAsync (mxc_i2c_req_t *req)

int	MXC_I2C_MasterTransactionDMA (mxc_i2c_req_t *req)

int	MXC_I2C_SlaveTransaction (mxc_i2c_regs_t *i2c, mxc_i2c_slave_handler_t callback)

int	MXC_I2C_SlaveTransactionAsync (mxc_i2c_regs_t *i2c, mxc_i2c_slave_handler_t callback)

int	MXC_I2C_SetRXThreshold (mxc_i2c_regs_t *i2c, unsigned int numBytes)

unsigned int	MXC_I2C_GetRXThreshold (mxc_i2c_regs_t *i2c)

int	MXC_I2C_SetTXThreshold (mxc_i2c_regs_t *i2c, unsigned int numBytes)

unsigned int	MXC_I2C_GetTXThreshold (mxc_i2c_regs_t *i2c)

void	MXC_I2C_AsyncStop (mxc_i2c_regs_t *i2c)

void	MXC_I2C_AbortAsync (mxc_i2c_regs_t *i2c)

void	MXC_I2C_AsyncHandler (mxc_i2c_regs_t *i2c)

void	MXC_I2C_DMACallback (int ch, int error)

Detailed Description

Data Structure Documentation

◆ _i2c_req_t

struct _i2c_req_t

The information required to perform a complete I2C transaction as the bus master.

The information required to perform a complete I2C transaction as the bus master. This structure is used by the MXC_I2C_MasterTransaction() and MXC_I2C_MasterTransactionAsync() functions.

Data Fields
mxc_i2c_regs_t *	i2c

unsigned int	addr

unsigned char *	tx_buf

unsigned int	tx_len

unsigned char *	rx_buf

unsigned int	rx_len

int	restart

mxc_i2c_complete_cb_t	callback

Field Documentation

◆ callback

mxc_i2c_complete_cb_t callback

The callback used to indicate the transaction is complete or an error has occurred. This field may be set to NULL if no indication is necessary. This field is only used by the MXC_I2C_MasterTransactionAsync() function. MXC_I2C_MasterTransaction() ignores the callback field.

◆ i2c

mxc_i2c_regs_t* i2c

I2C block used.)

Pointer to I2C registers (selects the

◆ restart

int restart

Controls whether the transaction is terminated with a stop or repeated start condition. Use 0 for a stop, non-zero for repeated start.

◆ rx_len

unsigned int rx_len

The number of bytes to read. On return from the function, this will be set to the number of bytes actually received.

◆ tx_len

unsigned int tx_len

The number of bytes to write. On return from the function, this will be set to the number of bytes actually transmitted.

Typedef Documentation

◆ mxc_i2c_complete_cb_t

typedef 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 transaction has completed.

Parameters

req	The details of the transaction.
result	0 if all bytes are acknowledged, 1 if any byte transmitted is not acknowledged, negative if error. See Error Codes for the list of error codes.

◆ mxc_i2c_dma_complete_cb_t

typedef 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 completed.

Parameters

len	The length of data actually read/written
result	See Error Codes for the list of error codes.

◆ mxc_i2c_getAck_t

typedef int(* mxc_i2c_getAck_t) (mxc_i2c_regs_t *i2c, unsigned char byte)

The callback used by the MXC_I2C_ReadByteInteractive() function.

The callback routine used by the MXC_I2C_ReadByteInteractive() function. This function allows the application to determine whether the byte received should be acknowledged or not.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
byte	The byte received.

Returns: 0 if the byte should not be acknowledged (NACK), non-zero to acknowledge the byte.

◆ mxc_i2c_slave_handler_t

typedef 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 functions to handle the various I2C slave events.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
event	The event that occurred to trigger this callback.
data	This field is used to pass Success/Fail for the MXC_I2C_EVT_TRANS_COMP event.

Returns: The return value is only used in the case of an MXC_I2C_EVT_RX_THRESH event. In this case, the return specifies if the last byte received should be acknowledged or not. Return 0 to acknowledge, non-zero to not acknowledge. The return value is ignored for all other event types.

Enumeration Type Documentation

◆ mxc_i2c_slave_event_t

enum mxc_i2c_slave_event_t

The list of events reported by the MXC_I2C_SlaveTransaction() and MXC_I2C_SlaveTransactionAsync() functions.

The list of events reported by the MXC_I2C_SlaveTransaction() and MXC_I2C_SlaveTransactionAsync() functions. It is up to the calling application to handle these events.

Enumerator
MXC_I2C_EVT_MASTER_WR	requesting a write to the slave. A slave address match occurred with the master
MXC_I2C_EVT_MASTER_RD	requesting a read from the slave. A slave address match occurred with the master
MXC_I2C_EVT_RX_THRESH	threshold level. The receive FIFO contains more bytes than its
MXC_I2C_EVT_TX_THRESH	threshold level. The transmit FIFO contains fewer bytes than its
MXC_I2C_EVT_TRANS_COMP	The transaction has ended.
MXC_I2C_EVT_UNDERFLOW	transmit FIFO was empty. The master has attempted a read when the
MXC_I2C_EVT_OVERFLOW	FIFO was already full. The master has written data when the receive

Function Documentation

◆ MXC_I2C_AbortAsync()

void MXC_I2C_AbortAsync ( mxc_i2c_regs_t * i2c )

Abort any asynchronous requests in progress.

Abort any asynchronous requests in progress. Any callbacks associated with the active transaction will be executed to indicate when the transaction has been terminated.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_AsyncHandler()

void MXC_I2C_AsyncHandler ( mxc_i2c_regs_t * i2c )

The processing function for asynchronous transactions.

When using the asynchronous functions, the application must call this function periodically. This can be done from within the I2C interrupt handler or periodically by the application if I2C interrupts are disabled.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_AsyncStop()

void MXC_I2C_AsyncStop ( mxc_i2c_regs_t * i2c )

Stop any asynchronous requests in progress.

Stop any asynchronous requests in progress. Any callbacks associated with the active transaction will be NOT executed.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_ClearFlags()

void MXC_I2C_ClearFlags	(	mxc_i2c_regs_t *	i2c,
		unsigned int	flags0,
		unsigned int	flags1
	)

Clears the Interrupt Flags.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
flags0	Flags to clear in the intfl0 interrupt register.
flags1	Flags to clear in the intfl1 interrupt register.

◆ MXC_I2C_ClearRXFIFO()

void MXC_I2C_ClearRXFIFO ( mxc_i2c_regs_t * i2c )

Removes and discards all bytes currently in the receive FIFO.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_ClearTXFIFO()

void MXC_I2C_ClearTXFIFO ( mxc_i2c_regs_t * i2c )

Removes and discards all bytes currently in the transmit FIFO.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_DisableGeneralCall()

void MXC_I2C_DisableGeneralCall ( mxc_i2c_regs_t * i2c )

Prevents the slave from responding to the general call address.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_DisableInt()

void MXC_I2C_DisableInt	(	mxc_i2c_regs_t *	i2c,
		unsigned int	flags0,
		unsigned int	flags1
	)

Disable Interrupts.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
flags0	Interrupts to be disabled in int->en0
flags1	Interrupts to be disabled in int->en1

◆ MXC_I2C_DisablePreload()

void MXC_I2C_DisablePreload ( mxc_i2c_regs_t * i2c )

Disable the slave preload mode.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_DMA_GetRXChannel()

int MXC_I2C_DMA_GetRXChannel ( mxc_i2c_regs_t * i2c )

Retreive the DMA RX Channel associated with I2C instance.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used).

Returns: If successful, the DMA RX Channel number is returned. Otherwise, see Error Codes for a list of return codes.

◆ MXC_I2C_DMA_GetTXChannel()

int MXC_I2C_DMA_GetTXChannel ( mxc_i2c_regs_t * i2c )

Retreive the DMA TX Channel associated with I2C instance.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used).

Returns: If successful, the DMA TX Channel number is returned. Otherwise, see Error Codes for a list of return codes.

◆ MXC_I2C_DMA_Init()

int MXC_I2C_DMA_Init	(	mxc_i2c_regs_t *	i2c,
		mxc_dma_regs_t *	dma,
		bool	use_dma_tx,
		bool	use_dma_rx
	)

Initializes the DMA for I2C DMA transactions.

This function will release any acquired DMA channels before reacquiring and reconfiguring selected I2C DMA TX or RX channels.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used).
dma	Pointer to DMA registers (selects the DMA block used).
use_dma_tx	If true, acquire and configure DMA TX channel, else release any acquired DMA TX channel.
use_dma_rx	If true, acquire and configure DMA RX channel, else release any acquired DMA RX channel.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_DMA_SetRequestSelect()

int MXC_I2C_DMA_SetRequestSelect	(	mxc_i2c_regs_t *	i2c,
		uint8_t *	txData,
		uint8_t *	rxData
	)

Sets the I2C instance's DMA TX/RX request select.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used).
txData	Pointer to transmit buffer.
rxData	Pointer to receive buffer.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_DMACallback()

void MXC_I2C_DMACallback	(	int	ch,
		int	error
	)

The processing function for DMA transactions.

When using the DMA functions, the application must call this function periodically. This can be done from within the DMA Interrupt Handler.

Parameters

ch	DMA channel
error	Error status

◆ MXC_I2C_EnableGeneralCall()

void MXC_I2C_EnableGeneralCall ( mxc_i2c_regs_t * i2c )

Enables the slave to respond to the general call address.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_EnableInt()

void MXC_I2C_EnableInt	(	mxc_i2c_regs_t *	i2c,
		unsigned int	flags0,
		unsigned int	flags1
	)

Enable Interrupts.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
flags0	Interrupts to be enabled in int->en0
flags1	Interrupts to be enabled in int->en1

◆ MXC_I2C_EnablePreload()

void MXC_I2C_EnablePreload ( mxc_i2c_regs_t * i2c )

Enables the slave preload mode.

Use this mode to preload the slave TX FIFO with data that can be sent when the slave is addressed for a read operation without software intervention.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

◆ MXC_I2C_GetClockStretching()

int MXC_I2C_GetClockStretching ( mxc_i2c_regs_t * i2c )

Determines if clock stretching has been enabled.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: Zero if clock stretching is disabled, non-zero otherwise

◆ MXC_I2C_GetFlags()

int MXC_I2C_GetFlags	(	mxc_i2c_regs_t *	i2c,
		unsigned int *	flags0,
		unsigned int *	flags1
	)

Get the presently set interrupt flags.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
flags0	Pointer to the variable to store the current status of the interrupt flags in intfl0.
flags1	Pointer to the variable to store the current status of the interrupt flags in intfl0.

Returns: See Error Codes for a list of return values

◆ MXC_I2C_GetFrequency()

unsigned int MXC_I2C_GetFrequency ( mxc_i2c_regs_t * i2c )

Get the frequency of the I2C interface.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: The I2C bus frequency in Hertz

◆ MXC_I2C_GetRXFIFOAvailable()

int MXC_I2C_GetRXFIFOAvailable ( mxc_i2c_regs_t * i2c )

Get the number of bytes currently available in the receive FIFO.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: The number of bytes available.

◆ MXC_I2C_GetRXThreshold()

unsigned int MXC_I2C_GetRXThreshold ( mxc_i2c_regs_t * i2c )

Get the current receive threshold level.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: The receive threshold value (in bytes).

◆ MXC_I2C_GetTimeout()

unsigned int MXC_I2C_GetTimeout ( mxc_i2c_regs_t * i2c )

Get the current I2C timeout.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: The current timeout in uS

◆ MXC_I2C_GetTXFIFOAvailable()

int MXC_I2C_GetTXFIFOAvailable ( mxc_i2c_regs_t * i2c )

Get the amount of free space available in the transmit FIFO.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: The number of bytes available.

◆ MXC_I2C_GetTXThreshold()

unsigned int MXC_I2C_GetTXThreshold ( mxc_i2c_regs_t * i2c )

Get the current transmit threshold level.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: The transmit threshold value (in bytes).

◆ MXC_I2C_Init()

int MXC_I2C_Init	(	mxc_i2c_regs_t *	i2c,
		int	masterMode,
		unsigned int	slaveAddr
	)

Initialize and enable I2C peripheral.

Note: On default this function enables I2C peripheral clock and i2c gpio pins. if you wish to manage clock and gpio related things in upper level instead of here. Define MSDK_NO_GPIO_CLK_INIT flag in project.mk file. By this flag this function will remove clock and gpio related codes from file.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
masterMode	Whether to put the device in master or slave mode. Use non-zero for master mode, and zero for slave mode.
slaveAddr	7-bit or 10-bit address to use when in slave mode. This parameter is ignored when masterMode is non-zero.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_MasterTransaction()

int MXC_I2C_MasterTransaction ( mxc_i2c_req_t * req )

Performs a blocking I2C Master transaction.

Performs a blocking I2C transaction. These actions will be performed:

If necessary, generate a start condition on the bus.
Send the slave address with the low bit set to 0 (indicating a write).
Transmit req->tx_len bytes of req->tx_buff.
Generate a repeated start condition on the bus.
Send the slave address with the low bit set to 1 (indicating a read).
Receive req->rx_len bytes into req->rx_buf, acknowledging each byte.
Generate a stop (or repeated start) condition on the bus. Steps 3-6 will be skipped if req->tx_len and req->rx_len are both 0. Steps 2-4 will be skipped if req->tx_len equals 0. Steps 4-6 will be skipped if req->rx_len equals 0.

Parameters

req	Pointer to details of the transaction

Returns: 0 if all bytes are acknowledged, 1 if any byte transmitted is not acknowledged, negative if error. See Error Codes for the list of error return codes.

◆ MXC_I2C_MasterTransactionAsync()

int MXC_I2C_MasterTransactionAsync ( mxc_i2c_req_t * req )

Performs a non-blocking I2C Master transaction.

Performs a non-blocking I2C transaction. These actions will be performed:

If necessary, generate a start condition on the bus.
Send the slave address with the low bit set to 0 (indicating a write).
Transmit req->tx_len bytes of req->tx_buff.
Generate a repeated start condition on the bus.
Send the slave address with the low bit set to 1 (indicating a read).
Receive req->rx_len bytes into req->rx_buf, acknowledging each byte.
Generate a stop (or repeated start) condition on the bus.
Execute req->callback to indicate the transaction is complete. Steps 3-6 will be skipped if tx_len and rx_len are both 0. Steps 2-4 will be skipped if tx_len equals 0. Steps 4-6 will be skipped if rx_len equals 0.

Note: MXC_I2C_AsyncHandler() must be called periodically for this function to operate properly. Ideally from the I2C ISR.

Parameters

req	Pointer to details of the transaction. The memory used by this parameter must remain available until the callback is executed.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ 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. This function initializes the DMA and acquires DMA channels if MXC_I2C_DMA_Init(...) was not called earlier.

It is recommended to initialize the DMA by calling MXC_I2C_DMA_Init(...) function before calling MXC_I2C_MasterTransactionDMA(...). This provides flexibility in setting up generic DMA channel vectors during run-time without knowing what DMA channels will be acquired beforehand.

Performs a non-blocking I2C transaction. These actions will be performed:

If necessary, generate a start condition on the bus.
Send the slave address with the low bit set to 0 (indicating a write).
Transmit req->tx_len bytes of req->tx_buff.
Generate a repeated start condition on the bus.
Send the slave address with the low bit set to 1 (indicating a read).
Receive req->rx_len bytes into req->rx_buf, acknowledging each byte.
Generate a stop (or repeated start) condition on the bus.
Execute req->callback to indicate the transaction is complete. Steps 3-6 will be skipped if tx_len and rx_len are both 0. Steps 2-4 will be skipped if tx_len equals 0. Steps 4-6 will be skipped if rx_len equals 0.

Note: MXC_I2C_AsyncHandler() must be called periodically for this function to operate properly. Ideally from the I2C ISR.

Parameters

req	Pointer to details of the transaction. The memory used by this parameter must remain available until the callback is executed.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ 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.

Read multiple byte from the I2C bus. This function assumes the I2C bus is already in the proper state (i.e. a start condition has already been generated and the bus is in the read phase of an I2C transaction).

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
bytes	The buffer to read the data into.
len	The number of bytes to read. On return from the function, this will be set to the number of bytes actually received.
ack	Whether or not to acknowledge the last byte once it is received. All previous bytes will be acknowledged.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ 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.

Read a single byte from the I2C bus. This function assumes the I2C bus is already in the proper state (i.e. a start condition has already been generated and the bus is in the read phase of an I2C transaction). If the FIFO is empty, this function will return E_UNDERFLOW.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
byte	Pointer to the byte to read into.
ack	Whether or not to acknowledge the byte once received.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ 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.

Read a single byte from the I2C bus. After the byte is received, the provided callback will be used to determine if the byte should be acknowledged or not before continuing with the rest of the transaction. This function assumes the I2C bus is already in the proper state (i.e. a start condition has already been generated and the bus is in the read phase of an I2C transaction). This function must be called with clock stretching enabled.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
byte	Pointer to the byte to read into.
getAck	A function to be called to determine whether or not to acknowledge the byte once received. A non-zero return value will acknowledge the byte. If this parameter is set to NULL or its return value is 0, the byte received will not be acknowledged (i.e., it will be NACKed).

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ 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.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
bytes	The buffer to read the data into.
len	The number of bytes to read.

Returns: The number of bytes actually read.

◆ 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.

Note: The operation is not complete until the callback has been called

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
bytes	The buffer to read the data into.
len	The number of bytes to read.
callback	The function to call when the read is complete

Returns: See Error Codes for a list of return values.

◆ MXC_I2C_ReadyForSleep()

int MXC_I2C_ReadyForSleep ( mxc_i2c_regs_t * i2c )

Checks if the given I2C bus can be placed in sleep more.

This functions checks to see if there are any on-going I2C transactions in progress. If there are transactions in progress, the application should wait until the I2C bus is free before entering a low-power state.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: E_NO_ERROR if ready, and non-zero if busy or error. See Error Codes for the list of error return codes.

◆ 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.

Attempts to recover and reset an I2C bus by sending I2C clocks. During each clock cycle, the SDA line is cycled to determine if the master has control of the line. The following steps are performed to create one SCL clock cycle:

Drive SCL low
Verify SCL is low
Drive SDA low
Verify SDA is low
Release SDA allowing it to return high
Verify SDA is high
Release SCL allowing it to return high.
Verify SCL is high If any of the steps fail, the bus is considered to still be busy and the sequence is repeated up to the requested number of times. If all steps succeed, a final stop condition is generated on the I2C bus.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
retries	Number of times to attempt the clock cycle sequence.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_SetClockStretching()

int MXC_I2C_SetClockStretching	(	mxc_i2c_regs_t *	i2c,
		int	enable
	)

Enables or disables clock stretching by the slave.

Enables or disables clock stretching by the slave. This function has no affect when operating as the master.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
enable	Enables clock stretching if non-zero, disables if zero.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_SetFrequency()

int MXC_I2C_SetFrequency	(	mxc_i2c_regs_t *	i2c,
		unsigned int	hz
	)

Set the frequency of the I2C interface.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
hz	The desired frequency in Hertz.

Returns: Negative if error, otherwise actual speed set. See Error Codes for the list of error return codes.

◆ MXC_I2C_SetRXThreshold()

int MXC_I2C_SetRXThreshold	(	mxc_i2c_regs_t *	i2c,
		unsigned int	numBytes
	)

Set the receive threshold level.

When operating as a master, the function sets the receive threshold level for when the master should unload the receive FIFO. Smaller values may consume more CPU cycles, but decrease the chances of the master delaying the generation of I2C bus clocks because it has no room in the FIFO to receive data. Larger values may consume fewer CPU cycles, but risk delays of the I2C clock. When operating as a slave, this function sets the number of bytes the slave transaction functions should receive before issuing a call to their callback function. Smaller values may consume more CPU cycles, but reduce the risk of missing data from the master due to the recieve FIFO being full. Larger values may reduce the number of CPU cycles, but may cause bytes sent from the master to be missed.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
numBytes	The threshold level to set. This value must be between 0 and 8 inclusive.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_SetSlaveAddr()

int MXC_I2C_SetSlaveAddr	(	mxc_i2c_regs_t *	i2c,
		unsigned int	slaveAddr,
		int	idx
	)

Set slave address for I2C instances acting as slaves on the bus.

Note: Set idx to zero, multiple I2C instances acting as slaves on the bus is not yet supported.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
slaveAddr	7-bit or 10-bit address to use when in slave mode. This parameter is ignored when masterMode is non-zero.
idx	Index of the I2C slave.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_SetTimeout()

void MXC_I2C_SetTimeout	(	mxc_i2c_regs_t *	i2c,
		unsigned int	timeout
	)

Set the I2C Timeout.

The I2C timeout determines the amount of time the master will wait while the slave is stretching the clock, and the amount of time the slave will stretch the clock while waiting for software to unload the fifo.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
timeout	Timeout in uS

◆ MXC_I2C_SetTXThreshold()

int MXC_I2C_SetTXThreshold	(	mxc_i2c_regs_t *	i2c,
		unsigned int	numBytes
	)

Set the transmit threshold level.

When operating as a master, the function sets the transmit threshold level for when the master should add additional bytes to the transmit FIFO. Larger values may consume more CPU cycles, but decrease the chances of the master delaying the generation of I2C bus clocks because it has no data in the FIFO to transmit. Smaller values may consume fewer CPU cycles, but risk delays of the I2C clock. When operating as a slave, this function sets the number of bytes the slave transaction functions should transmit before issuing a call to their callback function. Larger values may consume more CPU cycles, but reduce the risk of not having data ready when the master requests it. Smaller values may reduce the number of CPU cycles, but may cause the master to read from an empty FIFO. (The master will read 0xFF in this case.)

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
numBytes	The threshold level to set. This value must be between 0 and 8 inclusive.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_Shutdown()

int MXC_I2C_Shutdown ( mxc_i2c_regs_t * i2c )

Disable and shutdown I2C peripheral.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_SlaveTransaction()

int MXC_I2C_SlaveTransaction	(	mxc_i2c_regs_t *	i2c,
		mxc_i2c_slave_handler_t	callback
	)

Performs a blocking I2C Slave transaction.

Performs a blocking I2C transaction. This function will block until a complete transaction with this slave has been performed. A transaction begins with the master addressing the slave and ends with a repeated start condition, a stop condition, or a bus error. The provided callback function will be called for these events:

A slave address match occurs with the master requesting a write to the slave.
A slave address match occurs with the master requesting a read from the slave.
The receive FIFO crosses the set threshold (see MXC_I2C_SetRXThreshold()). The callback code should unload the receive FIFO (see MXC_I2C_ReadFIFO()) to allow the master to send more data. The return value of the callback function will determine if the last byte received should be acknowledged or not. Return 0 to acknowledge, non-zero to not acknowledge.
The transmit FIFO crosses the set threshold (see MXC_I2C_SetTXThreshold()). If the master is expected to read more data from this slave, the callback code should add data to the transmit FIFO (see MXC_I2C_WriteFIFO()).
The transaction ends. If the master was writing to the slave, the receive FIFO may still contain valid data that needs to be retreived (see MXC_I2C_ReadFIFO()).
The transmit FIFO underflows because the master requests data when the transmit FIFO is empty.
The receive FIFO overflows because the master writes data while the receive FIFO was full.

If clock stretching is disabled, careful attention must be paid to the timing of the callback to avoid losing data on write or unintentionally nacking a read.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
callback	The function to be called when an I2C event occurs.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ 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.

Performs a non-blocking I2C transaction. This request will remain active until a complete transaction with this slave has been performed. A transaction begins with the masterMXC_I2C_MasterTransactionDMA addressing the slave and ends with a repeated start condition, a stop condition, or a bus error. The provided callback function will be called for these events:

A slave address match occurs with the master requesting a write to the slave.
A slave address match occurs with the master requesting a read from the slave.
The receive FIFO crosses the set threshold (see MXC_I2C_SetRXThreshold()). The callback code should unload the receive FIFO (see MXC_I2C_ReadFIFO()) to allow the master to send more data. The return value of the callback function will determine if the last byte received should be acknowledged or not. Return 0 to acknowledge, non-zero to not acknowledge.
The transmit FIFO crosses the set threshold (see MXC_I2C_SetTXThreshold()). If the master is expected to read more data from this slave, the callback code should add data to the transmit FIFO (see MXC_I2C_WriteFIFO()).
The transaction ends. If the master was writing to the slave, the receive FIFO may still contain valid data that needs to be retreived (see MXC_I2C_ReadFIFO()).
The transmit FIFO underflows because the master requests data when the transmit FIFO is empty.
The receive FIFO overflows because the master writes data while the receive FIFO was full.

If clock stretching is disabled, careful attention must be paid to the timing of the callback to avoid losing data on write or unintentionally nacking a read.

Note: MXC_I2C_AsyncHandler() must be called peridocally for this function to operate properly.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
callback	The function to be called when an I2C event occurs.

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_Start()

int MXC_I2C_Start ( mxc_i2c_regs_t * i2c )

Generate a start (or repeated start) condition on the I2C bus.

Generate a start (or repeated start) condition on the I2C bus. This function may opt to delay the actual generation of the start condition until data is actually transferred.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ MXC_I2C_Stop()

int MXC_I2C_Stop ( mxc_i2c_regs_t * i2c )

Generate a stop condition on the I2C bus.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)

Returns: Success/Fail, see Error Codes for a list of return codes.

◆ 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.

Write multiple bytes to the I2C bus. This function assumes the I2C bus is already in the proper state (i.e. a start condition has already been generated and the bus is in the write phase of an I2C transaction).

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
bytes	The buffer containing the bytes to transmit.
len	The number of bytes to write. On return from the function, this will be set to the number of bytes actually transmitted.

Returns: 0 if all bytes are acknowledged, 1 if any byte transmitted is not acknowledged, negative if error. See Error Codes for the list of error return codes.

◆ MXC_I2C_WriteByte()

int MXC_I2C_WriteByte	(	mxc_i2c_regs_t *	i2c,
		unsigned char	byte
	)

Write a single byte to the I2C bus.

Write a single byte to the I2C bus. This function assumes the I2C bus is already in the proper state (i.e. a start condition has already been generated and the bus is in the write phase of an I2C transaction). If any bytes are pending in the FIFO (i.e. in the case of clock stretching), this function will return E_OVERFLOW.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
byte	The byte to transmit.

Returns: 0 if byte is acknowledged, 1 if not acknowledged, negative if error. See Error Codes for the list of error return codes.

◆ 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.

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
bytes	The buffer containing the bytes to write
len	The number of bytes to write.

Returns: The number of bytes actually written.

◆ 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.

Note: The operation is not complete until the callback has been called

Parameters

i2c	Pointer to I2C registers (selects the I2C block used.)
bytes	The buffer containing the bytes to write
len	The number of bytes to write.
callback	The function to call when the read is complete

Returns: See Error Codes for a list of return values

Modules

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ _i2c_req_t

Data Fields

Field Documentation

◆ callback

◆ i2c

◆ restart

◆ rx_len

◆ tx_len

Typedef Documentation

◆ mxc_i2c_complete_cb_t

◆ mxc_i2c_dma_complete_cb_t

◆ mxc_i2c_getAck_t

◆ mxc_i2c_slave_handler_t

Enumeration Type Documentation

◆ mxc_i2c_slave_event_t

Function Documentation

◆ MXC_I2C_AbortAsync()

◆ MXC_I2C_AsyncHandler()

◆ MXC_I2C_AsyncStop()

◆ MXC_I2C_ClearFlags()

◆ MXC_I2C_ClearRXFIFO()

◆ MXC_I2C_ClearTXFIFO()

◆ MXC_I2C_DisableGeneralCall()

◆ MXC_I2C_DisableInt()

◆ MXC_I2C_DisablePreload()

◆ MXC_I2C_DMA_GetRXChannel()

◆ MXC_I2C_DMA_GetTXChannel()

◆ MXC_I2C_DMA_Init()

◆ MXC_I2C_DMA_SetRequestSelect()

◆ MXC_I2C_DMACallback()

◆ MXC_I2C_EnableGeneralCall()

◆ MXC_I2C_EnableInt()

◆ MXC_I2C_EnablePreload()

◆ MXC_I2C_GetClockStretching()

◆ MXC_I2C_GetFlags()

◆ MXC_I2C_GetFrequency()

◆ MXC_I2C_GetRXFIFOAvailable()

◆ MXC_I2C_GetRXThreshold()

◆ MXC_I2C_GetTimeout()

◆ MXC_I2C_GetTXFIFOAvailable()

◆ MXC_I2C_GetTXThreshold()

◆ MXC_I2C_Init()

◆ MXC_I2C_MasterTransaction()

◆ MXC_I2C_MasterTransactionAsync()

◆ MXC_I2C_MasterTransactionDMA()

◆ MXC_I2C_Read()

◆ MXC_I2C_ReadByte()

◆ MXC_I2C_ReadByteInteractive()

◆ MXC_I2C_ReadRXFIFO()

◆ MXC_I2C_ReadRXFIFODMA()

◆ MXC_I2C_ReadyForSleep()

◆ MXC_I2C_Recover()

◆ MXC_I2C_SetClockStretching()

◆ MXC_I2C_SetFrequency()

◆ MXC_I2C_SetRXThreshold()

◆ MXC_I2C_SetSlaveAddr()

◆ MXC_I2C_SetTimeout()

◆ MXC_I2C_SetTXThreshold()

◆ MXC_I2C_Shutdown()

◆ MXC_I2C_SlaveTransaction()

◆ MXC_I2C_SlaveTransactionAsync()

◆ MXC_I2C_Start()

◆ MXC_I2C_Stop()

◆ MXC_I2C_Write()

◆ MXC_I2C_WriteByte()

◆ MXC_I2C_WriteTXFIFO()

◆ MXC_I2C_WriteTXFIFODMA()