I3C Interface

Detailed Description

Interface for I3C.

Summary

The I3C interface provides APIs and definitions for I3C communication.

Data Structures
struct	i3c_device_status_t
struct	i3c_slave_info_t
struct	i3c_device_table_cfg_t
struct	i3c_device_cfg_t
struct	i3c_command_descriptor_t
struct	i3c_callback_args_t
struct	i3c_cfg_t
struct	i3c_api_t
struct	i3c_instance_t

Typedefs
typedef void	i3c_ctrl_t

Enumerations
enum	i3c_common_command_code_t
enum	i3c_event_t
enum	i3c_device_type_t
enum	i3c_device_protocol_t
enum	i3c_address_assignment_mode_t
enum	i3c_ibi_type_t

---

Data Structure Documentation

i3c_device_status_t

struct i3c_device_status_t

The current status of the slave device (See GETSTATUS in the MIPI I3C Specification v1.0).

Data Fields
uint8_t	pending_interrupt	Contains the interrupt number of any pending interrupt, or 0 if no interrupts are pending.
uint8_t	vendor_status	Reserved for vendor-specific meaning.

i3c_slave_info_t

struct i3c_slave_info_t

Device characteristics that define the I3C capabilities of a slave.

Data Fields
uint8_t	pid[6]	Provisional ID.
union i3c_slave_info_t	__unnamed__
uint8_t	dcr	Device Characteristics Register.

i3c_device_table_cfg_t

struct i3c_device_table_cfg_t

Structure for configuring an entry in the device table when the driver is in master mode (See i3c_api_t::masterDeviceTableSet).

Data Fields
uint8_t	static_address	I3C Static address / I2C address for this device.
uint8_t	dynamic_address	Dynamic address for the device. This address will be assigned during Dynamic Address Assignment.
i3c_device_protocol_t	device_protocol	The protocol used to communicate with this device (I3C / I2C Legacy).
bool	ibi_accept	Accept or reject IBI requests from this device.
bool	master_request_accept	Accept mastership requests from this device.
bool	ibi_payload	IBI requests from this device have a data payload. Note: When the device is configured using ENTDAA, the ibi_payload will automatically be updated based on the value of BCR.

i3c_device_cfg_t

struct i3c_device_cfg_t

Structure for configuring a slave address when the driver is in slave mode (See i3c_api_t::deviceCfgSet).

Data Fields
uint8_t	static_address	I3C Static address / I2C address for this device.
uint8_t	dynamic_address	Dynamic address for this device. Note that the dynamic address will automatically be updated when ENTDAA is completed.
i3c_slave_info_t	slave_info	PID, BCR, and DCR registers for the device (Slave mode only).

i3c_command_descriptor_t

struct i3c_command_descriptor_t

Descriptor for completing CCC transfers.

Data Fields
uint8_t	command_code	Common Command Code for the transfer.
uint8_t *	p_buffer	Buffer for reading or writing data.
uint32_t	length	Length of the data portion of the command.
bool	restart	If true, issue a repeated-start after the transfer is completed.
bool	rnw	Set to true if the command type is Direct Get.

i3c_callback_args_t

struct i3c_callback_args_t

Arguments that are passed to the user callback when an event occurs.

Data Fields
i3c_event_t	event	The type of event that has occurred.
uint32_t	event_status	Status flags associated with the event.
uint32_t	transfer_size	Number of bytes transferred.
i3c_slave_info_t const *	p_slave_info	A pointer to the Characteristics Registers read during ENTDAA.
uint8_t	dynamic_address	The dynamic address that was assigned to the slave during ENTDAA.
i3c_ibi_type_t	ibi_type	The type of IBI that has been received.
uint8_t	ibi_address	The address of the device that sent the IBI.
uint8_t	command_code	The command code of the received command.
void const *	p_context	User defined context.

i3c_cfg_t

struct i3c_cfg_t

User configuration structure, used in open function

