I3C (r_i3c)

Functions
fsp_err_t	R_I3C_Open (i3c_ctrl_t *const p_api_ctrl, i3c_cfg_t const *const p_cfg)
fsp_err_t	R_I3C_Enable (i3c_ctrl_t *const p_api_ctrl)
fsp_err_t	R_I3C_DeviceCfgSet (i3c_ctrl_t *const p_api_ctrl, i3c_device_cfg_t const *const p_device_cfg)
fsp_err_t	R_I3C_MasterDeviceTableSet (i3c_ctrl_t *const p_api_ctrl, uint32_t device_index, i3c_device_table_cfg_t const *const p_device_table_cfg)
fsp_err_t	R_I3C_SlaveStatusSet (i3c_ctrl_t *const p_api_ctrl, i3c_device_status_t status)
fsp_err_t	R_I3C_DeviceSelect (i3c_ctrl_t *const p_api_ctrl, uint32_t device_index, uint32_t bitrate_mode)
fsp_err_t	R_I3C_DynamicAddressAssignmentStart (i3c_ctrl_t *const p_api_ctrl, i3c_address_assignment_mode_t address_assignment_mode, uint32_t starting_device_index, uint32_t device_count)
fsp_err_t	R_I3C_CommandSend (i3c_ctrl_t *const p_api_ctrl, i3c_command_descriptor_t const *const p_command_descriptor)
fsp_err_t	R_I3C_Write (i3c_ctrl_t *const p_api_ctrl, uint8_t const *const p_data, uint32_t length, bool restart)
fsp_err_t	R_I3C_Read (i3c_ctrl_t *const p_api_ctrl, uint8_t *const p_data, uint32_t length, bool restart)
fsp_err_t	R_I3C_IbiWrite (i3c_ctrl_t *const p_api_ctrl, i3c_ibi_type_t ibi_type, uint8_t const *const p_data, uint32_t length)
fsp_err_t	R_I3C_IbiRead (i3c_ctrl_t *const p_api_ctrl, uint8_t *const p_data, uint32_t length)
fsp_err_t	R_I3C_Close (i3c_ctrl_t *const p_api_ctrl)

Detailed Description

Driver for the I3C peripheral on RA MCUs. This module implements the I3C Interface.

Overview

I3C is a communication protocol defined by MIPI that aims to improve on I2C by increasing the maximum transfer rate, as well as providing other features like "In-band Interrupts", "Dynamic Address Assignment", and a set of standard "Common Command Codes".

Features

• I3C Master Mode
• I3C Slave Mode
• Dynamic Address Assignment (ENTDAA/SETDASA)
• SDR Read/Write transfers
• HDR-DDR Read/Write Commands
• I2C Legacy Read/Write transfers
• In-Band Interrupts (Interrupt Requests, Hot-Join Requests)
• Common Command Codes
• Clock Stalling
• Timeout Detection

Master Mode

On an I3C bus, only one device may operate in master mode at a time. The current master is responsible for initiating I2C Legacy transfers, SDR transfers, Common Command Codes, and handling IBIs (Interrupt Requests, Hot-Join Requests). In order to perform these operations, the driver has an internal device table that is used for storing configuration information for each device on the bus (See i3c_device_table_cfg_t). Each entry in the device table contains the static or dynamic address of the device, and IBI permissions for accepting or rejecting IBI requests from the device. The device table has a limited number of entries as well as one extended device entry that only contains the static or dynamic address of a device (See below).

Master Device Table

In order to initiate I2C Legacy transfers, SDR transfers, or Common Command Codes, the master must select a device entry from the device table using i3c_api_t::deviceSelect. Once a device has been selected, all subsequent operations will be directed to the selected device until a new device is selected using i3c_api_t::deviceSelect.

The master may also receive IBI requests that are initiated by slave devices on the bus. If there is a payload, then the driver will write the data into a buffer that is provided by the application by calling i3c_api_t::ibiRead. If the application has not provided an IBI buffer prior to receiving an IBI, then the it will get a callback requesting an IBI buffer. Once the IBI is completed, the application will be notified by a callback.

Note

1. Even though there are only a limited number of device table entries and one extended device table entry, the application can operate on more devices by maintaining its own list of devices and updating the extended device entry as needed. Note however that devices defined in the extended device table entry will not be able to initiate IBI requests.

Main Master

The main master is responsible for configuring the dynamic address of all devices on the bus. The driver initiates this procedure by calling i3c_api_t::dynamicAddressAssignmentStart. Before starting address assignment, the application must configure the device table using i3c_api_t::masterDeviceTableSet.

Enter Dynamic Address Assignment (ENTDAA):

The application initiates the ENTDAA operation by calling i3c_api_t::dynamicAddressAssignmentStart with a starting index into the master device table and a count specifying the number of devices to configure. The master starts by sending the ENTDAA command. Every I3C device on the bus that has not already been initialized will acknowledge the command and attempt to write its Provisional ID, DCR, and BCR registers. The device with the smallest value in these registers will win arbitration and be assigned with the first dynamic address defined in the master device table. The master will then increment the index and repeat the process by assigning the dynamic address to the next device. The process continues until the specified number of devices have been initialized or until there are no more devices to configure.

Note

1. The IBI payload setting will automatically be updated in the master device table based on the BCR setting that was read during ENTDAA.

2. After each device successfully writes its Provisional ID, DCR, and BCR registers, the application will get a callback that will provide the value of the registers.

3. If the starting index is set to the extended device entry, then the device count must be set to 1.

4. The main master assigns its own dynamic address with i3c_api_t::deviceCfgSet.

Set Dynamic Address from Static Address (SETDASA):

The application initiates the SETDASA operation by calling i3c_api_t::dynamicAddressAssignmentStart with an index into the master device table. The master sends the SETDASA command to the static address defined in the given device table entry, and then assigns the associated dynamic address.

Note

1. Set the count to 0 when using SETDASA.

Slave Mode

In slave mode, the device configures its static address, Provisional ID, BCR, and DCR registers using i3c_api_t::deviceCfgSet, and then waits for the master to initiate communication. Prior to being assigned a dynamic address, the slave will operate as an I2C device using its static address. The application will receive a callback when the master assigns it a dynamic address, after which point, the slave will operate as an I3C device until it receives the RSTDAA command.

Depending on the capabilities defined in its BCR register, the slave may also initiate IBI Interrupt Requests, and Hot-Join Requests using i3c_api_t::ibiWrite

Configuration

Build Time Configurations for r_i3c

The following build time configurations are defined in fsp_cfg/r_i3c_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
Unaligned Buffer Support	Enabled Disabled	Enabled	Unaligned buffer support may be optionally disabled for improved performance.
Master Support	Enabled Disabled	Enabled	If only slave mode is required, disable master support to decrease code size.
Slave Support	Enabled Disabled	Enabled	If only master mode is required, disable slave support to decrease code size.
Error Recovery Procedure	MCU Specific Options		There are two different chip versions of the RA2E2 MCU (Version 1 and Version 2). Each version requires a different procedure for recovering from errors.

Configurations for Connectivity > I3C (r_i3c)

This module can be added to the Stacks tab via New Stack > Connectivity > I3C (r_i3c).

