MCUXpresso SDK API Reference Manual  Rev. 0
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages

Data Structures

struct  i2c_slave_address_t
 Data structure with 7-bit Slave address and Slave address disable. More...
 
struct  i2c_slave_config_t
 Structure with settings to initialize the I2C slave module. More...
 
struct  i2c_slave_transfer_t
 I2C slave transfer structure. More...
 
struct  i2c_slave_handle_t
 I2C slave handle structure. More...
 

Typedefs

typedef void(* i2c_slave_transfer_callback_t )(I2C_Type *base, volatile i2c_slave_transfer_t *transfer, void *userData)
 Slave event callback function pointer type. More...
 
typedef void(* flexcomm_i2c_master_irq_handler_t )(I2C_Type *base, i2c_master_handle_t *handle)
 Typedef for master interrupt handler. More...
 
typedef void(* flexcomm_i2c_slave_irq_handler_t )(I2C_Type *base, i2c_slave_handle_t *handle)
 Typedef for slave interrupt handler. More...
 

Enumerations

enum  _i2c_slave_flags {
  kI2C_SlavePendingFlag = I2C_STAT_SLVPENDING_MASK,
  kI2C_SlaveNotStretching,
  kI2C_SlaveSelected = I2C_STAT_SLVSEL_MASK,
  kI2C_SaveDeselected
}
 I2C slave peripheral flags. More...
 
enum  i2c_slave_address_register_t {
  kI2C_SlaveAddressRegister0 = 0U,
  kI2C_SlaveAddressRegister1 = 1U,
  kI2C_SlaveAddressRegister2 = 2U,
  kI2C_SlaveAddressRegister3 = 3U
}
 I2C slave address register. More...
 
enum  i2c_slave_address_qual_mode_t {
  kI2C_QualModeMask = 0U,
  kI2C_QualModeExtend
}
 I2C slave address match options. More...
 
enum  i2c_slave_bus_speed_t
 I2C slave bus speed options. More...
 
enum  i2c_slave_transfer_event_t {
  kI2C_SlaveAddressMatchEvent = 0x01U,
  kI2C_SlaveTransmitEvent = 0x02U,
  kI2C_SlaveReceiveEvent = 0x04U,
  kI2C_SlaveCompletionEvent = 0x20U,
  kI2C_SlaveDeselectedEvent,
  kI2C_SlaveAllEvents
}
 Set of events sent to the callback for non blocking slave transfers. More...
 
enum  i2c_slave_fsm_t
 I2C slave software finite state machine states.
 

Slave initialization and deinitialization

void I2C_SlaveGetDefaultConfig (i2c_slave_config_t *slaveConfig)
 Provides a default configuration for the I2C slave peripheral. More...
 
status_t I2C_SlaveInit (I2C_Type *base, const i2c_slave_config_t *slaveConfig, uint32_t srcClock_Hz)
 Initializes the I2C slave peripheral. More...
 
void I2C_SlaveSetAddress (I2C_Type *base, i2c_slave_address_register_t addressRegister, uint8_t address, bool addressDisable)
 Configures Slave Address n register. More...
 
void I2C_SlaveDeinit (I2C_Type *base)
 Deinitializes the I2C slave peripheral. More...
 
static void I2C_SlaveEnable (I2C_Type *base, bool enable)
 Enables or disables the I2C module as slave. More...
 

Slave status

static void I2C_SlaveClearStatusFlags (I2C_Type *base, uint32_t statusMask)
 Clears the I2C status flag state. More...
 

Slave bus operations

status_t I2C_SlaveWriteBlocking (I2C_Type *base, const uint8_t *txBuff, size_t txSize)
 Performs a polling send transfer on the I2C bus. More...
 
status_t I2C_SlaveReadBlocking (I2C_Type *base, uint8_t *rxBuff, size_t rxSize)
 Performs a polling receive transfer on the I2C bus. More...
 

Slave non-blocking

void I2C_SlaveTransferCreateHandle (I2C_Type *base, i2c_slave_handle_t *handle, i2c_slave_transfer_callback_t callback, void *userData)
 Creates a new handle for the I2C slave non-blocking APIs. More...
 
status_t I2C_SlaveTransferNonBlocking (I2C_Type *base, i2c_slave_handle_t *handle, uint32_t eventMask)
 Starts accepting slave transfers. More...
 
status_t I2C_SlaveSetSendBuffer (I2C_Type *base, volatile i2c_slave_transfer_t *transfer, const void *txData, size_t txSize, uint32_t eventMask)
 Starts accepting master read from slave requests. More...
 
