Improved Inter-Integrated Circuit (I3C) Bus

I3C (Improved Inter-Integrated Circuit) is a two-signal shared peripheral interface bus. Devices on the bus can operate in two roles: as a “controller” that initiates transactions and controls the clock, or as a “target” that responds to transaction commands.

Currently, the API is based on I3C Specification version 1.1.1.

I3C Controller API

Zephyr’s I3C controller API is used when an I3C controller controls the bus, in particularly the start and stop conditions and the clock. This is the most common mode, used to interact with I3C target devices such as sensors.

Due to the nature of the I3C, there are devices on the bus where they may not have addresses when powered on. Therefore, an additional dynamic address assignment needs to be carried out by the I3C controller. Because of this, the controller needs to maintain separate structures to keep track of device status. This can be done at build time, for example, by creating arrays of device descriptors for both I3C and I2C devices:

static struct i3c_device_desc i3c_device_array[] = I3C_DEVICE_ARRAY_DT_INST(inst);
static struct i3c_i2c_device_desc i2c_device_array[] = I3C_I2C_DEVICE_ARRAY_DT_INST(inst);

The macros I3C_DEVICE_ARRAY_DT_INST and I3C_I2C_DEVICE_ARRAY_DT_INST are helper macros to aid in create arrays of device descriptors corresponding to the devicetree nodes under the I3C controller.

Here is a list of generic steps for initializing the I3C controller and the I3C bus inside the device driver initialization function:

  1. Initialize the data structure of the I3C controller device driver instance. The usual device defining macros such as DEVICE_DT_INST_DEFINE can be used, and the initialization function provided as a parameter to the macro.

    • The i3c_addr_slots and i3c_dev_list are structures to aid in address assignments and device list management. If this is being used, this struct needs to be initialized by calling i3c_addr_slots_init(). These two structures can also be used with various helper functions.

    • Initialize the device descriptors if needed by the controller driver.

  2. Initialize the hardware, including but not limited to:

    • Setup pin mux and directions.

    • Setup the clock for the controller.

    • Power on the hardware.

    • Configure the hardware (e.g. SCL clock frequency).

  3. Perform bus initialization. There is a generic helper function, i3c_bus_init(), which performs the following steps. This function can be used if the controller does not require any special handling during bus initialization.

    1. Do RSTDAA to reset dynamic addresses of connected devices. If any connected devices have already been assigned an address, the bookkeeping data structures do not have records of these, for example, at power-on. So it is a good idea to reset and assign them new addresses.

    2. Do DISEC to disable any events from devices.

    3. Do SETDASA to use static addresses as dynamic address if so desired.

      • SETAASA may not be supported for all connected devices to assign static addresses as dynamic addresses.

      • BCR and DCR need to be obtained separately to populate the relevant fields in the I3C target device descriptor struct.

    4. Do ENTDAA to start dynamic address assignment, if there are still devices without addresses.

      • If there is a device waiting for address, it will send its Provisioned ID, BCR, and DCR back. Match the received Provisioned ID to the list of registered I3C devices.

        • If there is a match, assign an address (either from the stated static address if SETDASA has not been done, or use a free address).

          • Also, set the BCR and DCR fields in the device descriptor struct.

        • If there is no match, depending on policy, it can be assigned a free address, or the device driver can stop the assignment process and errors out.

          • Note that the I3C API requires device descriptor to function. A device without a device descriptor cannot be accessed through the API.

      • This step can be skipped if there is no connected devices requiring DAA.

    5. These are optional but highly recommended:

      • Do GETMRL and GETMWL to get maximum read/write length.

      • Do GETMXDS to get maximum read/write speed and maximum read turnaround time.

      • The helper function, i3c_bus_init(), would retrieve basic device information such as BCR, DCR, MRL and MWL.

    6. Do ENEC to re-enable events from devices.

      • The helper function, i3c_bus_init(), only re-enables hot-join events. IBI event should only be enabled when enabling IBI of a device.

In-Band Interrupt (IBI)

If a target device can generate In-Band Interrupt (IBI), the controller needs to be made aware of it.

  • i3c_ibi_enable() to enable IBI of a target device.

    • Some controller hardware have IBI slots which need to be programmed so that the controller can recognize incoming IBIs from a particular target device.

      • If the hardware has IBI slots, i3c_ibi_enable() needs to program those IBI slots.

      • Note that there are usually limited IBI slots on the controller so this operation may fail.

    • The implementation in driver should also send the ENEC command to enable interrupt of this target device.

  • i3c_ibi_disable() to disable IBI of a target device.

    • If controller hardware makes use of IBI slots, this will remove description of the target device from the slots.

    • The implementation in driver should also send the DISEC command to disable interrupt of this target device.

Device Tree

Here is an example for defining a I3C controller in device tree:

i3c0: i3c@10000 {
        compatible = "vendor,i3c";

        #address-cells = < 0x3 >;
        #size-cells = < 0x0 >;

        reg = < 0x10000 0x1000 >;
        interrupts = < 0x1F 0x0 >;

        pinctrl-0 = < &pinmux-i3c >;
        pinctrl-names = "default";

        i2c-scl-hz = < 400000 >;

        i3c-scl-hz = < 12000000 >;

        status = "okay";

        i3c-dev0: i3c-dev0@420000ABCD12345678 {
                compatible = "vendor,i3c-dev";

                reg = < 0x42 0xABCD 0x12345678 >;

                status = "okay";
        };

        i2c-dev0: i2c-dev0@380000000000000050 {
                compatible = "vendor-i2c-dev";

                reg = < 0x38 0x0 0x50 >;

                status = "okay";
        };
};

I3C Devices

For I3C devices, the reg property has 3 elements:

  • The first one is the static address of the device.

    • Can be zero if static address is not used. Address will be assigned during DAA (Dynamic Address Assignment).

    • If non-zero and property assigned-address is not set, this will be the address of the device after SETDASA (Set Dynamic Address from Static Address) is issued.

  • Second element is the upper 16-bit of the Provisioned ID (PID) which contains the manufacturer ID left-shifted by 1. This is the bits 33-47 (zero-based) of the 48-bit Provisioned ID.

  • Third element contains the lower 32-bit of the Provisioned ID which is a combination of the part ID (left-shifted by 16, bits 16-31 of the PID) and the instance ID (left-shifted by 12, bits 12-15 of the PID).

Note that the unit-address (the part after @) must match the reg property fully where each element is treated as 32-bit integer, combining to form a 96-bit integer. This is required for properly generating device tree macros.

I2C Devices

For I2C devices where the device driver has support for working under I3C bus, the device node can be described as a child of the I3C controller. If the device driver is written to only work with I2C controllers, define the node under the I2C virtual controller as described below. Otherwise, the reg property, similar to I3C devices, has 3 elements:

  • The first one is the static address of the device. This must be a valid address as I2C devices do not support dynamic address assignment.

  • Second element is always zero.

    • This is used by various helper macros to determine whether the device tree entry corresponds to a I2C device.

  • Third element is the LVR (Legacy Virtual Register):

    • bit[31:8] are unused.

    • bit[7:5] are the I2C device index:

      • Index 0

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

      • Index 1

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

      • Index 2

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

    • bit[4] is the I2C mode indicator:

      • 0 is FM+ mode.

      • 1 is FM mode.

Similar to I3C devices, the unit-address must match the reg property fully where each element is treated as 32-bit integer, combining to form a 96-bit integer.

Device Drivers for I3C Devices

