i3c.h

Go to the documentation of this file.

/*
 * Copyright 2022 Intel Corporation
 * Copyright 2023 Meta Platforms, Inc. and its affiliates
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef ZEPHYR_INCLUDE_DRIVERS_I3C_H_
#define ZEPHYR_INCLUDE_DRIVERS_I3C_H_
 
#include <errno.h>
#include <stdint.h>
#include <stddef.h>
 
#include <zephyr/device.h>
#include <zephyr/drivers/i3c/addresses.h>
#include <zephyr/drivers/i3c/ccc.h>
#include <zephyr/drivers/i3c/devicetree.h>
#include <zephyr/drivers/i3c/ibi.h>
#include <zephyr/drivers/i2c.h>
#include <zephyr/sys/slist.h>
#include <zephyr/sys/util.h>
#include <zephyr/rtio/rtio.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define I3C_BCR_MAX_DATA_SPEED_LIMIT                    BIT(0)
 
#define I3C_BCR_IBI_REQUEST_CAPABLE                     BIT(1)
 
#define I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE               BIT(2)
 
#define I3C_BCR_OFFLINE_CAPABLE                         BIT(3)
 
#define I3C_BCR_VIRTUAL_TARGET                          BIT(4)
 
#define I3C_BCR_ADV_CAPABILITIES                        BIT(5)
 
#define I3C_BCR_DEVICE_ROLE_I3C_TARGET                  0U
 
#define I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE      1U
 
#define I3C_BCR_DEVICE_ROLE_MASK                        GENMASK(7U, 6U)
 
#define I3C_BCR_DEVICE_ROLE(bcr)                        \
        FIELD_GET(I3C_BCR_DEVICE_ROLE_MASK, (bcr))
 
#define I3C_LVR_I2C_FM_PLUS_MODE                        0
 
#define I3C_LVR_I2C_FM_MODE                             1
 
#define I3C_LVR_I2C_MODE_MASK                           BIT(4)
 
#define I3C_LVR_I2C_MODE(lvr)                           \
        FIELD_GET(I3C_LVR_I2C_MODE_MASK, (lvr))
 
#define I3C_LVR_I2C_DEV_IDX_0                           0
 
#define I3C_LVR_I2C_DEV_IDX_1                           1
 
#define I3C_LVR_I2C_DEV_IDX_2                           2
 
#define I3C_LVR_I2C_DEV_IDX_MASK                        GENMASK(7U, 5U)
 
#define I3C_LVR_I2C_DEV_IDX(lvr)                        \
        FIELD_GET(I3C_LVR_I2C_DEV_IDX_MASK, (lvr))
 
enum i3c_bus_mode {
        I3C_BUS_MODE_PURE,
 
        I3C_BUS_MODE_MIXED_FAST,
 
        I3C_BUS_MODE_MIXED_LIMITED,
 
        I3C_BUS_MODE_MIXED_SLOW,
 
        I3C_BUS_MODE_MAX = I3C_BUS_MODE_MIXED_SLOW,
        I3C_BUS_MODE_INVALID,
};
 
enum i3c_i2c_speed_type {
        I3C_I2C_SPEED_FM,
 
        I3C_I2C_SPEED_FMPLUS,
 
        I3C_I2C_SPEED_MAX = I3C_I2C_SPEED_FMPLUS,
        I3C_I2C_SPEED_INVALID,
};
 
enum i3c_data_rate {
        I3C_DATA_RATE_SDR,
 
        I3C_DATA_RATE_HDR_DDR,
 
        I3C_DATA_RATE_HDR_TSL,
 
        I3C_DATA_RATE_HDR_TSP,
 
        I3C_DATA_RATE_HDR_BT,
 
        I3C_DATA_RATE_MAX = I3C_DATA_RATE_HDR_BT,
        I3C_DATA_RATE_INVALID,
};
 
enum i3c_sdr_controller_error_codes {
        I3C_ERROR_CE0,
 
        I3C_ERROR_CE1,
 
        I3C_ERROR_CE2,
 
        I3C_ERROR_CE3,
 
        I3C_ERROR_CE_UNKNOWN,
 
        I3C_ERROR_CE_NONE,
 
        I3C_ERROR_CE_MAX = I3C_ERROR_CE_UNKNOWN,
        I3C_ERROR_CE_INVALID,
};
 
enum i3c_sdr_target_error_codes {
        I3C_ERROR_TE0,
 
        I3C_ERROR_TE1,
 
        I3C_ERROR_TE2,
 
        I3C_ERROR_TE3,
 
        I3C_ERROR_TE4,
 
        I3C_ERROR_TE5,
 
        I3C_ERROR_TE6,
 
        I3C_ERROR_DBR,
 
        I3C_ERROR_TE_UNKNOWN,
 
        I3C_ERROR_TE_NONE,
 
        I3C_ERROR_TE_MAX = I3C_ERROR_TE_UNKNOWN,
        I3C_ERROR_TE_INVALID,
};
 
/*
 * I3C_MSG_* are I3C Message flags.
 */
 
