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/error_types.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_OD_TLOW_MIN_NS            200
#define I3C_OD_MIXED_BUS_THIGH_MAX_NS 41
#define I3C_OD_FIRST_BC_THIGH_MIN_NS  200


#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,
};

 
/*
 * 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_NOACK_EXPECTED          BIT(5)

#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;

        enum i3c_sdr_controller_error_types err;

        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;
 
        struct {
                uint32_t high_ns;

                uint32_t low_ns;
        } scl_od_min;

        struct {
                uint32_t high_ns;
        } scl_pp_min;

        uint8_t supported_hdr;
};

struct i3c_config_custom {
        uint32_t id;

        union {
                uintptr_t val;

                void *ptr;
        };
};

typedef void (*i3c_callback_t)(const struct device *dev, int result, void *data);

struct i3c_device_desc;
struct i3c_device_id;
struct i3c_i2c_device_desc;
struct i3c_target_config;
struct i3c_config_target;
 
__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);
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
        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);
#if defined(CONFIG_I3C_CALLBACK) || defined(__DOXYGEN__)
        int (*do_ccc_cb)(const struct device *dev,
                         struct i3c_ccc_payload *payload,
                         i3c_callback_t cb,
                         void *userdata);

        int (*i3c_xfers_cb)(const struct device *dev,
                            struct i3c_device_desc *target,
                            struct i3c_msg *msgs,
                            uint8_t num_msgs,
                            i3c_callback_t cb,
                            void *userdata);
#endif /* CONFIG_I3C_CALLBACK */
        struct i3c_device_desc *(*i3c_device_find)(const struct device *dev,
                                                   const struct i3c_device_id *id);
#endif /* CONFIG_I3C_CONTROLLER */
#if defined(CONFIG_I3C_USE_IBI) || defined(__DOXYGEN__)
#if defined(CONFIG_I3C_TARGET) || defined(__DOXYGEN__)
        int (*ibi_raise)(const struct device *dev,
                         struct i3c_ibi *request);
#endif /* CONFIG_I3C_TARGET */
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
        int (*ibi_hj_response)(const struct device *dev,
                               bool ack);

        int (*ibi_crr_response)(struct i3c_device_desc *target,
                                bool ack);

        int (*ibi_enable)(const struct device *dev,
                          struct i3c_device_desc *target);

        int (*ibi_disable)(const struct device *dev,
                           struct i3c_device_desc *target);
#endif /* CONFIG_I3C_CONTROLLER */
#endif /* CONFIG_I3C_USE_IBI */
#if defined(CONFIG_I3C_TARGET) || defined(__DOXYGEN__)
        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);

        int (*target_controller_handoff)(const struct device *dev,
                                         bool accept);
#endif /* CONFIG_I3C_TARGET */
#if defined(CONFIG_I3C_RTIO) || defined(__DOXYGEN__)
        void (*iodev_submit)(const struct device *dev,
                             struct rtio_iodev_sqe *iodev_sqe);
#endif /* CONFIG_I3C_RTIO */
};
 
DEVICE_API_EXTENDS(i3c, i2c, i2c_api);


struct i3c_device_id {
        uint64_t pid:48;
};

#define I3C_DEVICE_ID(pid)                                              \
        {                                                               \
                .pid = pid                                              \
        }

struct i3c_device_desc {
        sys_snode_t node;

        const struct device *bus;

        const struct device *dev;

        uint64_t pid;

        uint8_t static_addr;

        const uint8_t init_dynamic_addr;

        const uint8_t flags;

        uint8_t dynamic_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;

        uint8_t crhdly1;

        struct {
                union {
                        uint8_t gethdrcap;

                        uint8_t getcap1;
                };

                uint8_t getcap2;

                uint8_t getcap3;

                uint8_t getcap4;
        } getcaps;

        struct {
                uint8_t crcaps1;

                uint8_t crcaps2;
        } crcaps;

        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;

        uint16_t addr;

        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 {
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
        struct i3c_dev_list dev_list;

        uint8_t primary_controller_da;

        uint8_t flags;
#elif defined(CONFIG_CPP)
       /* Empty struct has size 0 in C, size 1 in C++. Force them to be the same. */
        uint8_t unused_cpp_size_compatibility;
#endif
};
 
#if defined(CONFIG_CPP)
BUILD_ASSERT(sizeof(struct i3c_driver_config) >= 1);
#endif

struct i3c_driver_data {
        struct i3c_config_controller ctrl_config;
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
        struct i3c_dev_attached_list attached_dev;
#if defined(CONFIG_I3C_TARGET) || defined(__DOXYGEN__)
        struct i3c_ccc_deftgts *deftgts;