Data Fields
uint32_t	channel
i3c_device_type_t	device_type
void(*	p_callback )(i3c_callback_args_t const *const p_args)
void const *	p_context
	Pointer to the user-provided context.
void const *	p_extend

Field Documentation

channel

uint32_t i3c_cfg_t::channel

Select a channel corresponding to the channel number of the hardware.

device_type

i3c_device_type_t i3c_cfg_t::device_type

The type of device.

p_callback

void(* i3c_cfg_t::p_callback) (i3c_callback_args_t const *const p_args)

Pointer to the user callback.

p_extend

void const* i3c_cfg_t::p_extend

Pointer to extended configuration.

i3c_api_t

struct i3c_api_t

I3C functions implemented at the HAL layer will follow this API.

Data Fields
fsp_err_t(*	open )(i3c_ctrl_t *const p_ctrl, i3c_cfg_t const *const p_cfg)
fsp_err_t(*	enable )(i3c_ctrl_t *const p_ctrl)
fsp_err_t(*	deviceCfgSet )(i3c_ctrl_t *const p_ctrl, i3c_device_cfg_t const *const p_device_cfg)
fsp_err_t(*	masterDeviceTableSet )(i3c_ctrl_t *const p_ctrl, uint32_t device_index, i3c_device_table_cfg_t const *const p_device_table_cfg)
fsp_err_t(*	deviceSelect )(i3c_ctrl_t *const p_ctrl, uint32_t device_index, uint32_t bitrate_mode)
fsp_err_t(*	dynamicAddressAssignmentStart )(i3c_ctrl_t *const p_ctrl, i3c_address_assignment_mode_t address_assignment_mode, uint32_t starting_device_index, uint32_t device_count)
fsp_err_t(*	slaveStatusSet )(i3c_ctrl_t *const p_ctrl, i3c_device_status_t device_status)
fsp_err_t(*	commandSend )(i3c_ctrl_t *const p_ctrl, i3c_command_descriptor_t *p_command_descriptor)
fsp_err_t(*	write )(i3c_ctrl_t *const p_ctrl, uint8_t const *const p_data, uint32_t length, bool restart)
fsp_err_t(*	read )(i3c_ctrl_t *const p_ctrl, uint8_t *const p_data, uint32_t length, bool restart)
fsp_err_t(*	ibiWrite )(i3c_ctrl_t *const p_ctrl, i3c_ibi_type_t ibi_type, uint8_t const *const p_data, uint32_t length)
fsp_err_t(*	ibiRead )(i3c_ctrl_t *const p_ctrl, uint8_t *const p_data, uint32_t length)
fsp_err_t(*	close )(i3c_ctrl_t *const p_ctrl)

Field Documentation

open

fsp_err_t(* i3c_api_t::open) (i3c_ctrl_t *const p_ctrl, i3c_cfg_t const *const p_cfg)

Initial configuration.

Parameters

[in]	p_ctrl	Pointer to control block. Must be declared by user. Elements set here.
[in]	p_cfg	Pointer to configuration structure. All elements of this structure must be set by user.

enable

fsp_err_t(* i3c_api_t::enable) (i3c_ctrl_t *const p_ctrl)

Enable the I3C device.

Parameters

[in]

p_ctrl

Control block set in i3c_api_t::open call for this instance.

deviceCfgSet

fsp_err_t(* i3c_api_t::deviceCfgSet) (i3c_ctrl_t *const p_ctrl, i3c_device_cfg_t const *const p_device_cfg)

Set the configuration of this device.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	p_device_cfg	Pointer to device configuration.

masterDeviceTableSet

fsp_err_t(* i3c_api_t::masterDeviceTableSet) (i3c_ctrl_t *const p_ctrl, uint32_t device_index, i3c_device_table_cfg_t const *const p_device_table_cfg)

Set the configuration for the device at the given index in the device table. The configuration will be used by transfers when it is selected by deviceSelect.