#define I3C_MSG_WRITE                   (0U << 0U)
 
#define I3C_MSG_READ                    BIT(0)
 
#define I3C_MSG_RW_MASK                 BIT(0)
#define I3C_MSG_STOP                    BIT(1)
 
#define I3C_MSG_RESTART                 BIT(2)
 
#define I3C_MSG_HDR                     BIT(3)
 
#define I3C_MSG_NBCH                    BIT(4)
 
#define I3C_MSG_HDR_MODE0               BIT(0)
 
#define I3C_MSG_HDR_MODE1               BIT(1)
 
#define I3C_MSG_HDR_MODE2               BIT(2)
 
#define I3C_MSG_HDR_MODE3               BIT(3)
 
#define I3C_MSG_HDR_MODE4               BIT(4)
 
#define I3C_MSG_HDR_MODE5               BIT(5)
 
#define I3C_MSG_HDR_MODE6               BIT(6)
 
#define I3C_MSG_HDR_MODE7               BIT(7)
 
#define I3C_MSG_HDR_DDR                 I3C_MSG_HDR_MODE0
 
#define I3C_MSG_HDR_TSP                 I3C_MSG_HDR_MODE1
 
#define I3C_MSG_HDR_TSL                 I3C_MSG_HDR_MODE2
 
#define I3C_MSG_HDR_BT                  I3C_MSG_HDR_MODE3
 
struct i3c_msg {
        uint8_t                 *buf;
 
        uint32_t                len;
 
        uint32_t                num_xfer;
 
        uint8_t                 flags;
 
        uint8_t                 hdr_mode;
 
        uint8_t                 hdr_cmd_code;
};
 
enum i3c_config_type {
        I3C_CONFIG_CONTROLLER,
        I3C_CONFIG_TARGET,
        I3C_CONFIG_CUSTOM,
};
 
struct i3c_config_controller {
        bool is_secondary;
 
        struct {
                uint32_t i3c;
 
                uint32_t i2c;
        } scl;
 
        uint8_t supported_hdr;
};
 
struct i3c_config_custom {
        uint32_t id;
 
        union {
                uintptr_t val;
 
                void *ptr;
        };
};
 
struct i3c_device_desc;
struct i3c_device_id;
struct i3c_i2c_device_desc;
struct i3c_target_config;
 
