I2C
[EM_Library]

Inter-integrated Circuit (I2C) Peripheral API. More...

Collaboration diagram for I2C:

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

Defines

#define I2C_FREQ_STANDARD_MAX   92000
 Standard mode max frequency assuming using 4:4 ratio for Nlow:Nhigh.
#define I2C_FREQ_FAST_MAX   392157
 Fast mode max frequency assuming using 6:3 ratio for Nlow:Nhigh.
#define I2C_FREQ_FASTPLUS_MAX   987167
 Fast mode+ max frequency assuming using 11:6 ratio for Nlow:Nhigh.
#define I2C_FLAG_WRITE   0x0001
 Indicate plain write sequence: S+ADDR(W)+DATA0+P.
#define I2C_FLAG_READ   0x0002
 Indicate plain read sequence: S+ADDR(R)+DATA0+P.
#define I2C_FLAG_WRITE_READ   0x0004
 Indicate combined write/read sequence: S+ADDR(W)+DATA0+Sr+ADDR(R)+DATA1+P.
#define I2C_FLAG_WRITE_WRITE   0x0008
 Indicate write sequence using two buffers: S+ADDR(W)+DATA0+DATA1+P.
#define I2C_FLAG_10BIT_ADDR   0x0010
#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.
void I2C_BusFreqSet (I2C_TypeDef *i2c, uint32_t refFreq, uint32_t freq, I2C_ClockHLR_TypeDef type)
 Set I2C bus frequency.
void I2C_Enable (I2C_TypeDef *i2c, bool enable)
 Enable/disable I2C.
void I2C_Init (I2C_TypeDef *i2c, const I2C_Init_TypeDef *init)
 Initialize I2C.
__STATIC_INLINE void I2C_IntClear (I2C_TypeDef *i2c, uint32_t flags)
 Clear one or more pending I2C interrupts.
__STATIC_INLINE void I2C_IntDisable (I2C_TypeDef *i2c, uint32_t flags)
 Disable one or more I2C interrupts.
__STATIC_INLINE void I2C_IntEnable (I2C_TypeDef *i2c, uint32_t flags)
 Enable one or more I2C interrupts.
__STATIC_INLINE uint32_t I2C_IntGet (I2C_TypeDef *i2c)
 Get pending I2C interrupt flags.
__STATIC_INLINE void I2C_IntSet (I2C_TypeDef *i2c, uint32_t flags)
 Set one or more pending I2C interrupts from SW.
void I2C_Reset (I2C_TypeDef *i2c)
 Reset I2C to same state as after a HW reset.
__STATIC_INLINE uint8_t I2C_SlaveAddressGet (I2C_TypeDef *i2c)
 Get slave address used for I2C peripheral (when operating in slave mode).
__STATIC_INLINE void I2C_SlaveAddressSet (I2C_TypeDef *i2c, uint8_t addr)
 Set slave address to use for I2C peripheral (when operating in slave mode).
__STATIC_INLINE uint8_t I2C_SlaveAddressMaskGet (I2C_TypeDef *i2c)
 Get slave address mask used for I2C peripheral (when operating in slave mode).
__STATIC_INLINE void I2C_SlaveAddressMaskSet (I2C_TypeDef *i2c, uint8_t mask)
 Set slave address mask used for I2C peripheral (when operating in slave mode).
I2C_TransferReturn_TypeDef I2C_Transfer (I2C_TypeDef *i2c)
 Continue an initiated I2C transfer (single master mode only).
I2C_TransferReturn_TypeDef I2C_TransferInit (I2C_TypeDef *i2c, I2C_TransferSeq_TypeDef *seq)
 Prepare and start an I2C transfer (single master mode only).

Detailed Description

Inter-integrated Circuit (I2C) Peripheral API.


Define Documentation

#define I2C_FLAG_10BIT_ADDR   0x0010

Use 10 bit address.

Definition at line 156 of file em_i2c.h.

Referenced by I2C_Transfer().

#define I2C_FLAG_READ   0x0002

Indicate plain read sequence: S+ADDR(R)+DATA0+P.

  • S - Start
  • ADDR(R) - address with W/R bit set
  • DATA0 - Data read into buffer with index 0
  • P - Stop

Definition at line 129 of file em_i2c.h.

Referenced by I2C_Transfer(), and I2C_TransferInit().

#define I2C_FLAG_WRITE   0x0001