All of the transfer functions of I3C controller API require the use of device descriptors, i3c_device_desc. This struct contains runtime information about a I3C device, such as, its dynamic address, BCR, DCR, MRL and MWL. Therefore, the device driver of a I3C device should grab a pointer to this device descriptor from the controller using i3c_device_find(). This function takes an ID parameter of type i3c_device_id for matching. The returned pointer can then be used in subsequent API calls to the controller.

I2C Devices under I3C Bus

Since I3C is backware compatible with I2C, the I3C controller API can accommodate I2C API calls without modifications if the controller device driver implements the I2C API. This has the advantage of using existing I2C devices without any modifications to their device drivers. However, since the I3C controller API works on device descriptors, any calls to I2C API will need to look up the corresponding device descriptor from the I2C device address. This adds a bit of processing cost to any I2C API calls.

On the other hand, a device driver can be extended to utilize native I2C device support via the I3C controller API. During device initialization, i3c_i2c_device_find() needs to be called to retrieve the pointer to the device descriptor. This pointer can be used in subsequent API calls.

Note that, with either methods mentioned above, the devicetree node of the I2C device must be declared according to I3C standard:

The I2C virtual controller device driver provides a way to interface I2C devices on the I3C bus where the associated device drivers can be used as-is without modifications. This requires adding an intermediate node in the device tree:

i3c0: i3c@10000 {
        <... I3C controller related properties ...>
        <... Nodes of I3C devices, if any ...>

        i2c-dev0: i2c-dev0@420000000000000050 {
                compatible = "vendor-i2c-dev";

                reg = < 0x42 0x0 0x50 >;

                status = "okay";
        };
};

Configuration Options

Related configuration options:

API Reference

group i3c_interface

I3C Interface.

Defines

I3C_BCR_MAX_DATA_SPEED_LIMIT
I3C_BCR_IBI_REQUEST_CAPABLE
I3C_BCR_IBI_PAYLOAD_HAS_DATA_BYTE
I3C_BCR_OFFLINE_CAPABLE
I3C_BCR_VIRTUAL_TARGET
I3C_BCR_ADV_CAPABILITIES
I3C_BCR_DEVICE_ROLE_I3C_TARGET
I3C_BCR_DEVICE_ROLE_I3C_CONTROLLER_CAPABLE
I3C_BCR_DEVICE_ROLE_SHIFT
I3C_BCR_DEVICE_ROLE_MASK
I3C_BCR_DEVICE_ROLE(bcr)
I3C_DCR_I2C_FM_PLUS_MODE
I3C_DCR_I2C_FM_MODE
I3C_DCR_I2C_MODE_SHIFT
I3C_DCR_I2C_MODE_MASK
I3C_DCR_I2C_MODE(dcr)
I3C_DCR_I2C_DEV_IDX_0
I3C_DCR_I2C_DEV_IDX_1
I3C_DCR_I2C_DEV_IDX_2
I3C_DCR_I2C_DEV_IDX_SHIFT
I3C_DCR_I2C_DEV_IDX_MASK
I3C_DCR_I2C_DEV_IDX(dcr)
I3C_MSG_WRITE

Write message to I3C bus.

I3C_MSG_READ

Read message from I3C bus.

I3C_MSG_STOP

Send STOP after this message.

I3C_MSG_RESTART

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_HDR

Transfer use HDR mode

I3C_MSG_NBCH

Skip I3C broadcast header. Private Transfers only.

I3C_MSG_HDR_MODE0

I3C HDR Mode 0

I3C_MSG_HDR_MODE1

I3C HDR Mode 1

I3C_MSG_HDR_MODE2

I3C HDR Mode 2

I3C_MSG_HDR_MODE3

I3C HDR Mode 3

I3C_MSG_HDR_MODE4

I3C HDR Mode 4

I3C_MSG_HDR_MODE5

I3C HDR Mode 5

I3C_MSG_HDR_MODE6

I3C HDR Mode 6

I3C_MSG_HDR_MODE7

I3C HDR Mode 7

I3C_MSG_HDR_DDR

I3C HDR-DDR (Double Data Rate)

I3C_MSG_HDR_TSP

I3C HDR-TSP (Ternary Symbol Pure-bus)

I3C_MSG_HDR_TSL

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

I3C_MSG_HDR_BT

I3C HDR-BT (Bulk Transport)

I3C_DEVICE_ID(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.

Enums

enum i3c_bus_mode

I3C bus mode.

Values:

enumerator I3C_BUS_MODE_PURE

Only I3C devices are on the bus.

enumerator I3C_BUS_MODE_MIXED_FAST

Both I3C and legacy I2C devices are on the bus. The I2C devices have 50ns spike filter on SCL.

enumerator 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.

enumerator 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.

enumerator I3C_BUS_MODE_MAX = I3C_BUS_MODE_MIXED_SLOW
enumerator I3C_BUS_MODE_INVALID
enum i3c_i2c_speed_type

I2C bus speed under I3C bus.

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

Values:

enumerator I3C_I2C_SPEED_FM

I2C FM mode

enumerator I3C_I2C_SPEED_FMPLUS

I2C FM+ mode

enumerator I3C_I2C_SPEED_MAX = I3C_I2C_SPEED_FMPLUS
enumerator I3C_I2C_SPEED_INVALID
enum i3c_data_rate

I3C data rate.

I3C data transfer rate defined by the I3C specification.

Values:

enumerator I3C_DATA_RATE_SDR

Single Data Rate messaging

enumerator I3C_DATA_RATE_HDR_DDR

High Data Rate - Double Data Rate messaging

enumerator I3C_DATA_RATE_HDR_TSL

High Data Rate - Ternary Symbol Legacy-inclusive-Bus

enumerator I3C_DATA_RATE_HDR_TSP

High Data Rate - Ternary Symbol for Pure Bus

enumerator I3C_DATA_RATE_HDR_BT

High Data Rate - Bulk Transport

enumerator I3C_DATA_RATE_MAX = I3C_DATA_RATE_HDR_BT
enumerator I3C_DATA_RATE_INVALID
enum i3c_sdr_controller_error_codes

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.

Values:

enumerator I3C_ERROR_CE0

Transaction after sending CCC

enumerator I3C_ERROR_CE1

Monitoring Error

enumerator I3C_ERROR_CE2

No response to broadcast address (0x7E)

enumerator I3C_ERROR_CE3

Failed Controller Handoff

enumerator I3C_ERROR_CE_UNKNOWN

Unknown error (not official error code)

enumerator I3C_ERROR_CE_NONE

No error (not official error code)

enumerator I3C_ERROR_CE_MAX = I3C_ERROR_CE_UNKNOWN
enumerator I3C_ERROR_CE_INVALID
enum i3c_sdr_target_error_codes

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.

Values:

enumerator I3C_ERROR_TE0

Invalid Broadcast Address or Dynamic Address after DA assignment

enumerator I3C_ERROR_TE1

CCC Code

enumerator I3C_ERROR_TE2

Write Data

enumerator I3C_ERROR_TE3

Assigned Address during Dynamic Address Arbitration

enumerator I3C_ERROR_TE4

0x7E/R missing after RESTART during Dynamic Address Arbitration

enumerator I3C_ERROR_TE5

Transaction after detecting CCC

enumerator I3C_ERROR_TE6

Monitoring Error

enumerator I3C_ERROR_DBR

Dead Bus Recovery

enumerator I3C_ERROR_TE_UNKNOWN

Unknown error (not official error code)

enumerator I3C_ERROR_TE_NONE

No error (not official error code)

enumerator I3C_ERROR_TE_MAX = I3C_ERROR_TE_UNKNOWN
enumerator I3C_ERROR_TE_INVALID
enum i3c_config_type

Type of configuration being passed to configure function.

Values:

enumerator I3C_CONFIG_CONTROLLER
enumerator I3C_CONFIG_TARGET
enumerator I3C_CONFIG_CUSTOM

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.

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.

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.

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.

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.

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.

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.

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:

  • target – [in] The pointer of the device descriptor

  • addr – [out] Address to be assigned to target device.

Return values:

  • 0 – if successful.

  • -EINVAL – if the expected default address is already in use

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.

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,

If

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

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

If

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

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).

