The MCUXpresso SDK provides a peripheral driver for the Inter-Integrated Circuit (I2C) module of MCUXpresso SDK devices.
The I2C driver includes functional APIs and transactional APIs.
Functional APIs target the low-level APIs. Functional APIs can be used for the I2C master/slave initialization/configuration/operation for optimization/customization purpose. Using the functional APIs requires knowing the I2C master peripheral and how to organize functional APIs to meet the application requirements. The I2C functional operation groups provide the functional APIs set.
Transactional APIs target the high-level APIs. The transactional APIs can be used to enable the peripheral quickly and also in the application if the code size and performance of transactional APIs satisfy the requirements. If the code size and performance are critical requirements, see the transactional API implementation and write custom code using the functional APIs or accessing the hardware registers.
Transactional APIs support asynchronous transfer. This means that the functions I2C_MasterTransferNonBlocking() set up the interrupt non-blocking transfer. When the transfer completes, the upper layer is notified through a callback function with the status.
Typical use case
Master Operation in functional method
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/i2c
Master Operation in interrupt transactional method
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/i2c
Master Operation in DMA transactional method
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/i2c
Slave Operation in functional method
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/i2c
Slave Operation in interrupt transactional method
Refer to the driver examples codes located at <SDK_ROOT>/boards/<BOARD>/driver_examples/i2c
|
| #define | I2C_RETRY_TIMES 0U /* Default defines to zero, driver keeps checking status flag untill it changes. */ |
| | Retry times when checking status flags. More...
|
| |
|
| enum | {
kStatus_I2C_Busy = MAKE_STATUS(kStatusGroup_I2C, 0),
kStatus_I2C_Idle = MAKE_STATUS(kStatusGroup_I2C, 1),
kStatus_I2C_Nak = MAKE_STATUS(kStatusGroup_I2C, 2),
kStatus_I2C_ArbitrationLost = MAKE_STATUS(kStatusGroup_I2C, 3),
kStatus_I2C_Timeout,
kStatus_I2C_Addr_Nak = MAKE_STATUS(kStatusGroup_I2C, 5),
kStatus_I2C_GeneralCall_Nak,
kStatus_I2C_RxHardwareOverrun = MAKE_STATUS(kStatusGroup_I2C, 7),
kStatus_I2C_TxFifoFlushed = MAKE_STATUS(kStatusGroup_I2C, 8)
} |
| | I2C API status codes, used by bus operation APIs and transactional APIs as return value to indicate the bus's current status as the API's execution result, or used in the callback to indicate transfer results. More...
|
| |
| enum | _i2c_status_flags {
kI2C_RxUnderflowInterruptFlag,
kI2C_RxOverflowInterruptFlag,
kI2C_RxDataReadyInterruptFlag,
kI2C_TxOverflowInterruptFlag = I2C_IC_RAW_INTR_STAT_TX_OVER_MASK,
kI2C_TxRequestInterruptFlag,
kI2C_TxAbortInterruptFlag = I2C_IC_RAW_INTR_STAT_TX_ABRT_MASK,
kI2C_BusBusyInterruptFlag,
kI2C_StopDetectInterruptFlag,
kI2C_StartDetectInterruptFlag,
kI2C_ActiveFlag,
kI2C_TxFifoNotFullFlag = I2C_IC_STATUS_TFNF_MASK << 25U,
kI2C_TxFifoEmptyFlag = I2C_IC_STATUS_TFE_MASK << 25U,
kI2C_RxFifoNotEmptyFlag = I2C_IC_STATUS_RFNE_MASK << 25U,
kI2C_RxFifoFullFlag = I2C_IC_STATUS_RFF_MASK << 25U
} |
| | I2C common hardware status flags. More...
|
| |
| enum | _i2c_master_status_flags {
kI2C_Master7bitAddressNackFlag,
kI2C_Master10bitAddressNack1Flag,
kI2C_Master10bitAddressNack2Flag,
kI2C_MasterDataNackFlag,
kI2C_MasterGeneralCallNackFlag,
kI2C_MasterGeneralCallReadFlag,
kI2C_MasterHighSpeedCodeAckFlag,
kI2C_MasterStartByteAckFlag,
kI2C_MasterHighSpeedRestartDisabledFlag,
kI2C_MasterStartWithRestartDisabledFlag,
kI2C_Master10bitAddressReadRestartDisabledFlag,
kI2C_MasterOperateWhenDisabledFlag,
kI2C_MasterArbitrationLostFlag,
kI2C_MasterActiveFlag,
kI2C_MasterAutoClearFlags,
kI2C_MasterAllClearFlags
} |
| | I2C master hardware status flags. More...
|
| |
| enum | _i2c_slave_status_flags {
kI2C_SlaveReadRequestInterruptFlag,
kI2C_SlaveNackInterruptFlag,
kI2C_SlaveGeneralCallAckInterruptFlag,
kI2C_SlaveFlushTxFifoFlag,
kI2C_SlaveArbitrationLostFlag,
kI2C_SlaveReadWhenRequestedDataFlag,
kI2C_SlaveDisabledWhileBusy = I2C_IC_ENABLE_STATUS_SLV_DISABLED_WHILE_BUSY_MASK << 16U,
kI2C_SlaveRxDataLost,
kI2C_SlaveActiveFlag,
kI2C_SlaveAutoClearFlags,
kI2C_SlaveAllClearFlags
} |
| | I2C slave hardware status flags. More...
|
| |
| enum | _i2c_interrupt_enable {
kI2C_RxUnderflowInterruptEnable = I2C_IC_INTR_MASK_M_RX_UNDER_MASK,
kI2C_RxOverflowInterruptEnable = I2C_IC_INTR_MASK_M_RX_OVER_MASK,
kI2C_RxDataReadyInterruptEnable = I2C_IC_INTR_MASK_M_RX_FULL_MASK,
kI2C_TxOverflowInterruptEnable = I2C_IC_INTR_MASK_M_TX_OVER_MASK,
kI2C_TxRequestInterruptEnable = I2C_IC_INTR_MASK_M_TX_EMPTY_MASK,
kI2C_SlaveReadRequestInterruptEnable,
kI2C_TxAbortInterruptEnable = I2C_IC_INTR_MASK_M_TX_ABRT_MASK,
kI2C_SlaveNackInterruptEnable = I2C_IC_INTR_MASK_M_RX_DONE_MASK,
kI2C_BusBusyInterruptEnable = I2C_IC_INTR_MASK_M_ACTIVITY_MASK,
kI2C_StopDetectInterruptEnable,
kI2C_StartDetectInterruptEnable,
kI2C_SlaveGeneralCallAckInterruptEnable
} |
| | I2C interrupt enable/disable source. More...
|
| |
| enum | i2c_master_speed_mode_t {
kI2C_MasterSpeedStandard = 0x1U,
kI2C_MasterSpeedFast = 0X2U,
kI2C_MasterSpeedHigh = 0X3U
} |
| | Master speed mode. More...
|
| |
| enum | i2c_address_mode_t {
kI2C_AddressMatch7bit = 0x0U,
kI2C_AddressMatch10bit = 0X1U
} |
| | Addressing mode, normal 7-bit address or 10-bit address. More...
|
| |
| enum | _i2c_dma_enable_flags {
kQSPI_DmaRx = 0x1U,
kQSPI_DmaTx = 0x2U
} |
| | I2C DMA configuration for Transmit and Receive. More...
|
| |
| enum | i2c_direction_t {
kI2C_Write = 0U,
kI2C_Read = 1U
} |
| | Master transfer direction. More...
|
| |
| enum | i2c_slave_transfer_event_t {
kI2C_SlaveStartDetectEvent = 0x01U,
kI2C_SlaveGenaralcallEvent = 0x02U,
kI2C_SlaveTransmitEvent = 0x04U,
kI2C_SlaveReceiveEvent = 0x08U,
kI2C_SlaveCompletionEvent,
kI2C_SlaveAllEvents
} |
| | Set of slave transfer events. More...
|
| |
|
| static uint8_t | I2C_ReadByte (I2C_Type *base) |
| | Reads one byte from data register directly. More...
|
| |
| static void | I2C_WriteByte (I2C_Type *base, uint8_t data) |
| | Writes one byte to the data register directly. More...
|
| |
| struct i2c_master_config_t |
This structure includes all the master operation needed features, user can configure these features one by one manually, or call I2C_MasterGetDefaultConfig to set the structure to default value. Then, call I2C_MasterInit to initialize I2C module. After initialization, the I2C module can only operate as master. To deinitialize I2C, call I2C_MasterDeinit.
| bool i2c_master_config_t::enable |
I2C_IC_CON[IC_SLAVE_DISABLE], I2C_IC_CON[master_mode], I2C_IC_ENABLE[ENABLE]
I2C_IC_TAR[IC_10BITADDR_MASTER]
| uint8_t i2c_master_config_t::highSpeedMasterCodeAddress |
I2C_IC_HS_MADDR[IC_HS_MAR]
| uint8_t i2c_master_config_t::rxFifoWaterMark |
| uint8_t i2c_master_config_t::txFifoWaterMark |
| uint16_t i2c_master_config_t::dataHoldTime |
I2C_IC_SDA_HOLD[IC_SDA_HOLD]
| uint16_t i2c_master_config_t::dataSetupTime |
I2C_IC_SDA_SETUP[SDA_SETUP]
| uint8_t i2c_master_config_t::glitchFilter |
I2C_IC_FS_SPKLEN[IC_FS_SPKLEN]
| uint8_t i2c_master_config_t::glitchFilterHighSpeed |
I2C_IC_HS_SPKLEN[IC_HS_SPKLEN]
| struct i2c_slave_config_t |
This structure includes all the slave operation needed features, user can configure these features one by one manually, or call I2C_SlaveGetDefaultConfig to set the structure to default value. Then, call I2C_SlaveInit to initialize I2C module. After initialization, the I2C module can only operate as slave. To deinitialize I2C, call I2C_SlaveDeinit.
| bool i2c_slave_config_t::enable |
I2C_IC_CON[IC_SLAVE_DISABLE], I2C_IC_CON[master_mode], I2C_IC_ENABLE[ENABLE]
I2C_IC_CON[IC_10BITADDR_SLAVE]
| uint16_t i2c_slave_config_t::slaveAddress |
| uint8_t i2c_slave_config_t::rxFifoWaterMark |
| uint8_t i2c_slave_config_t::txFifoWaterMark |
| uint16_t i2c_slave_config_t::dataHoldTime |
I2C_IC_SDA_HOLD[IC_SDA_HOLD]
| uint16_t i2c_slave_config_t::dataSetupTime |
I2C_IC_SDA_SETUP[SDA_SETUP]
| bool i2c_slave_config_t::ackGeneralCall |
I2C_IC_ACK_GENERAL_CALL[ACK_GEN_CALL]
| uint8_t i2c_slave_config_t::glitchFilter |
I2C_IC_FS_SPKLEN[IC_FS_SPKLEN]
| uint8_t i2c_slave_config_t::glitchFilterHighSpeed |
I2C_IC_HS_SPKLEN[IC_HS_SPKLEN]
| struct i2c_master_transfer_t |
This structure definition includes all the user configurable features, that are used to control single I2C transfer of master mode, in polling way or in interrupt way.
| uint16_t i2c_master_transfer_t::slaveAddress |
| uint32_t i2c_master_transfer_t::subaddress |
| size_t i2c_master_transfer_t::subaddressSize |
| uint8_t* volatile i2c_master_transfer_t::data |
| volatile size_t i2c_master_transfer_t::dataSize |
| struct _i2c_master_handle |
Forward declaration of the I2C master transfer handle structure.
- Note
- If user wants to use the transactional API to transfer data in interrupt way in master mode, one I2C instance should and can only be allocated one master handle.
-
The handle is maintained by I2C driver internally, which means the transfer state is retained and user shall not modify its state state in application level. If user only wish to use transactional APIs without understanding its machanism, it is not necessary to understand these members.
| uint8_t i2c_master_handle_t::state |
| size_t i2c_master_handle_t::transmitSize |
| size_t i2c_master_handle_t::receiveSize |
| struct i2c_slave_transfer_t |
Covers slave transfer data buffer pointer, data size and the events user want driver to alert.
- Note
- Unlike master who controls the transfer flow, slave has to monitor any bus event and change its configuration accordingly. So this slave transfer configuration structure is also used as second parameter of callback, for user to change the transfer configuration in the callback. The read-only member eEvent shows which event occured that causes the callback being invoked.
| uint8_t* volatile i2c_slave_transfer_t::data |
| volatile uint16_t i2c_slave_transfer_t::dataSize |
| status_t i2c_slave_transfer_t::completionStatus |
| struct i2c_slave_handle_t |
- Note
- If user wants to use the transactional API to transfer data in slave mode, one I2C instance should and can only be allocated one handle.
-
The handle is maintained by I2C driver internally, which means the transfer state is retained and user shall not modify its state isBusy in application level. If user only wish to use transactional APIs without understanding its machanism, it is not necessary to understand these members.
| size_t i2c_slave_handle_t::transferredCount |
| bool i2c_slave_handle_t::isBusy |
| uint8_t i2c_slave_handle_t::eventMask |
When these enents occur during transfer driver will alert user using callback.
| status_t i2c_slave_handle_t::completionStatus |
| void* i2c_slave_handle_t::userData |
| #define I2C_RETRY_TIMES 0U /* Default defines to zero, driver keeps checking status flag untill it changes. */ |
| typedef void(* i2c_master_transfer_callback_t)(I2C_Type *base, i2c_master_handle_t *handle, status_t completionStatus, void *userData) |
Defines the interface of user callback function used in master interrupt transfer. The callback function shall be defined and declared in application level by user. Before starting master transfer by calling I2C_MasterTransferNonBlocking, call I2C_MasterTransferCreateHandle to install the user callback. When master transfer ends successfully or failed due to any event like arbitration lost or nacked by slave, user callback will be invoked by driver. And then user can decide what to do next in the callback according to its third parameter completionStatus that indicates how the transfer ends.
- Parameters
-
| base | The I2C peripheral base address. |
| handle | I2C transfer handle, which contains the information of base pointer, completionStatus and user data. |
| completionStatus | Either kStatus_Success or an error code describing how the transfer completed. |
| userData | Pointer to user configurable structure. |
| typedef void(* i2c_slave_transfer_callback_t)(I2C_Type *base, i2c_slave_transfer_t *transfer, void *userData) |
Defines the interface of slave user callback function. The callback function shall be defined and declared in application level by user. Before calling I2C_SlaveTransferNonBlocking to let I2C slave ready to process bus events, call I2C_SlaveTransferCreateHandle first to install the user callback to slave handle. When I2C slave meets user selected events, callback will be invoked and user can decide the following steps in the callback. All the events that can trigger callback are listed in i2c_slave_transfer_event_t.
- Parameters
-
| base | Base address for the I2C instance on which the event occurred. |
| transfer | Pointer to transfer descriptor containing values passed to and/or from the callback. |
| userData | Pointer to user configurable structure. |
| typedef void(* i2c_isr_t)(I2C_Type *base, void *i2cHandle) |
| Enumerator |
|---|
| kStatus_I2C_Busy |
I2C bus is busy.
|
| kStatus_I2C_Idle |
I2C Bus is idle.
|
| kStatus_I2C_Nak |
I2C detected NACK on bus.
When in SMBus mode, this means the receiver nacks transmitter before PEC byte.
|
| kStatus_I2C_ArbitrationLost |
I2C lost arbitration during addressing.
|
| kStatus_I2C_Timeout |
Timeout happens when waiting for status flags to change.
|
| kStatus_I2C_Addr_Nak |
NACK was detected during the address probe.
|
| kStatus_I2C_GeneralCall_Nak |
NACK was detected after issuing general call.
|
| kStatus_I2C_RxHardwareOverrun |
I2C rx receiver overrun.
|
| kStatus_I2C_TxFifoFlushed |
I2C tx FIFO is flushed by hardware.
|
These enumerations can be ORed together to form bit masks. The masks can be used together with masks in _i2c_master_status_flags as parameter by I2C_MasterClearStatusFlags or as return value by I2C_MasterGetStatusFlags. Or together with masks in _i2c_slave_status_flags as parameter by I2C_SlaveClearStatusFlags or as return value by I2C_SlaveGetStatusFlags
| Enumerator |
|---|
| kI2C_RxUnderflowInterruptFlag |
Sets when software tries to read from empty rx FIFO.
bit 0
|
| kI2C_RxOverflowInterruptFlag |
Sets when new data received and the rx FIFO is already full.
bit 1
|
| kI2C_RxDataReadyInterruptFlag |
Sets when data in rx FIFO reaches or is above rx watermark.
bit 2
|
| kI2C_TxOverflowInterruptFlag |
Sets when software tries to push data to tx FIFO and it's already full.
bit 3
|
| kI2C_TxRequestInterruptFlag |
Sets when data in tx FIFO is at or below tx FIFO watermark.
bit 4
|
| kI2C_TxAbortInterruptFlag |
Sets when any of the below status from kI2C_Master7bitAddressNackFlag to kI2C_MasterArbitrationLostFlag is set, results in the tx FIFO being flushed.
Clear this flag will also clear these status flags automatically. bit 6
|
| kI2C_BusBusyInterruptFlag |
Sets when there is I2C activity on bus.
bit 8
|
| kI2C_StopDetectInterruptFlag |
Sets when stop condition is detected.
bit 9
|
| kI2C_StartDetectInterruptFlag |
Sets when start condition is detected.
bit 10
|
| kI2C_ActiveFlag |
Sets when I2C module is in active transfer state.
bit 25
|
| kI2C_TxFifoNotFullFlag |
Sets when I2C tx FIFO is not full.
bit 26
|
| kI2C_TxFifoEmptyFlag |
Sets when I2C txFIFO is completely empty.
bit 27
|
| kI2C_RxFifoNotEmptyFlag |
Sets when I2C rx FIFO is not empty.
bit 28
|
| kI2C_RxFifoFullFlag |
Sets when I2C rx FIFO is completely full.
bit 29
|
These enumerations can be ORed together to form bit masks. The masks can be used as parameter by I2C_MasterClearStatusFlags or as return value by I2C_MasterGetStatusFlags.
| Enumerator |
|---|
| kI2C_Master7bitAddressNackFlag |
Sets when I2C master is nacked in 7-bit addressing.
bit 12
|
| kI2C_Master10bitAddressNack1Flag |
Sets when I2C master is nacked of first byte of address in 10-bit addressing.
bit 13
|
| kI2C_Master10bitAddressNack2Flag |
Sets when I2C master is nacked of second byte of address in 10-bit addressing.
bit 14
|
| kI2C_MasterDataNackFlag |
Sets when I2C master is nacked in data sending.
bit 15
|
| kI2C_MasterGeneralCallNackFlag |
Sets when I2C master is nacked after issueing general call.
bit 16
|
| kI2C_MasterGeneralCallReadFlag |
Sets when I2C master uses read command after issueing general call.
bit 17
|
| kI2C_MasterHighSpeedCodeAckFlag |
Sets when I2C master is in high speed mode and the high speed master code was acknowledged.
bit 18
|
| kI2C_MasterStartByteAckFlag |
Sets when I2C master has sent a START byte and the START byte was acknowledged.
bit 19
|
| kI2C_MasterHighSpeedRestartDisabledFlag |
Sets when I2C master tries to transfer data in high speed mode with restart disabled.
bit 20
|
| kI2C_MasterStartWithRestartDisabledFlag |
Sets when master tries to send a start with restart disabled.
bit 21
|
| kI2C_Master10bitAddressReadRestartDisabledFlag |
Sets when I2C master issues read command in 10-bit addessing with restart disabled.
bit 22
|
| kI2C_MasterOperateWhenDisabledFlag |
Sets when software wants to initiate a master operation with master mode disabled.
bit 23
|
| kI2C_MasterArbitrationLostFlag |
Sets when master loses arbitration or kI2C_SlaveArbitrationLostFlag is set.
bit 24
|
| kI2C_MasterActiveFlag |
Sets when I2C master operation is active.
bit 30
|
| kI2C_MasterAutoClearFlags |
These flags are cleared automatically according to module status, or when other status bit is cleared.
eg. once tx FIFO is not empty kI2C_TxFifoEmptyFlag is cleared automatically. eg. status bits from kI2C_Master7bitAddressNackFlag to kI2C_MasterArbitrationLostFlag are cleared when kI2C_TxAbortInterruptFlag is cleared.
|
| kI2C_MasterAllClearFlags |
All flags which are clearable.
|
These enumerations can be ORed together to form bit masks. The masks can be used as parameter by I2C_SlaveClearStatusFlags, or as return value by I2C_SlaveGetStatusFlags.
| Enumerator |
|---|
| kI2C_SlaveReadRequestInterruptFlag |
Sets when I2C as slave and master tries to read data from it.
bit 5
|
| kI2C_SlaveNackInterruptFlag |
Sets when I2C as slave transmiter and was nacked by master, indicating tx complete.
bit 7
|
| kI2C_SlaveGeneralCallAckInterruptFlag |
Sets when general call address is received and acknowledged.
bit 11
|
| kI2C_SlaveFlushTxFifoFlag |
Sets when I2C slave receives a read command but there are still old data remaining in tx FIFO.
Cleared when kI2C_TxAbortInterruptFlag is cleared. bit 13
|
| kI2C_SlaveArbitrationLostFlag |
Sets when data on bus is not the same as slave sends.
Cleared when kI2C_TxAbortInterruptFlag is cleared. bit 14
|
| kI2C_SlaveReadWhenRequestedDataFlag |
Sets when I2C slave is request data from master but use read command.
Cleared when kI2C_TxAbortInterruptFlag is cleared. bit 15
|
| kI2C_SlaveDisabledWhileBusy |
Sets when I2C slave is busy while disabled.
If slave is addressed when disabled, slave will nack the master even address matched, if slave is receiveing slave will nack the transfer immediately. Cleared when module is re-eanbled. bit 16
|
| kI2C_SlaveRxDataLost |
Sets when I2C slave is actively
receiving data when disabled, and at least one byte have been received.
Cleared when module is re-eanbled. bit 17
|
| kI2C_SlaveActiveFlag |
Sets when I2C slave operation is active.
bit 31
|
| kI2C_SlaveAutoClearFlags |
These flags are cleared automatically according to module status, or when other status bit is cleared.
eg. once tx FIFO is not empty kI2C_TxFifoEmptyFlag is cleared automatically. eg. kI2C_SlaveFlushTxFifoFlag, kI2C_SlaveArbitrationLostFlag and kI2C_SlaveReadWhenRequestedDataFlag are cleared when kI2C_TxAbortInterruptFlag is cleared.
|
| kI2C_SlaveAllClearFlags |
All flags which are clearable.
|
These enumerations can be ORed together to form bit masks. The masks can be used as parameter by I2C_EnableInterrupts, I2C_DisableInterrupts, or as return value by I2C_GetEnabledInterrupts.
| Enumerator |
|---|
| kI2C_RxUnderflowInterruptEnable |
Rx FIFO underflow interrupt.
bit 0
|
| kI2C_RxOverflowInterruptEnable |
Rx FIFO overflow interrupt.
bit 1
|
| kI2C_RxDataReadyInterruptEnable |
Rx data ready interrupt.
bit 2
|
| kI2C_TxOverflowInterruptEnable |
Tx FIFO overflow interrupt.
bit 3
|
| kI2C_TxRequestInterruptEnable |
Tx data request interrupt.
bit 4
|
| kI2C_SlaveReadRequestInterruptEnable |
I2C slave requested data by master interrupt.
bit 5
|
| kI2C_TxAbortInterruptEnable |
Tx abort interrupt.
bit 6
|
| kI2C_SlaveNackInterruptEnable |
I2C slave nack interrupt.
bit 7
|
| kI2C_BusBusyInterruptEnable |
I2C bus busy interrupt.
bit 8
|
| kI2C_StopDetectInterruptEnable |
I2C stop condition detect interrupt.
bit 9
|
| kI2C_StartDetectInterruptEnable |
I2C start condition detect interrupt.
bit 10
|
| kI2C_SlaveGeneralCallAckInterruptEnable |
I2C ganaral call detect and acknowledge interrupt.
bit 11
|
| Enumerator |
|---|
| kI2C_MasterSpeedStandard |
Standard mode, 100kbps.
|
| kI2C_MasterSpeedFast |
Fast mode, 400kbps.
|
| kI2C_MasterSpeedHigh |
High speed mode, 3.4Mbps.
|
| Enumerator |
|---|
| kI2C_AddressMatch7bit |
7-bit addressing mode.
|
| kI2C_AddressMatch10bit |
10-bit addressing mode.
|
| Enumerator |
|---|
| kQSPI_DmaRx |
Receive DMA Enable Flag.
|
| kQSPI_DmaTx |
Transmit DMA Enable Flag.
|
| Enumerator |
|---|
| kI2C_Write |
Master transmit.
|
| kI2C_Read |
Master receive.
|
This enumeration lists all the protocol level events that may happen during slave transfer. They can be used for two related purposes:
- User can select certain events and combined them by OR operation to form a mask, and use the mask to configure slave transfer configuration stucture i2c_slave_transfer_t::u8EventMask. If any of these selected events happens, driver will alert user by invoking callback.
- When slave callback is invoked, user has to know which specific event occured. Callback uses slave transfer configuration structure i2c_slave_transfer_t as 2nd parameter, its member i2c_slave_transfer_t::eEvent shows which event just happened.
| Enumerator |
|---|
| kI2C_SlaveStartDetectEvent |
A start/repeated start was detected.
|
| kI2C_SlaveGenaralcallEvent |
Received the general call address after a start or repeated start.
|
| kI2C_SlaveTransmitEvent |
Slave runs out of data to transmit, request a new data buffer.
|
| kI2C_SlaveReceiveEvent |
Slave runs out of space to store received data, request a new data buffer.
|
| kI2C_SlaveCompletionEvent |
Slave detects a stop signal, or slave is nacked by master during master-receive, or slave has finished transmit/receive previously configured amount of data.
|
| kI2C_SlaveAllEvents |
A bit mask of all available events.
|
| static uint32_t I2C_MasterGetStatusFlags |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- the mask of status flags, can be a single flag or several flags in _i2c_master_status_flags ORed together
| void I2C_MasterClearStatusFlags |
( |
I2C_Type * |
base, |
|
|
uint32_t |
statusFlags |
|
) |
| |
- Parameters
-
| base | I2C base pointer |
| statusFlags | The status flag mask, can be a single flag or several flags in _i2c_status_flags ORed together. |
| static uint32_t I2C_SlaveGetStatusFlags |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- the mask of status flags, can be a single flag or several flags in _i2c_status_flags ORed together
| void I2C_SlaveClearStatusFlags |
( |
I2C_Type * |
base, |
|
|
uint32_t |
statusFlags |
|
) |
| |
- Parameters
-
| base | I2C base pointer |
| statusFlags | The status flag mask, can be a single flag or several flags in _i2c_slave_status_flags ORed together |
| static void I2C_EnableInterrupts |
( |
I2C_Type * |
base, |
|
|
uint16_t |
interrupts |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| interrupts | The interrupt source mask, can be a single source or several sources in _i2c_interrupt_enable ORed together |
| static void I2C_DisableInterrupts |
( |
I2C_Type * |
base, |
|
|
uint16_t |
interrupts |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| interrupts | The interrupt source mask, can be a single source or several sources in _i2c_interrupt_enable ORed together |
| static uint16_t I2C_GetEnabledInterrupts |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- The interrupt source mask, can be a single source or several sources in _i2c_interrupt_enable ORed together
The purpose of this API is to initialize the configuration structure to default value for I2C_MasterInit to use. Use the unchanged structure in I2C_MasterInit or modify the structure before calling I2C_MasterInit. This is an example:
- Parameters
-
| masterConfig | Pointer to the master configuration structure |
| void I2C_MasterInit |
( |
I2C_Type * |
base, |
|
|
const i2c_master_config_t * |
masterConfig, |
|
|
uint32_t |
sourceClock_Hz |
|
) |
| |
This API initialize the I2C module for master operation.
- Note
- If FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL is enbaled by user, the init function will not ungate I2C clock source before initialization, to avoid hardfault, user has to manually enable ungate the clock source before calling the API
The configuration structure can be filled manully or be set with default values by calling I2C_MasterGetDefaultConfig. This is an example.
- Parameters
-
| base | I2C base pointer |
| masterConfig | Pointer to the master configuration structure |
| sourceClock_Hz | Frequency in Hertz of the I2C functional clock source |
| void I2C_MasterDeinit |
( |
I2C_Type * |
base | ) |
|
Call this API to disable the I2C module.
- Parameters
-
The purpose of this API is to initialize the configuration structure for I2C_SlaveInit to use. Use the unchanged initialized structure in I2C_SlaveInit or modify the structure before calling I2C_SlaveInit. This is an example.
* config.slaveAdress = 0x7FU;
*
- Parameters
-
| slaveConfig | Pointer to the slave configuration structure |
This API initialize the I2C module for slave operation. User can also configure whether to enable the module in the function.
- Note
- If FSL_SDK_DISABLE_DRIVER_CLOCK_CONTROL is enbaled by user, the init function will not ungate I2C clock source before initialization, to avoid hardfault, user has to manually ungate the clock source before calling the API
The configuration structure can be filled manully or be set with default values by calling I2C_SlaveGetDefaultConfig. This is an example.
* sConfig.address = 0x2AU;
*
- Parameters
-
| base | I2C base pointer |
| slaveConfig | Pointer to the slave configuration structure |
| void I2C_SlaveDeinit |
( |
I2C_Type * |
base | ) |
|
Call this API to disable the I2C module.
- Parameters
-
| static void I2C_SetRxWaterMark |
( |
I2C_Type * |
base, |
|
|
uint8_t |
rxWaterMark |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| rxWaterMark | rx watermark level |
| static void I2C_SetTxWaterMark |
( |
I2C_Type * |
base, |
|
|
uint8_t |
txWaterMark |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| txWaterMark | tx watermark level |
| static void I2C_Enable |
( |
I2C_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| enable | Pass true to enable and false to disable the module |
| static void I2C_EnableMaster |
( |
I2C_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| enable | Pass true to enable as master and false to enable as slave |
| static uint8_t I2C_GetTxFifoDataCount |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- The data count in tx FIFO
| static uint8_t I2C_GetRxFifoDataCount |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- The data count in rx FIFO
| static uint8_t I2C_GetTxFifoDepth |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- The tx FIFO depth
| static uint8_t I2C_GetRxFifoDepth |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- The rx FIFO depth
| static void I2C_SetSdaHoldTime |
( |
I2C_Type * |
base, |
|
|
uint16_t |
sdaHoldTime |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| sdaHoldTime | Number of clock source cycles of SDA hold time |
| static void I2C_SetSdaSetupTime |
( |
I2C_Type * |
base, |
|
|
uint16_t |
sdaSetupTime |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| sdaSetupTime | Number of clock source cycles of SDA setup time |
| static void I2C_EnableAckGeneralCall |
( |
I2C_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| enable | Pass true to enable and false to disable |
| static bool I2C_IsEnabled |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- True for enabled, false for disabled.
| static void I2C_SetGlitchFilter |
( |
I2C_Type * |
base, |
|
|
uint8_t |
glitchFilter |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| glitchFilter | Number of clock source cycles of max glitch time |
| static void I2C_SetGlitchFilterHighSpeed |
( |
I2C_Type * |
base, |
|
|
uint8_t |
glitchFilter |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| glitchFilter | Number of clock source cycles of max glitch time |
| static void I2C_MasterSetHighSpeedAddress |
( |
I2C_Type * |
base, |
|
|
uint8_t |
address |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| address | High speed address, only low 3 bits are avaliable |
| static bool I2C_IsMaster |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Note
- Although I2C can not be master and slave at the same time, when I2C is not in master mode does not mean it's in slave mode, the master and slave function may both be disabled.
- Parameters
-
- Returns
- True for master mode enabled, false for disabled.
| static void I2C_MasterSetAddressingMode |
( |
I2C_Type * |
base, |
|
|
i2c_address_mode_t |
addressingMode |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| addressingMode | The I2C addressing mode master operates |
| static void I2C_MasterSetTargetAddress |
( |
I2C_Type * |
base, |
|
|
uint16_t |
address |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| address | The I2C addressing mode master operates |
| static void I2C_MasterEnableGeneralCall |
( |
I2C_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| enable | True to issue general call, false to issue common start byte according to target address |
After the I2C module is initialized as master, user can call this function to change the transfer baud rate. There are 3 speed modes to choos from, kI2C_MasterSpeedStandard for 100kbps, kI2C_MasterSpeedFast for 400kbps and kI2C_MasterSpeedHigh for 3.4Mbps.
- Parameters
-
| base | I2C base pointer. |
| speed | Master transfer speed mode to be configured |
| sourceClock_Hz | I2C peripheral clock frequency in Hz |
| static bool I2C_IsSlave |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Note
- Although I2C can not be master and slave at the same time, when I2C is not in slave mode does not mean it's in master mode, the master and slave function may both be disabled.
- Parameters
-
- Returns
- True for slave mode enabled, false for disabled.
| static void I2C_SlaveSetAddressingMode |
( |
I2C_Type * |
base, |
|
|
i2c_address_mode_t |
addressingMode, |
|
|
uint16_t |
address |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| addressingMode | The I2C addressing mode slave resonses to |
| address | The I2C address, for 7-bit only low 7 bits are valid and for 10-bit only low 10 bits are valid |
| static uint8_t I2C_ReadByte |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- The data read from data register.
| static void I2C_WriteByte |
( |
I2C_Type * |
base, |
|
|
uint8_t |
data |
|
) |
| |
|
inlinestatic |
- Note
- If using I2C as master to perform read operation, user needs to write dummy to data register to generate clock, do not use this API to write dummy since this API will issue write command simultaneously, use I2C_MasterWriteDummy.
- Parameters
-
| base | I2C base pointer |
| data | The byte to write. |
| static void I2C_EnableDMA |
( |
I2C_Type * |
base, |
|
|
uint8_t |
mask |
|
) |
| |
|
inlinestatic |
| static void I2C_DisableDMA |
( |
I2C_Type * |
base, |
|
|
uint8_t |
mask |
|
) |
| |
|
inlinestatic |
| static void I2C_SetDmaTxWaterMark |
( |
I2C_Type * |
base, |
|
|
uint8_t |
txLevel |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| txLevel | tx DMA trigger level |
| static void I2C_SetDmaRxWaterMark |
( |
I2C_Type * |
base, |
|
|
uint8_t |
rxLevel |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| rxLevel | rx DMA trigger level |
| static uint32_t I2C_GetDataRegAddr |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- The I2C Data Register address.
| static void I2C_MasterWriteDummy |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Note
- If using I2C as master to perform read operation, user needs to write dummy to data register to generate clock, use this API not I2C_WriteByte to write dummy, since I2C_WriteByte issue write command simultaneously.
- Parameters
-
| status_t I2C_MasterCheckAndClearError |
( |
I2C_Type * |
base, |
|
|
uint32_t |
status |
|
) |
| |
- Note
- : The API only checks the error status that occured on bus, error caused by user misuse such as kI2C_RxUnderflowInterruptFlag, kI2C_TxOverflowInterruptFlag or kI2C_MasterOperateWhenDisabledFlag will not be checked
- Parameters
-
| base | The I2C peripheral base address. |
| status | Status flags to check. |
- Return values
-
| status_t I2C_MasterWriteBlocking |
( |
I2C_Type * |
base, |
|
|
const uint8_t * |
data, |
|
|
size_t |
txSize |
|
) |
| |
Call this function when using I2C as master to send certain bytes of data to bus. This function uses the blocking way, which means it does not return until all the data is sent to bus.
- Note
- The I2C module generates START/STOP/RESTART automatically. When tx FIFO state changes from empty to not empty, start signal is generated; when tx FIFO is empty again, stop signal is generated; when read command follows a write command, restart signal is generated in between. So stop signal will be generated after this API returns, and before calling this API if tx FIFO is empty, start signal will be generated first automatically, if tx FIFO is not empty and the last command in tx FIFO is write, restart signal will be generated first automatically.
- Parameters
-
| base | I2C base pointer. |
| data | The pointer to the data to be transmitted. |
| txSize | The length in bytes of the data to be transmitted. |
- Return values
-
| kStatus_Success | Successfully complete the data transmission. |
| kStatus_I2C_ArbitrationLost | Transfer error, arbitration lost. |
| kStatus_I2C_Nak | Transfer error, receive NAK during transfer. |
| kStatus_I2C_Addr_Nak | Transfer error, receive NAK during addressing, only applies when tx FIFO is empty before calling this API. |
| kStatus_I2C_Timeout | Transfer error, timeout happens when waiting for status flags to change. |
| status_t I2C_MasterReadBlocking |
( |
I2C_Type * |
base, |
|
|
uint8_t * |
data, |
|
|
size_t |
rxSize |
|
) |
| |
Call this function when using I2C as master to receive certain bytes of data from bus. This function uses the blocking way, which means it does not return until all the data is received or is nacked by slave.
- Note
- When doing read operation, software needs to push dummy data to tx FIFO with read command to generate clock, plus I2C module generates START/STOP/RESTART automatically, meaning when tx FIFO state changes from empty to not empty, start signal is generated, when tx FIFO is empty again, stop signal is generated, when read command follows a write command, restart signal is generated in between. So stop signal will be generated after this API returns, and before calling this API if tx FIFO is empty, start signal will be generated first automatically, if tx FIFO is not empty and the last command in tx FIFO is write, restart signal will be generated first automatically.
- Parameters
-
| base | I2C base pointer. |
| data | The pointer to the data to store the received data. |
| rxSize | The length in bytes of the data to be received. |
- Return values
-
| kStatus_Success | Successfully complete the data transmission. |
| kStatus_I2C_Timeout | Send stop signal failed, timeout. |
| static void I2C_SlaveNackNextByte |
( |
I2C_Type * |
base, |
|
|
bool |
enable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| enable | Pass true to enable nack and false to disable |
| status_t I2C_SlaveCheckAndClearError |
( |
I2C_Type * |
base, |
|
|
uint32_t |
status |
|
) |
| |
- Note
- : The API only checks the error status that occured on bus, error caused by user misuse such as kI2C_RxUnderflowInterruptFlag, kI2C_TxOverflowInterruptFlag, kI2C_SlaveReadWhenRequestedDataFlag or kI2C_SlaveDisabledWhileBusy will not be checked
- Parameters
-
| base | The I2C peripheral base address. |
| status | Status flags to check. |
- Return values
-
| status_t I2C_SlaveWriteBlocking |
( |
I2C_Type * |
base, |
|
|
const uint8_t * |
data, |
|
|
size_t |
txSize |
|
) |
| |
Call this funtion to let I2C slave poll register status until it is addressed, then slave sends txSize of data to bus until all the data has been sent to bus or untill it is nacked.
- Parameters
-
| base | I2C base pointer. |
| data | The pointer to the data to be transferred. |
| txSize | The length in bytes of the data to be transferred. |
- Return values
-
| status_t I2C_SlaveReadBlocking |
( |
I2C_Type * |
base, |
|
|
uint8_t * |
data, |
|
|
size_t |
rxSize |
|
) |
| |
Call this funtion to let I2C slave poll register status until it is addressed, then slave receives rxSize of data until all the data has been received.
- Parameters
-
| base | I2C base pointer. |
| data | The pointer to the data to store the received data. |
| rxSize | The length in bytes of the data to be received. |
- Return values
-
| kStatus_Success | Successfully complete data receive. |
| kStatus_I2C_Timeout | Wait status flag timeout. |
- Note
- The API does not return until the transfer succeeds or fails due to arbitration lost or receiving a NAK.
- Parameters
-
| base | I2C base pointer. |
| transferConfig | Pointer to the transfer configuration structure. |
- Return values
-
This function is responsible for initializig master transfer handle, installing user callback, registering master IRQ handling function and opening global interrupt.
- Parameters
-
| base | I2C base pointer. |
| handle | pointer to i2c_master_transfer_handle_t structure to store the transfer state. |
| callback | pointer to user callback function. |
| userData | User configurable pointer to any data, function, structure etc that user wish to use in the callback |
- Note
- Transfer in interrupt way is non-blocking which means this API returns immediately after transfer initiates. User can call I2C_MasterTransferGetCount to get the count of data that master has transmitted/received and check transfer status. If the return status is kStatus_NoTransferInProgress, the transfer is finished. Also if user installs a user callback when calling I2C_MasterTransferCreateHandle before, the callback will be invoked when transfer finishes.
- Parameters
-
| base | I2C base pointer |
| handle | pointer to i2c_master_transfer_handle_t structure which stores the transfer state. |
| transfer | Pointer to the transfer configuration structure. |
- Return values
-
| kStatus_Success | Successfully start the data transmission. |
| kStatus_I2C_Busy | Previous transmission still not finished. |
| status_t I2C_MasterTransferGetCount |
( |
I2C_Type * |
base, |
|
|
i2c_master_handle_t * |
handle, |
|
|
size_t * |
count |
|
) |
| |
- Parameters
-
| base | I2C base pointer. |
| handle | pointer to i2c_master_transfer_handle_t structure which stores the transfer state. |
| count | Pointer to number of bytes transferred so far by the non-blocking transaction. |
- Return values
-
| kStatus_InvalidArgument | count is Invalid. |
| kStatus_NoTransferInProgress | Curent no transfer is in progress. |
| kStatus_Success | Successfully obtained the count. |
| void I2C_MasterTransferAbort |
( |
I2C_Type * |
base, |
|
|
i2c_master_handle_t * |
handle |
|
) |
| |
- Note
- This API can be called at any time after a transfer of interrupt way initiates and before it finishes to abort the transfer early.
- Parameters
-
| base | I2C base pointer. |
| handle | pointer to i2c_master_handle_t structure which stores the transfer state |
This function is responsible for initializig slave transfer handle, installing user callback, registering master IRQ handling function and opening global interrupt.
- Parameters
-
| base | I2C base pointer |
| handle | pointer to i2c_slave_handle_t structure to store the transfer state |
| callback | pointer to user callback function |
| userData | User configurable pointer to any data, function, structure etc that user wish to use in the callback |
Call this API to let I2C start monitoring bus events driven by I2C master on bus. When user specified event occurs, callback will be invoked passes event information to the callback.
- Note
- When kI2C_SlaveTransmitEvent and kI2C_SlaveReceiveEvent occured, slave callback will always be revoked regardless which events user choose to enable. This means user need not configure them in the eventMask. If user wants to enable all the events, use kI2C_SlaveAllEvents for convenience.
- Parameters
-
| base | The I2C peripheral base address. |
| handle | Pointer to i2c_slave_handle_t structure which stores the transfer state. |
| eventMask | Bit mask formed by OR operation of event(s) in i2c_slave_transfer_event_t enumerators. When these events occur the callback will be invoked. |
- Return values
-
| kStatus_I2C_Busy | I2C slave has already been started on this handle. |
- Parameters
-
| base | I2C base pointer. |
| handle | pointer to i2c_slave_handle_t structure. |
| count | Number of bytes slave have transferred after the last start/repeated start. |
- Return values
-
| kStatus_InvalidArgument | count is Invalid. |
| kStatus_NoTransferInProgress | Curent no transfer is in progress. |
| kStatus_Success | Successfully obtained the count. |
- Note
- This API can be called at any time to stop slave for handling further bus events.
- Parameters
-
| base | I2C base pointer. |
| handle | pointer to i2c_slave_handle_t structure which stores the transfer state. |
| uint32_t I2C_GetInstance |
( |
I2C_Type * |
base | ) |
|
- Parameters
-
- Return values
-
| The | number of the instance. |
| const IRQn_Type s_I2cIrqs[] |