        bool deftgts_refreshed;
#endif /* CONFIG_I3C_TARGET */
#endif /* CONFIG_I3C_CONTROLLER */
};
 
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
#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)

#define I3C_BUS_FOR_EACH_I3CDEV_SAFE(bus, desc, desc_s)                                            \
        SYS_SLIST_FOR_EACH_CONTAINER_SAFE(                                                         \
                &((struct i3c_driver_data *)(bus->data))->attached_dev.devices.i3c, desc, desc_s,  \
                node)

#define I3C_BUS_FOR_EACH_I2CDEV_SAFE(bus, desc, desc_s)                                            \
        SYS_SLIST_FOR_EACH_CONTAINER_SAFE(                                                         \
                &((struct i3c_driver_data *)(bus->data))->attached_dev.devices.i2c, desc, desc_s,  \
                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_device_desc *i3c_dev_list_i3c_static_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(const struct device *dev,
                                 uint64_t pid, bool must_match,
                                 bool assigned_okay,
                                 struct i3c_device_desc **target,
                                 uint8_t *addr);
#endif /* CONFIG_I3C_CONTROLLER */

static inline int i3c_configure(const struct device *dev,
                                enum i3c_config_type type, void *config)
{
        const struct i3c_driver_api *api = DEVICE_API_GET(i3c, dev);
 
        if (api->configure == NULL) {
                return -ENOSYS;
        }
 
        return api->configure(dev, type, config);
}
 
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
static inline int i3c_configure_controller(const struct device *dev,
                                           struct i3c_config_controller *config)
{
        return i3c_configure(dev, I3C_CONFIG_CONTROLLER, config);
}
#endif /* CONFIG_I3C_CONTROLLER */
 
#if defined(CONFIG_I3C_TARGET) || defined(__DOXYGEN__)
static inline int i3c_configure_target(const struct device *dev,
                                       struct i3c_config_target *config)
{
        return i3c_configure(dev, I3C_CONFIG_TARGET, config);
}
#endif /* CONFIG_I3C_TARGET */

static inline int i3c_config_get(const struct device *dev,
                                 enum i3c_config_type type, void *config)
{
        const struct i3c_driver_api *api = DEVICE_API_GET(i3c, dev);
 
        if (api->config_get == NULL) {
                return -ENOSYS;
        }
 
        return api->config_get(dev, type, config);
}
 
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
static inline int i3c_config_get_controller(const struct device *dev,
                                            struct i3c_config_controller *config)
{
        return i3c_config_get(dev, I3C_CONFIG_CONTROLLER, config);
}
#endif /* CONFIG_I3C_CONTROLLER */
 
#if defined(CONFIG_I3C_TARGET) || defined(__DOXYGEN__)
static inline int i3c_config_get_target(const struct device *dev,
                                        struct i3c_config_target *config)
{
        return i3c_config_get(dev, I3C_CONFIG_TARGET, config);
}
#endif /* CONFIG_I3C_TARGET */
 
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
static inline int i3c_recover_bus(const struct device *dev)
{
        const struct i3c_driver_api *api = DEVICE_API_GET(i3c, dev);
 
        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);

static inline bool i3c_is_i3c_device_attached(struct i3c_device_desc *target)
{
        struct i3c_device_desc *desc;
 
        I3C_BUS_FOR_EACH_I3CDEV(target->bus, desc) {
                if (desc == target) {
                        return true;
                }
        }
        return false;
}

int i3c_attach_i2c_device(struct i3c_i2c_device_desc *target);

int i3c_detach_i2c_device(struct i3c_i2c_device_desc *target);

static inline bool i3c_is_i2c_device_attached(struct i3c_i2c_device_desc *target)
{
        struct i3c_i2c_device_desc *desc;
 
        I3C_BUS_FOR_EACH_I2CDEV(target->bus, desc) {
                if (desc == target) {
                        return true;
                }
        }
        return false;
}

static inline int i3c_do_daa(const struct device *dev)
{
        const struct i3c_driver_api *api = DEVICE_API_GET(i3c, dev);
 
        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 = DEVICE_API_GET(i3c, dev);
 
        if (api->do_ccc == NULL) {
                return -ENOSYS;
        }
 
        return api->do_ccc(dev, payload);
}
 
#if defined(CONFIG_I3C_CALLBACK) || defined(__DOXYGEN__)
__syscall int i3c_do_ccc_cb(const struct device *dev,
                            struct i3c_ccc_payload *payload,
                            i3c_callback_t cb,
                            void *userdata);
 
static inline int z_impl_i3c_do_ccc_cb(const struct device *dev,
                                      struct i3c_ccc_payload *payload,
                                      i3c_callback_t cb,
                                      void *userdata)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)dev->api;
 