Configuration	Options	Default	Description
Bitrate Settings
Bitrate Settings > Standard Mode
Bitrate Settings > Standard Mode > Open-Drain
Logic High Period (ns)	Must be an integer greater than 0.	167	The Logic High period of SCL during Standard Mode Open Drain transfers.
Frequency	Must be an integer greater than 0.	1000000	The Frequency of SCL during Standard Mode Open Drain transfers.
Bitrate Settings > Standard Mode > Push-Pull
Logic High Period (ns)	The Logic High Period must be greater than or equal to 24 Nanoseconds.	167	The Logic High period of SCL during Standard Mode Push Pull transfers.
Frequency	Push-Pull frequency must be greater than or equal to 10000 Hz.	3400000	The Frequency of SCL during Standard Mode Push-Pull transfers.
Bitrate Settings > Extended Mode
Bitrate Settings > Extended Mode > Open-Drain
Logic High Period (ns)	Must be an integer greater than 0.	167	The Logic High period of SCL during Extended Mode Open Drain transfers.
Frequency	Must be an integer greater than 0.	1000000	The Frequency of SCL during Extended Mode Open Drain transfers.
Bitrate Settings > Extended Mode > Push-Pull
Logic High Period (ns)	The Logic High Period must be greater than or equal to 24 Nanoseconds.	167	The Logic High period of SCL during Extended Mode Push Pull transfers.
Frequency	Push-Pull frequency must be greater than or equal to 10000 Hz.	3400000	The Frequency of SCL during Extended Mode Push-Pull transfers.
Bitrate Settings > Bus Timing
Open Drain Rising Time (ns)	Rising time must be greater than or equal to 0 nanoseconds.	0	The Open Drain rising time in nanoseconds.
Open Drain Falling Time (ns)	Falling time must be greater than or equal to 0 nanoseconds.	0	The Open Drain falling time in nanoseconds.
Push-Pull Rising Time (ns)	Rising time must be greater than or equal to 0 nanoseconds.	0	The Push-Pull rising time in nanoseconds.
Push-Pull Falling Time (ns)	Falling time must be greater than or equal to 0 nanoseconds.	0	The Push-Pull rising time in nanoseconds.
Bitrate Settings > Clock Stalling
Address Assignment Phase	Enabled Disabled	Disabled	Enable clock stalling during the Address Assignment Phase of ENTDAA.
Transition Phase	Enabled Disabled	Disabled	Enable clock stalling during the Transition Bit of a read transfer.
Parity Phase	Enabled Disabled	Disabled	Enable clock stalling during the Parity Bit of a write transfer.
Ack Phase	Enabled Disabled	Disabled	Enable clock stalling during the ACK phase of a transfer.
Time (us)	Must be greater than or equal to 0.	0	The amount of time to stall the clock during the Address Assignment Phase, Transition Phase, Parity Phase, and ACK Phase.
Master Mode
ACK Hot-Join Requests	Enabled Disabled	Disabled	If enabled, the I3C instance will ACK Hot-Join Requests and notify the application.
Notify Rejected Hot-Join Requests.	Enabled Disabled	Disabled	If enabled, the application will get a callback when an IBI Hot-Join Request is rejected.
Notify Rejected Mastership Requests.	Enabled Disabled	Disabled	If enabled, the application will get a callback when an IBI Mastership Request is rejected.
Notify Rejected Interrupt Requests.	Enabled Disabled	Disabled	If enabled, the application will get a callback when an IBI Interrupt Request is rejected.
Slave Mode
Slave Mode > Command Response Info
Slave Mode > Command Response Info > ENEC/DISEC
In-Band Interrupts	Enabled Disabled	Disabled	Configure whether the slave can issue IBI requests.
Hot-Join Requests	Enabled Disabled	Disabled	Configure whether the slave can issue Hot-Join requests.
Slave Mode > Command Response Info > ENTASn
Activity State	Activity State 0 Activity State 1 Activity State 2 Activity State 3	Activity State 0	Configure the starting activity state of the slave.
Slave Mode > Command Response Info > SETMWL/GETMWL
Max Write Length	Write length must be in the range of [8, 65535].	65535	Set the max write length.
Slave Mode > Command Response Info > SETMRL/GETMRL
Max Read Length	Read length must be in the range of [16, 65535].	65535	Set the max read length.
Max IBI Payload Length	Read length must be in the range of [0, 255].	0	Set the max IBI payload length, or set it to 0 for unlimited.
Slave Mode > Command Response Info > GETMXDS
Write Data Rate	FSCL_MAX 8Mhz 6Mhz 4Mhz 2Mhz	2Mhz	Set the max write data rate.
Read Data Rate	FSCL_MAX 8Mhz 6Mhz 4Mhz 2Mhz	2Mhz	Set the max read data rate.
Clock to Data Turnaround Time	8 Nanoseconds 9 Nanoseconds 10 Nanoseconds 11 Nanoseconds 12 Nanoseconds Greater than 12 Nanoseconds	8 Nanoseconds	Set the clock to data turnaround time.
Include Max Read Turnaround Time	Enabled Disabled	Disabled	Configure whether the Max Read Turnaround time will be transmitted.
Max Read Turnaround Time	Value must be in the range [0, 255].	0	Set max read turnaround time.
Slave Mode > Command Response Info > GETXTIME
Frequency Byte	Value must be in the range [0, 255].	0	Set the internal oscillator frequency in increments of 0.5 Mhz.
Inaccuracy Byte	Value must be in the range [0, 255].	0	Set the oscillator inaccuracy byte in increments of 0.5%
Slave Mode > Command Response Info > GETCAP/GETHDRCAP
HDR-DDR (Mode 0)	MCU Specific Options		Slave supports HDR-DDR (Mode 0)
HDR-TSP (Mode 1)	MCU Specific Options		Slave supports HDR-TSP (Mode 1)
HDR-TSL (Mode 2)	MCU Specific Options		Slave supports HDR-TSL (Mode 2)
Interrupts
Interrupt Priority	MCU Specific Options		The interrupt priority of the RX, TX, RESPONSE, RCV_STATUS, and IBI ISRs.
Error and Event Interrupt Priority	MCU Specific Options		The interrupt priority of the EEI ISR which is used to notify the application when an Internal Error, HDR Exit Pattern, or Timeout is detected.
Name	Name must be a valid C symbol	g_i3c0	Module name.
Callback	Name must be a valid C symbol	g_i3c0_callback	A user callback function must be provided. This will be called in order to notify the application of I3C events and provide status information.
Device Type	Main Master Slave	Slave	The role that the I3C instance will take on the I3C bus.
Bus Free Condition Detection Time (ns)	Must be greater than or equal to 38.4 nanoseconds.	38.4	The minimum period occurring after a STOP and before a START.
Bus Available Condition Detection Time (us)	Must be greater than or equal to 1 microsecond.	1	The minimum period occurring after the Bus Free Condition when Slaves can initiate IBI requests.
Bus Idle Condition Detection Time (us)	Must be greater than or equal to 1000 microseconds.	1000	The minimum period occurring after the Bus Available Condition when Slaves can initiate Hot-Join requests.
Timeout Detection	Enabled Disabled	Disabled	If enabled, the application will get a callback if SCL is stuck at a logic high or logic low level for more than 65535 cycles of the I3C source clock.

Clock Configuration

The following settings are used to configure the timing of SCL.

• Frequency of TCLK
• Standard Mode
  • Open Drain High Period (T_HIGH)
  • Open Drain Frequency
  • Push-Pull High Period (T_HIGH)
  • Push-Pull Frequency
• Extended Mode
  • Open Drain High Period (T_HIGH)
  • Open Drain Frequency
  • Push-Pull High Period (T_HIGH)
  • Push-Pull Frquency
• i3c_bitrate_mode_t (Set during i3c_api_t::deviceSelect)

The Standard and Extended Mode settings define two separate SCL configurations that can be selected at run-time using i3c_api_t::deviceSelect.

In addition to selecting between the Standard and Extended Mode settings, the base SCL period can also be multiplied using the following options:

• I3C_BITRATE_MODE_I3C_SDR2_STDBR_X2: Multiple the base Standard Open Drain and Push-Pull period by 2.
• I3C_BITRATE_MODE_I3C_SDR3_EXTBR_X2: Multiple the base Extended Open Drain and Push-Pull period by 2.
• I3C_BITRATE_MODE_I3C_SDR4_EXTBR_X4: Multiple the base Extended Open Drain and Push-Pull period by 4.

