i2c.h File Reference

Main header file for I2C (Inter-Integrated Circuit) driver API. More...

#include <errno.h>
#include <zephyr/types.h>
#include <zephyr/device.h>
#include <zephyr/kernel.h>
#include <zephyr/sys/slist.h>
#include <zephyr/rtio/rtio.h>
#include <zephyr/stats/stats.h>
#include <zephyr/syscalls/i2c.h>

Go to the source code of this file.

Data Structures
struct	i2c_dt_spec
	Complete I2C DT information. More...
struct	i2c_msg
	One I2C Message. More...
struct	i2c_target_callbacks
	Structure providing callbacks to be implemented for devices that supports the I2C target API. More...
struct	i2c_target_config
	Structure describing a device that supports the I2C target API. More...
struct	i2c_device_state
	I2C specific device state which allows for i2c device class specific additions. More...

Macros
#define	I2C_SPEED_STANDARD   (0x1U)
	I2C Standard Speed: 100 kHz.
#define	I2C_SPEED_FAST   (0x2U)
	I2C Fast Speed: 400 kHz.
#define	I2C_SPEED_FAST_PLUS   (0x3U)
	I2C Fast Plus Speed: 1 MHz.
#define	I2C_SPEED_HIGH   (0x4U)
	I2C High Speed: 3.4 MHz.
#define	I2C_SPEED_ULTRA   (0x5U)
	I2C Ultra Fast Speed: 5 MHz.
#define	I2C_SPEED_DT   (0x7U)
	Device Tree specified speed.
#define	I2C_SPEED_SHIFT   (1U)
#define	I2C_SPEED_SET(speed)
#define	I2C_SPEED_MASK   (0x7U << I2C_SPEED_SHIFT) /* 3 bits */
#define	I2C_SPEED_GET(cfg)
#define	I2C_ADDR_10_BITS   BIT(0)
	Use 10-bit addressing.
#define	I2C_MODE_CONTROLLER   BIT(4)
	Peripheral to act as Controller.
#define	I2C_DT_SPEC_GET_ON_I3C(node_id)
	Structure initializer for i2c_dt_spec from devicetree (on I3C bus)
#define	I2C_DT_SPEC_GET_ON_I2C(node_id)
	Structure initializer for i2c_dt_spec from devicetree (on I2C bus)
#define	I2C_DT_SPEC_GET(node_id)
	Structure initializer for i2c_dt_spec from devicetree.
#define	I2C_DT_SPEC_INST_GET(inst)    I2C_DT_SPEC_GET(DT_DRV_INST(inst))
	Structure initializer for i2c_dt_spec from devicetree instance.
#define	I2C_MSG_WRITE   (0U << 0U)
	Write message to I2C bus.
#define	I2C_MSG_READ   BIT(0)
	Read message from I2C bus.
#define	I2C_MSG_STOP   BIT(1)
	Send STOP after this message.
#define	I2C_MSG_RESTART   BIT(2)
	RESTART I2C transaction for this message.
#define	I2C_MSG_ADDR_10_BITS   BIT(3)
	Use 10-bit addressing for this message.
#define	I2C_TARGET_FLAGS_ADDR_10_BITS   BIT(0)
	Target device responds to 10-bit addressing.
#define	I2C_DEVICE_DT_DEINIT_DEFINE(node_id, init_fn, deinit_fn, pm, data, config, level, prio, api, ...)
	Like DEVICE_DT_DEINIT_DEFINE() with I2C specifics.
#define	I2C_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, prio, api, ...)
	Like I2C_DEVICE_DT_DEINIT_DEFINE() but without deinit_fn.
#define	I2C_DEVICE_DT_INST_DEINIT_DEFINE(inst, ...)    I2C_DEVICE_DT_DEINIT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
	Like I2C_DEVICE_DT_DEINIT_DEFINE() for an instance of a DT_DRV_COMPAT compatible.
#define	I2C_DEVICE_DT_INST_DEFINE(inst, ...)    I2C_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
	Like I2C_DEVICE_DT_DEFINE() for an instance of a DT_DRV_COMPAT compatible.
#define	I2C_CAT2(x, y)   x ## y
#define	I2C_DT_IODEV_DEFINE(name, node_id)
	Define an iodev for a given dt node on the bus.
#define	I2C_IODEV_DEFINE(name, _bus, _addr)
	Define an iodev for a given i2c device on a bus.