See also

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

Parameters:

  • addr_slots – [in] Pointer to address slots struct.

  • dev_list – [in] Pointer to the device list struct.

  • pid – [in] Provisioned ID of device to be assigned address.

  • must_match – [in] True if PID must match devices in the device list. False otherwise.

  • assigned_okay – [in] True if it is okay to return the address already assigned to the target matching the PID (pid).

  • target – [out] Store the pointer of the device descriptor if it matches the incoming PID (pid).

  • addr – [out] 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.

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

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.

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

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.

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

Parameters:

  • dev – [in] Pointer to controller device driver instance.

  • type – [in] Type of configuration parameters being passed in config.

  • config – [inout] Pointer to the configuration parameters.

Return values:

  • 0 – If successful.

  • -EIO – General Input/Output errors.

  • -ENOSYS – If not implemented.

static inline int i3c_recover_bus(const struct device *dev)

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.

int i3c_attach_i3c_device(struct i3c_device_desc *target)

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

int i3c_reattach_i3c_device(struct i3c_device_desc *target, uint8_t old_dyn_addr)

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

int i3c_detach_i3c_device(struct i3c_device_desc *target)

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

int i3c_attach_i2c_device(struct i3c_i2c_device_desc *target)

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

int i3c_detach_i2c_device(struct i3c_i2c_device_desc *target)

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

static inline int i3c_do_daa(const struct device *dev)

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.

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

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.

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.

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.

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

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.

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

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.

static inline int i3c_ibi_enable(struct i3c_device_desc *target)

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).

static inline int i3c_ibi_disable(struct i3c_device_desc *target)

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.

static inline int i3c_ibi_has_payload(struct i3c_device_desc *target)

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.

static inline int i3c_device_is_ibi_capable(struct i3c_device_desc *target)

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.

static inline 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.

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.

static inline 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.

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.

static inline 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.

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.

static inline 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.

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.

static inline 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.

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.

static inline 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.

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.

static inline 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.

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.

static inline 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.

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.

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.

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.

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

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.

int i3c_device_basic_info_get(struct i3c_device_desc *target)

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:

  • target – [inout] I3C target device descriptor.

Return values:

  • 0 – if successful.

  • -EIO – General Input/Output error.

struct i3c_msg
#include <i3c.h>

One I3C Message.

This defines one I3C message to transact on the I3C bus.

Note

Some of the configurations supported by this API may not be supported by specific SoC I3C hardware implementations, in particular features related to bus transactions intended to read or write data from different buffers within a single transaction. Invocations of i3c_transfer() may not indicate an error when an unsupported configuration is encountered. In some cases drivers will generate separate transactions for each message fragment, with or without presence of I3C_MSG_RESTART in flags.

Public Members

uint8_t *buf

Data buffer in bytes

uint32_t len

Length of buffer in bytes

uint8_t flags

Flags for this message

uint8_t hdr_mode

HDR mode (I3C_MSG_HDR_MODE*) for transfer if any I3C_MSG_HDR_* is set in flags.

Use SDR mode if none is set.

struct i3c_config_controller
#include <i3c.h>

Configuration parameters for I3C hardware to act as controller.

Public Members

bool is_secondary

True if the controller is to be the secondary controller of the bus. False to be the primary controller.

uint32_t i3c

SCL frequency (in Hz) for I3C transfers.

uint32_t i2c

SCL frequency (in Hz) for I2C transfers.

uint8_t supported_hdr

Bit mask of supported HDR modes (0 - 7).

This can be used to enable or disable HDR mode supported by the hardware at runtime.

struct i3c_config_custom
#include <i3c.h>

Custom I3C configuration parameters.

This can be used to configure the I3C hardware on parameters not covered by

See also

i3c_config_controller or

See also

i3c_config_target. Mostly used to configure vendor specific parameters of the I3C hardware.

Public Members

uint32_t id

ID of the configuration parameter.

uintptr_t val

Value of configuration parameter.

void *ptr

Pointer to configuration parameter.

Mainly used to pointer to a struct that the device driver understands.

struct i3c_device_id
#include <i3c.h>

Structure used for matching I3C devices.

Public Members

const uint64_t pid

Device Provisioned ID

struct i3c_device_desc
#include <i3c.h>

Structure describing a I3C target device.

Instances of this are passed to the I3C controller device APIs, for example:

  • i3c_device_register() to tell the controller of a target device.

  • i3c_transfers() to initiate data transfers between controller and target device.

Fields bus, pid and static_addr must be initialized by the module that implements the target device behavior prior to passing the object reference to I3C controller device APIs. static_addr can be zero if target device does not have static address.

Field node should not be initialized or modified manually.

Public Members

sys_snode_t node

Private, do not modify

const struct device *const bus

I3C bus to which this target device is attached

const struct device *const dev

Device driver instance of the I3C device

const uint64_t pid

Device Provisioned ID

const uint8_t static_addr

Static address for this target device.

0 if static address is not being used, and only dynamic address is used. This means that the target device must go through ENTDAA (Dynamic Address Assignment) to get a dynamic address before it can communicate with the controller. This means SETAASA and SETDASA CCC cannot be used to set dynamic address on the target device (as both are to tell target device to use static address as dynamic address).

const uint8_t init_dynamic_addr

Initial dynamic address.

This is specified in the device tree property “assigned-address” to indicate the desired dynamic address during address assignment (SETDASA and ENTDAA).

0 if there is no preference.

uint8_t dynamic_addr

Dynamic Address for this target device used for communication.

This is to be set by the controller driver in one of the following situations:

  • During Dynamic Address Assignment (during ENTDAA)

  • Reset Dynamic Address Assignment (RSTDAA)

  • Set All Addresses to Static Addresses (SETAASA)

  • Set New Dynamic Address (SETNEWDA)

  • Set Dynamic Address from Static Address (SETDASA)

0 if address has not been assigned.

uint8_t group_addr

Group address for this target device. Set during:

  • Reset Group Address(es) (RSTGRPA)

  • Set Group Address (SETGRPA)

0 if group address has not been assigned.

uint8_t bcr

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.

uint8_t dcr

Device Characteristic Register (DCR)

Describes the type of device. Refer to official documentation on what this number means.

uint8_t maxrd

Maximum Read Speed

uint8_t maxwr

Maximum Write Speed

uint32_t max_read_turnaround

Maximum Read turnaround time in microseconds.

uint16_t mrl

Maximum Read Length

uint16_t mwl

Maximum Write Length

uint8_t max_ibi

Maximum IBI Payload Size. Valid only if BCR[2] is 1.

void *controller_priv

Private data by the controller to aid in transactions. Do not modify.

i3c_target_ibi_cb_t ibi_cb

In-Band Interrupt (IBI) callback.

struct i3c_i2c_device_desc
#include <i3c.h>

Structure describing a I2C device on I3C bus.

Instances of this are passed to the I3C controller device APIs, for example: () i3c_i2c_device_register() to tell the controller of an I2C device. () i3c_i2c_transfers() to initiate data transfers between controller and I2C device.

Fields other than node must be initialized by the module that implements the device behavior prior to passing the object reference to I3C controller device APIs.

Public Members

sys_snode_t node

Private, do not modify

const struct device *bus

I3C bus to which this I2C device is attached

const uint16_t addr

Static address for this I2C device.

const uint8_t 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.

void *controller_priv

Private data by the controller to aid in transactions. Do not modify.

struct i3c_dev_attached_list
#include <i3c.h>

Structure for describing attached devices for a controller.

This contains slists of attached I3C and I2C devices.

This is a helper struct that can be used by controller device driver to aid in device management.

Public Members

struct i3c_addr_slots addr_slots

Address slots:

  • Aid in dynamic address assignment.

  • Quick way to find out if a target address is a I3C or I2C device.

sys_slist_t i3c

Linked list of attached I3C devices.

sys_slist_t i2c

Linked list of attached I2C devices.

struct i3c_dev_list
#include <i3c.h>

Structure for describing known devices for a controller.

This contains arrays of known I3C and I2C devices.

This is a helper struct that can be used by controller device driver to aid in device management.

Public Members

struct i3c_device_desc *const i3c

Pointer to array of known I3C devices.

struct i3c_i2c_device_desc *const i2c

Pointer to array of known I2C devices.

const uint8_t num_i3c

Number of I3C devices in array.

const uint8_t num_i2c

Number of I2C devices in array.

struct i3c_driver_config
#include <i3c.h>

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.

Public Members

struct i3c_dev_list dev_list

I3C/I2C device list struct.

struct i3c_driver_data
#include <i3c.h>

This structure is common to all I3C drivers and is expected to be the first element in the driver’s struct driver_data declaration.

Public Members

struct i3c_config_controller ctrl_config

Controller Configuration

struct i3c_dev_attached_list attached_dev

Attached I3C/I2C devices and addresses

group i3c_ccc

I3C Common Command Codes.

Defines

I3C_CCC_BROADCAST_MAX_ID

Maximum CCC ID for broadcast

I3C_CCC_ENEC(broadcast)

Enable Events Command

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_DISEC(broadcast)

Disable Events Command

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_ENTAS(as, broadcast)

Enter Activity State

Parameters:

  • as – Desired activity state

  • broadcast – True if broadcast, false if direct.

I3C_CCC_ENTAS0(broadcast)

Enter Activity State 0

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_ENTAS1(broadcast)

Enter Activity State 1

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_ENTAS2(broadcast)

Enter Activity State 2

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_ENTAS3(broadcast)

Enter Activity State 3

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_RSTDAA

Reset Dynamic Address Assignment (Broadcast)

I3C_CCC_ENTDAA

Enter Dynamic Address Assignment (Broadcast)

I3C_CCC_DEFTGTS

Define List of Targets (Broadcast)

I3C_CCC_SETMWL(broadcast)

Set Max Write Length (Broadcast or Direct)

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_SETMRL(broadcast)

Set Max Read Length (Broadcast or Direct)

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_ENTTM

Enter Test Mode (Broadcast)

I3C_CCC_SETBUSCON

Set Bus Context (Broadcast)

I3C_CCC_ENDXFER(broadcast)

Data Transfer Ending Procedure Control

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_ENTHDR(x)

Enter HDR Mode (HDR-DDR) (Broadcast)

I3C_CCC_ENTHDR0

Enter HDR Mode 0 (HDR-DDR) (Broadcast)

I3C_CCC_ENTHDR1

Enter HDR Mode 1 (HDR-TSP) (Broadcast)

I3C_CCC_ENTHDR2

Enter HDR Mode 2 (HDR-TSL) (Broadcast)

I3C_CCC_ENTHDR3

Enter HDR Mode 3 (HDR-BT) (Broadcast)

I3C_CCC_ENTHDR4

Enter HDR Mode 4 (Broadcast)

I3C_CCC_ENTHDR5

Enter HDR Mode 5 (Broadcast)

I3C_CCC_ENTHDR6

Enter HDR Mode 6 (Broadcast)

I3C_CCC_ENTHDR7

Enter HDR Mode 7 (Broadcast)

I3C_CCC_SETXTIME(broadcast)

Exchange Timing Information (Broadcast or Direct)

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_SETAASA

Set All Addresses to Static Addresses (Broadcast)

I3C_CCC_RSTACT(broadcast)

Target Reset Action

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_DEFGRPA

Define List of Group Address (Broadcast)

I3C_CCC_RSTGRPA(broadcast)

Reset Group Address

Parameters:

  • broadcast – True if broadcast, false if direct.

I3C_CCC_MLANE(broadcast)

Multi-Lane Data Transfer Control (Broadcast)

I3C_CCC_VENDOR(broadcast, id)

Vendor/Standard Extension

Parameters:

  • broadcast – True if broadcast, false if direct.

  • id – Extension ID.

I3C_CCC_SETDASA

Set Dynamic Address from Static Address (Direct)

I3C_CCC_SETNEWDA

Set New Dynamic Address (Direct)

I3C_CCC_GETMWL

Get Max Write Length (Direct)

I3C_CCC_GETMRL

Get Max Read Length (Direct)

I3C_CCC_GETPID

Get Provisioned ID (Direct)

I3C_CCC_GETBCR

Get Bus Characteristics Register (Direct)

I3C_CCC_GETDCR

Get Device Characteristics Register (Direct)

I3C_CCC_GETSTATUS

Get Device Status (Direct)

I3C_CCC_GETACCCR

Get Accept Controller Role (Direct)

I3C_CCC_SETBRGTGT

Set Bridge Targets (Direct)

I3C_CCC_GETMXDS

Get Max Data Speed (Direct)

I3C_CCC_GETCAPS

Get Optional Feature Capabilities (Direct)

I3C_CCC_SETROUTE

Set Route (Direct)

I3C_CCC_D2DXFER

Device to Device(s) Tunneling Control (Direct)

I3C_CCC_GETXTIME

Get Exchange Timing Information (Direct)

I3C_CCC_SETGRPA

Set Group Address (Direct)