In order to get accurate frequency calculations, the Rising and Falling edges must be input into the calculation. These values will depend on the topology the I3C bus that will be different for every application.

Note

1. The Standard and Extended Open Drain period settings define the period to use during legacy I2C transfers (Only use the following i3c_bitrate_mode_t settings with I2C transfers: I3C_BITRATE_MODE_I2C_STDBR, I3C_BITRATE_MODE_I2C_EXTBR).

2. T_HIGH is defined in Figure 31 in the MIPI I3C Specification v1.0 and describes the Logic High period.

3. Depending on the MCU, TCLK is either derived from PCLKD or from a dedicated I3C Clock (I3CCLK).

Pin Configuration

The I3C peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device. An I3C channel would consist of two pins - SDA and SCL for data/address and clock respectively.

Usage Notes

Read and Write in Slave Mode

In slave mode, calling read or write does not start a transfer. Instead, calling read or write will configure the driver to perform the next read or write transfer using the user provided buffer.

Provided that a transfer is not already in progress, i3c_api_t::read and i3c_api_t::write can be called to update the internal buffers even if the transfer has not been completed yet. Both the read and write buffers can be configured at the same time in order to prepare the driver for when the master initiates a read or a write transfer.

If there is no space remaining in a user configured read buffer, the application will get a I3C_EVENT_READ_BUFFER_FULL callback requesting for a new read buffer to be provided.

Event Status

When a write, read, ibiWrite, ibiRead or commandSend, operation is completed, the i3c_callback_args_t::event_status should be checked. The event_status will provide information about the success or failure of the operation.

The following are possible statuses:

• I3C_EVENT_STATUS_SUCCESS
• I3C_EVENT_STATUS_PARITY
• I3C_EVENT_STATUS_FRAME
• I3C_EVENT_STATUS_ADDRESS_HEADER
• I3C_EVENT_STATUS_NACK
• I3C_EVENT_STATUS_OVERFLOW
• I3C_EVENT_STATUS_ABORTED_TO_MASTER
• I3C_EVENT_STATUS_ABORTED

Note

In master mode, if the master issues a stop condition before the slave ends the transfer via the 'T' bit, the status will be I3C_EVENT_STATUS_ABORTED.

In slave mode, if the master issues a stop condition before the slave ends the transfer via the 'T' bit, the status will be I3C_EVENT_STATUS_ABORTED_TO_MASTER.

Direct Get Common Command Codes in Slave Mode

When an I3C slave receives a Command Code of type Direct Get, the response is automatically sent from the device Special Function Registers (SFR). The SFR contains information for each command code and can be configured during open (See i3c_extended_cfg_t::slave_command_response_info). This allows the slave to respond to Direct Get Command Codes much faster, and removes the burden of responding to these commands from the application.

The response to the GETSTATUS command can be configured at run-time using i3c_api_t::slaveStatusSet.

Disabling Unaligned Buffer Support

Support for performing read and write operations on unaligned buffers can be disabled in order to improve performance. When unaligned buffer support is disabled, all buffers passed to read, ibiRead, write, ibiWrite, and commandSend must be aligned to 4 bytes and the size of the buffers must be a multiple of 4 bytes.

In master mode, the value of the length passed to i3c_api_t::read and i3c_api_t::write sets the total length of the operation in bytes. During the read or write operation, the driver may read or write to the last word of memory during the operation. This means that the allocated memory for the buffer passed to read and write needs to be a multiple of 4 bytes even though the transfer length is not a multiple of 4 bytes.

In slave mode, the length passed to i3c_api_t::read must be a multiple of 4 bytes. The length passed to i3c_api_t::write sets the number of bytes that the slave will write. The size of the buffer passed to write still needs to be a multiple of 4 bytes.

Max Data Speed Limitation on RA2E2 MCUs

In Slave Mode, it is highly recommended that BCR[0] be set to '1' in order to indicate to the master that the device doesn't support the max data speed. The master is then required to use the GETMXDS command to get the device specific data speed limitations.

This will allow the slave to specify its maximum supported data rate for read/write, and the maximum read turnaround time (See GETMXDS in the MIPI I3C Specification v1.0).

Mixed Fast Bus

The MIPI I3C Specification v1.0 defines a Mixed Fast Bus as a bus that has legacy I2C devices that all have a 50ns Spike Filter.

On Mixed Fast Buses, SCL has the following constraints during I3C SDR transfers:

• SCL High Period: t_{DIG_H_MIXED(MIN)} to t_{DIG_H_MIXED(MAX)}
• SCL Low Period: Up to t_{DIG_L(MAX)}

In this case, configure the Extended Bitrate settings for I3C SDR transfers, and use the Standard Bitrate settings for I2C transfers.

Note

1. See section 5.1.2.4 in the MIPI I3C Specification v1.0.

Mixed Slow Bus

The MIPI I3C Specification v1.0 defines a Mixed Slow Bus as a bus that has legacy I2C devices that do not have a 50ns Spike Filter.

In this case, the SCL frequency is limited to I2C Fast Mode or I2C Fast Mode Plus.

Note

1. See section 5.1.2.4 in the MIPI I3C Specification v1.0.

RA2E2 MCU Version

There are two versions of the RA2E2. The version number can be identified by the part number or by reading the MCU Version Register.

Part Number	Chip Version
R7FA2E2A72DNK::HA0	Version 1
R7FA2E2A72DNK::HA1	Version 2
R7FA2E2A72DNK::AA0	Version 1
R7FA2E2A72DNK::AA1	Version 2

