i2c.h

Go to the documentation of this file.

 
/*
 * Copyright (c) 2015 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_DRIVERS_I2C_H_
#define ZEPHYR_INCLUDE_DRIVERS_I2C_H_
 
#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>
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
 * The following #defines are used to configure the I2C controller.
 */
 
#define I2C_SPEED_STANDARD              (0x1U)
 
#define I2C_SPEED_FAST                  (0x2U)
 
#define I2C_SPEED_FAST_PLUS             (0x3U)
 
#define I2C_SPEED_HIGH                  (0x4U)
 
#define I2C_SPEED_ULTRA                 (0x5U)
 
#define I2C_SPEED_DT                    (0x7U)
 
#define I2C_SPEED_SHIFT                 (1U)
#define I2C_SPEED_SET(speed)            (((speed) << I2C_SPEED_SHIFT) \
                                                & I2C_SPEED_MASK)
#define I2C_SPEED_MASK                  (0x7U << I2C_SPEED_SHIFT) /* 3 bits */
#define I2C_SPEED_GET(cfg)              (((cfg) & I2C_SPEED_MASK) \
                                                >> I2C_SPEED_SHIFT)
 
#define I2C_ADDR_10_BITS                BIT(0)
 
#define I2C_MODE_CONTROLLER             BIT(4)
 
struct i2c_dt_spec {
        const struct device *bus;
        uint16_t addr;
};
 
#define I2C_DT_SPEC_GET_ON_I3C(node_id)                                 \
        .bus = DEVICE_DT_GET(DT_BUS(node_id)),                          \
        .addr = DT_PROP_BY_IDX(node_id, reg, 0)
 
#define I2C_DT_SPEC_GET_ON_I2C(node_id)                                 \
        .bus = DEVICE_DT_GET(DT_BUS(node_id)),                          \
        .addr = DT_REG_ADDR(node_id)
 
#define I2C_DT_SPEC_GET(node_id)                                        \
        {                                                               \
                COND_CODE_1(DT_ON_BUS(node_id, i3c),                    \
                            (I2C_DT_SPEC_GET_ON_I3C(node_id)),          \
                            (I2C_DT_SPEC_GET_ON_I2C(node_id)))          \
        }
 
#define I2C_DT_SPEC_INST_GET(inst) \
        I2C_DT_SPEC_GET(DT_DRV_INST(inst))
 
 
/*
 * I2C_MSG_* are I2C Message flags.
 */
 
#define I2C_MSG_WRITE                   (0U << 0U)
 
#define I2C_MSG_READ                    BIT(0)
 
#define I2C_MSG_RW_MASK                 BIT(0)
#define I2C_MSG_STOP                    BIT(1)
 
#define I2C_MSG_RESTART                 BIT(2)
 
#define I2C_MSG_ADDR_10_BITS            BIT(3)
 
struct i2c_msg {
        uint8_t         *buf;
 
        uint32_t        len;
 
        uint8_t         flags;
};
 
typedef void (*i2c_callback_t)(const struct device *dev, int result, void *data);
 
struct i2c_target_config;
 
typedef int (*i2c_api_configure_t)(const struct device *dev,
                                   uint32_t dev_config);
typedef int (*i2c_api_get_config_t)(const struct device *dev,
                                    uint32_t *dev_config);
typedef int (*i2c_api_full_io_t)(const struct device *dev,
                                 struct i2c_msg *msgs,
                                 uint8_t num_msgs,
                                 uint16_t addr);
typedef int (*i2c_api_target_register_t)(const struct device *dev,
                                        struct i2c_target_config *cfg);
typedef int (*i2c_api_target_unregister_t)(const struct device *dev,
                                          struct i2c_target_config *cfg);
#ifdef CONFIG_I2C_CALLBACK
typedef int (*i2c_api_transfer_cb_t)(const struct device *dev,
                                 struct i2c_msg *msgs,
                                 uint8_t num_msgs,
                                 uint16_t addr,
                                 i2c_callback_t cb,
                                 void *userdata);