__subsystem struct i3c_driver_api {
        struct i2c_driver_api i2c_api;
 
        int (*configure)(const struct device *dev,
                         enum i3c_config_type type, void *config);
 
        int (*config_get)(const struct device *dev,
                          enum i3c_config_type type, void *config);
 
        int (*recover_bus)(const struct device *dev);
 
        int (*attach_i3c_device)(const struct device *dev,
                        struct i3c_device_desc *target);
 
        int (*reattach_i3c_device)(const struct device *dev,
                        struct i3c_device_desc *target,
                        uint8_t old_dyn_addr);
 
        int (*detach_i3c_device)(const struct device *dev,
                        struct i3c_device_desc *target);
 
        int (*attach_i2c_device)(const struct device *dev,
                        struct i3c_i2c_device_desc *target);
 
        int (*detach_i2c_device)(const struct device *dev,
                        struct i3c_i2c_device_desc *target);
 
        int (*do_daa)(const struct device *dev);
 
        int (*do_ccc)(const struct device *dev,
                      struct i3c_ccc_payload *payload);
 
        int (*i3c_xfers)(const struct device *dev,
                         struct i3c_device_desc *target,
                         struct i3c_msg *msgs,
                         uint8_t num_msgs);
 
        struct i3c_device_desc *(*i3c_device_find)(const struct device *dev,
                                                   const struct i3c_device_id *id);
 
        int (*ibi_raise)(const struct device *dev,
                         struct i3c_ibi *request);
 
        int (*ibi_enable)(const struct device *dev,
                          struct i3c_device_desc *target);
 
        int (*ibi_disable)(const struct device *dev,
                           struct i3c_device_desc *target);
 
        int (*target_register)(const struct device *dev,
                               struct i3c_target_config *cfg);
 
        int (*target_unregister)(const struct device *dev,
                                 struct i3c_target_config *cfg);
 
        int (*target_tx_write)(const struct device *dev,
                                 uint8_t *buf, uint16_t len, uint8_t hdr_mode);
 
#ifdef CONFIG_I3C_RTIO
        void (*iodev_submit)(const struct device *dev,
                                 struct rtio_iodev_sqe *iodev_sqe);
#endif
};
 
struct i3c_device_id {
        const uint64_t pid:48;
};
 
#define I3C_DEVICE_ID(pid)                                              \
        {                                                               \
                .pid = pid                                              \
        }
 
struct i3c_device_desc {
        sys_snode_t node;
 
        const struct device * const bus;
 
        const struct device * const dev;
 
        const uint64_t pid:48;
 
        const uint8_t static_addr;
 
        const uint8_t init_dynamic_addr;
 
        const bool supports_setaasa;
 
        uint8_t dynamic_addr;
 
#if defined(CONFIG_I3C_USE_GROUP_ADDR) || defined(__DOXYGEN__)
        uint8_t group_addr;
#endif /* CONFIG_I3C_USE_GROUP_ADDR */
 
        uint8_t bcr;
 
        uint8_t dcr;
 
        struct {
                uint8_t maxrd;
 
                uint8_t maxwr;
 
                uint32_t max_read_turnaround;
        } data_speed;
 
        struct {
                uint16_t mrl;
 
                uint16_t mwl;
 
                uint8_t max_ibi;
        } data_length;
 
        struct {
                union {
                        uint8_t gethdrcap;
 
                        uint8_t getcap1;
                };
 
                uint8_t getcap2;
 
                uint8_t getcap3;
 
                uint8_t getcap4;
        } getcaps;
 
        void *controller_priv;
#if defined(CONFIG_I3C_USE_IBI) || defined(__DOXYGEN__)
        i3c_target_ibi_cb_t ibi_cb;
#endif /* CONFIG_I3C_USE_IBI */
};
 
struct i3c_i2c_device_desc {
        sys_snode_t node;
 
        const struct device *bus;
 
        const uint16_t addr;
 
        const uint8_t lvr;
 
        void *controller_priv;
};
 
struct i3c_dev_attached_list {
        struct i3c_addr_slots addr_slots;
 
        struct {
                sys_slist_t i3c;
 
                sys_slist_t i2c;
        } devices;
};
 
struct i3c_dev_list {
        struct i3c_device_desc * const i3c;
 
        struct i3c_i2c_device_desc * const i2c;
 
        const uint8_t num_i3c;
 
        const uint8_t num_i2c;
};
 
