i3c.h

Go to the documentation of this file.

/*
 * Copyright 2022 Intel Corporation
 *
 * 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
 
/*
 * Bus Characteristic Register (BCR)
 * - BCR[7:6]: Device Role
 *   - 0: I3C Target
 *   - 1: I3C Controller capable
 *   - 2: Reserved
 *   - 3: Reserved
 * - BCR[5]: Advanced Capabilities
 *   - 0: Does not support optional advanced capabilities.
 *   - 1: Supports optional advanced capabilities which
 *        can be viewed via GETCAPS CCC.
 * - BCR[4}: Virtual Target Support
 *   - 0: Is not a virtual target.
 *   - 1: Is a virtual target.
 * - BCR[3]: Offline Capable
 *   - 0: Will always response to I3C commands.
 *   - 1: Will not always response to I3C commands.
 * - BCR[2]: IBI Payload
 *   - 0: No data bytes following the accepted IBI.
 *   - 1: One data byte (MDB, Mandatory Data Byte) follows
 *        the accepted IBI. Additional data bytes may also
 *        follows.
 * - BCR[1]: IBI Request Capable
 *   - 0: Not capable
 *   - 1: Capable
 * - BCR[0]: Max Data Speed Limitation
 *   - 0: No Limitation
 *   - 1: Limitation obtained via GETMXDS CCC.
 */
#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)
 
/*
 * Legacy Virtual Register (LVR)
 * - LVR[7:5]: I2C device index:
 *   - 0: I2C device has a 50 ns spike filter where
 *        it is not affected by high frequency on SCL.
 *   - 1: I2C device does not have a 50 ns spike filter
 *        but can work with high frequency on SCL.
 *   - 2: I2C device does not have a 50 ns spike filter
 *        and cannot work with high frequency on SCL.
 * - LVR[4]: I2C mode indicator:
 *   - 0: FM+ mode
 *   - 1: FM mode
 * - LVR[3:0]: Reserved.
 */
#define I3C_DCR_I2C_FM_PLUS_MODE                        0
#define I3C_DCR_I2C_FM_MODE                             1
 
#define I3C_DCR_I2C_MODE_SHIFT                          4
#define I3C_DCR_I2C_MODE_MASK                           BIT(4)
 
#define I3C_DCR_I2C_MODE(dcr)                           \
        (((mode) & I3C_DCR_I2C_MODE_MASK) >> I3C_DCR_I2C_MODE_SHIFT)
 
#define I3C_DCR_I2C_DEV_IDX_0                           0
#define I3C_DCR_I2C_DEV_IDX_1                           1
#define I3C_DCR_I2C_DEV_IDX_2                           2
 
#define I3C_DCR_I2C_DEV_IDX_SHIFT                       5
#define I3C_DCR_I2C_DEV_IDX_MASK                        (0x07U << I3C_DCR_I2C_DEV_IDX_SHIFT)
 
#define I3C_DCR_I2C_DEV_IDX(dcr)                        \
        (((dcr) & I3C_DCR_I2C_DEV_IDX_MASK) >> I3C_DCR_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;
 
        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;
 
        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_ */