The latest development version of this page may be more current than this released 2.1.0 version.

I2C

Overview

Configuration Options

Related configuration options:

API Reference

group i2c_interface

I2C Interface.

Defines

I2C_SPEED_STANDARD

I2C Standard Speed

I2C_SPEED_FAST

I2C Fast Speed

I2C_SPEED_FAST_PLUS

I2C Fast Plus Speed

I2C_SPEED_HIGH

I2C High Speed

I2C_SPEED_ULTRA

I2C Ultra Fast Speed

I2C_SPEED_SHIFT
I2C_SPEED_SET(speed)
I2C_SPEED_MASK
I2C_SPEED_GET(cfg)
I2C_ADDR_10_BITS

Use 10-bit addressing. DEPRECATED - Use I2C_MSG_ADDR_10_BITS instead.

I2C_MODE_MASTER

Controller to act as Master.

I2C_SLAVE_FLAGS_ADDR_10_BITS

Slave device responds to 10-bit addressing.

I2C_MSG_WRITE

Write message to I2C bus.

I2C_MSG_READ

Read message from I2C bus.

I2C_MSG_STOP

Send STOP after this message.

I2C_MSG_RESTART

RESTART I2C transaction for this message.

Note

Not all I2C drivers have or require explicit support for this feature. Some drivers require this be present on a read message that follows a write, or vice-versa. Some drivers will merge adjacent fragments into a single transaction using this flag; some will not.

I2C_MSG_ADDR_10_BITS

Use 10-bit addressing for this message.

Note

Not all SoC I2C implementations support this feature.

I2C_DECLARE_CLIENT_CONFIG
I2C_CLIENT(_master, _addr)
I2C_GET_MASTER(_conf)
I2C_GET_ADDR(_conf)

Functions

int i2c_configure(struct device *dev, u32_t dev_config)

Configure operation of a host controller.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • dev_config: Bit-packed 32-bit value to the device runtime configuration for the I2C controller.

Return Value

  • 0: If successful.

  • -EIO: General input / output error, failed to configure device.

int i2c_transfer(struct device *dev, struct i2c_msg *msgs, u8_t num_msgs, u16_t addr)

Perform data transfer to another I2C device.

This routine provides a generic interface to perform data transfer to another I2C device synchronously. Use i2c_read()/i2c_write() for simple read or write.

The array of message msgs must not be NULL. The number of message num_msgs may be zero,in which case no transfer occurs.

Note

Not all scatter/gather transactions can be supported by all drivers. As an example, a gather write (multiple consecutive i2c_msg buffers all configured for I2C_MSG_WRITE) may be packed into a single transaction by some drivers, but others may emit each fragment as a distinct write transaction, which will not produce the same behavior. See the documentation of struct i2c_msg for limitations on support for multi-message bus transactions.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • msgs: Array of messages to transfer.

  • num_msgs: Number of messages to transfer.

  • addr: Address of the I2C target device.

Return Value

  • 0: If successful.

  • -EIO: General input / output error.

int i2c_slave_register(struct device *dev, struct i2c_slave_config *cfg)

Registers the provided config as Slave device.

Enable I2C slave mode for the ‘dev’ I2C bus driver using the provided ‘config’ struct containing the functions and parameters to send bus events. The I2C slave will be registered at the address provided as ‘address’ struct member. Addressing mode - 7 or 10 bit - depends on the ‘flags’ struct member. Any I2C bus events related to the slave mode will be passed onto I2C slave device driver via a set of callback functions provided in the ‘callbacks’ struct member.

Most of the existing hardware allows simultaneous support for master and slave mode. This is however not guaranteed.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • cfg: Config struct with functions and parameters used by the I2C driver to send bus events

Return Value

  • 0: Is successful

  • -EINVAL: If parameters are invalid

  • -EIO: General input / output error.

  • -ENOTSUP: If slave mode is not supported

int i2c_slave_unregister(struct device *dev, struct i2c_slave_config *cfg)

Unregisters the provided config as Slave device.

This routine disables I2C slave mode for the ‘dev’ I2C bus driver using the provided ‘config’ struct containing the functions and parameters to send bus events.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • cfg: Config struct with functions and parameters used by the I2C driver to send bus events

Return Value

  • 0: Is successful

  • -EINVAL: If parameters are invalid

  • -ENOTSUP: If slave mode is not supported

int i2c_slave_driver_register(struct device *dev)

Instructs the I2C Slave device to register itself to the I2C Controller.

This routine instructs the I2C Slave device to register itself to the I2C Controller.

Parameters

  • dev: Pointer to the device structure for the driver instance.

Return Value

  • 0: Is successful

  • -EINVAL: If parameters are invalid

  • -EIO: General input / output error.

int i2c_slave_driver_unregister(struct device *dev)

Instructs the I2C Slave device to unregister itself from the I2C Controller.

This routine instructs the I2C Slave device to unregister itself from the I2C Controller.