struct i3c_driver_config {
        struct i3c_dev_list dev_list;
};
 
struct i3c_driver_data {
        struct i3c_config_controller ctrl_config;
 
        struct i3c_dev_attached_list attached_dev;
};
 
#define I3C_BUS_FOR_EACH_I3CDEV(bus, desc)                                                         \
        SYS_SLIST_FOR_EACH_CONTAINER(                                                              \
                &((struct i3c_driver_data *)(bus->data))->attached_dev.devices.i3c, desc, node)
 
#define I3C_BUS_FOR_EACH_I2CDEV(bus, desc)                                                         \
        SYS_SLIST_FOR_EACH_CONTAINER(                                                              \
                &((struct i3c_driver_data *)(bus->data))->attached_dev.devices.i2c, desc, node)
 
struct i3c_device_desc *i3c_dev_list_find(const struct i3c_dev_list *dev_list,
                                          const struct i3c_device_id *id);
 
struct i3c_device_desc *i3c_dev_list_i3c_addr_find(const struct device *dev,
                                                   uint8_t addr);
 
struct i3c_i2c_device_desc *i3c_dev_list_i2c_addr_find(const struct device *dev,
                                                           uint16_t addr);
 
int i3c_dev_list_daa_addr_helper(struct i3c_addr_slots *addr_slots,
                                 const struct i3c_dev_list *dev_list,
                                 uint64_t pid, bool must_match,
                                 bool assigned_okay,
                                 struct i3c_device_desc **target,
                                 uint8_t *addr);
 
static inline int i3c_configure(const struct device *dev,
                                enum i3c_config_type type, void *config)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)dev->api;
 
        if (api->configure == NULL) {
                return -ENOSYS;
        }
 
        return api->configure(dev, type, config);
}
 
static inline int i3c_config_get(const struct device *dev,
                                 enum i3c_config_type type, void *config)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)dev->api;
 
        if (api->config_get == NULL) {
                return -ENOSYS;
        }
 
        return api->config_get(dev, type, config);
}
 
static inline int i3c_recover_bus(const struct device *dev)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)dev->api;
 
        if (api->recover_bus == NULL) {
                return -ENOSYS;
        }
 
        return api->recover_bus(dev);
}
 
int i3c_attach_i3c_device(struct i3c_device_desc *target);
 
int i3c_reattach_i3c_device(struct i3c_device_desc *target, uint8_t old_dyn_addr);
 
int i3c_detach_i3c_device(struct i3c_device_desc *target);
 
int i3c_attach_i2c_device(struct i3c_i2c_device_desc *target);
 
int i3c_detach_i2c_device(struct i3c_i2c_device_desc *target);
 
static inline int i3c_do_daa(const struct device *dev)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)dev->api;
 
        if (api->do_daa == NULL) {
                return -ENOSYS;
        }
 
        return api->do_daa(dev);
}
 
__syscall int i3c_do_ccc(const struct device *dev,
                         struct i3c_ccc_payload *payload);
 
static inline int z_impl_i3c_do_ccc(const struct device *dev,
                                    struct i3c_ccc_payload *payload)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)dev->api;
 
        if (api->do_ccc == NULL) {
                return -ENOSYS;
        }
 
        return api->do_ccc(dev, payload);
}
 
__syscall int i3c_transfer(struct i3c_device_desc *target,
                           struct i3c_msg *msgs, uint8_t num_msgs);
 
static inline int z_impl_i3c_transfer(struct i3c_device_desc *target,
                                      struct i3c_msg *msgs, uint8_t num_msgs)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)target->bus->api;
 
        return api->i3c_xfers(target->bus, target, msgs, num_msgs);
}
 
static inline
struct i3c_device_desc *i3c_device_find(const struct device *dev,
                                        const struct i3c_device_id *id)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)dev->api;
 
        if (api->i3c_device_find == NULL) {
                return NULL;
        }
 
        return api->i3c_device_find(dev, id);
}
 
