Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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.
 
#define I3C_BUS_FOR_EACH_I3CDEV(bus, desc)
 iterate over all I3C devices present on the bus
 
#define I3C_BUS_FOR_EACH_I2CDEV(bus, desc)
 iterate over all I2C devices present on the bus
 

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 (const struct device *dev, uint8_t addr)
 Find a I3C target device descriptor by dynamic address.
 
struct i3c_i2c_device_desci3c_dev_list_i2c_addr_find (const struct device *dev, uint16_t addr)
 Find a I2C target device descriptor by address.
 
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_desci3c_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:
#define I3C_BCR_DEVICE_ROLE_MASK
Device Role bit shift mask.
Definition i3c.h:130
#define FIELD_GET(mask, value)
Extract a bitfield element from value corresponding to the field mask mask.
Definition util_macro.h:103

Device Role.

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

Parameters
bcrBCR 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_BUS_FOR_EACH_I2CDEV

#define I3C_BUS_FOR_EACH_I2CDEV ( bus,
desc )

#include <zephyr/drivers/i3c.h>

Value:
&((struct i3c_driver_data *)(bus->data))->attached_dev.devices.i2c, desc, node)
#define SYS_SLIST_FOR_EACH_CONTAINER(__sl, __cn, __n)
Provide the primitive to iterate on a list under a container Note: the loop is unsafe and thus __cn s...
Definition slist.h:165
This structure is common to all I3C drivers and is expected to be the first element in the driver's s...
Definition i3c.h:1199

iterate over all I2C devices present on the bus

Parameters
busthe I3C bus device pointer
descan I2C device descriptor pointer updated to point to the current slot at each iteration of the loop

◆ I3C_BUS_FOR_EACH_I3CDEV

#define I3C_BUS_FOR_EACH_I3CDEV ( bus,
desc )

#include <zephyr/drivers/i3c.h>

Value:
&((struct i3c_driver_data *)(bus->data))->attached_dev.devices.i3c, desc, node)

iterate over all I3C devices present on the bus

Parameters
busthe I3C bus device pointer
descan I3C device descriptor pointer updated to point to the current slot at each iteration of the loop

◆ 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
pidProvisioned ID.

◆ I3C_LVR_I2C_DEV_IDX

#define I3C_LVR_I2C_DEV_IDX ( lvr)

#include <zephyr/drivers/i3c.h>

Value:
#define I3C_LVR_I2C_DEV_IDX_MASK
I2C Device Index bitmask.
Definition i3c.h:208

I2C Device Index.

Obtain I2C Device Index value from the LVR value.

Parameters
lvrLVR 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:
#define I3C_LVR_I2C_MODE_MASK
I2C Mode Indicator bitmask.
Definition i3c.h:171

I2C Mode.

Obtain I2C Mode value from the LVR value.

Parameters
lvrLVR 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

#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

#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

#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

#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

#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

#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
targetPointer to the target device descriptor
Return values
0If successful.
-EINVALIf 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
targetPointer to the target device descriptor
Return values
0If successful.
-EINVALIf 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
devPointer to controller device driver instance.
Return values
0if successful.
-ENOMEMNo memory to build the payload.
-EIOGeneral 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
devPointer 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
devPointer to controller device driver instance.
i3c_dev_listPointer to I3C device list.
Return values
0If successful.
-EBUSYBus is busy.
-EIOGeneral input / output error.
-ENODEVIf a provisioned ID does not match to any target devices in the registered device list.
-ENOSPCNo more free addresses can be assigned to target.
-ENOSYSDynamic 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]devPointer to controller device driver instance.
[in]typeType of configuration parameters being passed in config.
[in,out]configPointer 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
0If successful.
-EIOGeneral Input/Output errors.
-ENOSYSIf 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
devPointer to controller device driver instance.
typeType of configuration parameters being passed in config.
configPointer to the configuration parameters.
Return values
0If successful.
-EINVALIf invalid configure parameters.
-EIOGeneral Input/Output errors.
-ENOSYSIf 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
targetPointer to the target device descriptor
Return values
0If successful.
-EINVALIf 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
targetPointer to the target device descriptor
Return values
0If successful.
-EINVALIf device is already detached

◆ 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_slotsPointer to address slots struct.
[in]dev_listPointer to the device list struct.
[in]pidProvisioned ID of device to be assigned address.
[in]must_matchTrue if PID must match devices in the device list. False otherwise.
[in]assigned_okayTrue if it is okay to return the address already assigned to the target matching the PID (pid).
[out]targetStore the pointer of the device descriptor if it matches the incoming PID (pid).
[out]addrAddress to be assigned to target device.
Return values
0if successful.
-ENODEVif no device matches the PID (pid) in the device list and must_match is true.
-EINVALif 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_listPointer to the device list struct.
idPointer 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 ( const struct device * dev,
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
devPointer to controller device driver instance.
addrAddress 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 ( const struct device * dev,
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
devPointer to controller device driver instance.
addrDynamic 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]targetI3C target device descriptor.
Return values
0if successful.
-EIOGeneral 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
devPointer to controller device driver instance.
idPointer 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
devPointer to the device structure for the controller driver instance.
payloadPointer to the structure describing the CCC payload.
Return values
0If successful.
-EBUSYBus is busy.
-EIOGeneral Input / output error.
-EINVALInvalid valid set in the payload structure.
-ENOSYSNot 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
devPointer to the device structure for the controller driver instance.
Return values
0If successful.
-EBUSYBus is busy.
-EIOGeneral input / output error.
-ENODEVIf a provisioned ID does not match to any target devices in the registered device list.
-ENOSPCNo more free addresses can be assigned to target.
-ENOSYSDynamic 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
targetPointer to the target device descriptor
old_dyn_addrThe old dynamic address of target device, 0 if there was no old dynamic address
Return values
0If successful.
-EINVALIf 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
0If successful.
-EBUSYIf bus recovery fails.
-EIOGeneral input / output error.
-ENOSYSBus recovery is not supported by the controller driver.