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 <zephyr/types.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>
 
#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_SHIFT 6U
 
#define I3C_BCR_DEVICE_ROLE_MASK (0x03U << I3C_BCR_DEVICE_ROLE_SHIFT)
 
#define I3C_BCR_DEVICE_ROLE(bcr) \
 (((bcr) & I3C_BCR_DEVICE_ROLE_MASK) >> I3C_BCR_DEVICE_ROLE_SHIFT)
 
#define I3C_LVR_I2C_FM_PLUS_MODE 0
 
#define I3C_LVR_I2C_FM_MODE 1
 
#define I3C_LVR_I2C_MODE_SHIFT 4
 
#define I3C_LVR_I2C_MODE_MASK BIT(4)
 
#define I3C_LVR_I2C_MODE(lvr) \
 (((lvr) & I3C_LVR_I2C_MODE_MASK) >> I3C_LVR_I2C_MODE_SHIFT)
 
#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_SHIFT 5
 
#define I3C_LVR_I2C_DEV_IDX_MASK (0x07U << I3C_LVR_I2C_DEV_IDX_SHIFT)
 
#define I3C_LVR_I2C_DEV_IDX(lvr) \
 (((lvr) & I3C_LVR_I2C_DEV_IDX_MASK) >> I3C_LVR_I2C_DEV_IDX_SHIFT)
 
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;
};
 
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,
 uint8_t addr);
 
 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);
};
 
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;
 
 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;
};
 
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(struct i3c_dev_attached_list *dev_list,
 uint8_t addr);
 
struct i3c_i2c_device_desc *i3c_dev_list_i2c_addr_find(struct i3c_dev_attached_list *dev_list,
 uint16_t addr);
 
int i3c_determine_default_addr(struct i3c_device_desc *target, uint8_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_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;
 
 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;
 
 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[1].buf = (uint8_t *)read_buf;
 msg[1].len = num_read;
 msg[1].flags = I3C_MSG_RESTART | I3C_MSG_READ | I3C_MSG_STOP;
 
 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[1].buf = (uint8_t *)buf;
 msg[1].len = num_bytes;
 msg[1].flags = I3C_MSG_WRITE | I3C_MSG_STOP;
 
 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);
 
/*
 * 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>
 
#ifdef __cplusplus
}
#endif
 
#include <syscalls/i3c.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_H_ */