I3C Interface. More...

Modules
	I3C Address-related Helper Code
	I3C Address-related Helper Code.

	I3C Common Command Codes
	I3C Common Command Codes.

	I3C Devicetree related bits
	I3C Devicetree related bits.

	I3C In-Band Interrupts
	I3C In-Band Interrupts.

	Target Device API
	I3C Target Device API.

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

struct	i3c_driver_data

Macros
#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_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)

#define	I3C_MSG_WRITE (0U << 0U)

#define	I3C_MSG_READ 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

#define	I3C_DEVICE_ID(pid)
	Structure initializer for i3c_device_id from PID.

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_desc *	i3c_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_desc *	i3c_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_desc *	i3c_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_desc *	i3c_device_find (const struct device dev, const struct i3c_device_id id)

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.

Detailed Description

I3C Interface.

Macro Definition Documentation

◆ I3C_BCR_ADV_CAPABILITIES

#define I3C_BCR_ADV_CAPABILITIES BIT(5)

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_DEVICE_ROLE

#define I3C_BCR_DEVICE_ROLE ( bcr ) (((bcr) & I3C_BCR_DEVICE_ROLE_MASK) >> I3C_BCR_DEVICE_ROLE_SHIFT)

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE

#define I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE 1U

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_DEVICE_ROLE_I3C_TARGET

#define I3C_BCR_DEVICE_ROLE_I3C_TARGET 0U

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_DEVICE_ROLE_MASK

#define I3C_BCR_DEVICE_ROLE_MASK (0x03U << I3C_BCR_DEVICE_ROLE_SHIFT)

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_DEVICE_ROLE_SHIFT

#define I3C_BCR_DEVICE_ROLE_SHIFT 6U

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE

#define I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE BIT(2)

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_IBI_REQUEST_CAPABLE

#define I3C_BCR_IBI_REQUEST_CAPABLE BIT(1)

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_MAX_DATA_SPEED_LIMIT

#define I3C_BCR_MAX_DATA_SPEED_LIMIT BIT(0)

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_OFFLINE_CAPABLE

#define I3C_BCR_OFFLINE_CAPABLE BIT(3)

#include <zephyr/drivers/i3c.h>

◆ I3C_BCR_VIRTUAL_TARGET

#define I3C_BCR_VIRTUAL_TARGET BIT(4)

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_DEV_IDX

#define I3C_DCR_I2C_DEV_IDX ( dcr ) (((dcr) & I3C_DCR_I2C_DEV_IDX_MASK) >> I3C_DCR_I2C_DEV_IDX_SHIFT)

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_DEV_IDX_0

#define I3C_DCR_I2C_DEV_IDX_0 0

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_DEV_IDX_1

#define I3C_DCR_I2C_DEV_IDX_1 1

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_DEV_IDX_2

#define I3C_DCR_I2C_DEV_IDX_2 2

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_DEV_IDX_MASK

#define I3C_DCR_I2C_DEV_IDX_MASK (0x07U << I3C_DCR_I2C_DEV_IDX_SHIFT)

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_DEV_IDX_SHIFT

#define I3C_DCR_I2C_DEV_IDX_SHIFT 5

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_FM_MODE

#define I3C_DCR_I2C_FM_MODE 1

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_FM_PLUS_MODE

#define I3C_DCR_I2C_FM_PLUS_MODE 0

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_MODE

#define I3C_DCR_I2C_MODE ( dcr ) (((mode) & I3C_DCR_I2C_MODE_MASK) >> I3C_DCR_I2C_MODE_SHIFT)

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_MODE_MASK

#define I3C_DCR_I2C_MODE_MASK BIT(4)

#include <zephyr/drivers/i3c.h>

◆ I3C_DCR_I2C_MODE_SHIFT

#define I3C_DCR_I2C_MODE_SHIFT 4

#include <zephyr/drivers/i3c.h>

◆ I3C_DEVICE_ID

#define I3C_DEVICE_ID ( pid )

#include <zephyr/drivers/i3c.h>

Value:

        {                                                               \
                .pid = pid                                              \
        }

Structure initializer for i3c_device_id from PID.

This helper macro expands to a static initializer for a struct i3c_device_id by populating the PID (Provisioned ID) field.

Parameters

pid	Provisioned ID.

◆ I3C_MSG_HDR

#define I3C_MSG_HDR BIT(3)

#include <zephyr/drivers/i3c.h>