#endif /* CONFIG_I2C_CALLBACK */
#if defined(CONFIG_I2C_RTIO) || defined(DOXYGEN)
 
typedef void (*i2c_api_iodev_submit)(const struct device *dev,
                                     struct rtio_iodev_sqe *iodev_sqe);
#endif /* CONFIG_I2C_RTIO */
 
typedef int (*i2c_api_recover_bus_t)(const struct device *dev);
 
__subsystem struct i2c_driver_api {
        i2c_api_configure_t configure;
        i2c_api_get_config_t get_config;
        i2c_api_full_io_t transfer;
        i2c_api_target_register_t target_register;
        i2c_api_target_unregister_t target_unregister;
#ifdef CONFIG_I2C_CALLBACK
        i2c_api_transfer_cb_t transfer_cb;
#endif
#ifdef CONFIG_I2C_RTIO
        i2c_api_iodev_submit iodev_submit;
#endif
        i2c_api_recover_bus_t recover_bus;
};
 
typedef int (*i2c_target_api_register_t)(const struct device *dev);
typedef int (*i2c_target_api_unregister_t)(const struct device *dev);
 
struct i2c_target_driver_api {
        i2c_target_api_register_t driver_register;
        i2c_target_api_unregister_t driver_unregister;
};
 
#define I2C_TARGET_FLAGS_ADDR_10_BITS   BIT(0)
 
typedef int (*i2c_target_write_requested_cb_t)(
                struct i2c_target_config *config);
 
typedef int (*i2c_target_write_received_cb_t)(
                struct i2c_target_config *config, uint8_t val);
 
typedef int (*i2c_target_read_requested_cb_t)(
                struct i2c_target_config *config, uint8_t *val);
 
typedef int (*i2c_target_read_processed_cb_t)(
                struct i2c_target_config *config, uint8_t *val);
 
typedef int (*i2c_target_stop_cb_t)(struct i2c_target_config *config);
 
struct i2c_target_callbacks {
        i2c_target_write_requested_cb_t write_requested;
        i2c_target_read_requested_cb_t read_requested;
        i2c_target_write_received_cb_t write_received;
        i2c_target_read_processed_cb_t read_processed;
        i2c_target_stop_cb_t stop;
};
 
struct i2c_target_config {
        sys_snode_t node;
 
        uint8_t flags;
 
        uint16_t address;
 
        const struct i2c_target_callbacks *callbacks;
};
 
static inline bool i2c_is_ready_dt(const struct i2c_dt_spec *spec)
{
        /* Validate bus is ready */
        return device_is_ready(spec->bus);
}
 
void i2c_dump_msgs_rw(const char *name, const struct i2c_msg *msgs,
                      uint8_t num_msgs, uint16_t addr, bool dump_read);
 
static inline void i2c_dump_msgs(const char *name, const struct i2c_msg *msgs,
                                 uint8_t num_msgs, uint16_t addr)
{
        i2c_dump_msgs_rw(name, msgs, num_msgs, addr, false);
}
 
#if defined(CONFIG_I2C_STATS) || defined(__DOXYGEN__)
 
#include <zephyr/stats/stats.h>
 
STATS_SECT_START(i2c)
STATS_SECT_ENTRY32(bytes_read)
STATS_SECT_ENTRY32(bytes_written)
STATS_SECT_ENTRY32(message_count)
STATS_SECT_ENTRY32(transfer_call_count)
STATS_SECT_END;
 
STATS_NAME_START(i2c)
STATS_NAME(i2c, bytes_read)
STATS_NAME(i2c, bytes_written)
STATS_NAME(i2c, message_count)
STATS_NAME(i2c, transfer_call_count)
STATS_NAME_END(i2c);
 
struct i2c_device_state {
        struct device_state devstate;
        struct stats_i2c stats;
};
 
