Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
i3c.h File Reference
#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>
#include <zephyr/drivers/i3c/target_device.h>
#include <zephyr/syscalls/i3c.h>

Go to the source code of this file.

Data Structures

struct  i3c_msg
 One I3C Message. More...
 
struct  i3c_config_controller
 Configuration parameters for I3C hardware to act as controller. More...
 
struct  i3c_config_custom
 Custom I3C configuration parameters. More...
 
struct  i3c_device_id
 Structure used for matching I3C devices. More...
 
struct  i3c_device_desc
 Structure describing a I3C target device. More...
 
struct  i3c_i2c_device_desc
 Structure describing a I2C device on I3C bus. More...
 
struct  i3c_dev_attached_list
 Structure for describing attached devices for a controller. More...
 
struct  i3c_dev_list
 Structure for describing known devices for a controller. More...
 
struct  i3c_driver_config
 This structure is common to all I3C drivers and is expected to be the first element in the object pointed to by the config field in the device structure. More...
 
struct  i3c_driver_data
 This structure is common to all I3C drivers and is expected to be the first element in the driver's struct driver_data declaration. More...
 

Macros

#define I3C_MSG_WRITE   (0U << 0U)
 Write message to I3C bus.
 
#define I3C_MSG_READ   BIT(0)
 Read message from I3C bus.
 
#define I3C_MSG_STOP   BIT(1)
 Send STOP after this message.
 
#define I3C_MSG_RESTART   BIT(2)
 RESTART I3C transaction for this message.
 
#define I3C_MSG_HDR   BIT(3)
 Transfer use HDR mode.
 
#define I3C_MSG_NBCH   BIT(4)
 Skip I3C broadcast header.
 
#define I3C_MSG_HDR_MODE0   BIT(0)
 I3C HDR Mode 0.
 
#define I3C_MSG_HDR_MODE1   BIT(1)
 I3C HDR Mode 1.
 
#define I3C_MSG_HDR_MODE2   BIT(2)
 I3C HDR Mode 2.
 
#define I3C_MSG_HDR_MODE3   BIT(3)
 I3C HDR Mode 3.
 
#define I3C_MSG_HDR_MODE4   BIT(4)
 I3C HDR Mode 4.
 
#define I3C_MSG_HDR_MODE5   BIT(5)
 I3C HDR Mode 5.
 
#define I3C_MSG_HDR_MODE6   BIT(6)
 I3C HDR Mode 6.
 
#define I3C_MSG_HDR_MODE7   BIT(7)
 I3C HDR Mode 7.
 
#define I3C_MSG_HDR_DDR   I3C_MSG_HDR_MODE0
 I3C HDR-DDR (Double Data Rate)
 
#define I3C_MSG_HDR_TSP   I3C_MSG_HDR_MODE1
 I3C HDR-TSP (Ternary Symbol Pure-bus)
 
#define I3C_MSG_HDR_TSL   I3C_MSG_HDR_MODE2
 I3C HDR-TSL (Ternary Symbol Legacy-inclusive-bus)
 
#define I3C_MSG_HDR_BT   I3C_MSG_HDR_MODE3
 I3C HDR-BT (Bulk Transport)
 
#define I3C_DEVICE_ID(pid)
 Structure initializer for i3c_device_id from PID.
 
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)
 Max Data Speed Limitation bit.
 
#define I3C_BCR_IBI_REQUEST_CAPABLE   BIT(1)
 IBI Request Capable bit.
 
#define I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE   BIT(2)
 IBI Payload bit.
 
#define I3C_BCR_OFFLINE_CAPABLE   BIT(3)
 Offline Capable bit.
 
#define I3C_BCR_VIRTUAL_TARGET   BIT(4)
 Virtual Target Support bit.
 
#define I3C_BCR_ADV_CAPABILITIES   BIT(5)
 Advanced Capabilities bit.
 
#define I3C_BCR_DEVICE_ROLE_I3C_TARGET   0U
 Device Role - I3C Target.
 
#define I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE   1U
 Device Role - I3C Controller Capable.
 
#define I3C_BCR_DEVICE_ROLE_SHIFT   6U
 Device Role bit shift value.
 
#define I3C_BCR_DEVICE_ROLE_MASK   (0x03U << I3C_BCR_DEVICE_ROLE_SHIFT)
 Device Role bit shift mask.
 
#define I3C_BCR_DEVICE_ROLE(bcr)    (((bcr) & I3C_BCR_DEVICE_ROLE_MASK) >> I3C_BCR_DEVICE_ROLE_SHIFT)
 Device Role.
 
Legacy Virtual Register (LVR)

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_LVR_I2C_FM_PLUS_MODE   0
 I2C FM+ Mode.
 
#define I3C_LVR_I2C_FM_MODE   1
 I2C FM Mode.
 
#define I3C_LVR_I2C_MODE_SHIFT   4
 I2C Mode Indicator bit shift value.
 
#define I3C_LVR_I2C_MODE_MASK   BIT(4)
 I2C Mode Indicator bitmask.
 
#define I3C_LVR_I2C_MODE(lvr)    (((lvr) & I3C_LVR_I2C_MODE_MASK) >> I3C_LVR_I2C_MODE_SHIFT)
 I2C Mode.
 
#define I3C_LVR_I2C_DEV_IDX_0   0
 I2C Device Index 0.
 
#define I3C_LVR_I2C_DEV_IDX_1   1
 I2C Device Index 1.
 
#define I3C_LVR_I2C_DEV_IDX_2   2
 I2C Device Index 2.
 
#define I3C_LVR_I2C_DEV_IDX_SHIFT   5
 I2C Device Index bit shift value.
 