status_t I2C_SlaveSetReceiveBuffer (I2C_Type *base, volatile i2c_slave_transfer_t *transfer, void *rxData, size_t rxSize, uint32_t eventMask)
 Starts accepting master write to slave requests. More...
 
static uint32_t I2C_SlaveGetReceivedAddress (I2C_Type *base, volatile i2c_slave_transfer_t *transfer)
 Returns the slave address sent by the I2C master. More...
 
void I2C_SlaveTransferAbort (I2C_Type *base, i2c_slave_handle_t *handle)
 Aborts the slave non-blocking transfers. More...
 
status_t I2C_SlaveTransferGetCount (I2C_Type *base, i2c_slave_handle_t *handle, size_t *count)
 Gets the slave transfer remaining bytes during a interrupt non-blocking transfer. More...
 

Slave IRQ handler

void I2C_SlaveTransferHandleIRQ (I2C_Type *base, i2c_slave_handle_t *handle)
 Reusable routine to handle slave interrupts. More...
 

Detailed Description


Data Structure Documentation

struct i2c_slave_address_t

Data Fields

uint8_t address
 7-bit Slave address SLVADR. More...
 
bool addressDisable
 Slave address disable SADISABLE. More...
 

Field Documentation

uint8_t i2c_slave_address_t::address
bool i2c_slave_address_t::addressDisable
struct i2c_slave_config_t

This structure holds configuration settings for the I2C slave peripheral. To initialize this structure to reasonable defaults, call the I2C_SlaveGetDefaultConfig() function and pass a pointer to your configuration structure instance.

The configuration structure can be made constant so it resides in flash.

Data Fields

i2c_slave_address_t address0
 Slave's 7-bit address and disable. More...
 
i2c_slave_address_t address1
 Alternate slave 7-bit address and disable. More...
 
i2c_slave_address_t address2
 Alternate slave 7-bit address and disable. More...
 
i2c_slave_address_t address3
 Alternate slave 7-bit address and disable. More...
 
i2c_slave_address_qual_mode_t qualMode
 Qualify mode for slave address 0. More...
 
uint8_t qualAddress
 Slave address qualifier for address 0. More...
 
i2c_slave_bus_speed_t busSpeed
 Slave bus speed mode. More...
 
bool enableSlave
 Enable slave mode. More...
 

Field Documentation

i2c_slave_address_t i2c_slave_config_t::address0
i2c_slave_address_t i2c_slave_config_t::address1
i2c_slave_address_t i2c_slave_config_t::address2
i2c_slave_address_t i2c_slave_config_t::address3
i2c_slave_address_qual_mode_t i2c_slave_config_t::qualMode
uint8_t i2c_slave_config_t::qualAddress
i2c_slave_bus_speed_t i2c_slave_config_t::busSpeed

If the slave function stretches SCL to allow for software response, it must provide sufficient data setup time to the master before releasing the stretched clock. This is accomplished by inserting one clock time of CLKDIV at that point. The busSpeed value is used to configure CLKDIV such that one clock time is greater than the tSU;DAT value noted in the I2C bus specification for the I2C mode that is being used. If the busSpeed mode is unknown at compile time, use the longest data setup time kI2C_SlaveStandardMode (250 ns)

bool i2c_slave_config_t::enableSlave
struct i2c_slave_transfer_t

Data Fields

i2c_slave_handle_t * handle
 Pointer to handle that contains this transfer. More...
 
i2c_slave_transfer_event_t event
 Reason the callback is being invoked. More...
 
uint8_t receivedAddress
 Matching address send by master. More...
 
uint32_t eventMask
 Mask of enabled events. More...
 
uint8_t * rxData
 Transfer buffer for receive data.
 
const uint8_t * txData
 Transfer buffer for transmit data.
 
size_t txSize
 Transfer size.
 
size_t rxSize
 Transfer size.
 
size_t transferredCount
 Number of bytes transferred during this transfer. More...
 
status_t completionStatus
 Success or error code describing how the transfer completed. More...
 

Field Documentation

i2c_slave_handle_t* i2c_slave_transfer_t::handle
i2c_slave_transfer_event_t i2c_slave_transfer_t::event
uint8_t i2c_slave_transfer_t::receivedAddress

7-bits plus R/nW bit0

uint32_t i2c_slave_transfer_t::eventMask
size_t i2c_slave_transfer_t::transferredCount
status_t i2c_slave_transfer_t::completionStatus

Only applies for kI2C_SlaveCompletionEvent.

struct _i2c_slave_handle

I2C slave handle typedef.

Note
The contents of this structure are private and subject to change.

Data Fields