static inline int i3c_ibi_raise(const struct device *dev,
                                struct i3c_ibi *request)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)dev->api;
 
        if (api->ibi_raise == NULL) {
                return -ENOSYS;
        }
 
        return api->ibi_raise(dev, request);
}
 
static inline int i3c_ibi_enable(struct i3c_device_desc *target)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)target->bus->api;
 
        if (api->ibi_enable == NULL) {
                return -ENOSYS;
        }
 
        return api->ibi_enable(target->bus, target);
}
 
static inline int i3c_ibi_disable(struct i3c_device_desc *target)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)target->bus->api;
 
        if (api->ibi_disable == NULL) {
                return -ENOSYS;
        }
 
        return api->ibi_disable(target->bus, target);
}
 
static inline int i3c_ibi_has_payload(struct i3c_device_desc *target)
{
        return (target->bcr & I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE)
                == I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE;
}
 
static inline int i3c_device_is_ibi_capable(struct i3c_device_desc *target)
{
        return (target->bcr & I3C_BCR_IBI_REQUEST_CAPABLE)
                == I3C_BCR_IBI_REQUEST_CAPABLE;
}
 
static inline int i3c_device_is_controller_capable(struct i3c_device_desc *target)
{
        return I3C_BCR_DEVICE_ROLE(target->bcr)
                == I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE;
}
 
static inline int i3c_write(struct i3c_device_desc *target,
                            const uint8_t *buf, uint32_t num_bytes)
{
        struct i3c_msg msg;
 
        msg.buf = (uint8_t *)buf;
        msg.len = num_bytes;
        msg.flags = I3C_MSG_WRITE | I3C_MSG_STOP;
        msg.hdr_mode = 0;
        msg.hdr_cmd_code = 0;
 
        return i3c_transfer(target, &msg, 1);
}
 
static inline int i3c_read(struct i3c_device_desc *target,
                           uint8_t *buf, uint32_t num_bytes)
{
        struct i3c_msg msg;
 
        msg.buf = buf;
        msg.len = num_bytes;
        msg.flags = I3C_MSG_READ | I3C_MSG_STOP;
        msg.hdr_mode = 0;
        msg.hdr_cmd_code = 0;
 
        return i3c_transfer(target, &msg, 1);
}
 
static inline int i3c_write_read(struct i3c_device_desc *target,
                                 const void *write_buf, size_t num_write,
                                 void *read_buf, size_t num_read)
{
        struct i3c_msg msg[2];
 
        msg[0].buf = (uint8_t *)write_buf;
        msg[0].len = num_write;
        msg[0].flags = I3C_MSG_WRITE;
        msg[0].hdr_mode = 0;
        msg[0].hdr_cmd_code = 0;
 
        msg[1].buf = (uint8_t *)read_buf;
        msg[1].len = num_read;
        msg[1].flags = I3C_MSG_RESTART | I3C_MSG_READ | I3C_MSG_STOP;
        msg[1].hdr_mode = 0;
        msg[1].hdr_cmd_code = 0;
 
        return i3c_transfer(target, msg, 2);
}
 
static inline int i3c_burst_read(struct i3c_device_desc *target,
                                 uint8_t start_addr,
                                 uint8_t *buf,
                                 uint32_t num_bytes)
{
        return i3c_write_read(target,
                              &start_addr, sizeof(start_addr),
                              buf, num_bytes);
}
 
static inline int i3c_burst_write(struct i3c_device_desc *target,
                                  uint8_t start_addr,
                                  const uint8_t *buf,
                                  uint32_t num_bytes)
{
        struct i3c_msg msg[2];
 
        msg[0].buf = &start_addr;
        msg[0].len = 1U;
        msg[0].flags = I3C_MSG_WRITE;
        msg[0].hdr_mode = 0;
        msg[0].hdr_cmd_code = 0;
 
        msg[1].buf = (uint8_t *)buf;
        msg[1].len = num_bytes;
        msg[1].flags = I3C_MSG_WRITE | I3C_MSG_STOP;
        msg[1].hdr_mode = 0;
        msg[1].hdr_cmd_code = 0;
 
        return i3c_transfer(target, msg, 2);
}
 