Indicate plain write sequence: S+ADDR(W)+DATA0+P.

  • S - Start
  • ADDR(W) - address with W/R bit cleared
  • DATA0 - Data taken from buffer with index 0
  • P - Stop

Definition at line 118 of file em_i2c.h.

Referenced by I2C_Transfer().

#define I2C_FLAG_WRITE_READ   0x0004

Indicate combined write/read sequence: S+ADDR(W)+DATA0+Sr+ADDR(R)+DATA1+P.

  • S - Start
  • Sr - Repeated start
  • ADDR(W) - address with W/R bit cleared
  • ADDR(R) - address with W/R bit set
  • DATAn - Data written from/read into buffer with index n
  • P - Stop

Definition at line 142 of file em_i2c.h.

Referenced by I2C_Transfer(), and I2C_TransferInit().

#define I2C_FLAG_WRITE_WRITE   0x0008

Indicate write sequence using two buffers: S+ADDR(W)+DATA0+DATA1+P.

  • S - Start
  • ADDR(W) - address with W/R bit cleared
  • DATAn - Data written from buffer with index n
  • P - Stop

Definition at line 153 of file em_i2c.h.

#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

Definition at line 93 of file em_i2c.h.

#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

Definition at line 106 of file em_i2c.h.

#define I2C_FREQ_STANDARD_MAX   92000

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

Note:
Due to chip characteristics, the max value is somewhat reduced.

Definition at line 77 of file em_i2c.h.

#define I2C_INIT_DEFAULT
Value:
{ true,                    /* Enable when init done */                    \
    true,                    /* Set to master mode */                       \
    0,                       /* Use currently configured reference clock */ \
    I2C_FREQ_STANDARD_MAX,   /* Set to standard rate assuring being */      \
                             /* within I2C spec */                          \
    i2cClockHLRStandard      /* Set to use 4:4 low/high duty cycle */       \
  }

Suggested default config for I2C init structure.

Definition at line 221 of file em_i2c.h.


Enumeration Type Documentation

Clock low to high ratio settings.

Enumerator:
i2cClockHLRStandard 

Ratio is 4:4

i2cClockHLRAsymetric 

Ratio is 6:3

i2cClockHLRFast 

Ratio is 11:3

Definition at line 164 of file em_i2c.h.

Return codes for single master mode transfer function.

Enumerator:
i2cTransferInProgress 

Transfer in progress.

i2cTransferDone 

Transfer completed successfully.

i2cTransferNack 

NACK received during transfer.

i2cTransferBusErr 

Bus error during transfer (misplaced START/STOP).

i2cTransferArbLost 

Arbitration lost during transfer.

i2cTransferUsageFault 

Usage fault.

i2cTransferSwFault 

SW fault.

Definition at line 173 of file em_i2c.h.


Function Documentation

uint32_t I2C_BusFreqGet ( I2C_TypeDef *  i2c  ) 

Get current configured I2C bus frequency.

This frequency is only of relevance when acting as master.

Parameters:
[in] i2c Pointer to I2C peripheral register block.
Returns:
Current I2C frequency in Hz.

Definition at line 160 of file em_i2c.c.

References CMU_ClockFreqGet(), and cmuClock_HFPER.

Here is the call graph for this function:

void I2C_BusFreqSet ( I2C_TypeDef *  i2c,
uint32_t  refFreq,
uint32_t  freq,
I2C_ClockHLR_TypeDef  type 
)

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.

Parameters:
[in] i2c Pointer to I2C peripheral register block.
[in] refFreq I2C reference clock frequency in Hz that will be used. If set to 0, the currently configured reference clock is assumed. Setting it to a higher than actual configured value only has the consequence of reducing the real I2C frequency.
[in] freq 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] type 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 211 of file em_i2c.c.

References CMU_ClockFreqGet(), and cmuClock_HFPER.

Referenced by I2C_Init().

Here is the call graph for this function:

Here is the caller graph for this function:

void I2C_Enable ( I2C_TypeDef *  i2c,
bool  enable 
)

Enable/disable I2C.

Note:
After enabling the I2C (from being disabled), the I2C is in BUSY state.
Parameters:
[in] i2c Pointer to I2C peripheral register block.
[in] enable true to enable counting, false to disable.

Definition at line 266 of file em_i2c.c.

References BITBAND_Peripheral().

Here is the call graph for this function:

void I2C_Init ( I2C_TypeDef *  i2c,
const I2C_Init_TypeDef init 
)

Initialize I2C.