volatile i2c_slave_transfer_t transfer
 I2C slave transfer. More...
 
volatile bool isBusy
 Whether transfer is busy. More...
 
volatile i2c_slave_fsm_t slaveFsm
 slave transfer state machine. More...
 
i2c_slave_transfer_callback_t callback
 Callback function called at transfer event. More...
 
void * userData
 Callback parameter passed to callback. More...
 

Field Documentation

volatile i2c_slave_transfer_t i2c_slave_handle_t::transfer
volatile bool i2c_slave_handle_t::isBusy
volatile i2c_slave_fsm_t i2c_slave_handle_t::slaveFsm
i2c_slave_transfer_callback_t i2c_slave_handle_t::callback
void* i2c_slave_handle_t::userData

Typedef Documentation

typedef void(* i2c_slave_transfer_callback_t)(I2C_Type *base, volatile i2c_slave_transfer_t *transfer, void *userData)

This callback is used only for the slave non-blocking transfer API. To install a callback, use the I2C_SlaveSetCallback() function after you have created a handle.

Parameters
baseBase address for the I2C instance on which the event occurred.
transferPointer to transfer descriptor containing values passed to and/or from the callback.
userDataArbitrary pointer-sized value passed from the application.
typedef void(* flexcomm_i2c_master_irq_handler_t)(I2C_Type *base, i2c_master_handle_t *handle)
typedef void(* flexcomm_i2c_slave_irq_handler_t)(I2C_Type *base, i2c_slave_handle_t *handle)

Enumeration Type Documentation

Note
These enums are meant to be OR'd together to form a bit mask.
Enumerator
kI2C_SlavePendingFlag 

The I2C module is waiting for software interaction.

kI2C_SlaveNotStretching 

Indicates whether the slave is currently stretching clock (0 = yes, 1 = no).

kI2C_SlaveSelected 

Indicates whether the slave is selected by an address match.

kI2C_SaveDeselected 

Indicates that slave was previously deselected (deselect event took place, w1c).

Enumerator
kI2C_SlaveAddressRegister0 

Slave Address 0 register.

kI2C_SlaveAddressRegister1 

Slave Address 1 register.

kI2C_SlaveAddressRegister2 

Slave Address 2 register.

kI2C_SlaveAddressRegister3 

Slave Address 3 register.

Enumerator
kI2C_QualModeMask 

The SLVQUAL0 field (qualAddress) is used as a logical mask for matching address0.

kI2C_QualModeExtend 

The SLVQUAL0 (qualAddress) field is used to extend address 0 matching in a range of addresses.

These event enumerations are used for two related purposes. First, a bit mask created by OR'ing together events is passed to I2C_SlaveTransferNonBlocking() in order to specify which events to enable. Then, when the slave callback is invoked, it is passed the current event through its transfer parameter.

Note
These enumerations are meant to be OR'd together to form a bit mask of events.
Enumerator
kI2C_SlaveAddressMatchEvent 

Received the slave address after a start or repeated start.

kI2C_SlaveTransmitEvent 

Callback is requested to provide data to transmit (slave-transmitter role).

kI2C_SlaveReceiveEvent 

Callback is requested to provide a buffer in which to place received data (slave-receiver role).

kI2C_SlaveCompletionEvent 

All data in the active transfer have been consumed.

kI2C_SlaveDeselectedEvent 