static inline void i2c_xfer_stats(const struct device *dev, struct i2c_msg *msgs,
                                  uint8_t num_msgs)
{
        struct i2c_device_state *state =
                CONTAINER_OF(dev->state, struct i2c_device_state, devstate);
        uint32_t bytes_read = 0U;
        uint32_t bytes_written = 0U;
 
        STATS_INC(state->stats, transfer_call_count);
        STATS_INCN(state->stats, message_count, num_msgs);
        for (uint8_t i = 0U; i < num_msgs; i++) {
                if (msgs[i].flags & I2C_MSG_READ) {
                        bytes_read += msgs[i].len;
                } else {
                        bytes_written += msgs[i].len;
                }
        }
        STATS_INCN(state->stats, bytes_read, bytes_read);
        STATS_INCN(state->stats, bytes_written, bytes_written);
}
 
#define Z_I2C_DEVICE_STATE_DEFINE(dev_id)                               \
        static struct i2c_device_state Z_DEVICE_STATE_NAME(dev_id)      \
        __attribute__((__section__(".z_devstate")))
 
#define Z_I2C_INIT_FN(dev_id, init_fn)                                  \
        static inline int UTIL_CAT(dev_id, _init)(const struct device *dev) \
        {                                                               \
                struct i2c_device_state *state =                        \
                        CONTAINER_OF(dev->state, struct i2c_device_state, devstate); \
                stats_init(&state->stats.s_hdr, STATS_SIZE_32, 4,       \
                           STATS_NAME_INIT_PARMS(i2c));                 \
                stats_register(dev->name, &(state->stats.s_hdr));       \
                if (init_fn != NULL) {                                  \
                        return init_fn(dev);                            \
                }                                                       \
                                                                        \
                return 0;                                               \
        }
 
#define I2C_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
                             prio, api, ...)                            \
        Z_I2C_DEVICE_STATE_DEFINE(Z_DEVICE_DT_DEV_ID(node_id));         \
        Z_I2C_INIT_FN(Z_DEVICE_DT_DEV_ID(node_id), init_fn)             \
        Z_DEVICE_DEFINE(node_id, Z_DEVICE_DT_DEV_ID(node_id),           \
                        DEVICE_DT_NAME(node_id),                        \
                        &UTIL_CAT(Z_DEVICE_DT_DEV_ID(node_id), _init),  \
                        pm_device, data, config, level, prio, api,      \
                        &(Z_DEVICE_STATE_NAME(Z_DEVICE_DT_DEV_ID(node_id)).devstate), \
                        __VA_ARGS__)
 
#else /* CONFIG_I2C_STATS */
 
static inline void i2c_xfer_stats(const struct device *dev, struct i2c_msg *msgs,
                                  uint8_t num_msgs)
{
        ARG_UNUSED(dev);
        ARG_UNUSED(msgs);
        ARG_UNUSED(num_msgs);
}
 
#define I2C_DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level, \
                             prio, api, ...)                            \
        DEVICE_DT_DEFINE(node_id, init_fn, pm, data, config, level,     \
                         prio, api, __VA_ARGS__)
 
#endif /* CONFIG_I2C_STATS */
 
#define I2C_DEVICE_DT_INST_DEFINE(inst, ...)            \
        I2C_DEVICE_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
 
 
__syscall int i2c_configure(const struct device *dev, uint32_t dev_config);
 
static inline int z_impl_i2c_configure(const struct device *dev,
                                       uint32_t dev_config)
{
        const struct i2c_driver_api *api =
                (const struct i2c_driver_api *)dev->api;
 
        return api->configure(dev, dev_config);
}
 
__syscall int i2c_get_config(const struct device *dev, uint32_t *dev_config);
 
static inline int z_impl_i2c_get_config(const struct device *dev, uint32_t *dev_config)
{
        const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
 
        if (api->get_config == NULL) {
                return -ENOSYS;
        }
 
        return api->get_config(dev, dev_config);
}
 