Parameters

  • dev: Pointer to the device structure for the driver instance.

Return Value

  • 0: Is successful

  • -EINVAL: If parameters are invalid

static int i2c_write(struct device *dev, const u8_t *buf, u32_t num_bytes, u16_t addr)

Write a set amount of data to an I2C device.

This routine writes a set amount of data synchronously.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • buf: Memory pool from which the data is transferred.

  • num_bytes: Number of bytes to write.

  • addr: Address to the target I2C device for writing.

Return Value

  • 0: If successful.

  • -EIO: General input / output error.

static int i2c_read(struct device *dev, u8_t *buf, u32_t num_bytes, u16_t addr)

Read a set amount of data from an I2C device.

This routine reads a set amount of data synchronously.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • buf: Memory pool that stores the retrieved data.

  • num_bytes: Number of bytes to read.

  • addr: Address of the I2C device being read.

Return Value

  • 0: If successful.

  • -EIO: General input / output error.

static int i2c_write_read(struct device *dev, u16_t addr, const void *write_buf, size_t num_write, void *read_buf, size_t num_read)

Write then read data from an I2C device.

This supports the common operation “this is what I want”, “now give

it to me” transaction pair through a combined write-then-read bus transaction.

Parameters

  • dev: Pointer to the device structure for the driver instance

  • addr: Address of the I2C device

  • write_buf: Pointer to the data to be written

  • num_write: Number of bytes to write

  • read_buf: Pointer to storage for read data

  • num_read: Number of bytes to read

Return Value

  • 0: if successful

  • negative: on error.

static int i2c_burst_read(struct device *dev, u16_t dev_addr, u8_t start_addr, u8_t *buf, u32_t num_bytes)

Read multiple bytes from an internal address of an I2C device.

This routine reads multiple bytes from an internal address of an I2C device synchronously.

Instances of this may be replaced by i2c_write_read().

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • dev_addr: Address of the I2C device for reading.

  • start_addr: Internal address from which the data is being read.

  • buf: Memory pool that stores the retrieved data.

  • num_bytes: Number of bytes being read.

Return Value

  • 0: If successful.

  • -EIO: General input / output error.

static int i2c_burst_write(struct device *dev, u16_t dev_addr, u8_t start_addr, const u8_t *buf, u32_t num_bytes)

Write multiple bytes to an internal address of an I2C device.

This routine writes multiple bytes to an internal address of an I2C device synchronously.

Warning

The combined write synthesized by this API may not be supported on all I2C devices. Uses of this API may be made more portable by replacing them with calls to i2c_write() passing a buffer containing the combined address and data.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • dev_addr: Address of the I2C device for writing.

  • start_addr: Internal address to which the data is being written.

  • buf: Memory pool from which the data is transferred.

  • num_bytes: Number of bytes being written.

Return Value

  • 0: If successful.

  • -EIO: General input / output error.

static int i2c_reg_read_byte(struct device *dev, u16_t dev_addr, u8_t reg_addr, u8_t *value)

Read internal register of an I2C device.

This routine reads the value of an 8-bit internal register of an I2C device synchronously.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • dev_addr: Address of the I2C device for reading.

  • reg_addr: Address of the internal register being read.

  • value: Memory pool that stores the retrieved register value.

Return Value

  • 0: If successful.

  • -EIO: General input / output error.

static int i2c_reg_write_byte(struct device *dev, u16_t dev_addr, u8_t reg_addr, u8_t value)

Write internal register of an I2C device.

This routine writes a value to an 8-bit internal register of an I2C device synchronously.

Note

This function internally combines the register and value into a single bus transaction.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • dev_addr: Address of the I2C device for writing.

  • reg_addr: Address of the internal register being written.

  • value: Value to be written to internal register.

Return Value

  • 0: If successful.

  • -EIO: General input / output error.

static int i2c_reg_update_byte(struct device *dev, u8_t dev_addr, u8_t reg_addr, u8_t mask, u8_t value)

Update internal register of an I2C device.

This routine updates the value of a set of bits from an 8-bit internal register of an I2C device synchronously.

Note

If the calculated new register value matches the value that was read this function will not generate a write operation.

Parameters

  • dev: Pointer to the device structure for the driver instance.

  • dev_addr: Address of the I2C device for updating.

  • reg_addr: Address of the internal register being updated.

  • mask: Bitmask for updating internal register.

  • value: Value for updating internal register.

Return Value

  • 0: If successful.

  • -EIO: General input / output error.

struct i2c_msg
#include <i2c.h>

One I2C Message.

This defines one I2C message to transact on the I2C bus.

Note

Some of the configurations supported by this API may not be supported by specific SoC I2C hardware implementations, in particular features related to bus transactions intended to read or write data from different buffers within a single transaction. Invocations of i2c_transfer() may not indicate an error when an unsupported configuration is encountered. In some cases drivers will generate separate transactions for each message fragment, with or without presence of I2C_MSG_RESTART in flags.