#define I3C_LVR_I2C_DEV_IDX_MASK   (0x07U << I3C_LVR_I2C_DEV_IDX_SHIFT)
 I2C Device Index bitmask.
 
#define I3C_LVR_I2C_DEV_IDX(lvr)    (((lvr) & I3C_LVR_I2C_DEV_IDX_MASK) >> I3C_LVR_I2C_DEV_IDX_SHIFT)
 I2C Device Index.
 

Enumerations

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
}
 I3C bus mode. More...
 
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 }
 I2C bus speed under I3C bus. More...
 
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 data rate. More...
 
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
}
 I3C SDR Controller Error Codes. More...
 
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 SDR Target Error Codes. More...
 
enum  i3c_config_type { I3C_CONFIG_CONTROLLER , I3C_CONFIG_TARGET , I3C_CONFIG_CUSTOM }
 Type of configuration being passed to configure function. More...
 

Functions

struct i3c_device_desci3c_dev_list_find (const struct i3c_dev_list *dev_list, const struct i3c_device_id *id)
 Find a I3C target device descriptor by ID.
 
struct i3c_device_desci3c_dev_list_i3c_addr_find (struct i3c_dev_attached_list *dev_list, uint8_t addr)
 Find a I3C target device descriptor by dynamic address.
 
struct i3c_i2c_device_desci3c_dev_list_i2c_addr_find (struct i3c_dev_attached_list *dev_list, uint16_t addr)
 Find a I2C target device descriptor by address.
 
int i3c_determine_default_addr (struct i3c_device_desc *target, uint8_t *addr)
 Helper function to find the default address an i3c device is attached with.
 
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)
 Helper function to find a usable address during ENTDAA.
 
static int i3c_configure (const struct device *dev, enum i3c_config_type type, void *config)
 Configure the I3C hardware.
 
static int i3c_config_get (const struct device *dev, enum i3c_config_type type, void *config)
 Get configuration of the I3C hardware.
 
static int i3c_recover_bus (const struct device *dev)
 Attempt bus recovery on the I3C bus.
 
int i3c_attach_i3c_device (struct i3c_device_desc *target)
 Attach an I3C device.
 
int i3c_reattach_i3c_device (struct i3c_device_desc *target, uint8_t old_dyn_addr)
 Reattach I3C device.
 
int i3c_detach_i3c_device (struct i3c_device_desc *target)
 Detach I3C Device.
 
int i3c_attach_i2c_device (struct i3c_i2c_device_desc *target)
 Attach an I2C device.
 
int i3c_detach_i2c_device (struct i3c_i2c_device_desc *target)
 Detach I2C Device.
 
static int i3c_do_daa (const struct device *dev)
 Perform Dynamic Address Assignment on the I3C bus.
 
int i3c_do_ccc (const struct device *dev, struct i3c_ccc_payload *payload)
 Send CCC to the bus.
 
int i3c_transfer (struct i3c_device_desc *target, struct i3c_msg *msgs, uint8_t num_msgs)
 Perform data transfer from the controller to a I3C target device.
 
static struct i3c_device_desci3c_device_find (const struct device *dev, const struct i3c_device_id *id)
 Find a registered I3C target device.
 
static int i3c_ibi_raise (const struct device *dev, struct i3c_ibi *request)
 Raise an In-Band Interrupt (IBI).
 
static int i3c_ibi_enable (struct i3c_device_desc *target)
 Enable IBI of a target device.
 
static int i3c_ibi_disable (struct i3c_device_desc *target)
 Disable IBI of a target device.
 
static int i3c_ibi_has_payload (struct i3c_device_desc *target)
 Check if target's IBI has payload.
 
static int i3c_device_is_ibi_capable (struct i3c_device_desc *target)
 Check if device is IBI capable.
 
static int i3c_write (struct i3c_device_desc *target, const uint8_t *buf, uint32_t num_bytes)
 Write a set amount of data to an I3C target device.
 
static int i3c_read (struct i3c_device_desc *target, uint8_t *buf, uint32_t num_bytes)
 Read a set amount of data from an I3C target device.
 
static int i3c_write_read (struct i3c_device_desc *target, const void *write_buf, size_t num_write, void *read_buf, size_t num_read)
 Write then read data from an I3C target device.
 
static int i3c_burst_read (struct i3c_device_desc *target, uint8_t start_addr, uint8_t *buf, uint32_t num_bytes)
 Read multiple bytes from an internal address of an I3C target device.
 
static int i3c_burst_write (struct i3c_device_desc *target, uint8_t start_addr, const uint8_t *buf, uint32_t num_bytes)
 Write multiple bytes to an internal address of an I3C target device.
 
static int i3c_reg_read_byte (struct i3c_device_desc *target, uint8_t reg_addr, uint8_t *value)
 Read internal register of an I3C target device.
 
static int i3c_reg_write_byte (struct i3c_device_desc *target, uint8_t reg_addr, uint8_t value)
 Write internal register of an I3C target device.
 
static int i3c_reg_update_byte (struct i3c_device_desc *target, uint8_t reg_addr, uint8_t mask, uint8_t value)
 Update internal register of an I3C target device.
 
void i3c_dump_msgs (const char *name, const struct i3c_msg *msgs, uint8_t num_msgs, struct i3c_device_desc *target)
 Dump out an I3C message.
 
int i3c_bus_init (const struct device *dev, const struct i3c_dev_list *i3c_dev_list)
 Generic helper function to perform bus initialization.
 
int i3c_device_basic_info_get (struct i3c_device_desc *target)
 Get basic information from device and update device descriptor.