Note: This function is not used in slave mode.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	device_index	Index into the device table.
[in]	p_device_table_cfg	Pointer to the table settings for the entry in the master device table.

deviceSelect

fsp_err_t(* i3c_api_t::deviceSelect) (i3c_ctrl_t *const p_ctrl, uint32_t device_index, uint32_t bitrate_mode)

In master mode, select the device for the next transfer.

Note: This function is not used in slave mode.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	device_index	Index into the device table.
[in]	bitrate_setting	The bitrate settings for the selected device.

dynamicAddressAssignmentStart

fsp_err_t(* i3c_api_t::dynamicAddressAssignmentStart) (i3c_ctrl_t *const p_ctrl, i3c_address_assignment_mode_t address_assignment_mode, uint32_t starting_device_index, uint32_t device_count)

Start Dynamic Address Assignment by sending either the ENTDAA or SETDASA command See i3c_address_assignment_mode_t for more information.

Note: This function is not used in slave mode.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	address_assignment_mode	The command to use for Dynamic Address Assignment.
[in]	starting_device_index	The device index that will be used to assign the first device during Dynamic Address Assignment.
[in]	device_count	The number of devices to assign (Only used with I3C_ADDRESS_ASSIGNMENT_MODE_ENTDAA).

slaveStatusSet

fsp_err_t(* i3c_api_t::slaveStatusSet) (i3c_ctrl_t *const p_ctrl, i3c_device_status_t device_status)

Set the status returned to the master in response to a GETSTATUS command.

Note: This function is not used in master mode.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	device_status	New status settings for responding to the GETSTATUS command code.

commandSend

fsp_err_t(* i3c_api_t::commandSend) (i3c_ctrl_t *const p_ctrl, i3c_command_descriptor_t *p_command_descriptor)

Send a broadcast or directed command to slave devices on the bus.

Note: This function is not used in slave mode.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	p_command_descriptor	A descriptor for executing the command.

write

fsp_err_t(* i3c_api_t::write) (i3c_ctrl_t *const p_ctrl, uint8_t const *const p_data, uint32_t length, bool restart)

In master mode: Start a write transfer. When the transfer is completed send a stop condition or a repeated-start. In slave mode: Set the write buffer and configure the number of bytes that will be transferred before the the transfer is ended by the slave via the 'T' bit or by the master issueing a stop condition.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	p_data	Pointer to a buffer to write.
[in]	length	Number of bytes to transfer.
[in]	restart	If true, issue a repeated-start after the transfer is completed (Master only).

read

fsp_err_t(* i3c_api_t::read) (i3c_ctrl_t *const p_ctrl, uint8_t *const p_data, uint32_t length, bool restart)

In master mode: Start a read transfer. When the transfer is completed, send a stop condition or a repeated-start. In slave mode: Set the read buffer for storing data read during the transfer. When the buffer is full, the application will receive a callback requesting a new read buffer. If no buffer is provided by the application, the driver will discard any remaining bytes read during the transfer.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	p_data	Pointer to a buffer to store the bytes read during the transfer.
[in]	length	Number of bytes to transfer.
[in]	restart	If true, issue a repeated-start after the transfer is completed (Master only).

ibiWrite

fsp_err_t(* i3c_api_t::ibiWrite) (i3c_ctrl_t *const p_ctrl, i3c_ibi_type_t ibi_type, uint8_t const *const p_data, uint32_t length)

Initiate an IBI write operation.

Note: This function is not used in master mode.

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	ibi_type	The type of In-Band Interrupt.
[in]	p_data	Pointer to a buffer to start the bytes read during the transfer.
[in]	length	Number of bytes to transfer.

ibiRead

fsp_err_t(* i3c_api_t::ibiRead) (i3c_ctrl_t *const p_ctrl, uint8_t *const p_data, uint32_t length)

Set the read buffer for storing received IBI data (This function is not used in slave mode).

Parameters