The I3C peripheral on the RA2E2 Version 1 has a hardware limitation related to using dynamic address assignment in slave mode. When the ENTDAA command is received, the peripheral will continue driving its PID, DCR, and BCR registers during arbitration even after its dynamic address has already been configured. This will prevent any other devices on the bus from being configured after the RA2E2 Version 1 device has been configured. One workaround for this limitation is to configure the Provisional ID to all '1's in order to ensure that the RA2E2 Version 1 device is configured last. If more than one RA2E2 Version 1 device is present on the same bus, consider initializing them using another method (Eg. SETDASA). Note that this issue has been corrected on the RA2E2 Version 2 (Part numbers ending in #AA1 or #HA1).

In addition to fixing this hardware limitation, the revised I3C peripheral on the RA2E2 version 2 also greatly simplifies the error recovery procedures. By default, the driver will automatically include the error recovery procedures for both versions, however, it can be configured to only support version 1 or version 2 procedures in order to reduce code size.

Limitations

Developers should be aware of the following limitations when using the I3C:

• The MIPI Reserved area and Vendor Extension area of Command Codes are not supported.
• Mixed Fast Bus topology has the following limitation on RA2E2 MCUs. The minimum SCL high period (T_{DIG_H}) is 156 nanoseconds when PCLKD is 48 Mhz, and 120 nanoseconds when PCLKD is 64 Mhz. On a Mixed Fast Bus, the high period T_{DIG_HIGH_MIXED} must be less than 45 nanoseconds in order to ensure that Legacy I2C devices do not interpret I3C signaling as valid I2C signaling (See Table 111 Push-Pull-Timing Parameters in the MIPI I3C Specification v1.1). This required high period cannot be achievable with RA2E2 MCUs.
• Secondary Master device role is not currently supported.

Examples

I3C Master Basic Example

This is a basic example of minimal use of the I3C Master in an application.

void i3c_master_basic_example (void)
{
    /* Initializes the module. */
    fsp_err_t status = R_I3C_Open(&g_i3c_ctrl, &g_i3c_cfg);
    assert(FSP_SUCCESS == status);

    static i3c_device_cfg_t master_device_cfg =
    {
        /* This is the Static I3C / I2C Legacy address defined by the device manufacturer. */
        .static_address  = EXAMPLE_MASTER_STATIC_ADDRESS,

        /* If the device is a main master, it must configure its own dynamic address. */
        .dynamic_address = EXAMPLE_MASTER_DYNAMIC_ADDRESS,
    };

    status = R_I3C_DeviceCfgSet(&g_i3c_ctrl, &master_device_cfg);
    assert(FSP_SUCCESS == status);

    static i3c_device_table_cfg_t device_table_cfg =
    {
        /* This is the Static I3C / I2C Legacy address defined by the device manufacturer. */
        .static_address        = EXAMPLE_STATIC_ADDRESS,

        /* Dynamic address is not used in I2C. */
        .dynamic_address       = EXAMPLE_DYNAMIC_ADDRESS,

        /* This is the type of device. It may be either an I2C device or an I3C device. */
        .device_protocol       = I3C_DEVICE_PROTOCOL_I3C,

        .ibi_accept            = false, 

        /* Depending on the device the IBI requests may have a data payload.
         * Note that this field will be automatically updated if the device is configured using ENTDAA.
         */
        .ibi_payload           = false,

        /* Master requests cannot be accepted because Secondary Master is not supported. */
        .master_request_accept = false,
    };

    /* Set the device configuration in the master device table. */
    status = R_I3C_MasterDeviceTableSet(&g_i3c_ctrl, 0, &device_table_cfg);
    assert(FSP_SUCCESS == status);

    /* Enable the I3C device. */
    status = R_I3C_Enable(&g_i3c_ctrl);
    assert(FSP_SUCCESS == status);

    /* Start assigning dynamic addresses to devices on the bus using the ENTDAA command. */
    status = R_I3C_DynamicAddressAssignmentStart(&g_i3c_ctrl, I3C_ADDRESS_ASSIGNMENT_MODE_ENTDAA, 0, 1);
    assert(FSP_SUCCESS == status);

    /* Wait for dynamic address assignment to complete. */
    i3c_app_event_wait(I3C_EVENT_ADDRESS_ASSIGNMENT_COMPLETE);

    /* Select the configured device and bitrate mode for the following operations. */
    status = R_I3C_DeviceSelect(&g_i3c_ctrl, 0, I3C_BITRATE_MODE_I3C_SDR0_STDBR);
    assert(FSP_SUCCESS == status);

    /* Start a write transfer. */
    static uint8_t p_write_buffer[] = {1, 2, 3, 4, 5};
    status = R_I3C_Write(&g_i3c_ctrl, p_write_buffer, sizeof(p_write_buffer), false);
    assert(FSP_SUCCESS == status);

    /* Wait for the write transfer to complete. */
    i3c_app_event_wait(I3C_EVENT_WRITE_COMPLETE);

    /* Start a read transfer. */
    static uint8_t p_read_buffer[16];
    status = R_I3C_Read(&g_i3c_ctrl, p_read_buffer, sizeof(p_read_buffer), false);
    assert(FSP_SUCCESS == status);

    /* Wait for the read transfer to complete. */
    i3c_app_event_wait(I3C_EVENT_READ_COMPLETE);
}

/* This function is called by the I3C driver from ISRs in order to notify the application of I3C events. */
void i3c_master_basic_example_callback (i3c_callback_args_t const * const p_args)
{
    switch (p_args->event)
    {
        case I3C_EVENT_ENTDAA_ADDRESS_PHASE:
        {
            /* The device PID, DCR, and BCR registers will be available in i3c_callback_args_t::p_slave_info. */
            break;
        }

        case I3C_EVENT_ADDRESS_ASSIGNMENT_COMPLETE:
        {
            i3c_app_event_notify(I3C_EVENT_ADDRESS_ASSIGNMENT_COMPLETE);
            break;
        }

        case I3C_EVENT_WRITE_COMPLETE:
        {
            i3c_app_event_notify(I3C_EVENT_WRITE_COMPLETE);
            break;
        }

        case I3C_EVENT_READ_COMPLETE:
        {
            /* The number of bytes read from the slave will be available in i3c_callback_args_t::transfer_size. */
            i3c_app_event_notify(I3C_EVENT_READ_COMPLETE);
            break;
        }

        default:
        {
            break;
        }
    }
}

I3C Slave Basic Example

This is a basic example of minimal use of the I3C Slave in an application.

void i3c_slave_basic_example (void)
{
    /* Initializes the module. */
    fsp_err_t status = R_I3C_Open(&g_i3c_ctrl, &g_i3c_cfg);
    assert(FSP_SUCCESS == status);

    static i3c_device_cfg_t slave_device_cfg =
    {
        /* This is the Static I3C / I2C Legacy address defined by the device manufacturer. */
        .static_address  = EXAMPLE_STATIC_ADDRESS,

        /* The dynamic address will be automatically updated when the master configures this device using ENTDAA. */
        .dynamic_address = 0,

        /* Device Registers that are read by the master. */
        .slave_info      =
        {
            .bcr = EXAMPLE_BCR_SETTING,
            .dcr = EXAMPLE_DCR_SETTING,
            .pid =
            {
                0, 1, 2, 3, 4, 5
            }
        }
    };

    /* Set the device configuration for this device. */
    status = R_I3C_DeviceCfgSet(&g_i3c_ctrl, &slave_device_cfg);
    assert(FSP_SUCCESS == status);

    /* Enable Slave Mode. */
    status = R_I3C_Enable(&g_i3c_ctrl);
    assert(FSP_SUCCESS == status);

    static uint8_t p_read_buffer[EXAMPLE_READ_BUFFER_SIZE];
    static uint8_t p_write_buffer[EXAMPLE_WRITE_BUFFER_SIZE];

    /* Set the buffer for storing data received during a read transfer. */
    status = R_I3C_Read(&g_i3c_ctrl, p_read_buffer, sizeof(p_read_buffer), false);
    assert(FSP_SUCCESS == status);

    /* Wait for the master to complete a read transfer. */
    i3c_app_event_wait(I3C_EVENT_READ_COMPLETE);

    /* Set the write buffer that will be transmitted during a write transfer. */
    status = R_I3C_Write(&g_i3c_ctrl, p_write_buffer, sizeof(p_write_buffer), false);
    assert(FSP_SUCCESS == status);

    /* Wait for the master to complete a write transfer. */
    i3c_app_event_wait(I3C_EVENT_WRITE_COMPLETE);
}

void i3c_slave_basic_example_callback (i3c_callback_args_t const * const p_args)
{
    switch (p_args->event)
    {
        case I3C_EVENT_ADDRESS_ASSIGNMENT_COMPLETE:
        {
            i3c_app_event_notify(I3C_EVENT_ADDRESS_ASSIGNMENT_COMPLETE);
            break;
        }

        case I3C_EVENT_READ_BUFFER_FULL:
        {
            /* If there is no user provided read buffer, or if the user provided read buffer has been filled,
             * the driver will notify the application that the buffer is full. The application may provide
             * a new read buffer by calling i3c_api_t::read. If no read buffer is provided, then any remaining bytes
             * in the transfer will be dropped. */
            uint8_t * p_read_buffer = i3c_app_next_read_buffer_get();
            R_I3C_Read(&g_i3c_ctrl, p_read_buffer, EXAMPLE_READ_BUFFER_SIZE, false);
            break;
        }

        case I3C_EVENT_READ_COMPLETE:
        {
            /* The number of bytes read by the slave will be available in i3c_callback_args_t::transfer_size. */
            i3c_app_event_notify(I3C_EVENT_READ_COMPLETE);

            /* Note that the application may also call i3c_api_t::read or i3c_api_t::write from this event
             * In order to set the transfer buffers for the next transfer. */
            break;
        }

        case I3C_EVENT_WRITE_COMPLETE:
        {
            /* The number of bytes written by the slave will be available in i3c_callback_args_t::transfer_size. */
            i3c_app_event_notify(I3C_EVENT_WRITE_COMPLETE);

            /* Note that the application may also call i3c_api_t::read or i3c_api_t::write from this event
             * In order to set the transfer buffers for the next transfer. */
            break;
        }

        default:
        {
            break;
        }
    }
}

I2C Legacy Basic Example

This is a basic example of minimal use of I2C Legacy transfers in an application.

void i2c_legacy_basic_example (void)
{
    /* Initializes the module. */
    fsp_err_t status = R_I3C_Open(&g_i3c_ctrl, &g_i3c_cfg);
    assert(FSP_SUCCESS == status);

    static i3c_device_cfg_t master_device_cfg =
    {
        /* This is the Static I3C / I2C Legacy address defined by the device manufacturer. */
        .static_address  = EXAMPLE_MASTER_STATIC_ADDRESS,

        /* If the device is a main master, it must configure its own dynamic address. */
        .dynamic_address = EXAMPLE_MASTER_DYNAMIC_ADDRESS,
    };

    status = R_I3C_DeviceCfgSet(&g_i3c_ctrl, &master_device_cfg);
    assert(FSP_SUCCESS == status);

    static i3c_device_table_cfg_t device_table_cfg =
    {
        /* This is the Static I3C / I2C Legacy address defined by the device manufacturer. */
        .static_address        = EXAMPLE_STATIC_ADDRESS,

        /* Dynamic address is not used in I2C. */
        .dynamic_address       = 0,

        /* This is the type of device. It may be either an I2C device or an I3C device. */
        .device_protocol       = I3C_DEVICE_PROTOCOL_I2C,

        /* These options are not used in I2C. */
        .ibi_accept            = false, 

        /* Depending on the device the IBI requests may have a data payload.
         * Note that this field will be automatically updated if the device is configured using ENTDAA.
         */
        .ibi_payload           = false,

        /* Master requests cannot be accepted because Secondary Master is not supported. */
        .master_request_accept = false,
    };

    /* Set the device configuration in the master device table. */
    status = R_I3C_MasterDeviceTableSet(&g_i3c_ctrl, 0, &device_table_cfg);
    assert(FSP_SUCCESS == status);

    /* Enable the I3C device. */
    status = R_I3C_Enable(&g_i3c_ctrl);
    assert(FSP_SUCCESS == status);

    /* Select the configured device for the following operations. */
    status = R_I3C_DeviceSelect(&g_i3c_ctrl, 0, I3C_BITRATE_MODE_I2C_STDBR);
    assert(FSP_SUCCESS == status);

    /* Start a write transfer. */
    static uint8_t p_write_data[] = {1, 2, 3, 4, 5};
    status = R_I3C_Write(&g_i3c_ctrl, p_write_data, sizeof(p_write_data), false);
    assert(FSP_SUCCESS == status);

    /* Wait for the write transfer to complete. */
    i3c_app_event_wait(I3C_EVENT_WRITE_COMPLETE);

    /* Start a read transfer. */
    static uint8_t p_read_data[16];
    status = R_I3C_Read(&g_i3c_ctrl, p_read_data, sizeof(p_read_data), false);
    assert(FSP_SUCCESS == status);

    /* Wait for the read transfer to complete. */
    i3c_app_event_wait(I3C_EVENT_READ_COMPLETE);
}

void i2c_legacy_basic_example_callback (i3c_callback_args_t const * const p_args)
{
    switch (p_args->event)
    {
        case I3C_EVENT_WRITE_COMPLETE:
        {
            i3c_app_event_notify(I3C_EVENT_WRITE_COMPLETE);
            break;
        }

        case I3C_EVENT_READ_COMPLETE:
        {
            /* The number of bytes read from the slave will be available in i3c_callback_args_t::transfer_size. */
            i3c_app_event_notify(I3C_EVENT_READ_COMPLETE);
            break;
        }

        default:
        {
            break;
        }
    }
}

I3C Master In-band Interrupts Example

This is a basic example of reading In-band Interrupts in I3C Master mode.

void i3c_master_ibi_basic_example (void)
{
    static uint8_t p_ibi_read_buffer[EXAMPLE_READ_BUFFER_SIZE];

    /* Set the buffer for storing IBI data that is read from the slave. */
    fsp_err_t status = R_I3C_IbiRead(&g_i3c_ctrl, p_ibi_read_buffer, sizeof(p_ibi_read_buffer));
    assert(FSP_SUCCESS == status);

    /* Wait for the ibiRead transfer to complete.
     * Note that the master does not need to wait for the IBI, and can start other operations. */
    i3c_app_event_wait(I3C_EVENT_IBI_READ_COMPLETE);
}

void i3c_master_ibi_basic_example_callback (i3c_callback_args_t const * const p_args)
{
    switch (p_args->event)
    {
        case I3C_EVENT_IBI_READ_BUFFER_FULL:
        {
            /* If there is no user provided ibiRead buffer, or if the user provided ibiRead buffer has been filled,
             * the driver will notify the application that the buffer is full. The application may provide
             * a new read buffer by calling i3c_api_t::ibiRead. If no read buffer is provided, then any remaining bytes
             * in the transfer will be dropped. */
            uint8_t * p_read_buffer = i3c_app_next_read_buffer_get();
            R_I3C_IbiRead(&g_i3c_ctrl, p_read_buffer, EXAMPLE_READ_BUFFER_SIZE);
            break;
        }

        case I3C_EVENT_IBI_READ_COMPLETE:
        {
            /* When an IBI is completed, the transfer_size, ibi_type, and ibi_address will be available in p_args. */
            switch (p_args->ibi_type)
            {
                case I3C_IBI_TYPE_INTERRUPT:
                {
                    /* Notify the application that an IBI was read. */
                    i3c_app_event_notify(I3C_EVENT_IBI_READ_COMPLETE);
                    break;
                }

                case I3C_IBI_TYPE_HOT_JOIN:
                {
                    /* If a Hot-Join event is received, then the master can initiate the dynamic address assignment procedure. */
                    R_I3C_DynamicAddressAssignmentStart(&g_i3c_ctrl, I3C_ADDRESS_ASSIGNMENT_MODE_ENTDAA, 0, 1);
                    break;
                }

                default:
                {
                    break;
                }
            }
        }

        default:
        {
            break;
        }
    }
}

I3C Slave In-band Interrupts Example

This is a basic example of writing In-band Interrupts in I3C Slave mode.

void i3c_slave_ibi_write_basic_example (void)
{
    uint8_t ibi_write_buffer[EXAMPLE_WRITE_BUFFER_SIZE] = {0};

    /* Initiate an In-band interrupt in slave mode.
     * Note: If the slave does not have an IBI payload or if it is a Hot-Join request, the write buffer should be set
     *       to NULL and the write length should be set to 0. */
    fsp_err_t status = R_I3C_IbiWrite(&g_i3c_ctrl, I3C_IBI_TYPE_INTERRUPT, ibi_write_buffer, sizeof(ibi_write_buffer));
    assert(FSP_SUCCESS == status);

    /* Wait for the ibiWrite transfer to complete. */
    i3c_app_event_wait(I3C_EVENT_IBI_WRITE_COMPLETE);
}

void i3c_slave_ibi_write_basic_example_callback (i3c_callback_args_t const * const p_args)
{
    switch (p_args->event)
    {
        case I3C_EVENT_IBI_WRITE_COMPLETE:
        {
            /* Notify the application that the IBI write is complete. */
            i3c_app_event_notify(I3C_EVENT_IBI_WRITE_COMPLETE);
            break;
        }

        default:
        {
            break;
        }
    }
}

I3C Master Common Command Codes Example

This is a basic example of sending Common Command Codes in I3C Master mode.

void i3c_master_ccc_example (void)
{
    static uint8_t command_buffer[EXAMPLE_READ_BUFFER_SIZE];

    /* Setup the command descriptor. */
    static i3c_command_descriptor_t command_descriptor =
    {
        .command_code = I3C_CCC_DIRECT_GETSTATUS,

        /* Set a buffer for storing the data read by the command. */
        .p_buffer     = command_buffer,

        /* The length for a GETSTATUS command is 2 bytes. */
        .length       = 2,

        /* Terminate the transfer with a STOP condition. */
        .restart      = false,

        /* The GETSTATUS command is a Direct Get Command so rnw should be true. */
        .rnw          = true,
    };

    /* Send the command. */
    fsp_err_t status = R_I3C_CommandSend(&g_i3c_ctrl, &command_descriptor);
    assert(FSP_SUCCESS == status);

    /* Wait for the command to complete. */
    i3c_app_event_wait(I3C_EVENT_COMMAND_COMPLETE);

    /* The command_buffer will have the status info that was read from the slave device. */
}

void i3c_master_ccc_example_callback (i3c_callback_args_t const * const p_args)
{
    switch (p_args->event)
    {
        case I3C_EVENT_COMMAND_COMPLETE:
        {
            /* Notify the application that the command is complete. */
            i3c_app_event_notify(I3C_EVENT_COMMAND_COMPLETE);
            break;
        }

        default:
        {
            break;
        }
    }
}

I3C Slave Common Command Codes Example

This is a basic example of receiving Common Command Codes in I3C Slave mode.

void i3c_slave_ccc_example (void)
{
    static uint8_t read_buffer[EXAMPLE_READ_BUFFER_SIZE];

    /* Broadcast and Direct Set commands will be read into the read_buffer the same way that
     * a normal SDR Master Write / Slave Read transfer is read. */
    fsp_err_t status = R_I3C_Read(&g_i3c_ctrl, read_buffer, sizeof(read_buffer), false);
    assert(FSP_SUCCESS == status);

    /* Wait for the command to complete. */
    i3c_app_event_wait(I3C_EVENT_COMMAND_COMPLETE);
}

void i3c_slave_ccc_example_callback (i3c_callback_args_t const * const p_args)
{
    switch (p_args->event)
    {
        case I3C_EVENT_COMMAND_COMPLETE:
        {
            /* The command code and transfer size will be available in p_args.
             * If the command code is a Broadcast or Direct Set, then data will
             * be stored in the read buffer provided by i3c_api_t::read.
             * If the command code is a Direct Get, then the data will be automatically
             * sent from device SFR. */
            i3c_app_event_notify(I3C_EVENT_COMMAND_COMPLETE);
            break;
        }

        default:
        {
            break;
        }
    }
}

I3C HDR Command Example

This is a basic example of sending an HDR command

#define I3C_HDR_COMMAND_CODE      (0x55)
#define I3C_HDR_COMMAND_LENGTH    (16)

void i3c_hdr_command_example (void)
{
    static uint8_t command_buffer[EXAMPLE_READ_BUFFER_SIZE];

    /* Setup the command descriptor. */
    static i3c_command_descriptor_t command_descriptor =
    {
        /* Specify the command code for the HDR transfer. */
        .command_code = I3C_HDR_COMMAND_CODE,

        /* Set a buffer for writing command data. */
        .p_buffer     = command_buffer,

        /* The length for command (HDR commands must be a multiple of 2 bytes). */
        .length       = I3C_HDR_COMMAND_LENGTH,

        /* Terminate the transfer with a HDR-EXIT. */
        .restart      = false,

        /* Specify if this is a read/write command. */
        .rnw          = false,
    };

    /* Select the HDR mode for subsequent transfers. */
    fsp_err_t status = R_I3C_DeviceSelect(&g_i3c_ctrl, 0, I3C_BITRATE_MODE_I3C_HDR_DDR_STDBR);
    assert(FSP_SUCCESS == status);

    /* Send the command. */
    status = R_I3C_CommandSend(&g_i3c_ctrl, &command_descriptor);
    assert(FSP_SUCCESS == status);

    /* Wait for the command to complete. */
    i3c_app_event_wait(I3C_EVENT_COMMAND_COMPLETE);
}

void i3c_hdr_command_example_callback (i3c_callback_args_t const * const p_args)
{
    switch (p_args->event)
    {
        case I3C_EVENT_COMMAND_COMPLETE:
        {
            /* Notify the application that the command is complete. */
            i3c_app_event_notify(I3C_EVENT_COMMAND_COMPLETE);
            break;
        }

        default:
        {
            break;
        }
    }
}

Data Structures
struct	i3c_clock_stalling_t
struct	i3c_bitrate_settings_t
struct	i3c_ibi_control_t
struct	i3c_slave_command_response_info_t
struct	i3c_instance_ctrl_t
struct	i3c_extended_cfg_t

Macros
#define	I3C_ERROR_RECOVERY_VERSION_1
	Support error recovery procedure for chip version 1. More...
#define	I3C_ERROR_RECOVERY_VERSION_2
	Support error recovery procedure for chip version 2.
#define	I3C_ERROR_RECOVERY_VERSION_BOTH
	Support error recovery procedure for chip version 1 and version 2.
#define	I3C_DEVICE_INDEX_EXTENDED_DEVICE
#define	I3C_EVENT_STATUS_SUCCESS
	The transfer was completed as expected. More...
#define	I3C_EVENT_STATUS_PARITY
	A parity error was detected.
#define	I3C_EVENT_STATUS_FRAME
	A frame error was detected.
#define	I3C_EVENT_STATUS_ADDRESS_HEADER
	An Address Header error wasdetected.
#define	I3C_EVENT_STATUS_NACK
	The transfer was NACK'd.
#define	I3C_EVENT_STATUS_OVERFLOW
	A Receive FIFO overflow or Transmit FIFO underflow occurred.
#define	I3C_EVENT_STATUS_ABORTED_TO_MASTER
	In slave mode, the write transfer was ended via the 'T' bit.
#define	I3C_EVENT_STATUS_ABORTED
	In master mode, the transfer was aborted.
#define	I3C_EVENT_STATUS_NOT_SUPPORTED
	Operation is not supported.
#define	I3C_EVENT_STATUS_IBI_NACK_DISABLED
	An IBI was NACK'd and the a DISEC command was sent.

Enumerations
enum	i3c_bitrate_mode_t
enum	i3c_activity_state_t
enum	i3c_data_rate_setting_t
enum	i3c_clock_data_turnaround_t

---

Data Structure Documentation

i3c_clock_stalling_t

struct i3c_clock_stalling_t

Clock stalling settings.

Data Fields
uint32_t	assigned_address_phase_enable: 1	Enable Clock Stalling during the address phase of the ENTDAA command.
uint32_t	transition_phase_enable: 1	Enable Clock Stalling during the transition bit in read transfers.
uint32_t	parity_phase_enable: 1	Enable Clock Stalling during the parity bit period in write transfers.
uint32_t	ack_phase_enable: 1	Enable Clock Stalling during the ACK/NACK phase.
uint16_t	clock_stalling_time	The amount of time to stall the clock in I3C source clock ticks.

i3c_bitrate_settings_t

struct i3c_bitrate_settings_t

Bitrate settings for configuring the SCL clock frequency.

Data Fields
uint32_t	stdbr	The standard bitrate settings.
uint32_t	extbr	The extended bitrate settings.
i3c_clock_stalling_t	clock_stalling	Clock Stalling settings (See Master Clock Stalling in the MIPI I3C Specification v1.0).

i3c_ibi_control_t

struct i3c_ibi_control_t

Settings for controlling the drivers behavior in response to IBIs.

Data Fields
uint32_t	hot_join_acknowledge: 1	If false, NACK all Hot Join requests.
uint32_t	notify_rejected_hot_join_requests: 1	Notify the application when an IBI Hot-Join request has been NACK'd.
uint32_t	notify_rejected_mastership_requests: 1	Notify the application when an IBI Mastership request has been NACK'd.
uint32_t	notify_rejected_interrupt_requests: 1	Notify the application when an IBI Interrupt request has been NACK'd.

i3c_slave_command_response_info_t

struct i3c_slave_command_response_info_t

Default configuration settings for the slave response to Direct Get Common Command Codes.

Data Fields
bool	inband_interrupt_enable	Enable IBI interrupts. Slave Event Settings (See ENEC and DISEC in the MIPI I3C Specification v1.0).
bool	mastership_request_enable	Enable Mastership requests.
bool	hotjoin_request_enable	Enable Hot-Join requests.
i3c_activity_state_t	activity_state	Starting Activity State (See ENTASn in the MIPI I3C Specification v1.0).
uint16_t	write_length	Max Write Length (See SETMWL and GETMWL in the MIPI I3C Specification v1.0).
uint16_t	read_length	Max Read Length (See SETMRL and GETMRL in the MIPI I3C Specification v1.0).
uint8_t	ibi_payload_length	Number of bytes that will be written by an IBI (See SETMRL and GETMRL in the MIPI I3C Specification v1.0).
i3c_data_rate_setting_t	write_data_rate	Max Write Data Rate. Max Data Rate Settings (See GETMXDS in the MIPI I3C Specification v1.0).
i3c_data_rate_setting_t	read_data_rate	Max Read Data Rate.
i3c_clock_data_turnaround_t	clock_data_turnaround	Max Data Speed Turnaround.
bool	read_turnaround_time_enable	Enable transmission of the of the Max Read Max Read Turnaround Time.
uint32_t	read_turnaround_time	Max Read Turnaround Time.
uint8_t	oscillator_frequency	This byte represents the Slave’s internal oscillator frequency in increments of 0.5 MHz (500kHz), up to 127.5 MHz. (See GETXTIME in the MIPI I3C Specification v1.1).
uint8_t	oscillator_inaccuracy	Oscillator inaccuracy in 0.5% increments of 0% up to 25.5% (See GETXTIME in the MIPI I3C Specification v1.1).
bool	hdr_ddr_support	HDR-DDR mode is supported.
bool	hdr_tsp_support	HDR-TSP mode is supported.
bool	hdr_tsl_support	HDR-TSL mode is supported.

i3c_instance_ctrl_t

struct i3c_instance_ctrl_t

Channel control block. DO NOT INITIALIZE. Initialization occurs when i3c_api_t::open is called.

Public Member Functions
i3c_slave_info_t current_slave_info	BSP_ALIGN_VARIABLE (4)
	The last i3c_slave_info_t read during ENTDAA.
Data Fields
uint32_t	open
	Indicates whether the open() API has been successfully called.
R_I3C0_Type *	p_reg
	Base register for this channel.
volatile uint32_t	internal_state
	Used to track the current state of the driver.
uint8_t	current_command_code
	The current Common Command Code that is being transferred.
uint32_t	device_index
	The device index selected using i3c_api_t::deviceSelect.
i3c_bitrate_mode_t	device_bitrate_mode
	Runtime bitrate settings to use for the next transfer.
uint32_t	next_word
	The next word that will be written to the FIFO.
uint32_t	ibi_next_word
	The next word that will be written to the IBI FIFO.
i3c_write_buffer_descriptor_t	write_buffer_descriptor
	Buffer descriptor for keeping track of a write transfer.
i3c_read_buffer_descriptor_t	read_buffer_descriptor
	Buffer descriptor for keeping track of a read transfer.
i3c_read_buffer_descriptor_t	ibi_buffer_descriptor
	Buffer descriptor for keeping track of an IBI read/write transfer.
volatile uint32_t	read_transfer_count_final
	The total number of bytes read during a read transfer.
volatile uint32_t	ibi_transfer_count_final
	The total number of bytes read during an IBI transfer.
i3c_cfg_t const *	p_cfg
	A pointer to the configuration structure provided during open.

i3c_extended_cfg_t

struct i3c_extended_cfg_t

Extended configuration for r_i3c.

Data Fields
i3c_bitrate_settings_t	bitrate_settings	Bitrate settings configuring the frequency and duty cycle for SCL.
i3c_ibi_control_t	ibi_control	Configure the driver's behavior in response to IBIs.
uint32_t	bus_free_detection_time	The time in I3C reference clock ticks needed in order to detect the bus free condition (See "Bus Free Condition" in the MIPI I3C Specification v1.0).
uint32_t	bus_available_detection_time	The time in I3C reference clock ticks needed in order to detect the bus available condition (See "Bus Available Condition" in the MIPI I3C Specification v1.0).
uint32_t	bus_idle_detection_time	The time in I3C reference clock ticks needed in order to detect the bus idle condition (See "Bus Idle Condition" in the MIPI I3C Specification v1.0).
bool	timeout_detection_enable	Notify the application if SCL is stuck high or low.
i3c_slave_command_response_info_t	slave_command_response_info	Initial settings for configuring the slave's responses to received commands.
IRQn_Type	resp_irq	Response Queue Full IRQ number.
IRQn_Type	rx_irq	Receive FIFO Full IRQ number.
IRQn_Type	tx_irq	Transmit FIFO Empty IRQ number.
IRQn_Type	rcv_irq	Receive Status Queue Full IRQ number.
IRQn_Type	ibi_irq	IBI IRQ number.
IRQn_Type	eei_irq	EEI IRQ number.
uint8_t	ipl	Interrupt Priority for Resp, Rx, Tx, and RCV IRQs.
uint8_t	eei_ipl	Error and Event Interrupt Priority.

Macro Definition Documentation

I3C_ERROR_RECOVERY_VERSION_1

#define I3C_ERROR_RECOVERY_VERSION_1

Support error recovery procedure for chip version 1.

There are two different versions of the RA2E2 MCU and the error recovery procedure is different for each version.

I3C_DEVICE_INDEX_EXTENDED_DEVICE

#define I3C_DEVICE_INDEX_EXTENDED_DEVICE

Index for selecting the device defined in the extended address table.

I3C_EVENT_STATUS_SUCCESS

#define I3C_EVENT_STATUS_SUCCESS

The transfer was completed as expected.

Event Status Provided by the callback.

Enumeration Type Documentation

i3c_bitrate_mode_t

enum i3c_bitrate_mode_t

Bitrate settings that can be selected at run-time using i3c_api_t::deviceSelect.

Enumerator
I3C_BITRATE_MODE_I2C_STDBR	Use standard period setting for subsequent I2C transfers.
I3C_BITRATE_MODE_I2C_EXTBR	Use extended period setting for subsequent I2C transfers.
I3C_BITRATE_MODE_I3C_SDR0_STDBR	Use standard period setting for subsequent I3C SDR transfers.
I3C_BITRATE_MODE_I3C_SDR1_EXTBR	Use extended period setting for subsequent I3C SDR transfers.
I3C_BITRATE_MODE_I3C_SDR2_STDBR_X2	Use standard period setting x 2 for subsequent I3C SDR transfers.
I3C_BITRATE_MODE_I3C_SDR3_EXTBR_X2	Use extended period setting x 2 for subsequent I3C SDR transfers.
I3C_BITRATE_MODE_I3C_SDR4_EXTBR_X4	Use extended period setting x 4 for subsequent I3C SDR transfers.
I3C_BITRATE_MODE_I3C_HDR_DDR_STDBR	Use standard period setting for subsequent I3C HDR-DDR transfers.

i3c_activity_state_t

enum i3c_activity_state_t

Supported activity states for ENTASn Command (See ENTASn in the MIPI I3C Specification v1.0).

Enumerator
I3C_ACTIVITY_STATE_ENTAS0	Activity Interval (1 microsecond).
I3C_ACTIVITY_STATE_ENTAS1	Activity Interval (100 microseconds).
I3C_ACTIVITY_STATE_ENTAS2	Activity Interval (2 milliseconds).
I3C_ACTIVITY_STATE_ENTAS3	Activity Interval (50 milliseconds).

i3c_data_rate_setting_t

enum i3c_data_rate_setting_t

Maximum Sustained Data Rate for non-CCC messages sent by Master Device to Slave Device (See GETMXDS in the MIPI I3C Specification v1.0).

Enumerator
I3C_DATA_RATE_SETTING_FSCL_MAX	There is no data rate limit.
I3C_DATA_RATE_SETTING_8MHZ	The max sustained data rate is 8 Mhz.
I3C_DATA_RATE_SETTING_6MHZ	The max sustained data rate is 6 Mhz.
I3C_DATA_RATE_SETTING_4MHZ	The max sustained data rate is 4 Mhz.
I3C_DATA_RATE_SETTING_2MHZ	The max sustained data rate is 2 Mhz.

i3c_clock_data_turnaround_t

enum i3c_clock_data_turnaround_t

Clock to Data Turnaround Time (See GETMXDS in the MIPI I3C Specification v1.0).

Enumerator
I3C_CLOCK_DATA_TURNAROUND_8NS	Clock to turnaround time is 8 nanoseconds or less.
I3C_CLOCK_DATA_TURNAROUND_9NS	Clock to turnaround time is 9 nanoseconds or less.
I3C_CLOCK_DATA_TURNAROUND_10NS	Clock to turnaround time is 10 nanoseconds or less.
I3C_CLOCK_DATA_TURNAROUND_11NS	Clock to turnaround time is 11 nanoseconds or less.
I3C_CLOCK_DATA_TURNAROUND_12NS	Clock to turnaround time is 12 nanoseconds or less.
I3C_CLOCK_DATA_TURNAROUND_EXTENDED	Clock to turnaround time is greater than 12 nanoseconds.

Function Documentation

R_I3C_Open()

fsp_err_t R_I3C_Open	(	i3c_ctrl_t *const	p_api_ctrl,
		i3c_cfg_t const *const	p_cfg
	)

Configure an I3C instance. Implements i3c_api_t::open.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was invalid.
FSP_ERR_ALREADY_OPEN	Open has already been called for this instance.
FSP_ERR_UNSUPPORTED	A selected feature is not supported with the current configuration.

R_I3C_Enable()

fsp_err_t R_I3C_Enable

(

i3c_ctrl_t *const

p_api_ctrl

)

Enable the I3C device.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_INVALID_MODE	This instance is already enabled.

R_I3C_DeviceCfgSet()

fsp_err_t R_I3C_DeviceCfgSet	(	i3c_ctrl_t *const	p_api_ctrl,
		i3c_device_cfg_t const *const	p_device_cfg
	)

Set the configuration for this device.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_UNSUPPORTED	The device cannot be a secondary master if master support is disabled.

R_I3C_MasterDeviceTableSet()

fsp_err_t R_I3C_MasterDeviceTableSet	(	i3c_ctrl_t *const	p_api_ctrl,
		uint32_t	device_index,
		i3c_device_table_cfg_t const *const	p_device_table_cfg
	)

Configure an entry in the master device table. This function is called in master mode in order to configure the devices on the I3C bus. It may also be called in slave mode when the slave receives the DEFSVLS command.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_UNSUPPORTED	Mastership requests must be rejected is slave support is disabled.

R_I3C_SlaveStatusSet()

fsp_err_t R_I3C_SlaveStatusSet	(	i3c_ctrl_t *const	p_api_ctrl,
		i3c_device_status_t	status
	)

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

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_INVALID_MODE	The instance is not in slave mode.
FSP_ERR_UNSUPPORTED	Slave support is disabled.

R_I3C_DeviceSelect()

fsp_err_t R_I3C_DeviceSelect	(	i3c_ctrl_t *const	p_api_ctrl,
		uint32_t	device_index,
		uint32_t	bitrate_mode
	)

In master mode, select the device for the next transfer. This function is not used in slave mode.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_INVALID_MODE	This operation is prohibited in slave mode.
FSP_ERR_UNSUPPORTED	Master support is disabled.

R_I3C_DynamicAddressAssignmentStart()

fsp_err_t R_I3C_DynamicAddressAssignmentStart	(	i3c_ctrl_t *const	p_api_ctrl,
		i3c_address_assignment_mode_t	address_assignment_mode,
		uint32_t	starting_device_index,
		uint32_t	device_count
	)

Start the Dynamic Address Assignment Process. Implements i3c_api_t::dynamicAddressAssignmentStart.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL or invalid.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_INVALID_MODE	This operation is prohibited in slave mode.
FSP_ERR_IN_USE	The operation could not be completed because the driver is busy.
FSP_ERR_UNSUPPORTED	Master support is disabled.

R_I3C_CommandSend()

fsp_err_t R_I3C_CommandSend	(	i3c_ctrl_t *const	p_api_ctrl,
		i3c_command_descriptor_t const *const	p_command_descriptor
	)

Send a broadcast or direct command to slave devices on the bus. Implements i3c_api_t::commandSend.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_IN_USE	The operation could not be completed because the driver is busy.
FSP_ERR_INVALID_MODE	This driver is not in master mode.
FSP_ERR_INVALID_ALIGNMENT	The buffer must be aligned to 4 bytes. If it is a read operation, the length also be a multiple of 4 bytes.
FSP_ERR_UNSUPPORTED	Master support must be enabled to call this function. Slave support must be enabled when sending the GETACCMST command.

R_I3C_Write()

fsp_err_t R_I3C_Write	(	i3c_ctrl_t *const	p_api_ctrl,
		uint8_t const *const	p_data,
		uint32_t	length,
		bool	restart
	)

Set the write buffer for the transfer. In master mode, start the transfer. When the transfer is completed send a stop condition or a repeated-start. Implements i3c_api_t::write.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_IN_USE	The operation could not be completed because the driver is busy.
FSP_ERR_INVALID_MODE	This driver is disabled, or an invalid bitrate mode is selected.
FSP_ERR_INVALID_ALIGNMENT	The buffer must be aligned to 4 bytes.

R_I3C_Read()

fsp_err_t R_I3C_Read	(	i3c_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_data,
		uint32_t	length,
		bool	restart
	)

Set the read buffer for the transfer. In master mode, start the transfer. When the transfer is completed send a stop condition or a repeated-start. Implements i3c_api_t::read.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_IN_USE	The operation could not be completed because the driver is busy.
FSP_ERR_INVALID_MODE	This driver is disabled, or an invalid bitrate mode is selected.
FSP_ERR_INVALID_ALIGNMENT	The buffer must be aligned to 4 bytes and the length must be a multiple of 4 bytes.

R_I3C_IbiWrite()

fsp_err_t R_I3C_IbiWrite	(	i3c_ctrl_t *const	p_api_ctrl,
		i3c_ibi_type_t	ibi_type,
		uint8_t const *const	p_data,
		uint32_t	length
	)

Initiate an IBI write operation (This function is only used in slave mode).

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_IN_USE	The operation could not be completed because the driver is busy.
FSP_ERR_INVALID_MODE	This function is only called in slave mode.
FSP_ERR_INVALID_ALIGNMENT	The buffer must be aligned to 4 bytes.
FSP_ERR_UNSUPPORTED	Slave supoprt is disabled.

R_I3C_IbiRead()

fsp_err_t R_I3C_IbiRead	(	i3c_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_data,
		uint32_t	length
	)

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

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.
FSP_ERR_INVALID_MODE	This function is only called in master mode.
FSP_ERR_INVALID_ALIGNMENT	The buffer must be aligned to 4 bytes and the length must be a multiple of 4 bytes.
FSP_ERR_UNSUPPORTED	Master support is disabled.

R_I3C_Close()

fsp_err_t R_I3C_Close

(

i3c_ctrl_t *const

p_api_ctrl

)

Close the I3C instance. Implements i3c_api_t::close.

Return values

FSP_SUCCESS	Open successful.
FSP_ERR_ASSERTION	An argument was NULL.
FSP_ERR_NOT_OPEN	This instance has not been opened yet.