This document consists of sections titled with Driver Overview, Data Structures, Enumerations, Functions, etc., each with an overview list and detailed documentation. It is recommended to read the Driver Overview first for it includes a comprehensive description of the peripheral, driver and driver changes. Other sections give detailed information for APIs, enums, macros, etc., for your further reference.
|
| #define | I2C_RETRY_TIMES 0U /* Default defines to zero, driver keeps checking status flag untill it changes. */ |
| | Retry times when checking status flags. More...
|
| |
| #define | I2C_SMBUS_ENABLE 0U /* Default defines to zero, driver uses simple I2C transfer. */ |
| | Control whether to use SMBus featues. More...
|
| |
| #define | I2C_MASTER_FACK_CONTROL 0U /* Default defines to zero means master will send ack automatically. */ |
| | Control whether to enable FACK for master read operation in non SMBus tranfer. 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_Pec_Error = MAKE_STATUS(kStatusGroup_I2C, 6)
} |
| | 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_InterruptPendingFlag = I2C_S_IICIF_MASK
,
kI2C_RangeAddressMatchInterruptFlag,
kI2C_ArbitrationLostInterruptFlag = I2C_S_ARBL_MASK
,
kI2C_AddressAsSlaveInterruptFlag
,
kI2C_StopDetectInterruptFlag = I2C_FLT_STOPF_MASK << 8,
kI2C_StartDetectInterruptFlag = I2C_FLT_STARTF_MASK << 8,
kI2C_SclLowTimeoutFlag = I2C_SMB_SLTF_MASK << 8,
kI2C_BusIdleFlag = I2C_SMB_SHTF1_MASK << 8,
kI2C_SdaLowTimeoutInterruptFlag,
kI2C_StatusAllFlags
} |
| | I2C hardware status flags. More...
|
| |
| enum | _i2c_interrupt_enable {
kI2C_GlobalInterruptEnable = I2C_C1_IICIE_MASK,
kI2C_StartStopDetectInterruptEnable = I2C_FLT_SSIE_MASK,
kI2C_SdaLowTimeoutInterruptEnable = I2C_SMB_SHTF2IE_MASK
} |
| | I2C interrupt enable/disable source. More...
|
| |
| enum | i2c_slave_address_mode_t {
kI2C_AddressMatch = 0x0U,
kI2C_AddressRangeMatch = 0X1U,
kI2C_AddressMatch10bit = 0X2U
} |
| | Slave addressing mode, address match or range address match. More...
|
| |
| enum | i2c_data_direction_t {
kI2C_Read = 0x0U,
kI2C_Write = 0x1U
} |
| | Peripheral data direction. More...
|
| |
| enum | _i2c_master_transfer_control_flags {
kI2C_TransferStartStopFlag = 0x0U,
kI2C_TransferNoStartFlag = 0x1U,
kI2C_TransferRepeatedStartFlag = 0x2U,
kI2C_TransferNoStopFlag = 0x4U
} |
| | I2C master transfer control flags. More...
|
| |
| enum | i2c_master_transfer_direction_t {
kI2C_MasterTransmit = 0x0U,
kI2C_MasterReceive = 0x1U
} |
| | Master transfer direction. More...
|
| |
| enum | i2c_slave_transfer_event_t {
kI2C_SlaveAddressMatchEvent,
kI2C_SlaveOutofTransmitDataEvent = 0x02U,
kI2C_SlaveOutofReceiveSpaceEvent,
kI2C_SlaveStartEvent = 0x08U,
kI2C_SlaveCompletionEvent,
kI2C_SlaveGenaralcallEvent = 0x20U,
kI2C_SlaveAllEvents
} |
| | Set of slave transfer events. More...
|
| |
|
| static bool | I2C_IsMaster (I2C_Type *base) |
| | Returns whether the I2C module is in master mode. More...
|
| |
| static void | I2C_Reset (I2C_Type *base) |
| | Sets the I2C register value to reset value. More...
|
| |
| static void | I2C_Enable (I2C_Type *base, bool bEnable) |
| | Enables or disables the I2C peripheral operation. More...
|
| |
| static void | I2C_EnableFastAck (I2C_Type *base, bool bEnable) |
| | Enables/Disables fast NACK/ACK feature. More...
|
| |
| static void | I2C_EnableHighDrive (I2C_Type *base, bool bEnable) |
| | Enables/Disables high drive. More...
|
| |
| static void | I2C_EnableStopHold (I2C_Type *base, bool bEnable) |
| | Enables/Disables double buffer. More...
|
| |
| static void | I2C_SetTransferDirection (I2C_Type *base, i2c_data_direction_t eDataDirection) |
| | Sets I2C module data direction. More...
|
| |
| void | I2C_SetSclTimeoutValue (I2C_Type *base, uint16_t u16SclTimout_Ms, uint32_t u32SrcClockHz) |
| | brief Sets the I2C SCL timeout value. More...
|
| |
| void | I2C_SetGlitchFilter (I2C_Type *base, uint16_t u16GlitchFilter_Ns, uint32_t u32SrcClockHz) |
| | brief Sets the I2C master glitch filter width. More...
|
| |
| static void | I2C_EnableDMA (I2C_Type *base, bool bEnable) |
| | Enables/disables the I2C DMA request. More...
|
| |
| static uint32_t | I2C_GetDataRegAddr (I2C_Type *base) |
| | Gets the I2C data register address. More...
|
| |
|
| void | I2C_MasterSetBaudRate (I2C_Type *base, uint32_t u32BaudRateBps, uint32_t u32SrcClockHz) |
| | Sets the I2C master transfer baud rate. 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 u8Data) |
| | Writes one byte to the data register directly. More...
|
| |
| static void | I2C_SendAck (I2C_Type *base, bool bIsAck) |
| | Sends an acknowledge/non-acknowledge signal to the bus on the following receiving byte if SMB[FACK] is cleared, or on the current receiving byte if SMB[FACK] is set. More...
|
| |
|
| status_t | I2C_MasterStart (I2C_Type *base, uint8_t u8Address, i2c_master_transfer_direction_t eDirection) |
| | Sends a START signal on the I2C bus then the 7-bit slave address with transmit/receive bit. More...
|
| |
| status_t | I2C_MasterRepeatedStart (I2C_Type *base, uint8_t u8Address, i2c_master_transfer_direction_t eDirection) |
| | Sends a repeated START signal, then the 7-bit slave address with transmit/receive bit to I2C bus. More...
|
| |
| status_t | I2C_MasterStop (I2C_Type *base) |
| | Sends a STOP signal on the I2C bus. More...
|
| |
| status_t | I2C_MasterWriteBlocking (I2C_Type *base, const uint8_t *pu8TxBuff, uint16_t txSize, bool bSendStop) |
| | Sends a piece of data to I2C bus in master mode in blocking way. More...
|
| |
| status_t | I2C_MasterReadBlocking (I2C_Type *base, uint8_t *pu8RxBuff, uint16_t rxSize, bool bSendStop) |
| | Receives a piece of data from I2C bus in master mode in blocking way. 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.
| uint32_t i2c_master_config_t::bEnableModule |
| uint32_t i2c_master_config_t::bEnableStopHold |
| uint32_t i2c_master_config_t::u8GlitchFilterWidth |
| uint32_t i2c_master_config_t::u8Interrupts |
| uint32_t i2c_master_config_t::u32BaudRateBps |
| uint32_t i2c_master_config_t::u32SrcClockHz |
| 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.
| uint32_t i2c_slave_config_t::bEnableModule |
| uint32_t i2c_slave_config_t::bEnableStopHold |
| uint32_t i2c_slave_config_t::u8GlitchFilterWidth |
| uint32_t i2c_slave_config_t::bEnableWakeUp |
| uint32_t i2c_slave_config_t::bEnableGeneralCall |
General call address is 0x00. I2C_C2_GCAEN
| uint32_t i2c_slave_config_t::eAddressingMode |
| uint32_t i2c_slave_config_t::bitsPrimaryAddress |
I2C_A1_AD[7] I2C_C2_AD[3]
| uint32_t i2c_slave_config_t::bitsMaxAddress |
In range address match, address greater than primary address and less than or equal to upper address is marked as matched. I2C_RA_RAD[7]
| uint32_t i2c_slave_config_t::u8Interrupts |
| uint32_t i2c_slave_config_t::u32SclStopHoldTime_ns |
| uint32_t i2c_slave_config_t::u32SrcClockHz |
This structure includes all I2C features, user can configure user can configure these features one by one manually, or call I2C_GetDefaultConfig to set the structure to default value. Then, call I2C_Init to initialize I2C module. To deinitialize I2C, call I2C_Deinit.
| uint32_t i2c_config_t::bEnableModule |
| uint32_t i2c_config_t::bEnableStopHold |
| uint32_t i2c_config_t::u8GlitchFilterWidth |
| uint32_t i2c_config_t::bEnableWakeUp |
| uint32_t i2c_config_t::bEnableGeneralCall |
General call address is 0x00. I2C_C2_GCAEN
| uint32_t i2c_config_t::eAddressingMode |
| uint32_t i2c_config_t::bitsPrimaryAddress |
I2C_A1_AD[7] I2C_C2_AD[3]
| uint32_t i2c_config_t::bitsMaxAddress |
In range address match, address greater than primary address and less than or equal to upper address is marked as matched. I2C_RA_RAD[7]
| uint32_t i2c_config_t::u8Interrupts |
| uint32_t i2c_config_t::u32BaudRateBps |
| uint32_t i2c_config_t::u32SrcClockHz |
| 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.
| uint8_t i2c_master_transfer_t::u8ControlFlagMask |
| uint8_t i2c_master_transfer_t::u8SlaveAddress |
| uint8_t* i2c_master_transfer_t::pu8Command |
| uint8_t i2c_master_transfer_t::u8CommandSize |
| uint8_t* volatile i2c_master_transfer_t::pu8Data |
| volatile uint16_t i2c_master_transfer_t::u16DataSize |
| struct _i2c_master_transfer_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 u8State in application level. If user only wish to use transactional APIs without understanding its machanism, it is not necessary to understand these members.
| I2C_Type* i2c_master_transfer_handle_t::base |
| uint16_t i2c_master_transfer_handle_t::u16TransferSize |
| uint8_t i2c_master_transfer_handle_t::u8State |
| status_t i2c_master_transfer_handle_t::completionStatus |
| 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 i2c_slave_transfer_t::u8EventMask |
When these enents occur during transfer driver will alert user using callback.
| uint8_t* volatile i2c_slave_transfer_t::pu8Data |
| volatile uint16_t i2c_slave_transfer_t::u16DataSize |
| struct _i2c_slave_transfer_handle |
Forward declaration of the I2C slave transfer handle structure.
- 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 u8State in application level. If user only wish to use transactional APIs without understanding its machanism, it is not necessary to understand these members.
| I2C_Type* i2c_slave_transfer_handle_t::base |
| uint16_t i2c_slave_transfer_handle_t::u16TransferredCount |
| uint8_t i2c_slave_transfer_handle_t::u8State |
| status_t i2c_slave_transfer_handle_t::completionStatus |
| void* i2c_slave_transfer_handle_t::pUserData |
| #define I2C_RETRY_TIMES 0U /* Default defines to zero, driver keeps checking status flag untill it changes. */ |
| #define I2C_SMBUS_ENABLE 0U /* Default defines to zero, driver uses simple I2C transfer. */ |
| #define I2C_MASTER_FACK_CONTROL 0U /* Default defines to zero means master will send ack automatically. */ |
This is used to lower transfer speed by clock stretch for MCU with FSL_FEATURE_I2C_HAS_DOUBLE_BUFFERING supported and enabled.
| typedef void(* i2c_master_transfer_callback_t)(i2c_master_transfer_handle_t *psHandle) |
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
-
| psHandle | I2C transfer handle, which contains the information of base pointer, completionStatus and user data. |
| typedef void(* i2c_slave_transfer_callback_t)(i2c_slave_transfer_handle_t *psHandle) |
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
-
| psHandle | I2C transfer handle, which contains the information of base pointer, completionStatus transfer data, data length and user data. |
| 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_Pec_Error |
Detected NACK for the PEC byte in transmit, or the received PEC does not match with the calculated CRC.
|
These enumerations can be ORed together to form bit masks. The masks can be used as parameter by I2C_MasterClearStatusFlags and I2C_SlaveClearStatusFlags, or as return value by I2C_MasterGetStatusFlags and I2C_SlaveGetStatusFlags.
| Enumerator |
|---|
| kI2C_InterruptPendingFlag |
I2C interrupt pending flag.
Byte transfer complete, address match, arbitration lost, start/stop detection and SMBus timeout can all cause this status bit to set. This flag can be cleared.
|
| kI2C_RangeAddressMatchInterruptFlag |
Received address is within address range.
This flag can be cleared.
|
| kI2C_ArbitrationLostInterruptFlag |
This flag can be cleared.
|
| kI2C_AddressAsSlaveInterruptFlag |
Addressed as slave, including general call, alert response, primary/secondary address and range address match.
This flag can be cleared.
|
| kI2C_StopDetectInterruptFlag |
This flag can be cleared.
|
| kI2C_StartDetectInterruptFlag |
This flag can be cleared.
|
| kI2C_SclLowTimeoutFlag |
I2C SCL signal low timeout flag.
This flag can be cleared.
|
| kI2C_BusIdleFlag |
I2C SCL and SDA both high timeout flag indicating bus idle.
|
| kI2C_SdaLowTimeoutInterruptFlag |
I2C SDA signal low timeout flag.
This flag can be cleared.
|
| kI2C_StatusAllFlags |
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_GetEnbaledInterrupts.
| Enumerator |
|---|
| kI2C_GlobalInterruptEnable |
I2C global interrupt.
|
| kI2C_StartStopDetectInterruptEnable |
I2C start&stop detect interrupt.
|
| kI2C_SdaLowTimeoutInterruptEnable |
I2C SDA low timeout interrupt.
|
| Enumerator |
|---|
| kI2C_AddressMatch |
7-bit addressing mode.
|
| kI2C_AddressRangeMatch |
Range address match addressing mode.
|
| kI2C_AddressMatch10bit |
10-bit addressing mode.
|
| Enumerator |
|---|
| kI2C_Read |
I2C read data from bus.
|
| kI2C_Write |
I2C write data to bus.
|
These flags can be ORed together to form bit mask. The mask is used to configure master transfer's start/stop condition in i2c_master_transfer_t::u8ControlFlagMask.
| Enumerator |
|---|
| kI2C_TransferStartStopFlag |
A transfer starts with a start signal, stops with a stop signal.
|
| kI2C_TransferNoStartFlag |
A transfer starts without a start signal, only support write only or write+read with no start flag, do not support read only with no start flag.
|
| kI2C_TransferRepeatedStartFlag |
A transfer starts with a repeated start signal.
|
| kI2C_TransferNoStopFlag |
A transfer ends without a stop signal.
|
| Enumerator |
|---|
| kI2C_MasterTransmit |
Master transmits data to slave.
|
| kI2C_MasterReceive |
Master receives data from slave.
|
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_SlaveAddressMatchEvent |
Slave detects general call or alert response address, or primary/secondary/range address is matched after a start or repeated start.
|
| kI2C_SlaveOutofTransmitDataEvent |
Slave runs out of data to transmit, request a new data buffer.
|
| kI2C_SlaveOutofReceiveSpaceEvent |
Slave runs out of space to store received data, request a new data buffer.
|
| kI2C_SlaveStartEvent |
A start/repeated start was detected.
|
| 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_SlaveGenaralcallEvent |
Received the general call address after a start or repeated start.
|
| kI2C_SlaveAllEvents |
A bit mask of all available events.
|
| void I2C_MasterGetDefaultConfig |
( |
i2c_master_config_t * |
psMasterConfig, |
|
|
uint32_t |
u32SrcClockHz |
|
) |
| |
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
-
| psMasterConfig | Pointer to the master configuration structure. |
| u32SrcClockHz | The clock source frequency for I2C module. |
This API initialize the I2C module for master operation, including the feature configuration of high drive capacity, doubble buffer, glitch filter, SCL timeout value, stop hold off enable and transfer baudrate. 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 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 |
| psMasterConfig | Pointer to the master configuration structure |
| void I2C_MasterDeinit |
( |
I2C_Type * |
base | ) |
|
Call this API to disable the I2C module.
- Parameters
-
| void I2C_SlaveGetDefaultConfig |
( |
i2c_slave_config_t * |
psSlaveConfig, |
|
|
uint16_t |
u16PrimaryAddress, |
|
|
uint32_t |
u32SrcClockHz |
|
) |
| |
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.
- Parameters
-
| psSlaveConfig | Pointer to the slave configuration structure. |
| u16PrimaryAddress | For 7-bit address low 7-bit is used, for 10-bit address low 10-bit is used. |
| u32SrcClockHz | The clock source frequency for I2C module. |
This API initialize the I2C module for slave operation, including the feature configuration of high drive capacity, doubble buffer, glitch filter, SCL timeout value, stop hold off enable, addressing mode, alert response/general call minitoring, auto baudrate control, low power mode wake up, SCL/SDA setup and hold time. 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 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_SlaveGetDefaultConfig. This is an example.
* sConfig.u8PrimaryAddress = 0x2AU;
*
- Parameters
-
| base | I2C base pointer |
| psSlaveConfig | Pointer to the slave configuration structure |
| static void I2C_SlaveDeinit |
( |
I2C_Type * |
base | ) |
|
|
static |
Call this API to disable the I2C module.
- Parameters
-
| void I2C_GetDefaultConfig |
( |
i2c_config_t * |
psConfig, |
|
|
uint16_t |
u16PrimaryAddress, |
|
|
uint32_t |
u32SrcClockHz |
|
) |
| |
The purpose of this API is to initialize the configuration structure for I2C_Init to use. Use the unchanged initialized structure in I2C_Init or modify the structure before calling I2C_Init. This is an example.
- Parameters
-
| psConfig | Pointer to the slave configuration structure. |
| u16PrimaryAddress | For 7-bit address low 7-bit is used, for 10-bit address low 10-bit is used. |
| u32SrcClockHz | The clock source frequency for I2C module. |
| void I2C_Init |
( |
I2C_Type * |
base, |
|
|
const i2c_config_t * |
psConfig |
|
) |
| |
This API initialize the I2C module, including the feature configuration of high drive capacity, doubble buffer, glitch filter, SCL timeout value, stop hold off enable, addressing mode, alert response/general call minitoring, auto baudrate control, low power mode wake up and baudrate. 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 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_GetDefaultConfig. This is an example.
- Parameters
-
| base | I2C base pointer |
| psConfig | Pointer to the I2C configuration structure |
| static void I2C_Deinit |
( |
I2C_Type * |
base | ) |
|
|
static |
Call this API to disable the I2C module.
- Parameters
-
| uint16_t I2C_MasterGetStatusFlags |
( |
I2C_Type * |
base | ) |
|
- Parameters
-
- Returns
- the mask of status flags, can be a single flag or several flags in _i2c_status_flags ORed together.
| static void I2C_MasterClearStatusFlags |
( |
I2C_Type * |
base, |
|
|
uint16_t |
u16StatusFlags |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| u16StatusFlags | The status flag mask, can be a single flag or several flags in _i2c_status_flags ORed together. These flags among _i2c_status_flags can be cleared:
- kI2C_StartDetectInterruptFlag (only supported on certain SoCs)
- kI2C_StopDetectInterruptFlag (only supported on certain SoCs)
- kI2C_ArbitrationLostInterruptFlag
- kI2C_InterruptPendingFlag
- kI2C_RangeAddressMatchInterruptFlag
- kI2C_AddressAsSlaveInterruptFlag
- kI2C_SclLowTimeoutFlag
- kI2C_SdaLowTimeoutInterruptFlag
|
| static uint16_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.
| static void I2C_SlaveClearStatusFlags |
( |
I2C_Type * |
base, |
|
|
uint16_t |
u16StatusFlags |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| u16StatusFlags | The status flag mask, can be a single flag or several flags in _i2c_status_flags ORed together. These flags among _i2c_status_flags can be cleared:
- kI2C_StartDetectInterruptFlag (only supported on certain SoCs)
- kI2C_StopDetectInterruptFlag (only supported on certain SoCs)
- kI2C_ArbitrationLostInterruptFlag
- kI2C_InterruptPendingFlag
- kI2C_RangeAddressMatchInterruptFlag
- kI2C_AddressAsSlaveInterruptFlag
- kI2C_SclLowTimeoutFlag
- kI2C_SdaLowTimeoutInterruptFlag
|
| void I2C_EnableInterrupts |
( |
I2C_Type * |
base, |
|
|
uint8_t |
u8Interrupts |
|
) |
| |
- Note
- Before enabling kI2C_GlobalInterruptEnable, check kI2C_RangeAddressMatchInterruptFlag and kI2C_AddressAsSlaveInterruptFlag first, because any write operation on C1 will clear these 2 bits.
- Parameters
-
| base | I2C base pointer |
| u8Interrupts | The interrupt source mask, can be a single source or several sources in _i2c_interrupt_enable ORed together. |
| void I2C_DisableInterrupts |
( |
I2C_Type * |
base, |
|
|
uint8_t |
u8Interrupts |
|
) |
| |
- Note
- Before disabling kI2C_GlobalInterruptEnable, check kI2C_RangeAddressMatchInterruptFlag and kI2C_AddressAsSlaveInterruptFlag first, because any write operation on C1 will clear these 2 bits.
- Parameters
-
| base | I2C base pointer |
| u8Interrupts | The interrupt source mask, can be a single source or several sources in _i2c_interrupt_enable ORed together. |
| uint8_t I2C_GetEnabledInterrupts |
( |
I2C_Type * |
base | ) |
|
- Parameters
-
- Returns
- The interrupt source mask, can be a single source or several sources in _i2c_interrupt_enable ORed together.
| static bool I2C_IsMaster |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
- Parameters
-
- Returns
- True for master mode, false for slave mode.
| static void I2C_Reset |
( |
I2C_Type * |
base | ) |
|
|
static |
| static void I2C_Enable |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| bEnable | Pass true to enable and false to disable the module. |
| static void I2C_EnableFastAck |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
When enbled, writing 0/1 to TXAK generates an ACK/NACK after receiving a data byte, when disabled, writing 0/1 to TXAK generates an ACK/NACK on the following receiving data byte.
- Parameters
-
| base | I2C base pointer |
| True | to bEnable, false to disable. |
| static void I2C_EnableHighDrive |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| True | to bEnable, false to disable. |
| static void I2C_EnableStopHold |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| True | to bEnable, false to disable. |
- Parameters
-
| base | I2C base pointer |
| eDataDirection | kI2C_Write to write data to bus, kI2C_Read to read data from bua |
| void I2C_SetSclTimeoutValue |
( |
I2C_Type * |
base, |
|
|
uint16_t |
u16SclTimout_Ms, |
|
|
uint32_t |
u32SrcClockHz |
|
) |
| |
After the I2C module is initialized, user can call this function to change the timeout value.
param base I2C base pointer. param u16SclTimout_Ms The SCL timeout value in ms. param u32SrcClockHz I2C peripheral clock frequency in Hz
| void I2C_SetGlitchFilter |
( |
I2C_Type * |
base, |
|
|
uint16_t |
u16GlitchFilter_Ns, |
|
|
uint32_t |
u32SrcClockHz |
|
) |
| |
After the I2C module is initialized as master, user can call this function to change the glitch filter width.
param base I2C base pointer. param u16GlitchFilter_Ns The GLitch filter length in nano seconds. param u32SrcClockHz I2C peripheral clock frequency in Hz
| static void I2C_EnableDMA |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| bEnable | true to enable, false to disable |
| static uint32_t I2C_GetDataRegAddr |
( |
I2C_Type * |
base | ) |
|
|
inlinestatic |
This API is used to provide the transfer address for I2C DMA transfer.
- Parameters
-
- Returns
- data register address
| static void I2C_SlaveEnableAlertResponse |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
When enbled, I2C slave will monitor the bus line, and when alert response address is received address match status flag will be set.
- Parameters
-
| base | I2C base pointer |
| True | to bEnable, false to disable. |
| static void I2C_SlaveEnableSecondaryAddress |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| True | to bEnable, false to disable. |
| static void I2C_SlaveEnableGeneralCall |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| True | to bEnable, false to disable. |
| static void I2C_SlaveEnableWakeUp |
( |
I2C_Type * |
base, |
|
|
bool |
bEnable |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| True | to bEnable, false to disable. |
| void I2C_SlaveSetAddressingMode |
( |
I2C_Type * |
base, |
|
|
i2c_slave_address_mode_t |
eAddressingMode, |
|
|
uint16_t |
u16Address, |
|
|
uint8_t |
u8MaxAddress |
|
) |
| |
After the I2C module is initialized as slave, user can call this function to change the configuration of slave addressing mode.
- Parameters
-
| base | I2C base pointer. |
| eAddressingMode | The slave addressing mode, single address or range address. |
| u16Address | I2C slave address. For 7-bit address low 7-bit is used, for 10-bit address low 10-bit is used. |
| u8MaxAddress | The maximum boundary of slave address used in a range address match. |
| void I2C_MasterSetBaudRate |
( |
I2C_Type * |
base, |
|
|
uint32_t |
u32BaudRateBps, |
|
|
uint32_t |
u32SrcClockHz |
|
) |
| |
After the I2C module is initialized as master, user can call this function to change the transfer baud rate.
- Parameters
-
| base | I2C base pointer. |
| u32BaudRateBps | the baud rate value in bits-per-second. |
| u32SrcClockHz | I2C peripheral clock frequency in Hz |
| 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 |
u8Data |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| u8Data | The byte to write. |
| static void I2C_SendAck |
( |
I2C_Type * |
base, |
|
|
bool |
bIsAck |
|
) |
| |
|
inlinestatic |
- Parameters
-
| base | I2C base pointer |
| bIsAck | True to send ACK signal, false to send NACK signal |
This function is used to initiate a new transfer in master mode, by sending a START signal, then the slave address with transmit/receive bit to I2C bus.
- Note
- The return value of this API only indicates whether the start signal is sent to bus, user has to check kI2C_ArbitrationLostInterruptFlag and #kI2C_ReceiveNakFlag using I2C_MasterClearStatusFlags to see if valid slave device is avaliable or the aribitration is lost.
- Parameters
-
| base | I2C base pointer |
| u8Address | 7-bit slave device address. |
| eDirection | Master transfer directions(transmit/receive). |
- Return values
-
| kStatus_I2C_Timeout | Transfer error, timeout happens when waiting for status flags to change. |
| kStatus_Success | Successfully send the start signal. |
| kStatus_I2C_Busy | Current bus is busy. |
- Parameters
-
| base | I2C peripheral base pointer |
| u8Address | 7-bit slave device address. |
| eDirection | Master transfer directions(transmit/receive). |
- Return values
-
| kStatus_I2C_Timeout | Transfer error, timeout happens when waiting for status flags to change. |
| kStatus_Success | Successfully send the start signal. |
| kStatus_I2C_Busy | Current bus is busy but not occupied by current I2C master. |
| status_t I2C_MasterStop |
( |
I2C_Type * |
base | ) |
|
- Parameters
-
- Return values
-
| kStatus_Success | Successfully send the stop signal. |
| kStatus_I2C_Timeout | Send stop signal failed, timeout. |
| status_t I2C_MasterWriteBlocking |
( |
I2C_Type * |
base, |
|
|
const uint8_t * |
pu8TxBuff, |
|
|
uint16_t |
txSize, |
|
|
bool |
bSendStop |
|
) |
| |
Call this function when using I2C as master to send certain bytes of data to bus when start signal is already sent. User can specify whether to send a stop siganl after the data. This function uses the blocking way, which means it does not return until all the data is sent to bus and stop signal is successfully issued(if user configures the stop signal).
- Parameters
-
| base | I2C base pointer. |
| pu8TxBuff | The pointer to the data to be transmitted. |
| txSize | The length in bytes of the data to be transmitted. |
| bSendStop | Whether to send stop signal after the data transfer. |
- Return values
-
| kStatus_Success | Successfully complete the data transmission. |
| kStatus_I2C_ArbitrationLost | Transfer error, arbitration lost. |
| kStataus_I2C_Nak | Transfer error, receive NAK during transfer. |
| kStatus_I2C_Timeout | Transfer error, timeout happens when waiting for status flags to change. |
| status_t I2C_MasterReadBlocking |
( |
I2C_Type * |
base, |
|
|
uint8_t * |
pu8RxBuff, |
|
|
uint16_t |
rxSize, |
|
|
bool |
bSendStop |
|
) |
| |
Call this function when using I2C as master to receive certain bytes of data from bus when start signal is already sent. User can specify whether to send a stop siganl after the data. This function uses the blocking way, which means it does not return until all the data has been received and stop signal is successfully issued(if user configures the stop signal).
- Note
- If user configures to send stop signal after the data, this function stops the bus before reading the final byte from data register. Without stopping the bus prior to the final read, the bus will issue another read, resulting in garbage data being read into the data register.
- Parameters
-
| base | I2C base pointer. |
| pu8RxBuff | The pointer to the data to store the received data. |
| rxSize | The length in bytes of the data to be received. |
| bSendStop | Whether to send stop signal after the data transfer. |
- Return values
-
| kStatus_Success | Successfully complete the data transmission. |
| kStatus_I2C_Timeout | Send stop signal failed, timeout. |
| status_t I2C_SlaveWriteBlocking |
( |
I2C_Type * |
base, |
|
|
const uint8_t * |
pu8TxBuff, |
|
|
uint16_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. |
| pu8TxBuff | The pointer to the data to be transferred. |
| txSize | The length in bytes of the data to be transferred. |
- Return values
-
| kStatus_Success | Successfully complete the data transmission. |
| kStatus_I2C_ArbitrationLost | Transfer error, arbitration lost. |
| kStataus_I2C_Nak | Transfer error, receive NAK during transfer. |
| kStatus_I2C_Timeout | Transfer error, timeout happens when waiting for status flags to change. |
| status_t I2C_SlaveReadBlocking |
( |
I2C_Type * |
base, |
|
|
uint8_t * |
pu8RxBuff, |
|
|
uint16_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. |
| pu8RxBuff | 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 peripheral base address. |
| psTransferConfig | Pointer to the transfer configuration structure. |
- Return values
-
| kStatus_Success | Successfully complete the data transmission. |
| kStatus_I2C_Busy | Previous transmission still not finished. |
| kStatus_I2C_Timeout | Transfer error, timeout happens when waiting for status flagsto change. |
| kStatus_I2C_ArbitrationLost | Transfer error, arbitration lost. |
| #kStataus_I2C_Nak | Transfer error, receive NAK during transfer. |
| void I2C_MasterTransferCreateHandle |
( |
I2C_Type * |
base, |
|
|
i2c_master_transfer_handle_t * |
psHandle, |
|
|
i2c_master_transfer_callback_t |
pfCallback, |
|
|
void * |
pUserData |
|
) |
| |
This function is responsible for initializig master transfer psHandle, installing user callback, registering master IRQ handling function and opening global interrupt.
- Parameters
-
| base | I2C base pointer. |
| psHandle | pointer to i2c_master_transfer_handle_t structure to store the transfer state. |
| pfCallback | pointer to user callback function. |
| pUserData | 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
-
| psHandle | pointer to i2c_master_transfer_handle_t structure which stores the transfer state. |
| psTransferConfig | Pointer to the transfer configuration structure. |
- Return values
-
| kStatus_Success | Successfully start the data transmission. |
| kStatus_I2C_Busy | Previous transmission still not finished. |
| kStatus_I2C_Timeout | Transfer error, timeout happens when waiting for status flagsto change. |
| status_t I2C_MasterTransferGetCount |
( |
i2c_master_transfer_handle_t * |
psHandle, |
|
|
uint16_t * |
count |
|
) |
| |
- Parameters
-
| base | I2C base pointer. |
| psHandle | 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. |
| status_t I2C_MasterTransferAbort |
( |
i2c_master_transfer_handle_t * |
psHandle | ) |
|
- 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. |
| psHandle | pointer to i2c_master_transfer_handle_t structure which stores the transfer state |
- Return values
-
| kStatus_I2C_Busy | Master lost arbitration, bus is in use by other master. |
| kStatus_I2C_Timeout | Transfer error, timeout happens when waiting for status flags to change. |
| kStatus_Success | Successfully abort the transfer. |
| void I2C_SlaveTransferCreateHandle |
( |
I2C_Type * |
base, |
|
|
i2c_slave_transfer_handle_t * |
psHandle, |
|
|
i2c_slave_transfer_callback_t |
pfCallback, |
|
|
void * |
pUserData |
|
) |
| |
This function is responsible for initializig slave transfer handle, installing user callback, registering slave IRQ handling function and opening global interrupt.
- Parameters
-
| base | I2C base pointer. |
| psHandle | pointer to i2c_slave_transfer_handle_t structure to store the transfer state. |
| pfCallback | pointer to user callback function. |
| pUserData | 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_SlaveOutofTransmitDataEvent and kI2C_SlaveOutofReceiveSpaceEvent occured, slave callback will always be revoked regardless which events user choose to enable. This means user need not configure them in the psTransferConfig. If user wants to enable all the events, use kI2C_SlaveAllEvents for convenience.
- Parameters
-
| base | The I2C peripheral base address. |
| psHandle | Pointer to #i2c_slave_transfer_handle_t structure which stores the transfer state. |
| psTransferConfig | I2C transfer configuration. |
- Return values
-
| kStatus_Success | I2C slave set to standby state successfully and ready to process events. |
| kStatus_I2C_Busy | I2C slave has already been started on this handle. |
| status_t I2C_SlaveTransferGetCount |
( |
i2c_slave_transfer_handle_t * |
psHandle, |
|
|
uint16_t * |
count |
|
) |
| |
- Parameters
-
| base | I2C base pointer. |
| psHandle | pointer to i2c_slave_transfer_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. |
| void I2C_SlaveTransferAbort |
( |
i2c_slave_transfer_handle_t * |
psHandle | ) |
|
- Note
- This API can be called at any time to stop slave for handling further bus events.
- Parameters
-
| base | I2C base pointer. |
| psHandle | pointer to i2c_slave_transfer_handle_t structure which stores the transfer state. |
| uint32_t I2C_GetInstance |
( |
I2C_Type * |
base | ) |
|
- Parameters
-
- Return values
-
| The | number of the instance. |