Transfer use HDR mode

◆ I3C_MSG_HDR_BT

#define I3C_MSG_HDR_BT I3C_MSG_HDR_MODE3

#include <zephyr/drivers/i3c.h>

I3C HDR-BT (Bulk Transport)

◆ I3C_MSG_HDR_DDR

#define I3C_MSG_HDR_DDR I3C_MSG_HDR_MODE0

#include <zephyr/drivers/i3c.h>

I3C HDR-DDR (Double Data Rate)

◆ I3C_MSG_HDR_MODE0

#define I3C_MSG_HDR_MODE0 BIT(0)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 0

◆ I3C_MSG_HDR_MODE1

#define I3C_MSG_HDR_MODE1 BIT(1)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 1

◆ I3C_MSG_HDR_MODE2

#define I3C_MSG_HDR_MODE2 BIT(2)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 2

◆ I3C_MSG_HDR_MODE3

#define I3C_MSG_HDR_MODE3 BIT(3)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 3

◆ I3C_MSG_HDR_MODE4

#define I3C_MSG_HDR_MODE4 BIT(4)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 4

◆ I3C_MSG_HDR_MODE5

#define I3C_MSG_HDR_MODE5 BIT(5)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 5

◆ I3C_MSG_HDR_MODE6

#define I3C_MSG_HDR_MODE6 BIT(6)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 6

◆ I3C_MSG_HDR_MODE7

#define I3C_MSG_HDR_MODE7 BIT(7)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 7

◆ I3C_MSG_HDR_TSL

#define I3C_MSG_HDR_TSL I3C_MSG_HDR_MODE2

#include <zephyr/drivers/i3c.h>

I3C HDR-TSL (Ternary Symbol Legacy-inclusive-bus)

◆ I3C_MSG_HDR_TSP

#define I3C_MSG_HDR_TSP I3C_MSG_HDR_MODE1

#include <zephyr/drivers/i3c.h>

I3C HDR-TSP (Ternary Symbol Pure-bus)

◆ I3C_MSG_NBCH

#define I3C_MSG_NBCH BIT(4)

#include <zephyr/drivers/i3c.h>

Skip I3C broadcast header. Private Transfers only.

◆ I3C_MSG_READ

#define I3C_MSG_READ BIT(0)

#include <zephyr/drivers/i3c.h>

Read message from I3C bus.

◆ I3C_MSG_RESTART

#define I3C_MSG_RESTART BIT(2)

#include <zephyr/drivers/i3c.h>

RESTART I3C transaction for this message.

Note: Not all I3C drivers have or require explicit support for this feature. Some drivers require this be present on a read message that follows a write, or vice-versa. Some drivers will merge adjacent fragments into a single transaction using this flag; some will not.

◆ I3C_MSG_STOP

#define I3C_MSG_STOP BIT(1)

#include <zephyr/drivers/i3c.h>

Send STOP after this message.

◆ I3C_MSG_WRITE

#define I3C_MSG_WRITE (0U << 0U)

#include <zephyr/drivers/i3c.h>

Write message to I3C bus.

Enumeration Type Documentation

◆ i3c_bus_mode

enum i3c_bus_mode

#include <zephyr/drivers/i3c.h>

I3C bus mode.

Enumerator
I3C_BUS_MODE_PURE	Only I3C devices are on the bus.
I3C_BUS_MODE_MIXED_FAST	Both I3C and legacy I2C devices are on the bus. The I2C devices have 50ns spike filter on SCL.
I3C_BUS_MODE_MIXED_LIMITED	Both I3C and legacy I2C devices are on the bus. The I2C devices do not have 50ns spike filter on SCL and can tolerate maximum SDR SCL clock frequency.
I3C_BUS_MODE_MIXED_SLOW	Both I3C and legacy I2C devices are on the bus. The I2C devices do not have 50ns spike filter on SCL but cannot tolerate maximum SDR SCL clock frequency.
I3C_BUS_MODE_MAX
I3C_BUS_MODE_INVALID

◆ i3c_config_type

enum i3c_config_type

#include <zephyr/drivers/i3c.h>

Type of configuration being passed to configure function.

Enumerator
I3C_CONFIG_CONTROLLER
I3C_CONFIG_TARGET
I3C_CONFIG_CUSTOM

◆ i3c_data_rate

enum i3c_data_rate

#include <zephyr/drivers/i3c.h>

