EFM32 Happy Gecko Software Documentation
efm32hg-doc-5.1.2
|
Inter-integrated Circuit (I2C) Peripheral API.
This module contains functions to control the I2C peripheral of Silicon Labs 32-bit MCUs and SoCs. The I2C interface allows communication on I2C buses with the lowest energy consumption possible.
Data Structures | |
struct | I2C_Init_TypeDef |
struct | I2C_TransferSeq_TypeDef |
Master mode transfer message structure used to define a complete I2C transfer sequence (from start to stop). More... | |
Macros | |
#define | I2C_FLAG_10BIT_ADDR 0x0010 |
#define | I2C_FLAG_READ 0x0002 |
Indicate plain read sequence: S+ADDR(R)+DATA0+P. More... | |
#define | I2C_FLAG_WRITE 0x0001 |
Indicate plain write sequence: S+ADDR(W)+DATA0+P. More... | |
#define | I2C_FLAG_WRITE_READ 0x0004 |
Indicate combined write/read sequence: S+ADDR(W)+DATA0+Sr+ADDR(R)+DATA1+P. More... | |
#define | I2C_FLAG_WRITE_WRITE 0x0008 |
Indicate write sequence using two buffers: S+ADDR(W)+DATA0+DATA1+P. More... | |
#define | I2C_FREQ_FAST_MAX 392157 |
Fast mode max frequency assuming using 6:3 ratio for Nlow:Nhigh. More... | |
#define | I2C_FREQ_FASTPLUS_MAX 987167 |
Fast mode+ max frequency assuming using 11:6 ratio for Nlow:Nhigh. More... | |
#define | I2C_FREQ_STANDARD_MAX 93000 |
Standard mode max frequency assuming using 4:4 ratio for Nlow:Nhigh. More... | |
#define | I2C_INIT_DEFAULT |
Enumerations | |
enum | I2C_ClockHLR_TypeDef { i2cClockHLRStandard = _I2C_CTRL_CLHR_STANDARD, i2cClockHLRAsymetric = _I2C_CTRL_CLHR_ASYMMETRIC, i2cClockHLRFast = _I2C_CTRL_CLHR_FAST } |
enum | I2C_TransferReturn_TypeDef { i2cTransferInProgress = 1, i2cTransferDone = 0, i2cTransferNack = -1, i2cTransferBusErr = -2, i2cTransferArbLost = -3, i2cTransferUsageFault = -4, i2cTransferSwFault = -5 } |
Functions | |
uint32_t | I2C_BusFreqGet (I2C_TypeDef *i2c) |
Get current configured I2C bus frequency. More... | |
void | I2C_BusFreqSet (I2C_TypeDef *i2c, uint32_t freqRef, uint32_t freqScl, I2C_ClockHLR_TypeDef i2cMode) |
Set I2C bus frequency. More... | |
void | I2C_Enable (I2C_TypeDef *i2c, bool enable) |
Enable/disable I2C. More... | |
void | I2C_Init (I2C_TypeDef *i2c, const I2C_Init_TypeDef *init) |
Initialize I2C. More... | |
__STATIC_INLINE void | I2C_IntClear (I2C_TypeDef *i2c, uint32_t flags) |
Clear one or more pending I2C interrupts. More... | |
__STATIC_INLINE void | I2C_IntDisable (I2C_TypeDef *i2c, uint32_t flags) |
Disable one or more I2C interrupts. More... | |
__STATIC_INLINE void | I2C_IntEnable (I2C_TypeDef *i2c, uint32_t flags) |
Enable one or more I2C interrupts. More... | |
__STATIC_INLINE uint32_t | I2C_IntGet (I2C_TypeDef *i2c) |
Get pending I2C interrupt flags. More... | |
__STATIC_INLINE uint32_t | I2C_IntGetEnabled (I2C_TypeDef *i2c) |
Get enabled and pending I2C interrupt flags. Useful for handling more interrupt sources in the same interrupt handler. More... | |
__STATIC_INLINE void | I2C_IntSet (I2C_TypeDef *i2c, uint32_t flags) |
Set one or more pending I2C interrupts from SW. More... | |
void | I2C_Reset (I2C_TypeDef *i2c) |
Reset I2C to same state as after a HW reset. More... | |
__STATIC_INLINE uint8_t | I2C_SlaveAddressGet (I2C_TypeDef *i2c) |
Get slave address used for I2C peripheral (when operating in slave mode). More... | |
__STATIC_INLINE uint8_t | I2C_SlaveAddressMaskGet (I2C_TypeDef *i2c) |
Get slave address mask used for I2C peripheral (when operating in slave mode). More... | |
__STATIC_INLINE void | I2C_SlaveAddressMaskSet (I2C_TypeDef *i2c, uint8_t mask) |
Set slave address mask used for I2C peripheral (when operating in slave mode). More... | |
__STATIC_INLINE void | I2C_SlaveAddressSet (I2C_TypeDef *i2c, uint8_t addr) |
Set slave address to use for I2C peripheral (when operating in slave mode). More... | |
I2C_TransferReturn_TypeDef | I2C_Transfer (I2C_TypeDef *i2c) |
Continue an initiated I2C transfer (single master mode only). More... | |
I2C_TransferReturn_TypeDef | I2C_TransferInit (I2C_TypeDef *i2c, I2C_TransferSeq_TypeDef *seq) |
Prepare and start an I2C transfer (single master mode only). More... | |
#define I2C_FLAG_10BIT_ADDR 0x0010 |
#define I2C_FLAG_READ 0x0002 |
Indicate plain read sequence: S+ADDR(R)+DATA0+P.
Definition at line 135 of file em_i2c.h.
Referenced by I2C_Transfer(), I2C_TransferInit(), performI2CTransfer(), and SI7021_cmdRead().
#define I2C_FLAG_WRITE 0x0001 |
Indicate plain write sequence: S+ADDR(W)+DATA0+P.
Definition at line 124 of file em_i2c.h.
Referenced by CCS811_setEnvData(), CCS811_setMeasureMode(), CCS811_softwareReset(), EEPROM_AckPoll(), I2C_Transfer(), SI1133_registerBlockWrite(), SI1133_registerWrite(), Si1147_Write_Block_Register(), Si1147_Write_Register(), SI7021_cmdWrite(), and TEMPSENS_RegisterSet().
#define I2C_FLAG_WRITE_READ 0x0004 |
Indicate combined write/read sequence: S+ADDR(W)+DATA0+Sr+ADDR(R)+DATA1+P.
Definition at line 148 of file em_i2c.h.
Referenced by CCS811_getMeasurement(), CCS811_getRawData(), CCS811_readMailbox(), EEPROM_Read(), I2C_Transfer(), I2C_TransferInit(), SI1133_registerBlockRead(), SI1133_registerRead(), Si1147_Read_Block_Register(), Si1147_Read_Register(), Si7013_Detect(), Si7013_GetFirmwareRevision(), SI7021_cmdRead(), SI7210_regRead(), and TEMPSENS_RegisterGet().
#define I2C_FLAG_WRITE_WRITE 0x0008 |
Indicate write sequence using two buffers: S+ADDR(W)+DATA0+DATA1+P.
Definition at line 159 of file em_i2c.h.
Referenced by EEPROM_Write(), SI7021_cmdWrite(), and SI7210_regWrite().
#define I2C_FREQ_FAST_MAX 392157 |
Fast mode max frequency assuming using 6:3 ratio for Nlow:Nhigh.
From I2C specification: Min Tlow = 1.3us, min Thigh = 0.6us, max Trise=0.3us, max Tfall=0.3us. Since ratio is 6:3, have to use worst case value of Tlow or 2xThigh as base.
1/(Tlow + Thigh + 0.3us + 0.3us) = 1/(1.3 + 0.65 + 0.6)us = 392157Hz
#define I2C_FREQ_FASTPLUS_MAX 987167 |
Fast mode+ max frequency assuming using 11:6 ratio for Nlow:Nhigh.
From I2C specification: Min Tlow = 0.5us, min Thigh = 0.26us, max Trise=0.12us, max Tfall=0.12us. Since ratio is 11:6, have to use worst case value of Tlow or (11/6)xThigh as base.
1/(Tlow + Thigh + 0.12us + 0.12us) = 1/(0.5 + 0.273 + 0.24)us = 987167Hz
#define I2C_FREQ_STANDARD_MAX 93000 |
Standard mode max frequency assuming using 4:4 ratio for Nlow:Nhigh.
From I2C specification: Min Tlow = 4.7us, min Thigh = 4.0us, max Trise=1.0us, max Tfall=0.3us. Since ratio is 4:4, have to use worst case value of Tlow or Thigh as base.
1/(Tlow + Thigh + 1us + 0.3us) = 1/(4.7 + 4.7 + 1.3)us = 93458Hz
#define I2C_INIT_DEFAULT |
Suggested default config for I2C init structure.
Definition at line 227 of file em_i2c.h.
Referenced by setupI2C().
enum I2C_ClockHLR_TypeDef |
Return codes for single master mode transfer function.
uint32_t I2C_BusFreqGet | ( | I2C_TypeDef * | i2c | ) |
Get current configured I2C bus frequency.
This frequency is only of relevance when acting as master.
[in] | i2c | Pointer to I2C peripheral register block. |
Definition at line 174 of file em_i2c.c.
References _I2C_CTRL_CLHR_MASK, _I2C_CTRL_CLHR_SHIFT, I2C_TypeDef::CLKDIV, CMU_ClockFreqGet(), cmuClock_HFPER, and I2C_TypeDef::CTRL.
void I2C_BusFreqSet | ( | I2C_TypeDef * | i2c, |
uint32_t | freqRef, | ||
uint32_t | freqScl, | ||
I2C_ClockHLR_TypeDef | i2cMode | ||
) |
Set I2C bus frequency.
The bus frequency is only of relevance when acting as a master. The bus frequency should not be set higher than the max frequency accepted by the slowest device on the bus.
Notice that due to asymmetric requirements on low and high I2C clock cycles by the I2C specification, the actual max frequency allowed in order to comply with the specification may be somewhat lower than expected.
Please refer to the reference manual, details on I2C clock generation, for max allowed theoretical frequencies for different modes.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | freqRef | I2C reference clock frequency in Hz that will be used. If set to 0, then HFPER clock is used. Setting it to a higher than actual configured value only has the consequence of reducing the real I2C frequency. |
[in] | freqScl | Bus frequency to set (actual bus speed may be lower due to integer prescaling). Safe (according to I2C specification) max frequencies for standard, fast and fast+ modes are available using I2C_FREQ_ defines. (Using I2C_FREQ_ defines requires corresponding setting of type .) Slowest slave device on bus must always be considered. |
[in] | i2cMode | Clock low to high ratio type to use. If not using i2cClockHLRStandard, make sure all devices on the bus support the specified mode. Using a non-standard ratio is useful to achieve higher bus clock in fast and fast+ modes. |
Definition at line 227 of file em_i2c.c.
References _I2C_CLKDIV_DIV_MASK, _I2C_CTRL_CLHR_MASK, _I2C_CTRL_CLHR_SHIFT, BUS_RegMaskedWrite(), I2C_TypeDef::CLKDIV, CMU_ClockFreqGet(), cmuClock_HFPER, I2C_TypeDef::CTRL, I2C_CTRL_SLAVE, i2cClockHLRAsymetric, i2cClockHLRFast, and i2cClockHLRStandard.
Referenced by I2C_Init().
void I2C_Enable | ( | I2C_TypeDef * | i2c, |
bool | enable | ||
) |
Enable/disable I2C.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | enable | true to enable counting, false to disable. |
Definition at line 335 of file em_i2c.c.
References _I2C_CTRL_EN_SHIFT, BUS_RegBitWrite(), and I2C_TypeDef::CTRL.
void I2C_Init | ( | I2C_TypeDef * | i2c, |
const I2C_Init_TypeDef * | init | ||
) |
Initialize I2C.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | init | Pointer to I2C initialization structure. |
Definition at line 353 of file em_i2c.c.
References _I2C_CTRL_EN_SHIFT, _I2C_CTRL_SLAVE_SHIFT, _I2C_IFC_MASK, BUS_RegBitWrite(), I2C_Init_TypeDef::clhr, I2C_TypeDef::CTRL, I2C_Init_TypeDef::enable, I2C_Init_TypeDef::freq, I2C_BusFreqSet(), I2C_TypeDef::IEN, I2C_TypeDef::IFC, I2C_Init_TypeDef::master, and I2C_Init_TypeDef::refFreq.
Referenced by I2CSPM_Init(), and setupI2C().
__STATIC_INLINE void I2C_IntClear | ( | I2C_TypeDef * | i2c, |
uint32_t | flags | ||
) |
Clear one or more pending I2C interrupts.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | flags | Pending I2C interrupt source to clear. Use a bitwse logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn). |
Definition at line 311 of file em_i2c.h.
References I2C_TypeDef::IFC.
__STATIC_INLINE void I2C_IntDisable | ( | I2C_TypeDef * | i2c, |
uint32_t | flags | ||
) |
Disable one or more I2C interrupts.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | flags | I2C interrupt sources to disable. Use a bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn). |
Definition at line 328 of file em_i2c.h.
References I2C_TypeDef::IEN.
__STATIC_INLINE void I2C_IntEnable | ( | I2C_TypeDef * | i2c, |
uint32_t | flags | ||
) |
Enable one or more I2C interrupts.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | flags | I2C interrupt sources to enable. Use a bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn). |
Definition at line 350 of file em_i2c.h.
References I2C_TypeDef::IEN.
__STATIC_INLINE uint32_t I2C_IntGet | ( | I2C_TypeDef * | i2c | ) |
Get pending I2C interrupt flags.
[in] | i2c | Pointer to I2C peripheral register block. |
Definition at line 370 of file em_i2c.h.
References I2C_TypeDef::IF.
__STATIC_INLINE uint32_t I2C_IntGetEnabled | ( | I2C_TypeDef * | i2c | ) |
Get enabled and pending I2C interrupt flags. Useful for handling more interrupt sources in the same interrupt handler.
[in] | i2c | Pointer to I2C peripheral register block. |
Definition at line 393 of file em_i2c.h.
References I2C_TypeDef::IEN, and I2C_TypeDef::IF.
__STATIC_INLINE void I2C_IntSet | ( | I2C_TypeDef * | i2c, |
uint32_t | flags | ||
) |
Set one or more pending I2C interrupts from SW.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | flags | I2C interrupt sources to set to pending. Use a bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn). |
Definition at line 413 of file em_i2c.h.
References I2C_TypeDef::IFS.
void I2C_Reset | ( | I2C_TypeDef * | i2c | ) |
Reset I2C to same state as after a HW reset.
[in] | i2c | Pointer to I2C peripheral register block. |
Definition at line 380 of file em_i2c.c.
References _I2C_CLKDIV_RESETVALUE, _I2C_CTRL_RESETVALUE, _I2C_IEN_RESETVALUE, _I2C_IFC_MASK, _I2C_SADDR_RESETVALUE, _I2C_SADDRMASK_RESETVALUE, I2C_TypeDef::CLKDIV, I2C_TypeDef::CTRL, I2C_TypeDef::IEN, I2C_TypeDef::IFC, I2C_TypeDef::SADDR, and I2C_TypeDef::SADDRMASK.
__STATIC_INLINE uint8_t I2C_SlaveAddressGet | ( | I2C_TypeDef * | i2c | ) |
Get slave address used for I2C peripheral (when operating in slave mode).
For 10 bit addressing mode, the address is split in two bytes, and only the first byte setting is fetched, effectively only controlling the 2 most significant bits of the 10 bit address. Full handling of 10 bit addressing in slave mode requires additional SW handling.
[in] | i2c | Pointer to I2C peripheral register block. |
Definition at line 437 of file em_i2c.h.
References I2C_TypeDef::SADDR.
__STATIC_INLINE uint8_t I2C_SlaveAddressMaskGet | ( | I2C_TypeDef * | i2c | ) |
Get slave address mask used for I2C peripheral (when operating in slave mode).
The address mask defines how the comparator works. A bit position with value 0 means that the corresponding slave address bit is ignored during comparison (don't care). A bit position with value 1 means that the corresponding slave address bit must match.
For 10 bit addressing mode, the address is split in two bytes, and only the mask for the first address byte is fetched, effectively only controlling the 2 most significant bits of the 10 bit address.
[in] | i2c | Pointer to I2C peripheral register block. |
Definition at line 489 of file em_i2c.h.
References I2C_TypeDef::SADDRMASK.
__STATIC_INLINE void I2C_SlaveAddressMaskSet | ( | I2C_TypeDef * | i2c, |
uint8_t | mask | ||
) |
Set slave address mask used for I2C peripheral (when operating in slave mode).
The address mask defines how the comparator works. A bit position with value 0 means that the corresponding slave address bit is ignored during comparison (don't care). A bit position with value 1 means that the corresponding slave address bit must match.
For 10 bit addressing mode, the address is split in two bytes, and only the mask for the first address byte is set, effectively only controlling the 2 most significant bits of the 10 bit address.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | mask | I2C slave address mask to use. The 7 most significant bits define the actual address mask, the least significant bit is reserved and should be 0. |
Definition at line 518 of file em_i2c.h.
References I2C_TypeDef::SADDRMASK.
__STATIC_INLINE void I2C_SlaveAddressSet | ( | I2C_TypeDef * | i2c, |
uint8_t | addr | ||
) |
Set slave address to use for I2C peripheral (when operating in slave mode).
For 10 bit addressing mode, the address is split in two bytes, and only the first byte is set, effectively only controlling the 2 most significant bits of the 10 bit address. Full handling of 10 bit addressing in slave mode requires additional SW handling.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | addr | I2C slave address to use. The 7 most significant bits define the actual address, the least significant bit is reserved and always set to 0. |
Definition at line 460 of file em_i2c.h.
References I2C_TypeDef::SADDR.
I2C_TransferReturn_TypeDef I2C_Transfer | ( | I2C_TypeDef * | i2c | ) |
Continue an initiated I2C transfer (single master mode only).
This function is used repeatedly after a I2C_TransferInit() in order to complete a transfer. It may be used in polled mode as the below example shows:
* I2C_TransferReturn_TypeDef ret; * * // Do a polled transfer * ret = I2C_TransferInit(I2C0, seq); * while (ret == i2cTransferInProgress) * { * ret = I2C_Transfer(I2C0); * } *
It may also be used in interrupt driven mode, where this function is invoked from the interrupt handler. Notice that if used in interrupt mode, NVIC interrupts must be configured and enabled for the I2C bus used. I2C peripheral specific interrupts are managed by this SW.
[in] | i2c | Pointer to I2C peripheral register block. |
Definition at line 428 of file em_i2c.c.
References I2C_TransferSeq_TypeDef::addr, I2C_TransferSeq_TypeDef::buf, I2C_TypeDef::CMD, I2C_TransferSeq_TypeDef::data, I2C_TransferSeq_TypeDef::flags, I2C0, I2C_CMD_ACK, I2C_CMD_NACK, I2C_CMD_START, I2C_CMD_STOP, I2C_FLAG_10BIT_ADDR, I2C_FLAG_READ, I2C_FLAG_WRITE, I2C_FLAG_WRITE_READ, I2C_IF_ACK, I2C_IF_ARBLOST, I2C_IF_BUSERR, I2C_IF_MSTOP, I2C_IF_NACK, I2C_IF_RXDATAV, I2C_IFC_ACK, I2C_IFC_MSTOP, I2C_IFC_NACK, i2cTransferArbLost, i2cTransferBusErr, i2cTransferDone, i2cTransferInProgress, i2cTransferNack, i2cTransferSwFault, i2cTransferUsageFault, I2C_TypeDef::IEN, I2C_TypeDef::IF, I2C_TypeDef::IFC, I2C_TransferSeq_TypeDef::len, I2C_TypeDef::RXDATA, and I2C_TypeDef::TXDATA.
Referenced by I2C_TransferInit(), I2CSPM_Transfer(), and performI2CTransfer().
I2C_TransferReturn_TypeDef I2C_TransferInit | ( | I2C_TypeDef * | i2c, |
I2C_TransferSeq_TypeDef * | seq | ||
) |
Prepare and start an I2C transfer (single master mode only).
This function must be invoked in order to start an I2C transfer sequence. In order to actually complete the transfer, I2C_Transfer() must be used either in polled mode or by adding a small driver wrapper utilizing interrupts.
[in] | i2c | Pointer to I2C peripheral register block. |
[in] | seq | Pointer to sequence structure defining the I2C transfer to take place. The referenced structure must exist until the transfer has fully completed. |
Definition at line 807 of file em_i2c.c.
References _I2C_IFC_MASK, I2C_TransferSeq_TypeDef::buf, I2C_TypeDef::CMD, I2C_TransferSeq_TypeDef::flags, I2C0, I2C_CMD_ABORT, I2C_CMD_CLEARPC, I2C_CMD_CLEARTX, I2C_FLAG_READ, I2C_FLAG_WRITE_READ, I2C_IF_ACK, I2C_IF_MSTOP, I2C_IF_NACK, I2C_IF_RXDATAV, I2C_STATE_BUSY, I2C_Transfer(), i2cTransferInProgress, i2cTransferUsageFault, I2C_TypeDef::IEN, I2C_TypeDef::IF, I2C_TypeDef::IFC, I2C_TransferSeq_TypeDef::len, I2C_TypeDef::RXDATA, and I2C_TypeDef::STATE.
Referenced by I2CSPM_Transfer(), and performI2CTransfer().