Parameters:
[in] i2c Pointer to I2C peripheral register block.
[in] init Pointer to I2C initialization structure.

Definition at line 284 of file em_i2c.c.

References BITBAND_Peripheral(), I2C_Init_TypeDef::clhr, I2C_Init_TypeDef::enable, I2C_Init_TypeDef::freq, I2C_BusFreqSet(), I2C_Init_TypeDef::master, and I2C_Init_TypeDef::refFreq.

Here is the call graph for this function:

__STATIC_INLINE void I2C_IntClear ( I2C_TypeDef *  i2c,
uint32_t  flags 
)

Clear one or more pending I2C interrupts.

Parameters:
[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 304 of file em_i2c.h.

__STATIC_INLINE void I2C_IntDisable ( I2C_TypeDef *  i2c,
uint32_t  flags 
)

Disable one or more I2C interrupts.

Parameters:
[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 321 of file em_i2c.h.

__STATIC_INLINE void I2C_IntEnable ( I2C_TypeDef *  i2c,
uint32_t  flags 
)

Enable one or more I2C interrupts.

Note:
Depending on the use, a pending interrupt may already be set prior to enabling the interrupt. Consider using I2C_IntClear() prior to enabling if such a pending interrupt should be ignored.
Parameters:
[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 343 of file em_i2c.h.

__STATIC_INLINE uint32_t I2C_IntGet ( I2C_TypeDef *  i2c  ) 

Get pending I2C interrupt flags.

Note:
The event bits are not cleared by the use of this function.
Parameters:
[in] i2c Pointer to I2C peripheral register block.
Returns:
I2C interrupt sources pending. A bitwise logic OR combination of valid interrupt flags for the I2C module (I2C_IF_nnn).

Definition at line 363 of file em_i2c.h.

__STATIC_INLINE void I2C_IntSet ( I2C_TypeDef *  i2c,
uint32_t  flags 
)

Set one or more pending I2C interrupts from SW.

Parameters:
[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 380 of file em_i2c.h.

void I2C_Reset ( I2C_TypeDef *  i2c  ) 

Reset I2C to same state as after a HW reset.

Note:
The ROUTE register is NOT reset by this function, in order to allow for centralized setup of this feature.
Parameters:
[in] i2c Pointer to I2C peripheral register block.

Definition at line 315 of file em_i2c.c.

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

Parameters:
[in] i2c Pointer to I2C peripheral register block.
Returns:
I2C slave address in use. The 7 most significant bits define the actual address, the least significant bit is reserved and always returned as 0.

Definition at line 404 of file em_i2c.h.

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

Parameters:
[in] i2c Pointer to I2C peripheral register block.
Returns:
I2C slave address mask in use. The 7 most significant bits define the actual address mask, the least significant bit is reserved and always returned as 0.

Definition at line 456 of file em_i2c.h.

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

Parameters:
[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 485 of file em_i2c.h.

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

Parameters:
[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 427 of file em_i2c.h.

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.

Note:
Only single master mode is supported.
Parameters:
[in] i2c Pointer to I2C peripheral register block.
Returns:
Returns status for ongoing transfer.

Definition at line 363 of file em_i2c.c.

References I2C_TransferSeq_TypeDef::addr, I2C_TransferSeq_TypeDef::buf, I2C_TransferSeq_TypeDef::data, I2C_TransferSeq_TypeDef::flags, I2C_FLAG_10BIT_ADDR, I2C_FLAG_READ, I2C_FLAG_WRITE, I2C_FLAG_WRITE_READ, i2cTransferArbLost, i2cTransferBusErr, i2cTransferDone, i2cTransferInProgress, i2cTransferNack, i2cTransferSwFault, i2cTransferUsageFault, and I2C_TransferSeq_TypeDef::len.

Referenced by I2C_TransferInit().

Here is the caller graph for this function:

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.

Note:
Only single master mode is supported.
Parameters:
[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.
Returns:
Returns status for ongoing transfer:
  • i2cTransferInProgress - indicates that transfer not finished.
  • otherwise some sort of error has occurred.

Definition at line 742 of file em_i2c.c.

References I2C_TransferSeq_TypeDef::buf, I2C_TransferSeq_TypeDef::flags, I2C_FLAG_READ, I2C_FLAG_WRITE_READ, I2C_Transfer(), i2cTransferInProgress, i2cTransferUsageFault, and I2C_TransferSeq_TypeDef::len.

Here is the call graph for this function: