Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
|
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 | |
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 (const struct device *dev, uint8_t addr) |
Find a I3C target device descriptor by dynamic address. | |
struct i3c_i2c_device_desc * | i3c_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_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) | |
| |
#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) | |
| |
#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. | |
I3C Interface .
#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.
#define I3C_BCR_DEVICE_ROLE | ( | bcr | ) |
#include <zephyr/drivers/i3c.h>
Device Role.
Obtain Device Role value from the BCR value obtained via GETBCR.
bcr | BCR value |
#define I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE 1U |
#include <zephyr/drivers/i3c.h>
Device Role - I3C Controller Capable.
#define I3C_BCR_DEVICE_ROLE_I3C_TARGET 0U |
#include <zephyr/drivers/i3c.h>
Device Role - I3C Target.
#define I3C_BCR_DEVICE_ROLE_MASK GENMASK(7U, 6U) |
#include <zephyr/drivers/i3c.h>
Device Role bit shift mask.
#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.
#define I3C_BCR_IBI_REQUEST_CAPABLE BIT(1) |
#include <zephyr/drivers/i3c.h>
IBI Request Capable bit.
#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.
#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.
#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.
#define I3C_BUS_FOR_EACH_I2CDEV | ( | bus, | |
desc ) |
#include <zephyr/drivers/i3c.h>
iterate over all I2C devices present on the bus
bus | the I3C bus device pointer |
desc | an I2C device descriptor pointer updated to point to the current slot at each iteration of the loop |
#define I3C_BUS_FOR_EACH_I3CDEV | ( | bus, | |
desc ) |
#include <zephyr/drivers/i3c.h>
iterate over all I3C devices present on the bus
bus | the I3C bus device pointer |
desc | an I3C device descriptor pointer updated to point to the current slot at each iteration of the loop |
#define I3C_DEVICE_ID | ( | pid | ) |
#include <zephyr/drivers/i3c.h>
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.
pid | Provisioned ID. |
#define I3C_LVR_I2C_DEV_IDX | ( | lvr | ) |
#include <zephyr/drivers/i3c.h>
I2C Device Index.
Obtain I2C Device Index value from the LVR value.
lvr | LVR value |
#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.
#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.
#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.
#define I3C_LVR_I2C_DEV_IDX_MASK GENMASK(7U, 5U) |
#include <zephyr/drivers/i3c.h>
I2C Device Index bitmask.
#define I3C_LVR_I2C_FM_MODE 1 |
#include <zephyr/drivers/i3c.h>
I2C FM Mode.
#define I3C_LVR_I2C_FM_PLUS_MODE 0 |
#include <zephyr/drivers/i3c.h>
I2C FM+ Mode.
#define I3C_LVR_I2C_MODE | ( | lvr | ) |
#include <zephyr/drivers/i3c.h>
I2C Mode.
Obtain I2C Mode value from the LVR value.
lvr | LVR value |
#define I3C_LVR_I2C_MODE_MASK BIT(4) |
#include <zephyr/drivers/i3c.h>
I2C Mode Indicator bitmask.
enum i3c_bus_mode |
#include <zephyr/drivers/i3c.h>
I3C bus mode.
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 |
enum i3c_data_rate |
#include <zephyr/drivers/i3c.h>
I3C data rate.
I3C data transfer rate defined by the I3C specification.
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 |
#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.
#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.
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.
target | Pointer to the target device descriptor |
0 | If successful. |
-EINVAL | If address is not available or if the device has already been attached before |
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.
target | Pointer to the target device descriptor |
0 | If successful. |
-EINVAL | If address is not available or if the device has already been attached before |
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
dev | Pointer to controller device driver instance. |
0 | if successful. |
-ENOMEM | No memory to build the payload. |
-EIO | General Input/Output error. |
#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.
dev | Pointer to controller device driver instance. |
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.
dev | Pointer to controller device driver instance. |
i3c_dev_list | Pointer to I3C device list. |
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. |
|
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.
[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.
0 | If successful. |
-EIO | General Input/Output errors. |
-ENOSYS | If not implemented. |
|
inlinestatic |
#include <zephyr/drivers/i3c.h>
Configure the I3C hardware.
dev | Pointer to controller device driver instance. |
type | Type of configuration parameters being passed in config . |
config | Pointer to the configuration parameters. |
0 | If successful. |
-EINVAL | If invalid configure parameters. |
-EIO | General Input/Output errors. |
-ENOSYS | If not implemented. |
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.
target | Pointer to the target device descriptor |
0 | If successful. |
-EINVAL | If device is already detached |
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.
target | Pointer to the target device descriptor |
0 | If successful. |
-EINVAL | If device is already detached |
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.
[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. |
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. |
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
).
dev_list | Pointer to the device list struct. |
id | Pointer to I3C device ID struct. |
NULL
if none is found. 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
)
dev | Pointer to controller device driver instance. |
addr | Address to be matched. |
NULL
if none is found. 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
)
dev | Pointer to controller device driver instance. |
addr | Dynamic address to be matched. |
NULL
if none is found. 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:
This only updates the field(s) in device descriptor only if CCC operations succeed.
[in,out] | target | I3C target device descriptor. |
0 | if successful. |
-EIO | General Input/Output error. |
|
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
.
dev | Pointer to controller device driver instance. |
id | Pointer to I3C device ID. |
NULL
if no I3C device found matching incoming id
. int i3c_do_ccc | ( | const struct device * | dev, |
struct i3c_ccc_payload * | payload ) |
#include <zephyr/drivers/i3c.h>
Send CCC to the bus.
dev | Pointer to the device structure for the controller driver instance. |
payload | Pointer to the structure describing the CCC payload. |
0 | If successful. |
-EBUSY | Bus is busy. |
-EIO | General Input / output error. |
-EINVAL | Invalid valid set in the payload structure. |
-ENOSYS | Not implemented. |
|
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.
dev | Pointer to the device structure for the controller driver instance. |
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. |
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.
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 |
0 | If successful. |
-EINVAL | If address is not available |
|
inlinestatic |
#include <zephyr/drivers/i3c.h>
Attempt bus recovery on the I3C bus.
This routine asks the controller to attempt bus recovery.
0 | If successful. |
-EBUSY | If bus recovery fails. |
-EIO | General input / output error. |
-ENOSYS | Bus recovery is not supported by the controller driver. |