I3C Transfer API. More...

Data Structures
struct	i3c_msg
	One I3C Message. More...

Macros
#define	I3C_MSG_WRITE (0U << 0U)
	Write message to I3C bus.

#define	I3C_MSG_READ BIT(0)
	Read message from I3C bus.

#define	I3C_MSG_STOP BIT(1)
	Send STOP after this message.

#define	I3C_MSG_RESTART BIT(2)
	RESTART I3C transaction for this message.

#define	I3C_MSG_HDR BIT(3)
	Transfer use HDR mode.

#define	I3C_MSG_NBCH BIT(4)
	Skip I3C broadcast header.

#define	I3C_MSG_HDR_MODE0 BIT(0)
	I3C HDR Mode 0.

#define	I3C_MSG_HDR_MODE1 BIT(1)
	I3C HDR Mode 1.

#define	I3C_MSG_HDR_MODE2 BIT(2)
	I3C HDR Mode 2.

#define	I3C_MSG_HDR_MODE3 BIT(3)
	I3C HDR Mode 3.

#define	I3C_MSG_HDR_MODE4 BIT(4)
	I3C HDR Mode 4.

#define	I3C_MSG_HDR_MODE5 BIT(5)
	I3C HDR Mode 5.

#define	I3C_MSG_HDR_MODE6 BIT(6)
	I3C HDR Mode 6.

#define	I3C_MSG_HDR_MODE7 BIT(7)
	I3C HDR Mode 7.

#define	I3C_MSG_HDR_DDR I3C_MSG_HDR_MODE0
	I3C HDR-DDR (Double Data Rate)

#define	I3C_MSG_HDR_TSP I3C_MSG_HDR_MODE1
	I3C HDR-TSP (Ternary Symbol Pure-bus)

#define	I3C_MSG_HDR_TSL I3C_MSG_HDR_MODE2
	I3C HDR-TSL (Ternary Symbol Legacy-inclusive-bus)

#define	I3C_MSG_HDR_BT I3C_MSG_HDR_MODE3
	I3C HDR-BT (Bulk Transport)

Functions
int	i3c_transfer (struct i3c_device_desc target, struct i3c_msg msgs, uint8_t num_msgs)
	Perform data transfer from the controller to a I3C target device.

static int	i3c_write (struct i3c_device_desc target, const uint8_t buf, uint32_t num_bytes)
	Write a set amount of data to an I3C target device.

static int	i3c_read (struct i3c_device_desc target, uint8_t buf, uint32_t num_bytes)
	Read a set amount of data from an I3C target device.

static int	i3c_write_read (struct i3c_device_desc target, const void write_buf, size_t num_write, void *read_buf, size_t num_read)
	Write then read data from an I3C target device.

static int	i3c_burst_read (struct i3c_device_desc target, uint8_t start_addr, uint8_t buf, uint32_t num_bytes)
	Read multiple bytes from an internal address of an I3C target device.

static int	i3c_burst_write (struct i3c_device_desc target, uint8_t start_addr, const uint8_t buf, uint32_t num_bytes)
	Write multiple bytes to an internal address of an I3C target device.

static int	i3c_reg_read_byte (struct i3c_device_desc target, uint8_t reg_addr, uint8_t value)
	Read internal register of an I3C target device.

static int	i3c_reg_write_byte (struct i3c_device_desc *target, uint8_t reg_addr, uint8_t value)
	Write internal register of an I3C target device.

static int	i3c_reg_update_byte (struct i3c_device_desc *target, uint8_t reg_addr, uint8_t mask, uint8_t value)
	Update internal register of an I3C target device.

void	i3c_dump_msgs (const char name, const struct i3c_msg msgs, uint8_t num_msgs, struct i3c_device_desc *target)
	Dump out an I3C message.

Detailed Description

I3C Transfer API.

Macro Definition Documentation

◆ I3C_MSG_HDR

#define I3C_MSG_HDR BIT(3)

#include <zephyr/drivers/i3c.h>

Transfer use HDR mode.

◆ I3C_MSG_HDR_BT

#define I3C_MSG_HDR_BT I3C_MSG_HDR_MODE3

#include <zephyr/drivers/i3c.h>

I3C HDR-BT (Bulk Transport)

◆ I3C_MSG_HDR_DDR

#define I3C_MSG_HDR_DDR I3C_MSG_HDR_MODE0

#include <zephyr/drivers/i3c.h>

I3C HDR-DDR (Double Data Rate)

◆ I3C_MSG_HDR_MODE0

#define I3C_MSG_HDR_MODE0 BIT(0)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 0.

◆ I3C_MSG_HDR_MODE1

#define I3C_MSG_HDR_MODE1 BIT(1)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 1.

◆ I3C_MSG_HDR_MODE2

#define I3C_MSG_HDR_MODE2 BIT(2)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 2.

◆ I3C_MSG_HDR_MODE3

#define I3C_MSG_HDR_MODE3 BIT(3)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 3.

