I3C Interface

I3C Interface . More...

Topics
	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 HDR DDR API
	I3C HDR DDR API .
	I3C In-Band Interrupts
	I3C In-Band Interrupts .
	I3C Target Device API
	I3C Target Device API .
	I3C Transfer API
	I3C Transfer API .

Data Structures
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_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.
static struct i3c_device_desc *	i3c_device_find (const struct device *dev, const struct i3c_device_id *id)
	Find a registered I3C target device.
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.
bool	i3c_bus_has_sec_controller (const struct device *dev)
	Check if the bus has a secondary controller.
int	i3c_bus_deftgts (const struct device *dev)
	Send the CCC DEFTGTS.

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_MASK   GENMASK(7U, 6U)
	Device Role bit shift mask.
#define	I3C_BCR_DEVICE_ROLE(bcr)
	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_MASK   BIT(4)
	I2C Mode Indicator bitmask.
#define	I3C_LVR_I2C_MODE(lvr)
	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_MASK   GENMASK(7U, 5U)
	I2C Device Index bitmask.
#define	I3C_LVR_I2C_DEV_IDX(lvr)
	I2C Device Index.

Detailed Description

I3C Interface .

Since

3.2

Version

0.1.0

Macro Definition Documentation

I3C_BCR_ADV_CAPABILITIES

#define I3C_BCR_ADV_CAPABILITIES   BIT(5)

#include <zephyr/drivers/i3c.h>

Advanced Capabilities bit.

0 - Does not support optional advanced capabilities. 1 - Supports optional advanced capabilities which can be viewed via GETCAPS CCC.

I3C_BCR_DEVICE_ROLE

#define I3C_BCR_DEVICE_ROLE

(

bcr

)

#include <zephyr/drivers/i3c.h>

Value:

        FIELD_GET(I3C_BCR_DEVICE_ROLE_MASK, (bcr))

Device Role.

Obtain Device Role value from the BCR value obtained via GETBCR.

Parameters

bcr

BCR value

I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE

#define I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE   1U

#include <zephyr/drivers/i3c.h>

Device Role - I3C Controller Capable.

I3C_BCR_DEVICE_ROLE_I3C_TARGET

#define I3C_BCR_DEVICE_ROLE_I3C_TARGET   0U

#include <zephyr/drivers/i3c.h>

Device Role - I3C Target.

I3C_BCR_DEVICE_ROLE_MASK

#define I3C_BCR_DEVICE_ROLE_MASK   GENMASK(7U, 6U)

#include <zephyr/drivers/i3c.h>

Device Role bit shift mask.

I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE

#define I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE   BIT(2)

#include <zephyr/drivers/i3c.h>

IBI Payload bit.

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.

I3C_BCR_IBI_REQUEST_CAPABLE

#define I3C_BCR_IBI_REQUEST_CAPABLE   BIT(1)

#include <zephyr/drivers/i3c.h>

IBI Request Capable bit.

I3C_BCR_MAX_DATA_SPEED_LIMIT

#define I3C_BCR_MAX_DATA_SPEED_LIMIT   BIT(0)

#include <zephyr/drivers/i3c.h>

Max Data Speed Limitation bit.

0 - No Limitation. 1 - Limitation obtained via GETMXDS CCC.

I3C_BCR_OFFLINE_CAPABLE

#define I3C_BCR_OFFLINE_CAPABLE   BIT(3)

#include <zephyr/drivers/i3c.h>

Offline Capable bit.

0 - Will always respond to I3C commands. 1 - Will not always respond to I3C commands.

I3C_BCR_VIRTUAL_TARGET

#define I3C_BCR_VIRTUAL_TARGET   BIT(4)

#include <zephyr/drivers/i3c.h>

Virtual Target Support bit.

0 - Is not a virtual target. 1 - Is a virtual target.

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 i3c_device_id by populating the PID (Provisioned ID) field.

Parameters

pid	Provisioned ID.

I3C_LVR_I2C_DEV_IDX

#define I3C_LVR_I2C_DEV_IDX

(

lvr

)

#include <zephyr/drivers/i3c.h>

Value:

        FIELD_GET(I3C_LVR_I2C_DEV_IDX_MASK, (lvr))

I2C Device Index.

Obtain I2C Device Index value from the LVR value.

Parameters

lvr

LVR value

I3C_LVR_I2C_DEV_IDX_0

#define I3C_LVR_I2C_DEV_IDX_0   0

#include <zephyr/drivers/i3c.h>

I2C Device Index 0.

I2C device has a 50 ns spike filter where it is not affected by high frequency on SCL.

I3C_LVR_I2C_DEV_IDX_1

#define I3C_LVR_I2C_DEV_IDX_1   1

#include <zephyr/drivers/i3c.h>

I2C Device Index 1.

I2C device does not have a 50 ns spike filter but can work with high frequency on SCL.

I3C_LVR_I2C_DEV_IDX_2

#define I3C_LVR_I2C_DEV_IDX_2   2

#include <zephyr/drivers/i3c.h>

I2C Device Index 2.

I2C device does not have a 50 ns spike filter and cannot work with high frequency on SCL.

I3C_LVR_I2C_DEV_IDX_MASK

#define I3C_LVR_I2C_DEV_IDX_MASK   GENMASK(7U, 5U)

#include <zephyr/drivers/i3c.h>

I2C Device Index bitmask.

I3C_LVR_I2C_FM_MODE

#define I3C_LVR_I2C_FM_MODE   1

#include <zephyr/drivers/i3c.h>

I2C FM Mode.

I3C_LVR_I2C_FM_PLUS_MODE

#define I3C_LVR_I2C_FM_PLUS_MODE   0

#include <zephyr/drivers/i3c.h>

I2C FM+ Mode.

I3C_LVR_I2C_MODE

#define I3C_LVR_I2C_MODE

(

lvr

)

#include <zephyr/drivers/i3c.h>

Value:

        FIELD_GET(I3C_LVR_I2C_MODE_MASK, (lvr))

I2C Mode.

Obtain I2C Mode value from the LVR value.

Parameters

lvr

LVR value

I3C_LVR_I2C_MODE_MASK

#define I3C_LVR_I2C_MODE_MASK   BIT(4)

#include <zephyr/drivers/i3c.h>

I2C Mode Indicator bitmask.

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_bus_deftgts()

int i3c_bus_deftgts

(

const struct device *

dev

)

#include <zephyr/drivers/i3c.h>

Send the CCC DEFTGTS.

This builds the payload required for DEFTGTS and transmits it out

Parameters

dev	Pointer to controller device driver instance.

Return values

0	if successful.
-ENOMEM	No memory to build the payload.
-EIO	General Input/Output error.

i3c_bus_has_sec_controller()

bool i3c_bus_has_sec_controller

(

const struct device *

dev

)

#include <zephyr/drivers/i3c.h>

Check if the bus has a secondary controller.

This reads the BCR from the device descriptor struct of all targets to determine whether a device is a secondary controller.

Parameters

dev	Pointer to controller device driver instance.

Returns

True if the bus has a secondary controller, false otherwise.

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, 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 (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 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 to 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 to 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 to 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_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_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.