I3C_CCC_ENEC_EVT_ENINTR
I3C_CCC_ENEC_EVT_ENCR
I3C_CCC_ENEC_EVT_ENHJ
I3C_CCC_ENEC_EVT_ALL
I3C_CCC_DISEC_EVT_DISINTR
I3C_CCC_DISEC_EVT_DISCR
I3C_CCC_DISEC_EVT_DISHJ
I3C_CCC_DISEC_EVT_ALL
I3C_CCC_EVT_INTR
I3C_CCC_EVT_CR
I3C_CCC_EVT_HJ
I3C_CCC_EVT_ALL
I3C_CCC_GETSTATUS_PROTOCOL_ERR
I3C_CCC_GETSTATUS_ACTIVITY_MODE_SHIFT
I3C_CCC_GETSTATUS_ACTIVITY_MODE_MASK
I3C_CCC_GETSTATUS_ACTIVITY_MODE(status)
I3C_CCC_GETSTATUS_NUM_INT_SHIFT
I3C_CCC_GETSTATUS_NUM_INT_MASK
I3C_CCC_GETSTATUS_NUM_INT(status)
I3C_CCC_GETSTATUS_PRECR_DEEP_SLEEP_DETECTED
I3C_CCC_GETSTATUS_PRECR_HANDOFF_DELAY_NACK
I3C_CCC_GETMXDS_MAX_SDR_FSCL_MAX
I3C_CCC_GETMXDS_MAX_SDR_FSCL_8MHZ
I3C_CCC_GETMXDS_MAX_SDR_FSCL_6MHZ
I3C_CCC_GETMXDS_MAX_SDR_FSCL_4MHZ
I3C_CCC_GETMXDS_MAX_SDR_FSCL_2MHZ
I3C_CCC_GETMXDS_TSCO_8NS
I3C_CCC_GETMXDS_TSCO_9NS
I3C_CCC_GETMXDS_TSCO_10NS
I3C_CCC_GETMXDS_TSCO_11NS
I3C_CCC_GETMXDS_TSCO_12NS
I3C_CCC_GETMXDS_TSCO_GT_12NS
I3C_CCC_GETMXDS_MAXWR_DEFINING_BYTE_SUPPORT
I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_SHIFT
I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL_MASK
I3C_CCC_GETMXDS_MAXWR_MAX_SDR_FSCL(maxwr)
I3C_CCC_GETMXDS_MAXRD_W2R_PERMITS_STOP_BETWEEN
I3C_CCC_GETMXDS_MAXRD_TSCO_SHIFT
I3C_CCC_GETMXDS_MAXRD_TSCO_MASK
I3C_CCC_GETMXDS_MAXRD_TSCO(maxrd)
I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_SHIFT
I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL_MASK
I3C_CCC_GETMXDS_MAXRD_MAX_SDR_FSCL(maxrd)
I3C_CCC_GETMXDS_CRDHLY1_SET_BUS_ACT_STATE
I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_SHIFT
I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE_MASK
I3C_CCC_GETMXDS_CRDHLY1_CTRL_HANDOFF_ACT_STATE(crhdly1)
I3C_CCC_GETCAPS1_HDR_DDR
I3C_CCC_GETCAPS1_HDR_BT
I3C_CCC_GETCAPS1_HDR_MODE(x)
I3C_CCC_GETCAPS1_HDR_MODE0
I3C_CCC_GETCAPS1_HDR_MODE1
I3C_CCC_GETCAPS1_HDR_MODE2
I3C_CCC_GETCAPS1_HDR_MODE3
I3C_CCC_GETCAPS1_HDR_MODE4
I3C_CCC_GETCAPS1_HDR_MODE5
I3C_CCC_GETCAPS1_HDR_MODE6
I3C_CCC_GETCAPS1_HDR_MODE7
I3C_CCC_GETCAPS2_HDRDDR_WRITE_ABORT
I3C_CCC_GETCAPS2_HDRDDR_ABORT_CRC
I3C_CCC_GETCAPS2_GRPADDR_CAP_SHIFT
I3C_CCC_GETCAPS2_GRPADDR_CAP_MASK
I3C_CCC_GETCAPS2_GRPADDR_CAP(getcaps2)
I3C_CCC_GETCAPS2_SPEC_VER_SHIFT
I3C_CCC_GETCAPS2_SPEC_VER_MASK
I3C_CCC_GETCAPS2_SPEC_VER(getcaps2)
I3C_CCC_GETCAPS3_MLAME_SUPPORT
I3C_CCC_GETCAPS3_D2DXFER_SUPPORT
I3C_CCC_GETCAPS3_D3DXFER_IBI_CAPABLE
I3C_CCC_GETCAPS3_GETCAPS_DEFINING_BYTE_SUPPORT
I3C_CCC_GETCAPS3_GETSTATUS_DEFINING_BYTE_SUPPORT
I3C_CCC_GETCAPS3_HDRBT_CRC32_SUPPORT
I3C_CCC_GETCAPS3_IBI_MDR_PENDING_READ_NOTIFICATION

Enums

enum i3c_ccc_getstatus_fmt

Indicate which format of GETSTATUS to use.

Values:

enumerator GETSTATUS_FORMAT_1
enumerator GETSTATUS_FORMAT_2
enum i3c_ccc_getstatus_defbyte

Values:

enumerator GETSTATUS_FORMAT_2_TGTSTAT = 0x00U
enumerator GETSTATUS_FORMAT_2_PRECR = 0x91U
enumerator GETSTATUS_FORMAT_2_INVALID = 0x100U
enum i3c_ccc_rstact_defining_byte

Values:

enumerator I3C_CCC_RSTACT_NO_RESET = 0x00U
enumerator I3C_CCC_RSTACT_PERIPHERAL_ONLY = 0x01U
enumerator I3C_CCC_RSTACT_RESET_WHOLE_TARGET = 0x02U
enumerator I3C_CCC_RSTACT_DEBUG_NETWORK_ADAPTER = 0x03U
enumerator I3C_CCC_RSTACT_VIRTUAL_TARGET_DETECT = 0x04U

Functions

static inline bool i3c_ccc_is_payload_broadcast(const struct i3c_ccc_payload *payload)

Test if I3C CCC payload is for broadcast.

This tests if the CCC payload is for broadcast.

Parameters:

  • payload – [in] Pointer to the CCC payload.

Return values:

  • true – if payload target is broadcast

  • false – if payload target is direct

int i3c_ccc_do_getbcr(struct i3c_device_desc *target, struct i3c_ccc_getbcr *bcr)

Get BCR from a target.

Helper function to get BCR (Bus Characteristic Register) from target device.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • bcr – [out] Pointer to the BCR payload structure.

Returns:

int i3c_ccc_do_getdcr(struct i3c_device_desc *target, struct i3c_ccc_getdcr *dcr)

Get DCR from a target.

Helper function to get DCR (Device Characteristic Register) from target device.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • dcr – [out] Pointer to the DCR payload structure.

Returns:

int i3c_ccc_do_getpid(struct i3c_device_desc *target, struct i3c_ccc_getpid *pid)

Get PID from a target.

Helper function to get PID (Provisioned ID) from target device.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • pid – [out] Pointer to the PID payload structure.

Returns:

int i3c_ccc_do_rstact_all(const struct device *controller, enum i3c_ccc_rstact_defining_byte action)

Broadcast RSTACT to reset I3C Peripheral.

Helper function to broadcast Target Reset Action (RSTACT) to all connected targets to Reset the I3C Peripheral Only (0x01).

See also

i3c_do_ccc

Parameters:

  • controller – [in] Pointer to the controller device driver instance.

  • action – [in] What reset action to perform.

Returns:

int i3c_ccc_do_rstdaa_all(const struct device *controller)

Broadcast RSTDAA to reset dynamic addresses for all targets.

Helper function to reset dynamic addresses of all connected targets.

See also

i3c_do_ccc

Parameters:

  • controller – [in] Pointer to the controller device driver instance.

Returns:

int i3c_ccc_do_setdasa(const struct i3c_device_desc *target)

Set Dynamic Address from Static Address for a target.

Helper function to do SETDASA (Set Dynamic Address from Static Address) for a particular target.

Note this does not update target with the new dynamic address.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor where the device is configured with a static address.

Returns:

int i3c_ccc_do_setnewda(const struct i3c_device_desc *target, struct i3c_ccc_address new_da)

Set New Dynamic Address for a target.

Helper function to do SETNEWDA(Set New Dynamic Address) for a particular target.

Note this does not update target with the new dynamic address.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor where the device is configured with a static address.

  • new_da – [in] Pointer to the new_da struct.

Returns:

int i3c_ccc_do_events_all_set(const struct device *controller, bool enable, struct i3c_ccc_events *events)