◆ I3C_MSG_HDR_MODE4

#define I3C_MSG_HDR_MODE4 BIT(4)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 4.

◆ I3C_MSG_HDR_MODE5

#define I3C_MSG_HDR_MODE5 BIT(5)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 5.

◆ I3C_MSG_HDR_MODE6

#define I3C_MSG_HDR_MODE6 BIT(6)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 6.

◆ I3C_MSG_HDR_MODE7

#define I3C_MSG_HDR_MODE7 BIT(7)

#include <zephyr/drivers/i3c.h>

I3C HDR Mode 7.

◆ I3C_MSG_HDR_TSL

#define I3C_MSG_HDR_TSL I3C_MSG_HDR_MODE2

#include <zephyr/drivers/i3c.h>

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

◆ I3C_MSG_HDR_TSP

#define I3C_MSG_HDR_TSP I3C_MSG_HDR_MODE1

#include <zephyr/drivers/i3c.h>

I3C HDR-TSP (Ternary Symbol Pure-bus)

◆ I3C_MSG_NBCH

#define I3C_MSG_NBCH BIT(4)

#include <zephyr/drivers/i3c.h>

Skip I3C broadcast header.

Private Transfers only.

◆ I3C_MSG_READ

#define I3C_MSG_READ BIT(0)

#include <zephyr/drivers/i3c.h>

Read message from I3C bus.

◆ I3C_MSG_RESTART

#define I3C_MSG_RESTART BIT(2)

#include <zephyr/drivers/i3c.h>

RESTART I3C transaction for this message.

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

◆ I3C_MSG_STOP

#define I3C_MSG_STOP BIT(1)

#include <zephyr/drivers/i3c.h>

Send STOP after this message.

◆ I3C_MSG_WRITE

#define I3C_MSG_WRITE (0U << 0U)

#include <zephyr/drivers/i3c.h>

Write message to I3C bus.

Function Documentation

◆ i3c_burst_read()

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

inlinestatic

#include <zephyr/drivers/i3c.h>

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

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

Instances of this may be replaced by i3c_write_read().

Parameters

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

Return values

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

◆ i3c_burst_write()

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

inlinestatic

#include <zephyr/drivers/i3c.h>

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

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

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

Parameters

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

Return values

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

◆ i3c_dump_msgs()

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

#include <zephyr/drivers/i3c.h>

Dump out an I3C message.

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

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

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

Parameters

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

◆ i3c_read()

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

inlinestatic

#include <zephyr/drivers/i3c.h>

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

This routine reads a set amount of data synchronously.

Parameters

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

Return values

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

◆ i3c_reg_read_byte()

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

inlinestatic

#include <zephyr/drivers/i3c.h>

Read internal register of an I3C target device.

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

Parameters

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

Return values

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

◆ i3c_reg_update_byte()

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

inlinestatic

#include <zephyr/drivers/i3c.h>

Update internal register of an I3C target device.

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

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

Parameters

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

Return values

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

◆ i3c_reg_write_byte()

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

inlinestatic

#include <zephyr/drivers/i3c.h>

Write internal register of an I3C target device.

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

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

Parameters

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

Return values

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

◆ i3c_transfer()

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

#include <zephyr/drivers/i3c.h>

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

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

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

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

Parameters

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

Return values

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

◆ i3c_write()

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

inlinestatic

#include <zephyr/drivers/i3c.h>

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

This routine writes a set amount of data synchronously.

Parameters

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

Return values

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

◆ i3c_write_read()

static int i3c_write_read	(	struct i3c_device_desc *	target,
		const void *	write_buf,
		size_t	num_write,
		void *	read_buf,
		size_t	num_read
	)

inlinestatic

#include <zephyr/drivers/i3c.h>

Write then read data from an I3C target device.

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

Parameters

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

Return values

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

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ I3C_MSG_HDR

◆ I3C_MSG_HDR_BT

◆ I3C_MSG_HDR_DDR

◆ I3C_MSG_HDR_MODE0

◆ I3C_MSG_HDR_MODE1

◆ I3C_MSG_HDR_MODE2

◆ I3C_MSG_HDR_MODE3

◆ I3C_MSG_HDR_MODE4

◆ I3C_MSG_HDR_MODE5

◆ I3C_MSG_HDR_MODE6

◆ I3C_MSG_HDR_MODE7

◆ I3C_MSG_HDR_TSL

◆ I3C_MSG_HDR_TSP

◆ I3C_MSG_NBCH

◆ I3C_MSG_READ

◆ I3C_MSG_RESTART

◆ I3C_MSG_STOP

◆ I3C_MSG_WRITE

Function Documentation

◆ i3c_burst_read()

◆ i3c_burst_write()

◆ i3c_dump_msgs()

◆ i3c_read()

◆ i3c_reg_read_byte()

◆ i3c_reg_update_byte()

◆ i3c_reg_write_byte()

◆ i3c_transfer()

◆ i3c_write()

◆ i3c_write_read()