I3C data rate.

I3C data transfer rate defined by the I3C specification.

Enumerator
I3C_DATA_RATE_SDR	Single Data Rate messaging
I3C_DATA_RATE_HDR_DDR	High Data Rate - Double Data Rate messaging
I3C_DATA_RATE_HDR_TSL	High Data Rate - Ternary Symbol Legacy-inclusive-Bus
I3C_DATA_RATE_HDR_TSP	High Data Rate - Ternary Symbol for Pure Bus
I3C_DATA_RATE_HDR_BT	High Data Rate - Bulk Transport
I3C_DATA_RATE_MAX
I3C_DATA_RATE_INVALID

◆ i3c_i2c_speed_type

enum i3c_i2c_speed_type

#include <zephyr/drivers/i3c.h>

I2C bus speed under I3C bus.

Only FM and FM+ modes are supported for I2C devices under I3C bus.

Enumerator
I3C_I2C_SPEED_FM	I2C FM mode
I3C_I2C_SPEED_FMPLUS	I2C FM+ mode
I3C_I2C_SPEED_MAX
I3C_I2C_SPEED_INVALID

◆ i3c_sdr_controller_error_codes

enum i3c_sdr_controller_error_codes

#include <zephyr/drivers/i3c.h>

I3C SDR Controller Error Codes.

These are error codes defined by the I3C specification.

I3C_ERROR_CE_UNKNOWN and I3C_ERROR_CE_NONE are not official error codes according to the specification. These are there simply to aid in error handling during interactions with the I3C drivers and subsystem.

Enumerator
I3C_ERROR_CE0	Transaction after sending CCC
I3C_ERROR_CE1	Monitoring Error
I3C_ERROR_CE2	No response to broadcast address (0x7E)
I3C_ERROR_CE3	Failed Controller Handoff
I3C_ERROR_CE_UNKNOWN	Unknown error (not official error code)
I3C_ERROR_CE_NONE	No error (not official error code)
I3C_ERROR_CE_MAX
I3C_ERROR_CE_INVALID

◆ i3c_sdr_target_error_codes

enum i3c_sdr_target_error_codes

#include <zephyr/drivers/i3c.h>

I3C SDR Target Error Codes.

These are error codes defined by the I3C specification.

I3C_ERROR_TE_UNKNOWN and I3C_ERROR_TE_NONE are not official error codes according to the specification. These are there simply to aid in error handling during interactions with the I3C drivers and subsystem.

Enumerator
I3C_ERROR_TE0	Invalid Broadcast Address or Dynamic Address after DA assignment
I3C_ERROR_TE1	CCC Code
I3C_ERROR_TE2	Write Data
I3C_ERROR_TE3	Assigned Address during Dynamic Address Arbitration
I3C_ERROR_TE4	0x7E/R missing after RESTART during Dynamic Address Arbitration
I3C_ERROR_TE5	Transaction after detecting CCC
I3C_ERROR_TE6	Monitoring Error
I3C_ERROR_DBR	Dead Bus Recovery
I3C_ERROR_TE_UNKNOWN	Unknown error (not official error code)
I3C_ERROR_TE_NONE	No error (not official error code)
I3C_ERROR_TE_MAX
I3C_ERROR_TE_INVALID

Function Documentation

◆ i3c_attach_i2c_device()

int i3c_attach_i2c_device ( struct i3c_i2c_device_desc * target )

#include <zephyr/drivers/i3c.h>

Attach an I2C device.

Called to attach a I2C device to the addresses. This will also call the optional api to update any registers within the driver if implemented.

Warning: Use cases involving multiple writers to the i3c/i2c devices must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the i3c/i2c devices.

Parameters

target Pointer to the target device descriptor

Return values

0	If successful.
-EINVAL	If address is not available or if the device has already been attached before

◆ i3c_attach_i3c_device()

int i3c_attach_i3c_device ( struct i3c_device_desc * target )

#include <zephyr/drivers/i3c.h>

Attach an I3C device.

Called to attach a I3C device to the addresses. This is typically called before a SETDASA or ENTDAA to reserve the addresses. This will also call the optional api to update any registers within the driver if implemented.

Warning: Use cases involving multiple writers to the i3c/i2c devices must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the i3c/i2c devices.

Parameters

target Pointer to the target device descriptor

Return values

0	If successful.
-EINVAL	If address is not available or if the device has already been attached before