Broadcast ENEC/DISEC to enable/disable target events.

Helper function to broadcast Target Events Command to enable or disable target events (ENEC/DISEC).

See also

i3c_do_ccc

Parameters:

  • controller – [in] Pointer to the controller device driver instance.

  • enable – [in] ENEC if true, DISEC if false.

  • events – [in] Pointer to the event struct.

Returns:

int i3c_ccc_do_events_set(struct i3c_device_desc *target, bool enable, struct i3c_ccc_events *events)

Direct CCC ENEC/DISEC to enable/disable target events.

Helper function to send Target Events Command to enable or disable target events (ENEC/DISEC) on a single target.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • enable – [in] ENEC if true, DISEC if false.

  • events – [in] Pointer to the event struct.

Returns:

int i3c_ccc_do_setmwl_all(const struct device *controller, const struct i3c_ccc_mwl *mwl)

Broadcast SETMWL to Set Maximum Write Length.

Helper function to do SETMWL (Set Maximum Write Length) to all connected targets.

See also

i3c_do_ccc

Parameters:

  • controller – [in] Pointer to the controller device driver instance.

  • mwl – [in] Pointer to SETMWL payload.

Returns:

int i3c_ccc_do_setmwl(const struct i3c_device_desc *target, const struct i3c_ccc_mwl *mwl)

Single target SETMWL to Set Maximum Write Length.

Helper function to do SETMWL (Set Maximum Write Length) to one target.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • mwl – [in] Pointer to SETMWL payload.

Returns:

int i3c_ccc_do_getmwl(const struct i3c_device_desc *target, struct i3c_ccc_mwl *mwl)

Single target GETMWL to Get Maximum Write Length.

Helper function to do GETMWL (Get Maximum Write Length) of one target.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • mwl – [out] Pointer to GETMWL payload.

Returns:

int i3c_ccc_do_setmrl_all(const struct device *controller, const struct i3c_ccc_mrl *mrl, bool has_ibi_size)

Broadcast SETMRL to Set Maximum Read Length.

Helper function to do SETMRL (Set Maximum Read Length) to all connected targets.

See also

i3c_do_ccc

Parameters:

  • controller – [in] Pointer to the controller device driver instance.

  • mrl – [in] Pointer to SETMRL payload.

  • has_ibi_size – [in] True if also sending the optional IBI payload size. False if not sending.

Returns:

int i3c_ccc_do_setmrl(const struct i3c_device_desc *target, const struct i3c_ccc_mrl *mrl)

Single target SETMRL to Set Maximum Read Length.

Helper function to do SETMRL (Set Maximum Read Length) to one target.

Note this uses the BCR of the target to determine whether to send the optional IBI payload size.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • mrl – [in] Pointer to SETMRL payload.

Returns:

int i3c_ccc_do_getmrl(const struct i3c_device_desc *target, struct i3c_ccc_mrl *mrl)

Single target GETMRL to Get Maximum Read Length.

Helper function to do GETMRL (Get Maximum Read Length) of one target.

Note this uses the BCR of the target to determine whether to send the optional IBI payload size.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • mrl – [out] Pointer to GETMRL payload.

Returns:

int i3c_ccc_do_getstatus(const struct i3c_device_desc *target, union i3c_ccc_getstatus *status, enum i3c_ccc_getstatus_fmt fmt, enum i3c_ccc_getstatus_defbyte defbyte)

Single target GETSTATUS to Get Target Status.

Helper function to do GETSTATUS (Get Target Status) of one target.

Note this uses the BCR of the target to determine whether to send the optional IBI payload size.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • status – [out] Pointer to GETSTATUS payload.

  • fmt – [in] Which GETSTATUS to use.

  • defbyte – [in] Defining Byte if using format 2.

Returns:

static inline int i3c_ccc_do_getstatus_fmt1(const struct i3c_device_desc *target, union i3c_ccc_getstatus *status)

Single target GETSTATUS to Get Target Status (Format 1).

Helper function to do GETSTATUS (Get Target Status, format 1) of one target.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • status – [out] Pointer to GETSTATUS payload.

Returns:

static inline int i3c_ccc_do_getstatus_fmt2(const struct i3c_device_desc *target, union i3c_ccc_getstatus *status, enum i3c_ccc_getstatus_defbyte defbyte)

Single target GETSTATUS to Get Target Status (Format 2).

Helper function to do GETSTATUS (Get Target Status, format 2) of one target.

See also

i3c_do_ccc

Parameters:

  • target – [in] Pointer to the target device descriptor.

  • status – [out] Pointer to GETSTATUS payload.

  • defbyte – [in] Defining Byte for GETSTATUS format 2.

Returns:

struct i3c_ccc_target_payload
#include <ccc.h>

Payload structure for Direct CCC to one target.

Public Members

uint8_t addr

Target address

uint8_t rnw

0 for Write, 1 for Read

uint8_t *data

  • For Write CCC, pointer to the byte array of data to be sent, which may contain the Sub-Command Byte and additional data.

  • For Read CCC, pointer to the byte buffer for data to be read into.

size_t data_len

Length in bytes for data.

struct i3c_ccc_payload
#include <ccc.h>

Payload structure for one CCC transaction.

Public Members

uint8_t id

The CCC ID (I3C_CCC_*).

uint8_t *data

Pointer to byte array of data for this CCC.

This is the bytes following the CCC command in CCC frame. Set to NULL if no associated data.

size_t data_len

Length in bytes for optional data array.

struct i3c_ccc_target_payload *payloads

Array of struct i3c_ccc_target_payload.

Each element describes the target and associated payloads for this CCC.

Use with Direct CCC.

size_t num_targets

Number of targets

struct i3c_ccc_events
#include <ccc.h>

Payload for ENEC/DISEC CCC (Target Events Command).

Public Members

uint8_t events

Event byte:

  • Bit[0]: ENINT/DISINT:

    • Target Interrupt Requests

  • Bit[1]: ENCR/DISCR:

    • Controller Role Requests

  • Bit[3]: ENHJ/DISHJ:

    • Hot-Join Event

struct i3c_ccc_mwl
#include <ccc.h>

Payload for SETMWL/GETMWL CCC (Set/Get Maximum Write Length).

Note

For drivers and help functions, the raw data coming back from target device is in big endian. This needs to be translated back to CPU endianness before passing back to function caller.

Public Members

uint16_t len

Maximum Write Length

struct i3c_ccc_mrl
#include <ccc.h>

Payload for SETMRL/GETMRL CCC (Set/Get Maximum Read Length).

Note

For drivers and help functions, the raw data coming back from target device is in big endian. This needs to be translated back to CPU endianness before passing back to function caller.

Public Members

uint16_t len

Maximum Read Length

uint8_t ibi_len

Optional IBI Payload Size

struct i3c_ccc_deftgts_active_controller
#include <ccc.h>

The active controller part of payload for DEFTGTS CCC.

This is used by DEFTGTS (Define List of Targets) CCC to describe the active controller on the I3C bus.

Public Members

uint8_t addr

Dynamic Address of Active Controller

uint8_t dcr

Device Characteristic Register of Active Controller

uint8_t bcr

Bus Characteristic Register of Active Controller

uint8_t static_addr

Static Address of Active Controller

struct i3c_ccc_deftgts_target
#include <ccc.h>

The target device part of payload for DEFTGTS CCC.

This is used by DEFTGTS (Define List of Targets) CCC to describe the existing target devices on the I3C bus.

Public Members

uint8_t addr