Typedefs
typedef void(*	i2c_callback_t) (const struct device *dev, int result, void *data)
	I2C callback for asynchronous transfer requests.
typedef int(*	i2c_target_write_requested_cb_t) (struct i2c_target_config *config)
	Function called when a write to the device is initiated.
typedef int(*	i2c_target_write_received_cb_t) (struct i2c_target_config *config, uint8_t val)
	Function called when a write to the device is continued.
typedef int(*	i2c_target_read_requested_cb_t) (struct i2c_target_config *config, uint8_t *val)
	Function called when a read from the device is initiated.
typedef int(*	i2c_target_read_processed_cb_t) (struct i2c_target_config *config, uint8_t *val)
	Function called when a read from the device is continued.
typedef int(*	i2c_target_stop_cb_t) (struct i2c_target_config *config)
	Function called when a stop condition is observed after a start condition addressed to a particular device.
typedef void(*	i2c_target_error_cb_t) (struct i2c_target_config *config, enum i2c_error_reason error_code)
	Function called when an error is detected on the I2C bus while acting as a target.

Enumerations
enum	i2c_error_reason {   I2C_ERROR_TIMEOUT = 0 , I2C_ERROR_ARBITRATION , I2C_ERROR_SIZE , I2C_ERROR_DMA ,   I2C_ERROR_GENERIC }
	I2C error reasons. More...

Functions
static bool	i2c_is_ready_dt (const struct i2c_dt_spec *spec)
	Validate that I2C bus is ready.
static bool	i2c_is_read_op (const struct i2c_msg *msg)
	Check if the current message is a read operation.
static bool	i2c_is_stop_op (const struct i2c_msg *msg)
	Check if the current message includes a stop.
void	i2c_dump_msgs_rw (const struct device *dev, const struct i2c_msg *msgs, uint8_t num_msgs, uint16_t addr, bool dump_read)
	Dump out an I2C message.
static void	i2c_dump_msgs (const struct device *dev, const struct i2c_msg *msgs, uint8_t num_msgs, uint16_t addr)
	Dump out an I2C message, before it is executed.
static void	i2c_xfer_stats (const struct device *dev, struct i2c_msg *msgs, uint8_t num_msgs)
	Updates the i2c stats for i2c transfers.
int	i2c_configure (const struct device *dev, uint32_t dev_config)
	Configure operation of a host controller.
static int	i2c_configure_dt (const struct i2c_dt_spec *spec, uint32_t dev_config)
	Configure operation of a host controller.
int	i2c_get_config (const struct device *dev, uint32_t *dev_config)
	Get configuration of a host controller.
int	i2c_transfer (const struct device *dev, struct i2c_msg *msgs, uint8_t num_msgs, uint16_t addr)
	Perform data transfer to another I2C device in controller mode.
static int	i2c_transfer_cb (const struct device *dev, struct i2c_msg *msgs, uint8_t num_msgs, uint16_t addr, i2c_callback_t cb, void *userdata)
	Perform data transfer to another I2C device in controller mode.
static int	i2c_transfer_cb_dt (const struct i2c_dt_spec *spec, struct i2c_msg *msgs, uint8_t num_msgs, i2c_callback_t cb, void *userdata)
	Perform data transfer to another I2C device in master mode asynchronously.
static int	i2c_write_read_cb (const struct device *dev, struct i2c_msg *msgs, uint8_t num_msgs, uint16_t addr, const void *write_buf, size_t num_write, void *read_buf, size_t num_read, i2c_callback_t cb, void *userdata)
	Write then read data from an I2C device asynchronously.
static int	i2c_write_read_cb_dt (const struct i2c_dt_spec *spec, struct i2c_msg *msgs, uint8_t num_msgs, const void *write_buf, size_t num_write, void *read_buf, size_t num_read, i2c_callback_t cb, void *userdata)
	Write then read data from an I2C device asynchronously.
static int	i2c_transfer_signal (const struct device *dev, struct i2c_msg *msgs, uint8_t num_msgs, uint16_t addr, struct k_poll_signal *sig)
	Perform data transfer to another I2C device in controller mode.
void	i2c_iodev_submit_fallback (const struct device *dev, struct rtio_iodev_sqe *iodev_sqe)
	Fallback submit implementation.
static void	i2c_iodev_submit (struct rtio_iodev_sqe *iodev_sqe)
	Submit request(s) to an I2C device with RTIO.
static bool	i2c_is_ready_iodev (const struct rtio_iodev *i2c_iodev)
	Validate that I2C bus is ready.
