i2c.h — Maple v0.0.12 Documentation

### Navigation

- next
- previous |
- LeafLabs |
- Index »
- `libmaple` »
- APIs »

# `i2c.h`

Inter-Integrated Circuit (I2C) peripheral support.

Contents

- Important Note
- Types
- Devices
- Functions
- Register Map Base Pointers
- Register Bit Definitions
  - Control register 1
  - Control register 2
  - Clock control register
  - Status register 1
  - Status register 2

## 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 i2c_reg_map

> I2C register map type.

> Public Members

> > __io uint32 CR1

> >   Control register 1.

> > __io uint32 CR2

> >   Control register 2.

> > __io uint32 OAR1

> >   Own address register 1.

> > __io uint32 OAR2

> >   Own address register 2.

> > __io uint32 DR

> >   Data register.

> > __io uint32 SR1

> >   Status register 1.

> > __io uint32 SR2

> >   Status register 2.

> > __io uint32 CCR

> >   Clock control register.

> > __io uint32 TRISE

> >   TRISE (rise time) register.

i2c_state enum

  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.

> Public Members

> > uint16 addr

> >   Address.

> > uint16 flags

> >   Bitwise OR of I2C_MSG_READ and I2C_MSG_10BIT_ADDR.

> > uint16 length

> >   Message length.

> > uint16 xferred

> >   Messages transferred.

> > uint8 * data

> >   Data.

struct i2c_dev

> I2C device type.

> Public Members

> > i2c_reg_map * regs

> >   Register map.

> > gpio_dev * gpio_port

> >   SDA, SCL pins’ GPIO port.

> > uint8 sda_pin

> >   SDA bit on gpio_port.

> > uint8 scl_pin

> >   SCL bit on gpio_port.

> > rcc_clk_id clk_id

> >   RCC clock information.

> > nvic_irq_num ev_nvic_line

> >   Event IRQ number.

> > nvic_irq_num er_nvic_line

> >   Error IRQ number.

> > i2c_state state

> >   Device state.

> > uint16 msgs_left

> >   Messages left.

> > i2c_msg * msg

> >   Messages.

> > uint32 timestamp

> >   For internal use.

> > uint32 error_flags

> >   Error flags, set on I2C error condition.

## Devices

i2c_dev *const I2C1

  I2C1 device.

i2c_dev *const I2C2

  I2C2 device.

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

  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.
  Return: | 0 on success, I2C_ERROR_PROTOCOL if there was a protocol error, I2C_ERROR_TIMEOUT if the transfer timed out.

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

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.

void i2c_peripheral_enable(i2c_dev * dev)

  Turn on an I2C peripheral.

  Parameters: | `dev` - Device to enable

void i2c_peripheral_disable(i2c_dev * dev)

  Turn off an I2C peripheral.

  Parameters: | `dev` - Device to turn off

void i2c_write(i2c_dev * dev, uint8 byte)

  Fill transmit register.

  Parameters: | `dev` - I2C device `byte` - Byte to write

void i2c_set_input_clk(i2c_dev * dev, uint32 freq)

  Set input clock frequency, in MHz.

  Parameters: | `dev` - I2C device `freq` - Frequency in megahertz (2-36)

void i2c_set_clk_control(i2c_dev * dev, uint32 val)

  Set I2C clock control register.

  See RM008

  Parameters: | `dev` - I2C device `val` - Value to use for clock control register (in Fast/Standard mode)

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 RM0008 for relevant formula).

void i2c_start_condition(i2c_dev * dev)

  Generate a start condition on the bus.

  Parameters: | `dev` - I2C device

void i2c_stop_condition(i2c_dev * dev)

  Generate a stop condition on the bus.

  Parameters: | `dev` - I2C device

void i2c_enable_irq(i2c_dev * dev, uint32 irqs)

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

void i2c_enable_ack(i2c_dev * dev)

  Enable I2C acknowledgment.

  Parameters: | `dev` - I2C device

void i2c_disable_ack(i2c_dev * dev)

  Disable I2C acknowledgment.

  Parameters: | `dev` - I2C device

## Register Map Base Pointers

I2C1_BASE

  I2C1 register map base pointer.

I2C2_BASE

  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

### Navigation

- next
- previous |
- LeafLabs |
- Index »
- `libmaple` »
- APIs »