        if (api->do_ccc_cb == NULL) {
                return -ENOSYS;
        }
 
        return api->do_ccc_cb(dev, payload, cb, userdata);
}
#endif /* CONFIG_I3C_CALLBACK */


__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)
{
        return DEVICE_API_GET(i3c, target->bus)->i3c_xfers(target->bus, target, msgs, num_msgs);
}
 
#if defined(CONFIG_I3C_CALLBACK) || defined(__DOXYGEN__)
__syscall int i3c_transfer_cb(struct i3c_device_desc *target,
                              struct i3c_msg *msgs,
                              uint8_t num_msgs,
                              i3c_callback_t cb,
                              void *userdata);
 
static inline int z_impl_i3c_transfer_cb(struct i3c_device_desc *target,
                                         struct i3c_msg *msgs,
                                         uint8_t num_msgs,
                                         i3c_callback_t cb,
                                         void *userdata)
{
        const struct i3c_driver_api *api = (const struct i3c_driver_api *)target->bus->api;
 
        if (api->i3c_xfers_cb == NULL) {
                return -ENOSYS;
        }
 
        return api->i3c_xfers_cb(target->bus, target, msgs, num_msgs, cb, userdata);
}
#endif /* CONFIG_I3C_CALLBACK */


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 = DEVICE_API_GET(i3c, dev);
 
        if (api->i3c_device_find == NULL) {
                return NULL;
        }
 
        return api->i3c_device_find(dev, id);
}
#endif /* CONFIG_I3C_CONTROLLER */
 
#if defined(CONFIG_I3C_USE_IBI) || defined(__DOXYGEN__)
 
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
static inline int i3c_ibi_hj_response(const struct device *dev,
                                      bool ack)
{
        const struct i3c_driver_api *api = DEVICE_API_GET(i3c, dev);
 
        if (api->ibi_hj_response == NULL) {
                return -ENOSYS;
        }
 
        return api->ibi_hj_response(dev, ack);
}

static inline int i3c_ibi_crr_response(struct i3c_device_desc *target,
                                        bool ack)
{
        const struct i3c_driver_api *api =
                (const struct i3c_driver_api *)target->bus->api;
 
        if (api->ibi_crr_response == NULL) {
                return -ENOSYS;
        }
 
        return api->ibi_crr_response(target, ack);
}
#endif /* CONFIG_I3C_CONTROLLER */
 
#if defined(CONFIG_I3C_TARGET) || defined(__DOXYGEN__)
static inline int i3c_ibi_raise(const struct device *dev,
                                struct i3c_ibi *request)
{
        const struct i3c_driver_api *api = DEVICE_API_GET(i3c, dev);
 
        if (api->ibi_raise == NULL) {
                return -ENOSYS;
        }
 
        return api->ibi_raise(dev, request);
}
#endif /* CONFIG_I3C_TARGET */
 
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
static inline int i3c_ibi_enable(struct i3c_device_desc *target)
{
        const struct i3c_driver_api *api = DEVICE_API_GET(i3c, target->bus);
 
        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 = DEVICE_API_GET(i3c, target->bus);
 
        if (api->ibi_disable == NULL) {
                return -ENOSYS;
        }
 
        return api->ibi_disable(target->bus, target);
}
#endif /* CONFIG_I3C_CONTROLLER */
#endif /* CONFIG_I3C_USE_IBI */

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;
}

 
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)

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);

int i3c_device_adv_info_get(struct i3c_device_desc *target);

static inline int i3c_device_info_get(struct i3c_device_desc *target)
{
        int rc;
 
        rc = i3c_device_basic_info_get(target);
        if (rc != 0) {
                return rc;
        }
 
        return i3c_device_adv_info_get(target);
}

enum i3c_bus_mode i3c_bus_mode(const struct i3c_dev_list *dev_list);

bool i3c_bus_has_sec_controller(const struct device *dev);

int i3c_bus_rstdaa_all(const struct device *dev);

int i3c_bus_setdasa(struct i3c_device_desc *desc, uint8_t dynamic_addr);

int i3c_bus_setnewda(struct i3c_device_desc *desc, uint8_t dynamic_addr);

int i3c_bus_setaasa(const struct device *dev);

int i3c_bus_getbcr(struct i3c_device_desc *desc);