The slave function has become deselected (SLVSEL flag changing from 1 to 0.

kI2C_SlaveAllEvents 

Bit mask of all available events.

Function Documentation

void I2C_SlaveGetDefaultConfig ( i2c_slave_config_t slaveConfig)

This function provides the following default configuration for the I2C slave peripheral:

* slaveConfig->enableSlave = true;
* slaveConfig->address0.disable = false;
* slaveConfig->address0.address = 0u;
* slaveConfig->address1.disable = true;
* slaveConfig->address2.disable = true;
* slaveConfig->address3.disable = true;
* slaveConfig->busSpeed = kI2C_SlaveStandardMode;
*

After calling this function, override any settings to customize the configuration, prior to initializing the master driver with I2C_SlaveInit(). Be sure to override at least the address0.address member of the configuration structure with the desired slave address.

Parameters
[out]slaveConfigUser provided configuration structure that is set to default values. Refer to i2c_slave_config_t.
status_t I2C_SlaveInit ( I2C_Type *  base,
const i2c_slave_config_t slaveConfig,
uint32_t  srcClock_Hz 
)

This function enables the peripheral clock and initializes the I2C slave peripheral as described by the user provided configuration.

Parameters
baseThe I2C peripheral base address.
slaveConfigUser provided peripheral configuration. Use I2C_SlaveGetDefaultConfig() to get a set of defaults that you can override.
srcClock_HzFrequency in Hertz of the I2C functional clock. Used to calculate CLKDIV value to provide enough data setup time for master when slave stretches the clock.
void I2C_SlaveSetAddress ( I2C_Type *  base,
i2c_slave_address_register_t  addressRegister,
uint8_t  address,
bool  addressDisable 
)

This function writes new value to Slave Address register.

Parameters
baseThe I2C peripheral base address.
addressRegisterThe module supports multiple address registers. The parameter determines which one shall be changed.
addressThe slave address to be stored to the address register for matching.
addressDisableDisable matching of the specified address register.
void I2C_SlaveDeinit ( I2C_Type *  base)

This function disables the I2C slave peripheral and gates the clock. It also performs a software reset to restore the peripheral to reset conditions.

Parameters
baseThe I2C peripheral base address.
static void I2C_SlaveEnable ( I2C_Type *  base,
bool  enable 
)
inlinestatic
Parameters
baseThe I2C peripheral base address.
enableTrue to enable or flase to disable.
static void I2C_SlaveClearStatusFlags ( I2C_Type *  base,
uint32_t  statusMask 
)
inlinestatic

The following status register flags can be cleared:

  • slave deselected flag

Attempts to clear other flags has no effect.

Parameters
baseThe I2C peripheral base address.
statusMaskA bitmask of status flags that are to be cleared. The mask is composed of _i2c_slave_flags enumerators OR'd together. You may pass the result of a previous call to I2C_SlaveGetStatusFlags().
See Also
_i2c_slave_flags.
status_t I2C_SlaveWriteBlocking ( I2C_Type *  base,
const uint8_t *  txBuff,
size_t  txSize 
)

The function executes blocking address phase and blocking data phase.

Parameters
baseThe I2C peripheral base address.
txBuffThe pointer to the data to be transferred.
txSizeThe length in bytes of the data to be transferred.
Returns
kStatus_Success Data has been sent.
kStatus_Fail Unexpected slave state (master data write while master read from slave is expected).
status_t I2C_SlaveReadBlocking ( I2C_Type *  base,
uint8_t *  rxBuff,
size_t  rxSize 
)

The function executes blocking address phase and blocking data phase.

Parameters
baseThe I2C peripheral base address.
rxBuffThe pointer to the data to be transferred.
rxSizeThe length in bytes of the data to be transferred.
Returns
kStatus_Success Data has been received.
kStatus_Fail Unexpected slave state (master data read while master write to slave is expected).
void I2C_SlaveTransferCreateHandle ( I2C_Type *  base,
i2c_slave_handle_t *  handle,
i2c_slave_transfer_callback_t  callback,
void *  userData 
)

The creation of a handle is for use with the non-blocking APIs. Once a handle is created, there is not a corresponding destroy handle. If the user wants to terminate a transfer, the I2C_SlaveTransferAbort() API shall be called.

Parameters
baseThe I2C peripheral base address.
[out]handlePointer to the I2C slave driver handle.
callbackUser provided pointer to the asynchronous callback function.
userDataUser provided pointer to the application callback data.
status_t I2C_SlaveTransferNonBlocking ( I2C_Type *  base,
i2c_slave_handle_t *  handle,
uint32_t  eventMask 
)

Call this API after calling I2C_SlaveInit() and I2C_SlaveTransferCreateHandle() to start processing transactions driven by an I2C master. The slave monitors the I2C bus and pass events to the callback that was passed into the call to I2C_SlaveTransferCreateHandle(). The callback is always invoked from the interrupt context.

If no slave Tx transfer is busy, a master read from slave request invokes kI2C_SlaveTransmitEvent callback. If no slave Rx transfer is busy, a master write to slave request invokes kI2C_SlaveReceiveEvent callback.

The set of events received by the callback is customizable. To do so, set the eventMask parameter to the OR'd combination of i2c_slave_transfer_event_t enumerators for the events you wish to receive. The kI2C_SlaveTransmitEvent and kI2C_SlaveReceiveEvent events are always enabled and do not need to be included in the mask. Alternatively, you can pass 0 to get a default set of only the transmit and receive events that are always enabled. In addition, the kI2C_SlaveAllEvents constant is provided as a convenient way to enable all events.

Parameters
baseThe I2C peripheral base address.
handlePointer to i2c_slave_handle_t structure which stores the transfer state.
eventMaskBit mask formed by OR'ing together i2c_slave_transfer_event_t enumerators to specify which events to send to the callback. Other accepted values are 0 to get a default set of only the transmit and receive events, and kI2C_SlaveAllEvents to enable all events.
Return values
kStatus_SuccessSlave transfers were successfully started.
kStatus_I2C_BusySlave transfers have already been started on this handle.
status_t I2C_SlaveSetSendBuffer ( I2C_Type *  base,
volatile i2c_slave_transfer_t transfer,
const void *  txData,
size_t  txSize,
uint32_t  eventMask 
)

The function can be called in response to kI2C_SlaveTransmitEvent callback to start a new slave Tx transfer from within the transfer callback.

The set of events received by the callback is customizable. To do so, set the eventMask parameter to the OR'd combination of i2c_slave_transfer_event_t enumerators for the events you wish to receive. The kI2C_SlaveTransmitEvent and kI2C_SlaveReceiveEvent events are always enabled and do not need to be included in the mask. Alternatively, you can pass 0 to get a default set of only the transmit and receive events that are always enabled. In addition, the kI2C_SlaveAllEvents constant is provided as a convenient way to enable all events.

Parameters
baseThe I2C peripheral base address.
transferPointer to i2c_slave_transfer_t structure.
txDataPointer to data to send to master.
txSizeSize of txData in bytes.
eventMaskBit mask formed by OR'ing together i2c_slave_transfer_event_t enumerators to specify which events to send to the callback. Other accepted values are 0 to get a default set of only the transmit and receive events, and kI2C_SlaveAllEvents to enable all events.
Return values
kStatus_SuccessSlave transfers were successfully started.
kStatus_I2C_BusySlave transfers have already been started on this handle.
status_t I2C_SlaveSetReceiveBuffer ( I2C_Type *  base,
volatile i2c_slave_transfer_t transfer,
void *  rxData,
size_t  rxSize,
uint32_t  eventMask 
)

The function can be called in response to kI2C_SlaveReceiveEvent callback to start a new slave Rx transfer from within the transfer callback.

The set of events received by the callback is customizable. To do so, set the eventMask parameter to the OR'd combination of i2c_slave_transfer_event_t enumerators for the events you wish to receive. The kI2C_SlaveTransmitEvent and kI2C_SlaveReceiveEvent events are always enabled and do not need to be included in the mask. Alternatively, you can pass 0 to get a default set of only the transmit and receive events that are always enabled. In addition, the kI2C_SlaveAllEvents constant is provided as a convenient way to enable all events.

Parameters
baseThe I2C peripheral base address.
transferPointer to i2c_slave_transfer_t structure.
rxDataPointer to data to store data from master.
rxSizeSize of rxData in bytes.
eventMaskBit mask formed by OR'ing together i2c_slave_transfer_event_t enumerators to specify which events to send to the callback. Other accepted values are 0 to get a default set of only the transmit and receive events, and kI2C_SlaveAllEvents to enable all events.
Return values
kStatus_SuccessSlave transfers were successfully started.
kStatus_I2C_BusySlave transfers have already been started on this handle.
static uint32_t I2C_SlaveGetReceivedAddress ( I2C_Type *  base,
volatile i2c_slave_transfer_t transfer 
)
inlinestatic

This function should only be called from the address match event callback kI2C_SlaveAddressMatchEvent.

Parameters
baseThe I2C peripheral base address.
transferThe I2C slave transfer.
Returns
The 8-bit address matched by the I2C slave. Bit 0 contains the R/w direction bit, and the 7-bit slave address is in the upper 7 bits.
void I2C_SlaveTransferAbort ( I2C_Type *  base,
i2c_slave_handle_t *  handle 
)
Note
This API could be called at any time to stop slave for handling the bus events.
Parameters
baseThe I2C peripheral base address.
handlePointer to i2c_slave_handle_t structure which stores the transfer state.
Return values
kStatus_Success
kStatus_I2C_Idle
status_t I2C_SlaveTransferGetCount ( I2C_Type *  base,
i2c_slave_handle_t *  handle,
size_t *  count 
)
Parameters
baseI2C base pointer.
handlepointer to i2c_slave_handle_t structure.
countNumber of bytes transferred so far by the non-blocking transaction.
Return values
kStatus_InvalidArgumentcount is Invalid.
kStatus_SuccessSuccessfully return the count.
void I2C_SlaveTransferHandleIRQ ( I2C_Type *  base,
i2c_slave_handle_t *  handle 
)
Note
This function does not need to be called unless you are reimplementing the non blocking API's interrupt handler routines to add special functionality.
Parameters
baseThe I2C peripheral base address.
handlePointer to i2c_slave_handle_t structure which stores the transfer state.