struct rtio_sqe *	i2c_rtio_copy (struct rtio *r, struct rtio_iodev *iodev, const struct i2c_msg *msgs, uint8_t num_msgs)
	Copy the i2c_msgs into a set of RTIO requests.
struct rtio_sqe *	i2c_rtio_copy_reg_write_byte (struct rtio *r, struct rtio_iodev *iodev, uint8_t reg_addr, uint8_t data)
	Copy the register address and data to a SQE.
struct rtio_sqe *	i2c_rtio_copy_reg_burst_read (struct rtio *r, struct rtio_iodev *iodev, uint8_t start_addr, void *buf, size_t num_bytes)
	acquire and configure a i2c burst read transmission
static int	i2c_transfer_dt (const struct i2c_dt_spec *spec, struct i2c_msg *msgs, uint8_t num_msgs)
	Perform data transfer to another I2C device in controller mode.
int	i2c_recover_bus (const struct device *dev)
	Recover the I2C bus.
static int	i2c_target_register (const struct device *dev, struct i2c_target_config *cfg)
	Registers the provided config as Target device of a controller.
static int	i2c_target_unregister (const struct device *dev, struct i2c_target_config *cfg)
	Unregisters the provided config as Target device.
int	i2c_target_driver_register (const struct device *dev)
	Instructs the I2C Target device to register itself to the I2C Controller.
int	i2c_target_driver_unregister (const struct device *dev)
	Instructs the I2C Target device to unregister itself from the I2C Controller.
static int	i2c_write (const struct device *dev, const uint8_t *buf, uint32_t num_bytes, uint16_t addr)
	Write a set amount of data to an I2C device.
static int	i2c_write_dt (const struct i2c_dt_spec *spec, const uint8_t *buf, uint32_t num_bytes)
	Write a set amount of data to an I2C device.
static int	i2c_read (const struct device *dev, uint8_t *buf, uint32_t num_bytes, uint16_t addr)
	Read a set amount of data from an I2C device.
static int	i2c_read_dt (const struct i2c_dt_spec *spec, uint8_t *buf, uint32_t num_bytes)
	Read a set amount of data from an I2C device.
static int	i2c_write_read (const struct device *dev, uint16_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.
static int	i2c_write_read_dt (const struct i2c_dt_spec *spec, const void *write_buf, size_t num_write, void *read_buf, size_t num_read)
	Write then read data from an I2C device.
static int	i2c_burst_read (const struct device *dev, uint16_t dev_addr, uint8_t start_addr, uint8_t *buf, uint32_t num_bytes)
	Read multiple bytes from an internal address of an I2C device.
static int	i2c_burst_read_dt (const struct i2c_dt_spec *spec, uint8_t start_addr, uint8_t *buf, uint32_t num_bytes)
	Read multiple bytes from an internal address of an I2C device.
static int	i2c_burst_write (const struct device *dev, uint16_t dev_addr, uint8_t start_addr, const uint8_t *buf, uint32_t num_bytes)
	Write multiple bytes to an internal address of an I2C device.
static int	i2c_burst_write_dt (const struct i2c_dt_spec *spec, uint8_t start_addr, const uint8_t *buf, uint32_t num_bytes)
	Write multiple bytes to an internal address of an I2C device.
static int	i2c_reg_read_byte (const struct device *dev, uint16_t dev_addr, uint8_t reg_addr, uint8_t *value)
	Read internal register of an I2C device.
static int	i2c_reg_read_byte_dt (const struct i2c_dt_spec *spec, uint8_t reg_addr, uint8_t *value)
	Read internal register of an I2C device.
static int	i2c_reg_write_byte (const struct device *dev, uint16_t dev_addr, uint8_t reg_addr, uint8_t value)
	Write internal register of an I2C device.
static int	i2c_reg_write_byte_dt (const struct i2c_dt_spec *spec, uint8_t reg_addr, uint8_t value)
	Write internal register of an I2C device.
static int	i2c_reg_update_byte (const struct device *dev, uint8_t dev_addr, uint8_t reg_addr, uint8_t mask, uint8_t value)
	Update internal register of an I2C device.
static int	i2c_reg_update_byte_dt (const struct i2c_dt_spec *spec, uint8_t reg_addr, uint8_t mask, uint8_t value)
	Update internal register of an I2C device.

Variables
const struct rtio_iodev_api	i2c_iodev_api

Detailed Description

Main header file for I2C (Inter-Integrated Circuit) driver API.