int i3c_bus_getdcr(struct i3c_device_desc *desc);

int i3c_bus_getpid(struct i3c_device_desc *desc);

int i3c_bus_getmrl(struct i3c_device_desc *desc);

int i3c_bus_getmwl(struct i3c_device_desc *desc);

int i3c_bus_setmrl(struct i3c_device_desc *desc, uint16_t mrl, uint8_t ibi_len);

int i3c_bus_setmwl(struct i3c_device_desc *desc, uint16_t mwl);

int i3c_bus_setmrl_all(const struct device *dev, uint16_t mrl, uint8_t ibi_len, bool has_ibi_size);

int i3c_bus_setmwl_all(const struct device *dev, uint16_t mwl);
 
#if defined(CONFIG_I3C_TARGET) || defined(__DOXYGEN__)
int i3c_bus_getacccr(struct i3c_device_desc *desc);

int i3c_bus_deftgts(const struct device *dev);
#endif /* CONFIG_I3C_TARGET */

uint8_t i3c_odd_parity(uint8_t p);

int i3c_device_controller_handoff(struct i3c_device_desc *target, bool requested);
#endif /* CONFIG_I3C_CONTROLLER */
 
#if defined(CONFIG_I3C_USE_IBI) || defined(__DOXYGEN__)
#if (defined(CONFIG_I3C_CONTROLLER) && defined(CONFIG_I3C_TARGET)) || defined(__DOXYGEN__)
void i3c_sec_handoffed(struct k_work *work);
#endif /* CONFIG_I3C_CONTROLLER && CONFIG_I3C_TARGET */
#endif /* CONFIG_I3C_USE_IBI */
 
#if (defined(CONFIG_I3C_NUM_OF_DESC_MEM_SLABS) && CONFIG_I3C_NUM_OF_DESC_MEM_SLABS > 0) ||         \
        defined(__DOXYGEN__)

struct i3c_device_desc *i3c_device_desc_alloc(void);

void i3c_device_desc_free(struct i3c_device_desc *desc);

bool i3c_device_desc_in_pool(struct i3c_device_desc *desc);
 
#else
 
static inline struct i3c_device_desc *i3c_device_desc_alloc(void)
{
        return NULL;
}
 
static inline void i3c_device_desc_free(struct i3c_device_desc *desc)
{
        ARG_UNUSED(desc);
}
 
static inline bool i3c_device_desc_in_pool(struct i3c_device_desc *desc)
{
        ARG_UNUSED(desc);
        return false;
}
 
#endif /* CONFIG_I3C_NUM_OF_DESC_MEM_SLABS > 0 */
 
#if (defined(CONFIG_I3C_I2C_NUM_OF_DESC_MEM_SLABS) && CONFIG_I3C_I2C_NUM_OF_DESC_MEM_SLABS > 0) || \
        defined(__DOXYGEN__)

struct i3c_i2c_device_desc *i3c_i2c_device_desc_alloc(void);

void i3c_i2c_device_desc_free(struct i3c_i2c_device_desc *desc);

bool i3c_i2c_device_desc_in_pool(struct i3c_i2c_device_desc *desc);
 
#else
 
static inline struct i3c_i2c_device_desc *i3c_i2c_device_desc_alloc(void)
{
        return NULL;
}
 
static inline void i3c_i2c_device_desc_free(struct i3c_i2c_device_desc *desc)
{
        ARG_UNUSED(desc);
}
 
static inline bool i3c_i2c_device_desc_in_pool(struct i3c_i2c_device_desc *desc)
{
        ARG_UNUSED(desc);
        return false;
}
 
#endif /* CONFIG_I3C_I2C_NUM_OF_DESC_MEM_SLABS > 0 */
 
#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 = DEVICE_API_GET(i3c, data->bus);
 
        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)

#define I3C_DT_INST_IODEV_DEFINE(name, inst)                                    \
        I3C_DT_IODEV_DEFINE(name, DT_DRV_INST(inst))

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 */
 
#if defined(CONFIG_I3C_TARGET) || defined(__DOXYGEN__)
/*
 * 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>
#endif /* CONFIG_I3C_TARGET */
 
#if defined(CONFIG_I3C_CONTROLLER) || defined(__DOXYGEN__)
/*
 * Include High-Data-Rate (HDR) inline helper functions
 */
#include <zephyr/drivers/i3c/hdr_ddr.h>
#endif /* CONFIG_I3C_CONTROLLER */
 
#ifdef __cplusplus
}
#endif

 
#include <zephyr/syscalls/i3c.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_I3C_H_ */