Dynamic Address of a target device, or a group address

uint8_t dcr

Device Characteristic Register of a I3C target device or a group.

uint8_t lvr

Legacy Virtual Register for legacy I2C device.

uint8_t bcr

Bus Characteristic Register of a target device or a group

uint8_t static_addr

Static Address of a target device or a group

struct i3c_ccc_deftgts
#include <ccc.h>

Payload for DEFTGTS CCC (Define List of Targets).

Note

i3c_ccc_deftgts_target is an array of targets, where the number of elements is dependent on the number of I3C targets on the bus. Please have enough space for both read and write of this CCC.

Public Members

struct i3c_ccc_deftgts_active_controller active_controller

Data describing the active controller

struct i3c_ccc_deftgts_target targets[]

Data describing the target(s) on the bus

struct i3c_ccc_address
#include <ccc.h>

Payload for a single device address.

This is used for:

  • SETDASA (Set Dynamic Address from Static Address)

  • SETNEWDA (Set New Dynamic Address)

  • SETGRPA (Set Group Address)

  • GETACCCR (Get Accept Controller Role)

Note that the target address is encoded within struct i3c_ccc_target_payload instead of being encoded in this payload.

Public Members

uint8_t addr

  • For SETDASA, Static Address to be assigned as Dynamic Address.

  • For SETNEWDA, new Dynamic Address to be assigned.

  • For SETGRPA, new Group Address to be set.

  • For GETACCCR, the correct address of Secondary Controller.

Note

For SETDATA, SETNEWDA and SETGRAP, the address is left-shift by 1, and bit[0] is always 0.

Note

Fpr SET GETACCCR, the address is left-shift by 1, and bit[0] is the calculated odd parity bit.

struct i3c_ccc_getpid
#include <ccc.h>

Payload for GETPID CCC (Get Provisioned ID).

Public Members

uint8_t pid[6]

48-bit Provisioned ID.

Note

Data is big-endian where first byte is MSB.

struct i3c_ccc_getbcr
#include <ccc.h>

Payload for GETBCR CCC (Get Bus Characteristics Register).

Public Members

uint8_t bcr

Bus Characteristics Register

struct i3c_ccc_getdcr
#include <ccc.h>

Payload for GETDCR CCC (Get Device Characteristics Register).

Public Members

uint8_t dcr

Device Characteristics Register

union i3c_ccc_getstatus
#include <ccc.h>

Payload for GETSTATUS CCC (Get Device Status).

Public Members

uint16_t status

Device Status

  • Bit[15:8]: Reserved.

  • Bit[7:6]: Activity Mode.

  • Bit[5]: Protocol Error.

  • Bit[4]: Reserved.

  • Bit[3:0]: Number of Pending Interrupts.

Note

For drivers and help functions, the raw data coming back from target device is in big endian. This needs to be translated back to CPU endianness before passing back to function caller.

struct i3c_ccc_getstatus.[anonymous] fmt1
uint16_t tgtstat

Defining Byte 0x00: TGTSTAT

See also

i3c_ccc_getstatus::fmt1::status

uint16_t precr

Defining Byte 0x91: PRECR

  • Bit[15:8]: Vendor Reserved

  • Bit[7:2]: Reserved

  • Bit[1]: Handoff Delay NACK

  • Bit[0]: Deep Sleep Detected

Note

For drivers and help functions, the raw data coming back from target device is in big endian. This needs to be translated back to CPU endianness before passing back to function caller.

uint16_t raw_u16
union i3c_ccc_getstatus.[anonymous] fmt2
struct i3c_ccc_setbrgtgt_tgt
#include <ccc.h>

One Bridged Target for SETBRGTGT payload.

Public Members

uint8_t addr

Dynamic address of the bridged target.

Note

The address is left-shift by 1, and bit[0] is always 0.

uint16_t id

16-bit ID for the bridged target.

Note

For drivers and help functions, the raw data coming back from target device is in big endian. This needs to be translated back to CPU endianness before passing back to function caller.

struct i3c_ccc_setbrgtgt
#include <ccc.h>

Payload for SETBRGTGT CCC (Set Bridge Targets).

Note that the bridge target address is encoded within struct i3c_ccc_target_payload instead of being encoded in this payload.

Public Members

uint8_t count

Number of bridged targets

struct i3c_ccc_setbrgtgt_tgt targets[]

Array of bridged targets

union i3c_ccc_getmxds
#include <ccc.h>

Payload for GETMXDS CCC (Get Max Data Speed).

Note

This is only for GETMXDS Format 1 and Format 2.

Public Members

uint8_t maxwr

maxWr

uint8_t maxrd

maxRd

struct i3c_ccc_getmxds.[anonymous] fmt1
uint8_t maxrdturn[3]

Maximum Read Turnaround Time in microsecond.

This is in little-endian where first byte is LSB.

struct i3c_ccc_getmxds.[anonymous] fmt2
uint8_t wrrdturn

Defining Byte 0x00: WRRDTURN

See also

i3c_ccc_getmxds::fmt2

uint8_t crhdly1

Defining Byte 0x91: CRHDLY

  • Bit[2]: Set Bus Actibity State

  • Bit[1:0]: Controller Handoff Activity State

struct i3c_ccc_getmxds.[anonymous] fmt3
struct i3c_ccc_getcaps
#include <ccc.h>

Payload for GETCAPS CCC (Get Optional Feature Capabilities).

Note

Only support GETCAPS Format 1.

Public Members

uint8_t getcaps[4]

GETCAP[1-4] bytes.

group i3c_addresses

I3C Address-related Helper Code.

Defines

I3C_BROADCAST_ADDR
I3C_MAX_ADDR

Enums

enum i3c_addr_slot_status

Values:

enumerator I3C_ADDR_SLOT_STATUS_FREE = 0U
enumerator I3C_ADDR_SLOT_STATUS_RSVD
enumerator I3C_ADDR_SLOT_STATUS_I3C_DEV
enumerator I3C_ADDR_SLOT_STATUS_I2C_DEV
enumerator I3C_ADDR_SLOT_STATUS_MASK = 0x03U

Functions

int i3c_addr_slots_init(const struct device *dev)

Initialize the I3C address slots struct.

This clears out the assigned address bits, and set the reserved address bits according to the I3C specification.

Parameters:

  • dev – Pointer to controller device driver instance.

Return values:

  • 0 – if successful.

  • -EINVAL – if duplicate addresses.

void i3c_addr_slots_set(struct i3c_addr_slots *slots, uint8_t dev_addr, enum i3c_addr_slot_status status)

Set the address status of a device.

Parameters:

  • slots – Pointer to the address slots structure.

  • dev_addr – Device address.

  • status – New status for the address dev_addr.

enum i3c_addr_slot_status i3c_addr_slots_status(struct i3c_addr_slots *slots, uint8_t dev_addr)

Get the address status of a device.

Parameters:

  • slots – Pointer to the address slots structure.

  • dev_addr – Device address.

Returns:

Address status for the address dev_addr.

bool i3c_addr_slots_is_free(struct i3c_addr_slots *slots, uint8_t dev_addr)

Check if the address is free.

Parameters:

  • slots – Pointer to the address slots structure.

  • dev_addr – Device address.

Return values:

  • true – if address is free.

  • false – if address is not free.

uint8_t i3c_addr_slots_next_free_find(struct i3c_addr_slots *slots)

Find the next free address.

This can be used to find the next free address that can be assigned to a new device.

Parameters:

  • slots – Pointer to the address slots structure.