static inline int i3c_reg_read_byte(struct i3c_device_desc *target,
                                    uint8_t reg_addr, uint8_t *value)
{
        return i3c_write_read(target,
                              &reg_addr, sizeof(reg_addr),
                              value, sizeof(*value));
}
 
static inline int i3c_reg_write_byte(struct i3c_device_desc *target,
                                     uint8_t reg_addr, uint8_t value)
{
        uint8_t tx_buf[2] = {reg_addr, value};
 
        return i3c_write(target, tx_buf, 2);
}
 
static inline int i3c_reg_update_byte(struct i3c_device_desc *target,
                                      uint8_t reg_addr, uint8_t mask,
                                      uint8_t value)
{
        uint8_t old_value, new_value;
        int rc;
 
        rc = i3c_reg_read_byte(target, reg_addr, &old_value);
        if (rc != 0) {
                return rc;
        }
 
        new_value = (old_value & ~mask) | (value & mask);
        if (new_value == old_value) {
                return 0;
        }
 
        return i3c_reg_write_byte(target, reg_addr, new_value);
}
 
void i3c_dump_msgs(const char *name, const struct i3c_msg *msgs,
                   uint8_t num_msgs, struct i3c_device_desc *target);
 
int i3c_bus_init(const struct device *dev,
                 const struct i3c_dev_list *i3c_dev_list);
 
int i3c_device_basic_info_get(struct i3c_device_desc *target);
 
bool i3c_bus_has_sec_controller(const struct device *dev);
 
int i3c_bus_deftgts(const struct device *dev);
 
#if defined(CONFIG_I3C_RTIO) || defined(__DOXYGEN__)
 
struct i3c_iodev_data {
        const struct device *bus;
        const struct i3c_device_id dev_id;
};
 
void i3c_iodev_submit_fallback(const struct device *dev, struct rtio_iodev_sqe *iodev_sqe);
 
static inline void i3c_iodev_submit(struct rtio_iodev_sqe *iodev_sqe)
{
        const struct i3c_iodev_data *data =
                (const struct i3c_iodev_data *)iodev_sqe->sqe.iodev->data;
        const struct i3c_driver_api *api = (const struct i3c_driver_api *)data->bus->api;
 
        if (api->iodev_submit == NULL) {
                rtio_iodev_sqe_err(iodev_sqe, -ENOSYS);
                return;
        }
        api->iodev_submit(data->bus, iodev_sqe);
}
 
extern const struct rtio_iodev_api i3c_iodev_api;
 
#define I3C_DT_IODEV_DEFINE(name, node_id)                                      \
        const struct i3c_iodev_data _i3c_iodev_data_##name = {                  \
                .bus = DEVICE_DT_GET(DT_BUS(node_id)),                          \
                .dev_id = I3C_DEVICE_ID_DT(node_id),                            \
        };                                                                      \
        RTIO_IODEV_DEFINE(name, &i3c_iodev_api, (void *)&_i3c_iodev_data_##name)
 
struct rtio_sqe *i3c_rtio_copy(struct rtio *r,
                               struct rtio_iodev *iodev,
                               const struct i3c_msg *msgs,
                               uint8_t num_msgs);
 
#endif /* CONFIG_I3C_RTIO */
 
/*
 * This needs to be after declaration of struct i3c_driver_api,
 * or else compiler complains about undefined type inside
 * the static inline API wrappers.
 */
#include <zephyr/drivers/i3c/target_device.h>
 
/*
 * Include High-Data-Rate (HDR) inline helper functions
 */
#include <zephyr/drivers/i3c/hdr_ddr.h>
 
#ifdef __cplusplus
}
#endif
 
#include <zephyr/syscalls/i3c.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_H_ */