◆ i3c_burst_read()

static int i3c_burst_read	(	struct i3c_device_desc *	target,
		uint8_t	start_addr,
		uint8_t *	buf,
		uint32_t	num_bytes
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Read multiple bytes from an internal address of an I3C target device.

This routine reads multiple bytes from an internal address of an I3C target device synchronously.

Instances of this may be replaced by i3c_write_read().

Parameters

target	I3C target device descriptor,
start_addr	Internal address from which the data is being read.
buf	Memory pool that stores the retrieved data.
num_bytes	Number of bytes being read.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.

◆ i3c_burst_write()

static int i3c_burst_write	(	struct i3c_device_desc *	target,
		uint8_t	start_addr,
		const uint8_t *	buf,
		uint32_t	num_bytes
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Write multiple bytes to an internal address of an I3C target device.

This routine writes multiple bytes to an internal address of an I3C target device synchronously.

Warning: The combined write synthesized by this API may not be supported on all I3C devices. Uses of this API may be made more portable by replacing them with calls to i3c_write() passing a buffer containing the combined address and data.

Parameters

target	I3C target device descriptor.
start_addr	Internal address to which the data is being written.
buf	Memory pool from which the data is transferred.
num_bytes	Number of bytes being written.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.

◆ i3c_bus_init()

int i3c_bus_init	(	const struct device *	dev,
		const struct i3c_dev_list *	i3c_dev_list
	)

#include <zephyr/drivers/i3c.h>

Generic helper function to perform bus initialization.

Parameters

dev	Pointer to controller device driver instance.
i3c_dev_list	Pointer to I3C device list.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.
-ENODEV	If a provisioned ID does not match to any target devices in the registered device list.
-ENOSPC	No more free addresses can be assigned to target.
-ENOSYS	Dynamic address assignment is not supported by the controller driver.

◆ i3c_config_get()

static int i3c_config_get	(	const struct device *	dev,
		enum i3c_config_type	type,
		void *	config
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Get configuration of the I3C hardware.

This provides a way to get the current configuration of the I3C hardware.

This can return cached config or probed hardware parameters, but it has to be up to date with current configuration.

Parameters

[in]	dev	Pointer to controller device driver instance.
[in]	type	Type of configuration parameters being passed in `config`.
[in,out]	config	Pointer to the configuration parameters.

Note that if type is I3C_CONFIG_CUSTOM, config must contain the ID of the parameter to be retrieved.

Return values

0	If successful.
-EIO	General Input/Output errors.
-ENOSYS	If not implemented.

◆ i3c_configure()

static int i3c_configure	(	const struct device *	dev,
		enum i3c_config_type	type,
		void *	config
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Configure the I3C hardware.

Parameters

dev	Pointer to controller device driver instance.
type	Type of configuration parameters being passed in `config`.
config	Pointer to the configuration parameters.

Return values

0	If successful.
-EINVAL	If invalid configure parameters.
-EIO	General Input/Output errors.
-ENOSYS	If not implemented.

◆ i3c_detach_i2c_device()

int i3c_detach_i2c_device ( struct i3c_i2c_device_desc * target )

#include <zephyr/drivers/i3c.h>

Detach I2C Device.

called to remove an I2C device and to free up the address that it used. This will also call the optional api to update any registers within the driver if implemented.

Warning: Use cases involving multiple writers to the i3c/i2c devices must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the i3c/i2c devices.

Parameters

target Pointer to the target device descriptor

Return values

0	If successful.
-EINVAL	If device is already detached

◆ i3c_detach_i3c_device()

int i3c_detach_i3c_device ( struct i3c_device_desc * target )

#include <zephyr/drivers/i3c.h>

Detach I3C Device.

called to remove an I3C device and to free up the address that it used. If it's dynamic address was not set, then it assumed that SETDASA failed and will free it's static addr. This will also call the optional api to update any registers within the driver if implemented.

Warning: Use cases involving multiple writers to the i3c/i2c devices must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the i3c/i2c devices.

Parameters

target Pointer to the target device descriptor

Return values

0	If successful.
-EINVAL	If device is already detached

◆ i3c_determine_default_addr()

int i3c_determine_default_addr	(	struct i3c_device_desc *	target,
		uint8_t *	addr
	)

#include <zephyr/drivers/i3c.h>

Helper function to find the default address an i3c device is attached with.

This is a helper function to find the default address the device will be loaded with. This could be either it's static address, a requested dynamic address, or just a dynamic address that is available

Parameters

[in]	target	The pointer of the device descriptor
[out]	addr	Address to be assigned to target device.

Return values

0	if successful.
-EINVAL	if the expected default address is already in use

◆ i3c_dev_list_daa_addr_helper()

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
	)

#include <zephyr/drivers/i3c.h>

Helper function to find a usable address during ENTDAA.

This is a helper function to find a usable address during Dynamic Address Assignment. Given the PID (pid), it will search through the device list for the matching device descriptor. If the device descriptor indicates that there is a preferred address (i.e. assigned-address in device tree,

See also: i3c_device_desc::init_dynamic_addr), this preferred address will be returned if this address is still available. If it is not available, another free address will be returned.

If must_match is true, the PID (pid) must match one of the device in the device list.

If must_match is false, this will return an arbitrary address. This is useful when not all devices are described in device tree. Or else, the DAA process cannot proceed since there is no address to be assigned.

If assigned_okay is true, it will return the same address already assigned to the device (

See also: i3c_device_desc::dynamic_addr). If no address has been assigned, it behaves as if assigned_okay is false. This is useful for assigning the same address to the same device (for example, hot-join after device coming back from suspend).

If assigned_okay is false, the device cannot have an address assigned already (that

See also: i3c_device_desc::dynamic_addr is not zero). This is mainly used during the initial DAA.

Parameters

[in]	addr_slots	Pointer to address slots struct.
[in]	dev_list	Pointer to the device list struct.
[in]	pid	Provisioned ID of device to be assigned address.
[in]	must_match	True if PID must match devices in the device list. False otherwise.
[in]	assigned_okay	True if it is okay to return the address already assigned to the target matching the PID (`pid`).
[out]	target	Store the pointer of the device descriptor if it matches the incoming PID (`pid`).
[out]	addr	Address to be assigned to target device.

Return values

0	if successful.
-ENODEV	if no device matches the PID (`pid`) in the device list and `must_match` is true.
-EINVAL	if the device matching PID (`pid`) already has an address assigned or invalid function arguments.

◆ i3c_dev_list_find()

struct i3c_device_desc * i3c_dev_list_find	(	const struct i3c_dev_list *	dev_list,
		const struct i3c_device_id *	id
	)

#include <zephyr/drivers/i3c.h>

Find a I3C target device descriptor by ID.

This finds the I3C target device descriptor in the device list matching the provided ID struct (id).

Parameters

dev_list	Pointer to the device list struct.
id	Pointer to I3C device ID struct.

Returns: Pointer the the I3C target device descriptor, or NULL if none is found.

◆ i3c_dev_list_i2c_addr_find()

struct i3c_i2c_device_desc * i3c_dev_list_i2c_addr_find	(	struct i3c_dev_attached_list *	dev_list,
		uint16_t	addr
	)

#include <zephyr/drivers/i3c.h>

Find a I2C target device descriptor by address.

This finds the I2C target device descriptor in the attached device list matching the address (addr)

Parameters

dev_list	Pointer to the device list struct.
addr	Address to be matched.

Returns: Pointer the the I2C target device descriptor, or NULL if none is found.

◆ i3c_dev_list_i3c_addr_find()

struct i3c_device_desc * i3c_dev_list_i3c_addr_find	(	struct i3c_dev_attached_list *	dev_list,
		uint8_t	addr
	)

#include <zephyr/drivers/i3c.h>

Find a I3C target device descriptor by dynamic address.

This finds the I3C target device descriptor in the attached device list matching the dynamic address (addr)

Parameters

dev_list	Pointer to the device list struct.
addr	Dynamic address to be matched.

Returns: Pointer the the I3C target device descriptor, or NULL if none is found.

◆ i3c_device_basic_info_get()

int i3c_device_basic_info_get ( struct i3c_device_desc * target )

#include <zephyr/drivers/i3c.h>

Get basic information from device and update device descriptor.

This retrieves some basic information:

Bus Characteristics Register (GETBCR)
Device Characteristics Register (GETDCR)
Max Read Length (GETMRL)
Max Write Length (GETMWL) from the device and update the corresponding fields of the device descriptor.

This only updates the field(s) in device descriptor only if CCC operations succeed.

Parameters

[in,out] target I3C target device descriptor.

Return values

0	if successful.
-EIO	General Input/Output error.

◆ i3c_device_find()

static struct i3c_device_desc * i3c_device_find	(	const struct device *	dev,
		const struct i3c_device_id *	id
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Find a registered I3C target device.

Controller only API.

This returns the I3C device descriptor of the I3C device matching the incoming id.

Parameters

dev	Pointer to controller device driver instance.
id	Pointer to I3C device ID.

Returns: Pointer to I3C device descriptor, or NULL if no I3C device found matching incoming id.

◆ i3c_device_is_ibi_capable()

static int i3c_device_is_ibi_capable ( struct i3c_device_desc * target )

inlinestatic

#include <zephyr/drivers/i3c.h>

Check if device is IBI capable.

This reads the BCR from the device descriptor struct to determine whether device is capable of IBI.

Note that BCR must have been obtained from device and

See also: i3c_device_desc::bcr must be set.

Returns: True if IBI has payload, false otherwise.

◆ i3c_do_ccc()

int i3c_do_ccc	(	const struct device *	dev,
		struct i3c_ccc_payload *	payload
	)

#include <zephyr/drivers/i3c.h>

Send CCC to the bus.

Parameters

dev	Pointer to the device structure for the controller driver instance.
payload	Pointer to the structure describing the CCC payload.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General Input / output error.
-EINVAL	Invalid valid set in the payload structure.
-ENOSYS	Not implemented.

◆ i3c_do_daa()

static int i3c_do_daa ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/i3c.h>

Perform Dynamic Address Assignment on the I3C bus.

This routine asks the controller to perform dynamic address assignment where the controller belongs. Only the active controller of the bus should do this.

Note: For controller driver implementation, the controller should perform SETDASA to allow static addresses to be the dynamic addresses before actually doing ENTDAA.

Parameters

dev	Pointer to the device structure for the controller driver instance.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.
-ENODEV	If a provisioned ID does not match to any target devices in the registered device list.
-ENOSPC	No more free addresses can be assigned to target.
-ENOSYS	Dynamic address assignment is not supported by the controller driver.

◆ i3c_dump_msgs()

void i3c_dump_msgs	(	const char *	name,
		const struct i3c_msg *	msgs,
		uint8_t	num_msgs,
		struct i3c_device_desc *	target
	)

#include <zephyr/drivers/i3c.h>

Dump out an I3C message.

Dumps out a list of I3C messages. For any that are writes (W), the data is displayed in hex.

It looks something like this (with name "testing"):

D: I3C msg: testing, addr=56
D:    W len=01:
D: contents:
D: 06                      |.
D:    W len=0e:
D: contents:
D: 00 01 02 03 04 05 06 07 |........
D: 08 09 0a 0b 0c 0d       |......

Parameters

name	Name of this dump, displayed at the top.
msgs	Array of messages to dump.
num_msgs	Number of messages to dump.
target	I3C target device descriptor.

◆ i3c_ibi_disable()

static int i3c_ibi_disable ( struct i3c_device_desc * target )

inlinestatic

#include <zephyr/drivers/i3c.h>

Disable IBI of a target device.

This enables IBI of a target device where the IBI has already been request.

Parameters

target I3C target device descriptor.

Return values

0	If successful.
-EIO	General Input / output error.
-ENODEV	If IBI is not previously enabled for `target`.

◆ i3c_ibi_enable()

static int i3c_ibi_enable ( struct i3c_device_desc * target )

inlinestatic

#include <zephyr/drivers/i3c.h>

Enable IBI of a target device.

This enables IBI of a target device where the IBI has already been request.

Parameters

target I3C target device descriptor.

Return values

0	If successful.
-EIO	General Input / output error.
-ENOMEM	If these is no more empty entries in the controller's IBI table (if the controller uses such table).

◆ i3c_ibi_has_payload()

static int i3c_ibi_has_payload ( struct i3c_device_desc * target )

inlinestatic

#include <zephyr/drivers/i3c.h>

Check if target's IBI has payload.

This reads the BCR from the device descriptor struct to determine whether IBI from device has payload.

Note that BCR must have been obtained from device and

See also: i3c_device_desc::bcr must be set.

Returns: True if IBI has payload, false otherwise.

◆ i3c_ibi_raise()

static int i3c_ibi_raise	(	const struct device *	dev,
		struct i3c_ibi *	request
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Raise an In-Band Interrupt (IBI).

This raises an In-Band Interrupt (IBI) to the active controller.

Parameters

dev	Pointer to controller device driver instance.
request	Pointer to the IBI request struct.

Return values

0	if operation is successful.
-EIO	General input / output error.

◆ i3c_read()

static int i3c_read	(	struct i3c_device_desc *	target,
		uint8_t *	buf,
		uint32_t	num_bytes
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Read a set amount of data from an I3C target device.

This routine reads a set amount of data synchronously.

Parameters

target	I3C target device descriptor.
buf	Memory pool that stores the retrieved data.
num_bytes	Number of bytes to read.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.

◆ i3c_reattach_i3c_device()

int i3c_reattach_i3c_device	(	struct i3c_device_desc *	target,
		uint8_t	old_dyn_addr
	)

#include <zephyr/drivers/i3c.h>

Reattach I3C device.

called after every time an I3C device has its address changed. It can be because the device has been powered down and has lost its address, or it can happen when a device had a static address and has been assigned a dynamic address with SETDASA or a dynamic address has been updated with SETNEWDA. This will also call the optional api to update any registers within the driver if implemented.

Warning: Use cases involving multiple writers to the i3c/i2c devices must prevent concurrent write operations, either by preventing all writers from being preempted or by using a mutex to govern writes to the i3c/i2c devices.

Parameters

target	Pointer to the target device descriptor
old_dyn_addr	The old dynamic address of target device, 0 if there was no old dynamic address

Return values

0	If successful.
-EINVAL	If address is not available

◆ i3c_recover_bus()

static int i3c_recover_bus ( const struct device * dev )

inlinestatic

#include <zephyr/drivers/i3c.h>

Attempt bus recovery on the I3C bus.

This routine asks the controller to attempt bus recovery.

Return values

0	If successful.
-EBUSY	If bus recovery fails.
-EIO	General input / output error.
-ENOSYS	Bus recovery is not supported by the controller driver.

◆ i3c_reg_read_byte()

static int i3c_reg_read_byte	(	struct i3c_device_desc *	target,
		uint8_t	reg_addr,
		uint8_t *	value
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Read internal register of an I3C target device.

This routine reads the value of an 8-bit internal register of an I3C target device synchronously.

Parameters

target	I3C target device descriptor.
reg_addr	Address of the internal register being read.
value	Memory pool that stores the retrieved register value.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.

◆ i3c_reg_update_byte()

static int i3c_reg_update_byte	(	struct i3c_device_desc *	target,
		uint8_t	reg_addr,
		uint8_t	mask,
		uint8_t	value
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Update internal register of an I3C target device.

This routine updates the value of a set of bits from an 8-bit internal register of an I3C target device synchronously.

Note: If the calculated new register value matches the value that was read this function will not generate a write operation.

Parameters

target	I3C target device descriptor.
reg_addr	Address of the internal register being updated.
mask	Bitmask for updating internal register.
value	Value for updating internal register.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.

◆ i3c_reg_write_byte()

static int i3c_reg_write_byte	(	struct i3c_device_desc *	target,
		uint8_t	reg_addr,
		uint8_t	value
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Write internal register of an I3C target device.

This routine writes a value to an 8-bit internal register of an I3C target device synchronously.

Note: This function internally combines the register and value into a single bus transaction.

Parameters

target	I3C target device descriptor.
reg_addr	Address of the internal register being written.
value	Value to be written to internal register.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.

◆ i3c_transfer()

int i3c_transfer	(	struct i3c_device_desc *	target,
		struct i3c_msg *	msgs,
		uint8_t	num_msgs
	)

#include <zephyr/drivers/i3c.h>

Perform data transfer from the controller to a I3C target device.

This routine provides a generic interface to perform data transfer to a target device synchronously. Use i3c_read()/i3c_write() for simple read or write.

The array of message msgs must not be NULL. The number of message num_msgs may be zero, in which case no transfer occurs.

Note: Not all scatter/gather transactions can be supported by all drivers. As an example, a gather write (multiple consecutive i3c_msg buffers all configured for I3C_MSG_WRITE) may be packed into a single transaction by some drivers, but others may emit each fragment as a distinct write transaction, which will not produce the same behavior. See the documentation of struct i3c_msg for limitations on support for multi-message bus transactions.

Parameters

target	I3C target device descriptor.
msgs	Array of messages to transfer.
num_msgs	Number of messages to transfer.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.

◆ i3c_write()

static int i3c_write	(	struct i3c_device_desc *	target,
		const uint8_t *	buf,
		uint32_t	num_bytes
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Write a set amount of data to an I3C target device.

This routine writes a set amount of data synchronously.

Parameters

target	I3C target device descriptor.
buf	Memory pool from which the data is transferred.
num_bytes	Number of bytes to write.

Return values

0	If successful.
-EBUSY	Bus is busy.
-EIO	General input / output error.

◆ i3c_write_read()

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
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Write then read data from an I3C target device.

This supports the common operation "this is what I want", "now give it to me" transaction pair through a combined write-then-read bus transaction.

Parameters

target	I3C target device descriptor.
write_buf	Pointer to the data to be written
num_write	Number of bytes to write
read_buf	Pointer to storage for read data
num_read	Number of bytes to read

Return values

0	if successful
-EBUSY	Bus is busy.
-EIO	General input / output error.

	Zephyr API Documentation 3.4.0 A Scalable Open Source RTOS
3.4.0

Modules

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ I3C_BCR_ADV_CAPABILITIES

◆ I3C_BCR_DEVICE_ROLE

◆ I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE

◆ I3C_BCR_DEVICE_ROLE_I3C_TARGET

◆ I3C_BCR_DEVICE_ROLE_MASK

◆ I3C_BCR_DEVICE_ROLE_SHIFT

◆ I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE

◆ I3C_BCR_IBI_REQUEST_CAPABLE

◆ I3C_BCR_MAX_DATA_SPEED_LIMIT

◆ I3C_BCR_OFFLINE_CAPABLE

◆ I3C_BCR_VIRTUAL_TARGET

◆ I3C_DCR_I2C_DEV_IDX

◆ I3C_DCR_I2C_DEV_IDX_0

◆ I3C_DCR_I2C_DEV_IDX_1

◆ I3C_DCR_I2C_DEV_IDX_2

◆ I3C_DCR_I2C_DEV_IDX_MASK

◆ I3C_DCR_I2C_DEV_IDX_SHIFT

◆ I3C_DCR_I2C_FM_MODE

◆ I3C_DCR_I2C_FM_PLUS_MODE

◆ I3C_DCR_I2C_MODE

◆ I3C_DCR_I2C_MODE_MASK

◆ I3C_DCR_I2C_MODE_SHIFT

◆ I3C_DEVICE_ID

◆ I3C_MSG_HDR

◆ I3C_MSG_HDR_BT

◆ I3C_MSG_HDR_DDR

◆ I3C_MSG_HDR_MODE0

◆ I3C_MSG_HDR_MODE1

◆ I3C_MSG_HDR_MODE2

◆ I3C_MSG_HDR_MODE3

◆ I3C_MSG_HDR_MODE4

◆ I3C_MSG_HDR_MODE5

◆ I3C_MSG_HDR_MODE6

◆ I3C_MSG_HDR_MODE7

◆ I3C_MSG_HDR_TSL

◆ I3C_MSG_HDR_TSP

◆ I3C_MSG_NBCH

◆ I3C_MSG_READ

◆ I3C_MSG_RESTART

◆ I3C_MSG_STOP

◆ I3C_MSG_WRITE

Enumeration Type Documentation

◆ i3c_bus_mode

◆ i3c_config_type

◆ i3c_data_rate

◆ i3c_i2c_speed_type

◆ i3c_sdr_controller_error_codes

◆ i3c_sdr_target_error_codes

Function Documentation

◆ i3c_attach_i2c_device()

◆ i3c_attach_i3c_device()

◆ i3c_burst_read()

◆ i3c_burst_write()

◆ i3c_bus_init()

◆ i3c_config_get()

◆ i3c_configure()

◆ i3c_detach_i2c_device()

◆ i3c_detach_i3c_device()

◆ i3c_determine_default_addr()

◆ i3c_dev_list_daa_addr_helper()

◆ i3c_dev_list_find()

◆ i3c_dev_list_i2c_addr_find()

◆ i3c_dev_list_i3c_addr_find()

◆ i3c_device_basic_info_get()

◆ i3c_device_find()

◆ i3c_device_is_ibi_capable()

◆ i3c_do_ccc()

◆ i3c_do_daa()

◆ i3c_dump_msgs()

◆ i3c_ibi_disable()

◆ i3c_ibi_enable()

◆ i3c_ibi_has_payload()

◆ i3c_ibi_raise()