Returns:

The next free address, or 0 if none found.

static inline void i3c_addr_slots_mark_free(struct i3c_addr_slots *addr_slots, uint8_t addr)

Mark the address as free (not used) in device list.

Parameters:

  • addr_slots – Pointer to the address slots struct.

  • addr – Device address.

static inline void i3c_addr_slots_mark_rsvd(struct i3c_addr_slots *addr_slots, uint8_t addr)

Mark the address as reserved in device list.

Parameters:

  • addr_slots – Pointer to the address slots struct.

  • addr – Device address.

static inline void i3c_addr_slots_mark_i3c(struct i3c_addr_slots *addr_slots, uint8_t addr)

Mark the address as I3C device in device list.

Parameters:

  • addr_slots – Pointer to the address slots struct.

  • addr – Device address.

static inline void i3c_addr_slots_mark_i2c(struct i3c_addr_slots *addr_slots, uint8_t addr)

Mark the address as I2C device in device list.

Parameters:

  • addr_slots – Pointer to the address slots struct.

  • addr – Device address.

struct i3c_addr_slots
#include <addresses.h>

Structure to keep track of addresses on I3C bus.

group i3c_target_device

I3C Target Device API.

Functions

static inline int i3c_target_tx_write(const struct device *dev, uint8_t *buf, uint16_t len)

Writes to the Target’s TX FIFO.

Write to the TX FIFO dev I3C bus driver using the provided buffer and length. Some I3C targets will NACK read requests until data is written to the TX FIFO. This function will write as much as it can to the FIFO return the total number of bytes written. It is then up to the application to utalize the target callbacks to write the remaining data. Negative returns indicate error.

Most of the existing hardware allows simultaneous support for master and target mode. This is however not guaranteed.

Parameters:

  • dev – Pointer to the device structure for an I3C controller driver configured in target mode.

  • buf – Pointer to the buffer

  • len – Length of the buffer

Return values:

  • Total – number of bytes written

  • -ENOTSUP – Not in Target Mode

  • -ENOSPC – No space in Tx FIFO

  • -ENOSYS – If target mode is not implemented

static inline int i3c_target_register(const struct device *dev, struct i3c_target_config *cfg)

Registers the provided config as target device of a controller.

Enable I3C target mode for the dev I3C bus driver using the provided config struct (cfg) containing the functions and parameters to send bus events. The I3C target will be registered at the address provided as i3c_target_config::address struct member. Any I3C bus events related to the target mode will be passed onto I3C target device driver via a set of callback functions provided in the ‘callbacks’ struct member.

Most of the existing hardware allows simultaneous support for master and target mode. This is however not guaranteed.

Parameters:

  • dev – Pointer to the device structure for an I3C controller driver configured in target mode.

  • cfg – Config struct with functions and parameters used by the I3C target driver to send bus events

Return values:

  • 0 – Is successful

  • -EINVAL – If parameters are invalid

  • -EIO – General input / output error.

  • -ENOSYS – If target mode is not implemented

static inline int i3c_target_unregister(const struct device *dev, struct i3c_target_config *cfg)

Unregisters the provided config as target device.

This routine disables I3C target mode for the dev I3C bus driver using the provided config struct (cfg) containing the functions and parameters to send bus events.

Parameters:

  • dev – Pointer to the device structure for an I3C controller driver configured in target mode.

  • cfg – Config struct with functions and parameters used by the I3C target driver to send bus events

Return values:

  • 0 – Is successful

  • -EINVAL – If parameters are invalid

  • -ENOSYS – If target mode is not implemented

struct i3c_config_target
#include <target_device.h>

Configuration parameters for I3C hardware to act as target device.

This can also be used to configure the controller if it is to act as a secondary controller on the bus.

Public Members

bool enable

If the hardware is to act as a target device on the bus.

uint8_t static_addr

I3C target address.

Used used when operates as secondary controller or as a target device.

uint64_t pid

Provisioned ID.

bool pid_random

True if lower 32-bit of Provisioned ID is random.

This sets the bit 32 of Provisioned ID which means the lower 32-bit is random value.

uint8_t bcr

Bus Characteristics Register (BCR).

uint8_t dcr

Device Characteristics Register (DCR).

uint16_t max_read_len

Maximum Read Length (MRL).

uint16_t max_write_len

Maximum Write Length (MWL).

uint8_t supported_hdr

Bit mask of supported HDR modes (0 - 7).

This can be used to enable or disable HDR mode supported by the hardware at runtime.

struct i3c_target_config
#include <target_device.h>

Structure describing a device that supports the I3C target API.

Instances of this are passed to the i3c_target_register() and i3c_target_unregister() functions to indicate addition and removal of a target device, respective.

Fields other than node must be initialized by the module that implements the device behavior prior to passing the object reference to i3c_target_register().

Public Members

sys_snode_t node

Private, do not modify

uint8_t flags

Flags for the target device defined by I3C_TARGET_FLAGS_* constants.

uint8_t address

Address for this target device

const struct i3c_target_callbacks *callbacks

Callback functions

struct i3c_target_callbacks
#include <target_device.h>

Public Members

int (*write_requested_cb)(struct i3c_target_config *config)

Function called when a write to the device is initiated.

This function is invoked by the controller when the bus completes a start condition for a write operation to the address associated with a particular device.

A success return shall cause the controller to ACK the next byte received. An error return shall cause the controller to NACK the next byte received.

Param config:

Configuration structure associated with the device to which the operation is addressed.

Return:

0 if the write is accepted, or a negative error code.

int (*write_received_cb)(struct i3c_target_config *config, uint8_t val)

Function called when a write to the device is continued.

This function is invoked by the controller when it completes reception of a byte of data in an ongoing write operation to the device.

A success return shall cause the controller to ACK the next byte received. An error return shall cause the controller to NACK the next byte received.

Param config:

Configuration structure associated with the device to which the operation is addressed.

Param val:

the byte received by the controller.

Return:

0 if more data can be accepted, or a negative error code.

int (*read_requested_cb)(struct i3c_target_config *config, uint8_t *val)

Function called when a read from the device is initiated.

This function is invoked by the controller when the bus completes a start condition for a read operation from the address associated with a particular device.

The value returned in val will be transmitted. A success return shall cause the controller to react to additional read operations. An error return shall cause the controller to ignore bus operations until a new start condition is received.

Param config:

Configuration structure associated with the device to which the operation is addressed.

Param val:

Pointer to storage for the first byte of data to return for the read request.

Return:

0 if more data can be requested, or a negative error code.

int (*read_processed_cb)(struct i3c_target_config *config, uint8_t *val)

Function called when a read from the device is continued.

This function is invoked by the controller when the bus is ready to provide additional data for a read operation from the address associated with the device device.

The value returned in val will be transmitted. A success return shall cause the controller to react to additional read operations. An error return shall cause the controller to ignore bus operations until a new start condition is received.

Param config:

Configuration structure associated with the device to which the operation is addressed.

Param val:

Pointer to storage for the next byte of data to return for the read request.

Return:

0 if data has been provided, or a negative error code.

int (*stop_cb)(struct i3c_target_config *config)

Function called when a stop condition is observed after a start condition addressed to a particular device.

This function is invoked by the controller when the bus is ready to provide additional data for a read operation from the address associated with the device device. After the function returns the controller shall enter a state where it is ready to react to new start conditions.

Param config:

Configuration structure associated with the device to which the operation is addressed.

Return:

Ignored.

struct i3c_target_driver_api
#include <target_device.h>