__syscall int i2c_transfer(const struct device *dev,
                           struct i2c_msg *msgs, uint8_t num_msgs,
                           uint16_t addr);
 
static inline int z_impl_i2c_transfer(const struct device *dev,
                                      struct i2c_msg *msgs, uint8_t num_msgs,
                                      uint16_t addr)
{
        const struct i2c_driver_api *api =
                (const struct i2c_driver_api *)dev->api;
 
        int res =  api->transfer(dev, msgs, num_msgs, addr);
 
        i2c_xfer_stats(dev, msgs, num_msgs);
 
        if (IS_ENABLED(CONFIG_I2C_DUMP_MESSAGES)) {
                i2c_dump_msgs_rw(dev->name, msgs, num_msgs, addr, true);
        }
 
        return res;
}
 
#ifdef CONFIG_I2C_CALLBACK
 
static inline 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)
{
        const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
 
        if (api->transfer_cb == NULL) {
                return -ENOSYS;
        }
 
        return api->transfer_cb(dev, msgs, num_msgs, addr, cb, userdata);
}
 
static inline 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)
{
        return i2c_transfer_cb(spec->bus, msgs, num_msgs, spec->addr, cb, userdata);
}
 
static inline 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)
{
        if ((msgs == NULL) || (num_msgs != 2)) {
                return -EINVAL;
        }
 
        msgs[0].buf = (uint8_t *)write_buf;
        msgs[0].len = num_write;
        msgs[0].flags = I2C_MSG_WRITE;
 
        msgs[1].buf = (uint8_t *)read_buf;
        msgs[1].len = num_read;
        msgs[1].flags = I2C_MSG_RESTART | I2C_MSG_READ | I2C_MSG_STOP;
 
        return i2c_transfer_cb(dev, msgs, num_msgs, addr, cb, userdata);
}
 
static inline 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)
{
        return i2c_write_read_cb(spec->bus, msgs, num_msgs, spec->addr, write_buf, num_write,
                                 read_buf, num_read, cb, userdata);
}
 
#ifdef CONFIG_POLL
 
void z_i2c_transfer_signal_cb(const struct device *dev, int result, void *userdata);
static inline int i2c_transfer_signal(const struct device *dev,
                                 struct i2c_msg *msgs,
                                 uint8_t num_msgs,
                                 uint16_t addr,
                                 struct k_poll_signal *sig)
{
        const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
 
        if (api->transfer_cb == NULL) {
                return -ENOSYS;
        }
 
        return api->transfer_cb(dev, msgs, num_msgs, addr, z_i2c_transfer_signal_cb, sig);
}
 
#endif /* CONFIG_POLL */
 
#endif /* CONFIG_I2C_CALLBACK */
 
 
#if defined(CONFIG_I2C_RTIO) || defined(DOXYGEN)
 
static inline void i2c_iodev_submit(struct rtio_iodev_sqe *iodev_sqe)
{
        const struct i2c_dt_spec *dt_spec = iodev_sqe->sqe->iodev->data;
        const struct device *dev = dt_spec->bus;
        const struct i2c_driver_api *api = (const struct i2c_driver_api *)dev->api;
 
        api->iodev_submit(dt_spec->bus, iodev_sqe);
}
 
extern const struct rtio_iodev_api i2c_iodev_api;
 