[in]	p_ctrl	Control block set in i3c_api_t::open call for this instance.
[in]	p_data	Pointer to a buffer to store the bytes read during the transfer.
[in]	length	Number of bytes to transfer.

close

fsp_err_t(* i3c_api_t::close) (i3c_ctrl_t *const p_ctrl)

Allows driver to be reconfigured and may reduce power consumption.

Parameters

[in]

p_ctrl

Control block set in i3c_api_t::open call for this instance.

i3c_instance_t

struct i3c_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
i3c_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
i3c_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
i3c_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

i3c_ctrl_t

typedef void i3c_ctrl_t

I3C control block. Allocate an instance specific control block to pass into the I3C API calls.

Enumeration Type Documentation

i3c_common_command_code_t

enum i3c_common_command_code_t

Common Command Codes defined by MIPI I3C Specification v1.1.

Enumerator
I3C_CCC_BROADCAST_ENEC	Enable Slave initiated events.
I3C_CCC_BROADCAST_DISEC	Disable Slave initiated events.
I3C_CCC_BROADCAST_ENTAS0	Enter Activity State 0.
I3C_CCC_BROADCAST_ENTAS1	Enter Activity State 1.
I3C_CCC_BROADCAST_ENTAS2	Enter Activity State 2.
I3C_CCC_BROADCAST_ENTAS3	Enter Activity State 3.
I3C_CCC_BROADCAST_RSTDAA	Reset Dynamic Address Assignment.
I3C_CCC_BROADCAST_ENTDAA	Enter Dynamic Address Assignment.
I3C_CCC_BROADCAST_DEFSVLS	Define List of Slaves.
I3C_CCC_BROADCAST_SETMWL	Set Max Write Length.
I3C_CCC_BROADCAST_SETMRL	Set Max Read Length.
I3C_CCC_BROADCAST_ENTTM	Enter Test Mode.
I3C_CCC_BROADCAST_ENTHDR0	Enter HDR Mode 0.
I3C_CCC_BROADCAST_ENTHDR1	Enter HDR Mode 1.
I3C_CCC_BROADCAST_ENTHDR2	Enter HDR Mode 2.
I3C_CCC_BROADCAST_ENTHDR3	Enter HDR Mode 3.
I3C_CCC_BROADCAST_ENTHDR4	Enter HDR Mode 4 (Reserved for future definition).
I3C_CCC_BROADCAST_ENTHDR5	Enter HDR Mode 5 (Reserved for future definition).
I3C_CCC_BROADCAST_ENTHDR6	Enter HDR Mode 6 (Reserved for future definition).
I3C_CCC_BROADCAST_ENTHDR7	Enter HDR Mode 7 (Reserved for future definition).
I3C_CCC_BROADCAST_SETXTIME	Set Exchange Timing Info.
I3C_CCC_BROADCAST_SETAASA	Set All Addresses to Static Address.
I3C_CCC_DIRECT_ENEC	Enable Slave initiated events.
I3C_CCC_DIRECT_DISEC	Disable Slave initiated events.
I3C_CCC_DIRECT_ENTAS0	Enter Activity State 0.
I3C_CCC_DIRECT_ENTAS1	Enter Activity State 1.
I3C_CCC_DIRECT_ENTAS2	Enter Activity State 2.
I3C_CCC_DIRECT_ENTAS3	Enter Activity State 3.
I3C_CCC_DIRECT_RSTDAA	Reset Dynamic Address Assignment.
I3C_CCC_DIRECT_SETDASA	Set Dynamic Address from Static Address.
I3C_CCC_DIRECT_SETNEWDA	Set New Dynamic Address.
I3C_CCC_DIRECT_SETMWL	Set Max Write Length.
I3C_CCC_DIRECT_SETMRL	Set Max Read Length.
I3C_CCC_DIRECT_GETMWL	Get Max Write Length.
I3C_CCC_DIRECT_GETMRL	Get Max Read Length.
I3C_CCC_DIRECT_GETPID	Get Provisional ID.
I3C_CCC_DIRECT_GETBCR	Get Bus Characteristic Register.
I3C_CCC_DIRECT_GETDCR	Get Device Characteristic Register.
I3C_CCC_DIRECT_GETSTATUS	Get Device Status.
I3C_CCC_DIRECT_GETACCMST	Get Accept Mastership.
I3C_CCC_DIRECT_GETMXDS	Get Max Data Speed.
I3C_CCC_DIRECT_SETXTIME	Set Exchange Timing Information.
I3C_CCC_DIRECT_GETXTIME	Get Exchange Timing Information.

