i2c.h

Inter-Integrated Circuit (I2C) peripheral support.

Important Note

There are some important known problems with the built-in I2C peripherals. For more information, see STM32F10xx8 and STM32F10xxB Errata sheet (ST Doc ID 14574 Rev 8), Section 2.11.1, 2.11.2. An important consequence of these problems is that the I2C interrupt must not be preempted. Consequently, (by default) Wirish uses an I2C interrupt priority which is the highest in the system (priority level 0). Other interrupt priorities are set lower.

Types

struct stm32f1::i2c_reg_map

I2C register map type.

struct stm32f2_f4::i2c_reg_map

I2C register map type.

enum i2c_state

I2C device states.

Values:

I2C_STATE_DISABLED = 0

Disabled.

I2C_STATE_IDLE = 1

Idle.

I2C_STATE_XFER_DONE = 2

Done with transfer.

I2C_STATE_BUSY = 3

Busy.

I2C_STATE_ERROR = -1

Error occurred.

struct i2c_msg

I2C message type.

struct i2c_dev

I2C device type.

Devices

i2c_dev *stm32f1::I2C1

STM32F1 I2C device 1.

STM32F1 I2C device 1.

i2c_dev *stm32f1::I2C2

STM32F1 I2C device 2.

STM32F1 I2C device 2.

Functions

void i2c_init(i2c_dev *dev)

Initialize an I2C device and reset its registers to their default values.

Parameters
  • dev -

    Device to initialize.

void i2c_master_enable(i2c_dev *dev, uint32 flags)

Initialize an I2C device as bus master.

Parameters
  • dev -

    Device to enable

  • flags -

    Bitwise or of the following I2C options: I2C_FAST_MODE: 400 khz operation, I2C_DUTY_16_9: 16/9 Tlow/Thigh duty cycle (only applicable for fast mode), I2C_BUS_RESET: Reset the bus and clock out any hung slaves on initialization, I2C_10BIT_ADDRESSING: Enable 10-bit addressing, I2C_REMAP: (deprecated, STM32F1 only) Remap I2C1 to SCL/PB8 SDA/PB9.

int32 i2c_master_xfer(i2c_dev *dev, i2c_msg *msgs, uint16 num, uint32 timeout)

Process an i2c transaction.

Transactions are composed of one or more i2c_msg‘s, and may be read or write tranfers. Multiple i2c_msg‘s will generate a repeated start in between messages.

Return
0 on success, I2C_ERROR_PROTOCOL if there was a protocol error, I2C_ERROR_TIMEOUT if the transfer timed out.
Parameters
  • dev -

    I2C device

  • msgs -

    Messages to send/receive

  • num -

    Number of messages to send/receive

  • timeout -

    Bus idle timeout in milliseconds before aborting the transfer. 0 denotes no timeout.

void i2c_bus_reset(const i2c_dev *dev)

Reset an I2C bus.

Reset is accomplished by clocking out pulses until any hung slaves release SDA and SCL, then generating a START condition, then a STOP condition.

Parameters
  • dev -

    I2C device

static void i2c_disable(i2c_dev *dev)

Disable an I2C device.

This function disables the corresponding peripheral and marks dev’s state as I2C_STATE_DISABLED.

Parameters
  • dev -

    Device to disable.

static void i2c_peripheral_enable(i2c_dev *dev)

Turn on an I2C peripheral.

Parameters
  • dev -

    Device to enable

static void i2c_peripheral_disable(i2c_dev *dev)

Turn off an I2C peripheral.

Parameters
  • dev -

    Device to turn off

static void i2c_write(i2c_dev *dev, uint8 byte)

Fill transmit register.

Parameters
  • dev -

    I2C device

  • byte -

    Byte to write

static void i2c_set_input_clk(i2c_dev *dev, uint32 freq)

Set input clock frequency, in MHz.

Parameters
  • dev -

    I2C device

  • freq -

    Frequency, in MHz. This must be at least 2, and at most the APB frequency of dev’s bus. (For example, if rcc_dev_clk(dev) == RCC_APB1, freq must be at most PCLK1, in MHz). There is an additional limit of 46 MHz.

static void i2c_set_clk_control(i2c_dev *dev, uint32 val)

Set I2C clock control register.

See the chip reference manual for the details.

Parameters
  • dev -

    I2C device

  • val -

    Value to use for clock control register (in Fast/Standard mode)

static void i2c_set_trise(i2c_dev *dev, uint32 trise)

Set SCL rise time.

Parameters
  • dev -

    I2C device

  • trise -

    Maximum rise time in fast/standard mode (see chip reference manual for the relevant formulas).

static void i2c_start_condition(i2c_dev *dev)

Generate a start condition on the bus.

Parameters
  • dev -

    I2C device

static void i2c_stop_condition(i2c_dev *dev)

Generate a stop condition on the bus.

Parameters
  • dev -

    I2C device

static void i2c_enable_irq(i2c_dev *dev, uint32 irqs)

Enable one or more I2C interrupts.

Parameters
  • dev -

    I2C device

  • irqs -

    Bitwise or of: I2C_IRQ_ERROR (error interrupt), I2C_IRQ_EVENT (event interrupt), and I2C_IRQ_BUFFER (buffer interrupt).

static void i2c_disable_irq(i2c_dev *dev, uint32 irqs)

Disable one or more I2C interrupts.

Parameters
  • dev -

    I2C device

  • irqs -

    Bitwise or of: I2C_IRQ_ERROR (error interrupt), I2C_IRQ_EVENT (event interrupt), and I2C_IRQ_BUFFER (buffer interrupt).

static void i2c_enable_ack(i2c_dev *dev)

Enable I2C acknowledgment.

Parameters
  • dev -

    I2C device

static void i2c_disable_ack(i2c_dev *dev)

Disable I2C acknowledgment.

Parameters
  • dev -

    I2C device

Register Map Base Pointers

I2C1_BASE

STM32F1 I2C1 register map base pointer.

I2C2_BASE

STM32F1 I2C2 register map base pointer.

Register Bit Definitions

Control register 1

I2C_CR1_SWRST
I2C_CR1_ALERT
I2C_CR1_PEC
I2C_CR1_POS
I2C_CR1_ACK
I2C_CR1_START
I2C_CR1_STOP
I2C_CR1_PE

Control register 2

I2C_CR2_LAST
I2C_CR2_DMAEN
I2C_CR2_ITBUFEN
I2C_CR2_ITEVTEN
I2C_CR2_ITERREN
I2C_CR2_FREQ

Clock control register

I2C_CCR_FS
I2C_CCR_DUTY
I2C_CCR_CCR

Status register 1

I2C_SR1_SB
I2C_SR1_ADDR
I2C_SR1_BTF
I2C_SR1_ADD10
I2C_SR1_STOPF
I2C_SR1_RXNE
I2C_SR1_TXE
I2C_SR1_BERR
I2C_SR1_ARLO
I2C_SR1_AF
I2C_SR1_OVR
I2C_SR1_PECERR
I2C_SR1_TIMEOUT
I2C_SR1_SMBALERT

Status register 2

I2C_SR2_MSL
I2C_SR2_BUSY
I2C_SR2_TRA
I2C_SR2_GENCALL
I2C_SR2_SMBDEFAULT
I2C_SR2_SMBHOST
I2C_SR2_DUALF
I2C_SR2_PEC