#define I2C_DT_IODEV_DEFINE(name, node_id)                                      \
        const struct i2c_dt_spec _i2c_dt_spec_##name =                          \
                I2C_DT_SPEC_GET(node_id);                                       \
        RTIO_IODEV_DEFINE(name, &i2c_iodev_api, (void *)&_i2c_dt_spec_##name)
 
struct rtio_sqe *i2c_rtio_copy(struct rtio *r,
                               struct rtio_iodev *iodev,
                               const struct i2c_msg *msgs,
                               uint8_t num_msgs);
 
#endif /* CONFIG_I2C_RTIO */
 
static inline int i2c_transfer_dt(const struct i2c_dt_spec *spec,
                                  struct i2c_msg *msgs, uint8_t num_msgs)
{
        return i2c_transfer(spec->bus, msgs, num_msgs, spec->addr);
}
 
__syscall int i2c_recover_bus(const struct device *dev);
 
static inline int z_impl_i2c_recover_bus(const struct device *dev)
{
        const struct i2c_driver_api *api =
                (const struct i2c_driver_api *)dev->api;
 
        if (api->recover_bus == NULL) {
                return -ENOSYS;
        }
 
        return api->recover_bus(dev);
}
 
static inline int i2c_target_register(const struct device *dev,
                                     struct i2c_target_config *cfg)
{
        const struct i2c_driver_api *api =
                (const struct i2c_driver_api *)dev->api;
 
        if (api->target_register == NULL) {
                return -ENOSYS;
        }
 
        return api->target_register(dev, cfg);
}
 
static inline int i2c_target_unregister(const struct device *dev,
                                       struct i2c_target_config *cfg)
{
        const struct i2c_driver_api *api =
                (const struct i2c_driver_api *)dev->api;
 
        if (api->target_unregister == NULL) {
                return -ENOSYS;
        }
 
        return api->target_unregister(dev, cfg);
}
 
__syscall int i2c_target_driver_register(const struct device *dev);
 
static inline int z_impl_i2c_target_driver_register(const struct device *dev)
{
        const struct i2c_target_driver_api *api =
                (const struct i2c_target_driver_api *)dev->api;
 
        return api->driver_register(dev);
}
 
__syscall int i2c_target_driver_unregister(const struct device *dev);
 
static inline int z_impl_i2c_target_driver_unregister(const struct device *dev)
{
        const struct i2c_target_driver_api *api =
                (const struct i2c_target_driver_api *)dev->api;
 
        return api->driver_unregister(dev);
}
 
/*
 * Derived i2c APIs -- all implemented in terms of i2c_transfer()
 */
 
static inline int i2c_write(const struct device *dev, const uint8_t *buf,
                            uint32_t num_bytes, uint16_t addr)
{
        struct i2c_msg msg;
 
        msg.buf = (uint8_t *)buf;
        msg.len = num_bytes;
        msg.flags = I2C_MSG_WRITE | I2C_MSG_STOP;
 
        return i2c_transfer(dev, &msg, 1, addr);
}
 
static inline int i2c_write_dt(const struct i2c_dt_spec *spec,
                               const uint8_t *buf, uint32_t num_bytes)
{
        return i2c_write(spec->bus, buf, num_bytes, spec->addr);
}
 
static inline int i2c_read(const struct device *dev, uint8_t *buf,
                           uint32_t num_bytes, uint16_t addr)
{
        struct i2c_msg msg;
 
        msg.buf = buf;
        msg.len = num_bytes;
        msg.flags = I2C_MSG_READ | I2C_MSG_STOP;
 
        return i2c_transfer(dev, &msg, 1, addr);
}
 
static inline int i2c_read_dt(const struct i2c_dt_spec *spec,
                              uint8_t *buf, uint32_t num_bytes)
{
        return i2c_read(spec->bus, buf, num_bytes, spec->addr);
}
 
static inline 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)
{
        struct i2c_msg msg[2];
 
        msg[0].buf = (uint8_t *)write_buf;
        msg[0].len = num_write;
        msg[0].flags = I2C_MSG_WRITE;
 
        msg[1].buf = (uint8_t *)read_buf;
        msg[1].len = num_read;
        msg[1].flags = I2C_MSG_RESTART | I2C_MSG_READ | I2C_MSG_STOP;
 
        return i2c_transfer(dev, msg, 2, addr);
}
 