i3c_event_t

enum i3c_event_t

I3C Events that result in a callback.

Enumerator
I3C_EVENT_ENTDAA_ADDRESS_PHASE	Events that only occur in Master mode. A Slave device has finished writing its PID, BCR, and DCR. This information is provided in i3c_callback_args_t::p_slave_info.
I3C_EVENT_IBI_READ_COMPLETE	An IBI has successfully been read.
I3C_EVENT_IBI_READ_BUFFER_FULL	There is no more space in the IBI read buffer. The application may provide another buffer by calling i3c_api_t::ibiRead.
I3C_EVENT_READ_BUFFER_FULL	Events that only occur in Slave mode. There is no more space in the read buffer. The application may provide another buffer by calling i3c_api_t::read.
I3C_EVENT_IBI_WRITE_COMPLETE	A IBI was written successfully.
I3C_EVENT_HDR_EXIT_PATTERN_DETECTED	The HDR exit pattern was detected on the bus.
I3C_EVENT_ADDRESS_ASSIGNMENT_COMPLETE	Dynamic Address Assignment has completed. Events that are common to Master and Slave mode.
I3C_EVENT_COMMAND_COMPLETE	A command was completed.
I3C_EVENT_WRITE_COMPLETE	A write transfer has completed.
I3C_EVENT_READ_COMPLETE	A read transfer has completed.
I3C_EVENT_TIMEOUT_DETECTED	SCL is stuck at the logic high or logic low level during a transfer.
I3C_EVENT_INTERNAL_ERROR	An internal error occurred.

i3c_device_type_t

enum i3c_device_type_t

The type of device.

Enumerator
I3C_DEVICE_TYPE_MAIN_MASTER	The main master starts in master mode and is responsible for configuring the bus.
I3C_DEVICE_TYPE_SLAVE	A slave device listens to the bus for relevant I3C Commands (CCCs) sent by the current master, and responds accordingly. Slave devices may also initiate In-band interrupts and Hot-Join requests.

i3c_device_protocol_t

enum i3c_device_protocol_t

Identifies the protocol for transferring data with the device on the bus.

Enumerator
I3C_DEVICE_PROTOCOL_I2C	Transfers will use legacy I2C protocol with open-drain output at a reduced baudrate.
I3C_DEVICE_PROTOCOL_I3C	Transfers will use I3C SDR mode.

i3c_address_assignment_mode_t

enum i3c_address_assignment_mode_t

Address Assignment Mode.

Enumerator
I3C_ADDRESS_ASSIGNMENT_MODE_ENTDAA	Send the ENTDAA command to enter Dynamic Address Assignment mode and assign dynamic addresses in order, starting with the starting device index. The procedure is completed after the specified number of devices have been configured. The callback will be called after the PID, DCR, and BCR registers have been read for each device.

i3c_ibi_type_t

enum i3c_ibi_type_t

The type of In-Band Interrupt.

Enumerator
I3C_IBI_TYPE_INTERRUPT	Application specific In-Band Interrupt for notifying the master when an event occurs.
I3C_IBI_TYPE_HOT_JOIN	Request the master to perform the Dynamic Address Assignment process.
I3C_IBI_TYPE_MASTERSHIP_REQUEST	Request the master to give up control of the bus.