static inline 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)
{
        return i2c_write_read(spec->bus, spec->addr,
                              write_buf, num_write,
                              read_buf, num_read);
}
 
static inline int i2c_burst_read(const struct device *dev,
                                 uint16_t dev_addr,
                                 uint8_t start_addr,
                                 uint8_t *buf,
                                 uint32_t num_bytes)
{
        return i2c_write_read(dev, dev_addr,
                              &start_addr, sizeof(start_addr),
                              buf, num_bytes);
}
 
static inline int i2c_burst_read_dt(const struct i2c_dt_spec *spec,
                                    uint8_t start_addr,
                                    uint8_t *buf,
                                    uint32_t num_bytes)
{
        return i2c_burst_read(spec->bus, spec->addr,
                              start_addr, buf, num_bytes);
}
 
static inline int i2c_burst_write(const struct device *dev,
                                  uint16_t dev_addr,
                                  uint8_t start_addr,
                                  const uint8_t *buf,
                                  uint32_t num_bytes)
{
        struct i2c_msg msg[2];
 
        msg[0].buf = &start_addr;
        msg[0].len = 1U;
        msg[0].flags = I2C_MSG_WRITE;
 
        msg[1].buf = (uint8_t *)buf;
        msg[1].len = num_bytes;
        msg[1].flags = I2C_MSG_WRITE | I2C_MSG_STOP;
 
        return i2c_transfer(dev, msg, 2, dev_addr);
}
 
static inline int i2c_burst_write_dt(const struct i2c_dt_spec *spec,
                                     uint8_t start_addr,
                                     const uint8_t *buf,
                                     uint32_t num_bytes)
{
        return i2c_burst_write(spec->bus, spec->addr,
                               start_addr, buf, num_bytes);
}
 
static inline int i2c_reg_read_byte(const struct device *dev,
                                    uint16_t dev_addr,
                                    uint8_t reg_addr, uint8_t *value)
{
        return i2c_write_read(dev, dev_addr,
                              &reg_addr, sizeof(reg_addr),
                              value, sizeof(*value));
}
 
static inline int i2c_reg_read_byte_dt(const struct i2c_dt_spec *spec,
                                       uint8_t reg_addr, uint8_t *value)
{
        return i2c_reg_read_byte(spec->bus, spec->addr, reg_addr, value);
}
 
static inline int i2c_reg_write_byte(const struct device *dev,
                                     uint16_t dev_addr,
                                     uint8_t reg_addr, uint8_t value)
{
        uint8_t tx_buf[2] = {reg_addr, value};
 
        return i2c_write(dev, tx_buf, 2, dev_addr);
}
 
static inline int i2c_reg_write_byte_dt(const struct i2c_dt_spec *spec,
                                        uint8_t reg_addr, uint8_t value)
{
        return i2c_reg_write_byte(spec->bus, spec->addr, reg_addr, value);
}
 
static inline int i2c_reg_update_byte(const struct device *dev,
                                      uint8_t dev_addr,
                                      uint8_t reg_addr, uint8_t mask,
                                      uint8_t value)
{
        uint8_t old_value, new_value;
        int rc;
 
        rc = i2c_reg_read_byte(dev, dev_addr, reg_addr, &old_value);
        if (rc != 0) {
                return rc;
        }
 
        new_value = (old_value & ~mask) | (value & mask);
        if (new_value == old_value) {
                return 0;
        }
 
        return i2c_reg_write_byte(dev, dev_addr, reg_addr, new_value);
}
 
static inline int i2c_reg_update_byte_dt(const struct i2c_dt_spec *spec,
                                         uint8_t reg_addr, uint8_t mask,
                                         uint8_t value)
{
        return i2c_reg_update_byte(spec->bus, spec->addr,
                                   reg_addr, mask, value);
}
 
#ifdef __cplusplus
}
#endif
 
#include <syscalls/i2c.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_I2C_H_ */