I3C 主机接口

[English]

本文介绍了 ESP-IDF 的 I3C 主机驱动功能，章节目录如下：

概述

I3C (Improved Inter‑Integrated Circuit) 是一种串行同步半双工通信协议，是 I2C 协议的增强版本。I3C 在保持与 I2C 大部分功能兼容的同时，提供了更高的速度、更低的功耗和更丰富的功能。

关于 I3C 的硬件相关信息，请参考 I3C 技术参考手册。

I3C 协议的主要特性包括：

• 向后兼容 I2C：I3C 总线可以同时支持 I2C 设备和 I3C 设备

• 更高的速度：I3C 速度最高可达 12.5 MHz，I2C 最高速度可达 1 MHz

• 静态地址分配：通过 SETDASA 过程手动根据静态地址分配动态地址

• 动态地址分配：通过 ENTDAA 过程自动分配动态地址，避免地址冲突

• 带内中断（IBI）：支持从机通过 I3C 总线发送中断请求，无需额外的中断线

• 公共命令码（CCC）：支持广播和直接 CCC 命令，用于总线管理和设备配置

重要

1. 当兼容 I2C 设备时，请确保在 I3C 总线上挂载的 I2C 设备 不启用 时钟拉伸功能，否则当 I2C 从机拉伸时钟时会导致硬件状态机卡死。

2. I3C 的频率取决于电路设计和时序调整，具体请参考使用的 I3C 设备手册。

3. 部分 I3C 从机设备的应答机制（ACK/NACK）有严格的时序限制，请参考所使用的 I3C 从机设备手册。

快速入门

本节将带你快速了解如何使用 I3C 主机驱动。通过实际的使用场景，展示如何创建总线、添加设备并进行数据传输。一般的使用流程如下：

I3C 驱动的一般使用流程（点击图片查看大图）

创建 I3C 总线

I3C 主机总线在驱动程序中使用 i3c_master_bus_handle_t 来表示。驱动内部维护了一个资源池，可管理多条总线，并在有请求时分配空闲的总线端口。

I3C 总线结构

当创建 I3C 总线实例时，我们需要通过 i3c_master_bus_config_t 配置 GPIO 引脚、时钟源、频率等参数。这些参数将决定总线的工作方式。以下代码展示了如何创建一个基本的 I3C 总线：

#include "driver/i3c_master.h"

i3c_master_bus_config_t i3c_mst_config = {
    .sda_io_num = I3C_MASTER_SDA_IO,        // SDA 信号线的 GPIO 编号
    .scl_io_num = I3C_MASTER_SCL_IO,        // SCL 信号线的 GPIO 编号
    .i3c_scl_freq_hz_od = 600 * 1000,       // Open-Drain 模式下的 SCL 时钟频率，请参考设备手册获取合适的值
    .i3c_scl_freq_hz_pp = 2 * 1000 * 1000,  // Push-Pull 模式下的 SCL 时钟频率，请参考设备手册获取合适的值
    .i3c_sda_od_hold_time_ns = 25, // Open-Drain 模式下 SDA 在 SCL 下降沿后的保持时间（纳秒），建议设置为 25，请参考设备手册获取合适的值
    .i3c_sda_pp_hold_time_ns = 0,  // Push-Pull 模式下 SDA 在 SCL 下降沿后的保持时间（纳秒），默认值为 0，请参考设备手册获取合适的值
    .entdaa_device_num = 0,        // 最大允许通过 ENTDAA 动态发现的设备数量，范围从 [0x0, 0x7F]，0x0 表示不使用动态设备发现
};

i3c_master_bus_handle_t bus_handle;
ESP_ERROR_CHECK(i3c_new_master_bus(&i3c_mst_config, &bus_handle));

备注

I3C 协议需要在每次传输过程中在寻址过程与数据传输过程之间自动切换开漏和推挽模式。在 ESP32-P4 上，只有 GPIO32/GPIO33 支持自动打开/关闭内部上拉开关且支持用户调整内部上拉阻值。当使用其他 GPIO 时内部上拉不足建议额外添加外部上拉电阻，但此时在推挽模式下该上拉不可取消，可能会增加额外功耗。

添加并驱动传统 I2C 设备

写入传统 I2C 设备

从传统 I2C 设备读取

I3C 总线支持和传统的 I2C 设备兼容，如果你需要在 I3C 总线上连接一个传统的 I2C 设备（例如 EEPROM、传感器等），请务必注意，I2C 从机不可在与 I3C 通信时发生时钟拉伸，具体流程可以使用以下方式：

// 1. 创建 I3C 总线（参考上面的代码）
i3c_master_bus_handle_t bus_handle;
ESP_ERROR_CHECK(i3c_new_master_bus(&i3c_mst_config, &bus_handle));

// 2. 添加 I2C 设备
i3c_device_i2c_config_t i2c_dev_cfg = {
    .device_address = 0x50,        // I2C 设备的 7 位地址
    .scl_freq_hz = 100 * 1000,     // I2C 设备的时钟频率（100 kHz）
};
i3c_master_i2c_device_handle_t i2c_dev_handle;
ESP_ERROR_CHECK(i3c_master_bus_add_i2c_device(bus_handle, &i2c_dev_cfg, &i2c_dev_handle));

// 3. 写入数据到 I2C 设备
uint8_t write_data[10] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A};
ESP_ERROR_CHECK(i3c_master_i2c_device_transmit(i2c_dev_handle, write_data, sizeof(write_data), -1)); // -1 表示传输超时时间为无限长

// 4. 从 I2C 设备读取数据
uint8_t read_data[10] = {0};
ESP_ERROR_CHECK(i3c_master_i2c_device_receive(i2c_dev_handle, read_data, sizeof(read_data), -1));

// 5. 写入-读取组合事务（先写寄存器地址，再读数据，中间没有 STOP）
uint8_t reg_addr = 0x00;
uint8_t read_buffer[5] = {0};
ESP_ERROR_CHECK(i3c_master_i2c_device_transmit_receive(i2c_dev_handle, &reg_addr, 1, read_buffer, sizeof(read_buffer), -1));

// 6. 清理资源
ESP_ERROR_CHECK(i3c_master_bus_rm_i2c_device(i2c_dev_handle));
ESP_ERROR_CHECK(i3c_del_master_bus(bus_handle));

在这个场景中，我们：

1. 通过 i3c_new_master_bus() 创建了一个 I3C 总线实例

2. 通过 i3c_master_bus_add_i2c_device() 添加了一个 I2C 设备，需要指定设备的静态地址和时钟频率

3. 使用 i3c_master_i2c_device_transmit() 写入数据，默认为阻塞模式，在非阻塞模式下工作请参考 关于 DMA 和异步传输，其它传输函数同理。

4. 使用 i3c_master_i2c_device_receive() 读取数据

5. 使用 i3c_master_i2c_device_transmit_receive() 执行写入-读取组合事务（常用于先写寄存器地址再读数据，中间没有停止位）

6. 最后清理资源

通过 SETDASA 添加并驱动 I3C 设备

对 I3C 传输过程中可能出现的具体行为，请参考标准 I3C 协议。该图例用作简要解释 I3C 传输中的行为以理解本文档中出现的 I3C 传输示意图：

I3C 传输图例

如果你知道 I3C 设备的静态地址，可以使用 SETDASA 方式添加设备：

I3C 定向动态地址分配

// 1. 创建 I3C 总线
i3c_master_bus_handle_t bus_handle;
ESP_ERROR_CHECK(i3c_new_master_bus(&i3c_mst_config, &bus_handle));

// 2. 添加 I3C 设备（使用 SETDASA）
i3c_device_i3c_config_t i3c_dev_cfg = {
    .dynamic_addr = 0x08,          // 为设备分配的动态地址，可以是除了 I3C 协议中规定为保留地址外的任意值，也可以通过 `i3c_master_get_valid_address_slot` 获取一个可用的动态地址
    .static_addr = 0x74,            // 设备的静态地址（从设备手册获取）
};
i3c_master_i3c_device_handle_t i3c_dev_handle;
ESP_ERROR_CHECK(i3c_master_bus_add_i3c_static_device(bus_handle, &i3c_dev_cfg, &i3c_dev_handle));

// 3. 写入数据到 I3C 设备
uint8_t write_data[100] = {0};
ESP_ERROR_CHECK(i3c_master_i3c_device_transmit(i3c_dev_handle, write_data, sizeof(write_data), -1));

// 4. 从 I3C 设备读取数据
uint8_t read_data[100] = {0};
ESP_ERROR_CHECK(i3c_master_i3c_device_receive(i3c_dev_handle, read_data, sizeof(read_data), -1));

// 5. 写入-读取组合事务
uint8_t reg_addr = 0x12;
uint8_t read_buffer[10] = {0};
ESP_ERROR_CHECK(i3c_master_i3c_device_transmit_receive(i3c_dev_handle, &reg_addr, 1, read_buffer, sizeof(read_buffer), -1));

// 6. 清理资源
ESP_ERROR_CHECK(i3c_master_bus_rm_i3c_device(i3c_dev_handle));
ESP_ERROR_CHECK(i3c_del_master_bus(bus_handle));

在这个场景中：

1. 我们使用 i3c_master_bus_add_i3c_static_device() 添加 I3C 设备

2. 需要提供设备的静态地址（从设备手册获取）和要分配的动态地址

3. 驱动程序会自动执行 SETDASA 过程，将动态地址分配给设备, 若地址冲突会返回 ESP_ERR_INVALID_STATE。

4. 之后可以使用动态地址 通过 i3c_master_i3c_device_transmit() 或 i3c_master_i3c_device_receive() 或 i3c_master_i3c_device_transmit_receive() 进行数据传输，默认为阻塞模式，在非阻塞模式下工作请参考 关于 DMA 和异步传输，其它传输函数同理。

5. 最后清理资源

通过 ENTDAA 添加并驱动 I3C 设备

如果你不知道总线上有哪些 I3C 设备，或者想让系统自动发现和分配地址，可以使用 ENTDAA 方式：

I3C 自动动态地址分配

// 1. 创建 I3C 总线（需要设置 entdaa_device_num）
i3c_master_bus_config_t i3c_mst_config = {
    // ... 其他配置 ...
    .entdaa_device_num = 5,        // 驱动最大可以动态发现的设备数量
};
i3c_master_bus_handle_t bus_handle;
ESP_ERROR_CHECK(i3c_new_master_bus(&i3c_mst_config, &bus_handle));

// 2. 扫描总线上的 I3C 设备
i3c_master_i3c_device_table_handle_t table_handle = NULL;
ESP_ERROR_CHECK(i3c_master_scan_devices_by_entdaa(bus_handle, &table_handle));

// 3. 获取发现的设备数量
size_t device_count = 0;
ESP_ERROR_CHECK(i3c_master_get_device_count(table_handle, &device_count));
printf("Found %zu I3C devices\n", device_count);

// 4. 遍历所有设备并获取设备信息
i3c_master_i3c_device_handle_t dev = NULL;
for (size_t i = 0; i < device_count; i++) {
    i3c_master_i3c_device_handle_t dev_handle = NULL;
    ESP_ERROR_CHECK(i3c_master_get_device_handle(table_handle, i, &dev_handle));

    // 获取设备信息
    i3c_device_information_t info;
    ESP_ERROR_CHECK(i3c_master_i3c_device_get_info(dev_handle, &info));
    printf("Device %d: Dynamic Addr=0x%02X, BCR=0x%02X, DCR=0x%02X, PID=0x%016llX\n",
           i, info.dynamic_addr, info.bcr, info.dcr, info.pid);

    if (info.pid == /* 设备 PID，从设备手册获取 */) {
        dev = dev_handle;
        break;
    }
}
// 释放设备句柄表，不再需要时调用
ESP_ERROR_CHECK(i3c_master_free_device_handle_table(table_handle));

// 5. 通过 transmit 或 receive 进行数据传输
ESP_ERROR_CHECK(i3c_master_i3c_device_transmit(dev, data, sizeof(data), -1));
ESP_ERROR_CHECK(i3c_master_i3c_device_receive(dev, data, sizeof(data), -1));

在这个场景中：

1. 创建总线时需要设置 entdaa_device_num，表示预期发现的设备数量

2. 使用 i3c_master_scan_devices_by_entdaa() 扫描总线上的所有 I3C 设备

3. 系统会自动为每个设备分配动态地址

4. 可以通过 i3c_master_get_device_count() 获取设备数量

5. 通过 i3c_master_get_device_handle() 获取每个设备的句柄

6. 使用 i3c_master_i3c_device_get_info() 可以获取设备的详细信息（动态地址、BCR、DCR、PID）

7. 根据获得的设备信息通过 i3c_master_i3c_device_transmit() 或 i3c_master_i3c_device_receive() 进行数据传输

备注

i3c_master_scan_devices_by_entdaa() 是线程安全的，不会有两个线程同时寻址的情况。根据协议，当从机被 i3c_master_scan_devices_by_entdaa() 寻址发现后，不再具有响应第二次寻址的能力。因此不会出现因为在不同线程寻址而导致的地址变化的情况。该接口支持在初始化后新增设备。若要重新扫描，请用 CCC 机制重置 I3C 总线上的地址，或通过重新上电清除总线上的地址信息。

公共命令码（CCC）传输

I3C 协议使用公共命令码（CCC）进行总线管理和设备配置。可以使用 i3c_master_transfer_ccc() 函数来发送 CCC 命令。

CCC 传输可以是广播的（发送给所有设备）或直接的（发送给特定设备）：

I3C 广播命令

I3C 直接命令

// 广播 CCC 命令示例：发送 RSTDAA（重置所有动态地址）
i3c_master_ccc_transfer_config_t ccc_trans = {
    .ccc_command = I3C_CCC_RSTDAA,
    .direction = I3C_MASTER_TRANSFER_DIRECTION_WRITE,
    .device_address = 0,  // 广播命令，此字段被忽略
    .data = NULL,
    .data_size = 0,
};
ESP_ERROR_CHECK(i3c_master_transfer_ccc(bus_handle, &ccc_trans));

// 直接 CCC 命令示例：读取设备的 GETPID（获取设备 ID）
uint8_t pid_data[6] = {0};
ccc_trans = (i3c_master_ccc_transfer_config_t) {
    .ccc_command = I3C_CCC_GETPID,
    .direction = I3C_MASTER_TRANSFER_DIRECTION_READ,
    .device_address = 0x08,  // 目标设备地址，为动态地址
    .data = pid_data,
    .data_size = sizeof(pid_data),
};
ESP_ERROR_CHECK(i3c_master_transfer_ccc(bus_handle, &ccc_trans));

备注

i3c_master_transfer_ccc() 永远是阻塞的，不受到 DMA 和异步配置的影响。用户需要通过查询 I3C 协议获知 CCC 命令的具体格式，根据下发命令或获取数值的格式填充 i3c_master_ccc_transfer_config_t::direction 为 I3C_MASTER_TRANSFER_DIRECTION_READ 或 I3C_MASTER_TRANSFER_DIRECTION_WRITE 并填充 i3c_master_ccc_transfer_config_t::data 和 i3c_master_ccc_transfer_config_t::data_size。

资源回收

当不再需要之前安装的 I3C 总线或设备，请调用 i3c_master_bus_rm_i3c_device() 或 i3c_master_bus_rm_i2c_device() 来删除设备，然后调用 i3c_del_master_bus() 来回收资源，以释放底层硬件。

ESP_ERROR_CHECK(i3c_master_bus_rm_i3c_device(i3c_dev_handle));
ESP_ERROR_CHECK(i3c_del_master_bus(bus_handle));

高级功能

时钟及时序参数微调

时钟源选择

I3C 总线的时钟源可以通过 i3c_master_bus_config_t::clock_source 进行选择。

i3c_master_bus_config_t i3c_mst_config = {
    // ... 其他配置 ...
    .clock_source = I3C_MASTER_CLK_SRC_DEFAULT, // 默认时钟源
};

备注

当 I3C 推挽输出频率大于 3 MHz 时，请将时钟源设置为 i3c_master_clock_source_t::I3C_MASTER_CLK_SRC_PLL_F120M 或 i3c_master_clock_source_t::I3C_MASTER_CLK_SRC_PLL_F160M。

I3C 驱动提供了丰富的时序参数配置选项，可以根据实际硬件情况调整这些参数以优化性能或解决时序问题。

占空比和保持时间

部分 I3C 从机设备的应答机制（ACK/NACK）有严格的时序限制，比如对 SCL 波形的占空比的要求以及对 SDA 保持时间的要求，这些参数可通过以下配置项进行配置。

i3c_master_bus_config_t i3c_mst_config = {
    // ... 其他配置 ...
    .i3c_scl_pp_duty_cycle = 0.5,   // Push-Pull 模式占空比，通常为 0.5 (默认值 0 时占空比也为 0.5)
    .i3c_scl_od_duty_cycle = 0.5,   // Open-Drain 模式占空比，通常为 0.5 (默认值 0 时占空比也为 0.5)
    .i3c_sda_od_hold_time_ns = 25,   // Open-Drain 模式保持时间，默认 25 ns
    .i3c_sda_pp_hold_time_ns = 0,    // Push-Pull 模式保持时间，默认 0 ns
};

这些参数的具体值需要根据设备手册和实际测试来确定。

关于事件回调函数

I3C 驱动支持事件回调机制，可以在传输完成或收到 IBI 中断时通知应用程序。

当 I3C 控制器生成发送或接收完成等事件时，会通过中断告知 CPU。如果需要在发生特定事件时调用函数，可以为 I3C 和 I2C 从机分别调用 i3c_master_i3c_device_register_event_callbacks() 和 i3c_master_i2c_device_register_event_callbacks()，向 I3C 驱动程序的中断服务程序 (ISR) 注册事件回调。由于上述回调函数是在 ISR 中调用的，因此，这些函数不应涉及阻塞操作。可以检查调用 API 的后缀，确保在函数中只调用了后缀为 ISR 的 FreeRTOS API。回调函数具有布尔返回值，指示回调是否解除了更高优先级任务的阻塞状态。

有关 I2C 从机的事件回调，请参阅 i2c_master_i2c_event_callbacks_t。

• i3c_master_i2c_event_callbacks_t::on_trans_done 可设置用于主机“传输完成”事件的回调函数。该函数原型在 i3c_master_i2c_callback_t 中声明。请注意，当 I2C 从机设备使能 DMA 且使用异步传输时，才能使用该回调函数，具体请参考 关于 DMA 和异步传输。

有关 I3C 从机的事件回调，请参阅 i3c_master_i3c_event_callbacks_t。

• i3c_master_i3c_event_callbacks_t::on_trans_done 可设置用于主机“传输完成”事件的回调函数。该函数原型在 i3c_master_i3c_callback_t 中声明。请注意，当 I3C 从机设备使能 DMA 且使用异步传输时，才能使用该回调函数，具体请参考 关于 DMA 和异步传输。

• i3c_master_i3c_event_callbacks_t::on_ibi 可设置用于 IBI 事件的回调函数。该函数原型在 i3c_master_ibi_callback_t 中声明, 关于 IBI 事件的详细信息请参阅 关于带内中断（IBI）

备注

回调函数在 ISR 上下文中执行，因此：

• 不能执行阻塞操作

• 只能调用后缀为 ISR 的 FreeRTOS API

• 如果启用了 CONFIG_I3C_MASTER_ISR_CACHE_SAFE，回调函数必须放在 IRAM 中

关于带内中断（IBI）

I3C 协议支持带内中断（IBI），允许从机设备通过 I3C 总线发送中断请求，无需额外的中断线。

配置 IBI

I3C 总线配置结构体 i3c_master_bus_config_t 中包含 IBI 相关的全局配置项：

• i3c_master_bus_config_t::ibi_rstart_trans_en 在 IBI 上启用重启事务，I3C 控制器在 IBI 完成后继续执行之前被 IBI 中断的命令。若 IBI 发生在总线空闲期间，且 I3C 传输任务非空，则 I3C 控制器将继续执行该任务。若 IBI 与 I3C 控制器传输冲突，并赢得仲裁，则 IBI 处理完成后会继续执行被打断的任务。

• i3c_master_bus_config_t::ibi_silent_sir_rejected 当写入为 0 时，当从机中断请求（SIR）被拒绝时不通知应用层。当写入为 1 时，仍将 IBI 状态写入 IBI FIFO，并通知应用层。

• i3c_master_bus_config_t::ibi_no_auto_disable 如果设置，在控制器 NACK In-Band 中断后，不自动禁用 IBI，保持带内中断使能。

可以使用 i3c_master_i3c_device_ibi_config() 函数为特定设备配置 IBI：

i3c_ibi_config_t ibi_cfg = {
    .enable_ibi = true,
    .enable_ibi_payload = true,  // 允许 IBI 携带有效载荷
};
ESP_ERROR_CHECK(i3c_master_i3c_device_ibi_config(dev_handle, &ibi_cfg));

处理 IBI 事件

IBI 事件的详细信息将通过 i3c_master_ibi_info_t 从回调中给出：

i3c_master_ibi_info_t::ibi_id 是 IBI 的原始标识符，通常编码自从机设备的动态地址；它是原始值，即 动态地址 + 读/写位。 i3c_master_ibi_info_t::ibi_sts 是 IBI 状态字段，由控制器报告。i3c_master_ibi_info_t::data_length 是有效载荷缓冲区 i3c_master_ibi_info_t::ibi_data 中的有效字节数。 i3c_master_ibi_info_t::ibi_data 是与 IBI 关联的可选有效载荷。只有前 i3c_master_ibi_info_t::data_length 字节是有效的。

static bool i3c_ibi_callback(i3c_master_i3c_device_handle_t dev_handle, const i3c_master_ibi_info_t *ibi_info, void *user_ctx)
{
    // 可以将 IBI 事件数据复制到用户提供的上下文中, 并在任务中做进一步处理
    // i3c_master_ibi_event_t 是用户自定定义的结构体，在这里包括了ibi_id 和 ibi_data_len，可根据实际需求增删成员
    i3c_master_ibi_event_t evt = {
        .ibi_id = ibi_info->ibi_id,
        .ibi_data_len = ibi_info->data_length,
    };

    return false;
}

i3c_master_i3c_event_callbacks_t cbs = {
    .on_ibi = i3c_ibi_callback,
};
ESP_ERROR_CHECK(i3c_master_i3c_device_register_event_callbacks(dev_handle, &cbs, NULL));

关于 DMA 和异步传输

I3C 驱动程序支持 DMA 来支持大容量数据传输和异步传输，可以提高传输效率并减少 CPU 占用。

启用 DMA

可以通过 i3c_master_bus_decorate_dma() 函数为总线配置 DMA：

i3c_master_dma_config_t dma_config = {
    .max_transfer_size = 4096,  // 最大传输大小（字节）
    .dma_burst_size = 16,       // DMA 突发大小（字节）
};
ESP_ERROR_CHECK(i3c_master_bus_decorate_dma(bus_handle, &dma_config));

启用异步传输

当 DMA 被启用时，可以进一步启用异步传输以提高性能：

i3c_master_bus_config_t i3c_mst_config = {
    // ... 其他配置 ...
    .trans_queue_depth = 5,  // 设置内部传输队列的深度
    .flags = {
        .enable_async_trans = 1,  // 启用异步传输
    }
};

此时，I3C 主机的传输类函数被调用后会立即返回，当每一次传输完成后会调用 i3c_master_i3c_event_callbacks_t::on_trans_done 回调函数表示一次传输的完成。如果需要等待传输完成，可以调用 i3c_master_bus_wait_all_done() 函数来等待所有传输完成：

// 启动多个异步传输
ESP_ERROR_CHECK(i3c_master_i3c_device_transmit(dev_handle1, data1, size1, -1));
ESP_ERROR_CHECK(i3c_master_i3c_device_transmit(dev_handle2, data2, size2, -1));
ESP_ERROR_CHECK(i3c_master_i3c_device_transmit(dev_handle3, data3, size3, -1));

// 等待所有传输完成
ESP_ERROR_CHECK(i3c_master_bus_wait_all_done(bus_handle, -1));

线程安全

I3C 驱动程序的以下函数是线程安全的，可以从不同的 RTOS 任务调用，无需额外的锁保护：

工厂函数：

• i3c_new_master_bus()

• i3c_del_master_bus()

I3C 主机操作函数（通过总线操作信号保证线程安全）：

• i3c_master_bus_add_i3c_static_device()

• i3c_master_bus_rm_i3c_device()

• i3c_master_i3c_device_transmit()

• i3c_master_i3c_device_receive()

• i3c_master_i3c_device_transmit_receive()

• i3c_master_i2c_device_transmit()

• i3c_master_i2c_device_receive()

• i3c_master_i2c_device_transmit_receive()

• i3c_master_transfer_ccc()

Cache 安全

默认情况下，当 cache 被禁用时（例如 SPI Flash 写入时），I3C 中断会被延迟，事件回调函数将无法按时执行，会影响实时应用的系统响应。

可以通过启用 Kconfig 选项 CONFIG_I3C_MASTER_ISR_CACHE_SAFE 来避免此种情况发生，启用后：

1. 即使在 cache 被禁用的情况下，中断仍可继续运行

2. 将 ISR 使用的所有函数放入 IRAM 中

3. 将驱动程序对象放入 DRAM 中（以防它被意外映射到 PSRAM 中）

启用该选项可以保证 cache 禁用时的中断运行，但会占用更多的 IRAM。

备注

启用此选项后，当 cache 被禁用时，ISR 回调函数将继续运行。因此，必须确保回调函数及其上下文也是 IRAM 安全的。同时，数据传输的 buffer 也必须放在 DRAM 中。

关于低功耗

当启用电源管理 CONFIG_PM_ENABLE 时，系统在进入睡眠模式前可能会调整或禁用时钟源，从而导致 I3C 传输出错。

为了防止这种情况发生， I3C 驱动内部创建了一个电源管理锁。当调用传输函数后，该锁将被激活，确保系统不会进入睡眠模式，从而保持定时器的正确工作，直至传输完成后，驱动自动释放该锁。使系统能够进入睡眠模式。

Kconfig 选项

以下 Kconfig 选项可用于配置 I3C 驱动程序：

• CONFIG_I3C_MASTER_ISR_CACHE_SAFE：确保 I3C 中断在缓存被禁用时也能正常工作（例如 SPI Flash 写入时）

• CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM：将 I3C 主机 ISR 处理程序放入 IRAM 以提高性能并减少缓存未命中

• CONFIG_I3C_MASTER_ENABLE_DEBUG_LOG：启用 I3C 调试日志

关于资源消耗

使用 IDF Size 工具可以查看 I3C 驱动的代码和数据消耗。以下是测试前提条件（以 ESP32-P4 为例）：

• 编译器优化等级设置为 -Os，以确保代码尺寸最小化。

• 默认日志等级设置为 ESP_LOG_INFO，以平衡调试信息和性能。

• 关闭以下驱动优化选项：

  • CONFIG_I3C_MASTER_ISR_HANDLER_IN_IRAM - 中断处理程序不放入 IRAM。

  • CONFIG_I3C_MASTER_ISR_CACHE_SAFE - 不启用 Cache 安全选项。

注意，以下数据不是精确值，仅供参考，在不同型号的芯片上，数据会有所出入。

Component Layer	Total Size	DIRAM	.bss	.data	.text	Flash Code	.text	Flash Data	.rodata
hal	30	0	0	0	0	30	18	0	12
driver	9249	12	12	0	0	9237	8666	571	571

应用示例

• peripherals/i3c/i3c_i2c_basic 演示了初始化 I3C 主机驱动程序并用 I2C 接口从 ICM42688 传感器读取数据的基本步骤。

• peripherals/i3c/i3c_lsm6dscx 演示了如何使用 I3C 主机模式从连接的 LSM6DSOX 传感器读取和写入数据，并支持带内中断（IBI）事件处理。

API 参考

I3C 驱动 API

Header File

• components/esp_driver_i3c/include/driver/i3c_master.h

• This header file can be included with:

  #include "driver/i3c_master.h"
  

• This header file is a part of the API provided by the esp_driver_i3c component. To declare that your component depends on esp_driver_i3c, add the following to your CMakeLists.txt:

  REQUIRES esp_driver_i3c
  

  or

  PRIV_REQUIRES esp_driver_i3c
  

Functions

esp_err_t i3c_new_master_bus(const i3c_master_bus_config_t *bus_config, i3c_master_bus_handle_t *ret_bus_handle)

Create a new I3C master bus.

This function initializes a new I3C master bus with the provided configuration.

参数:

• bus_config -- [in] Pointer to the I3C master bus configuration structure.

• ret_bus_handle -- [out] Pointer to the location where the handle of the newly created bus will be stored.

返回:

• ESP_OK: Bus created successfully.

• ESP_ERR_INVALID_ARG: Invalid configuration or parameters.

• ESP_ERR_NO_MEM: Memory allocation failed.

esp_err_t i3c_del_master_bus(i3c_master_bus_handle_t bus_handle)

Deletes an I3C master bus and releases associated resources.

This function deinitializes and deletes the specified I3C master bus instance. It ensures that all resources allocated for the bus are properly released. The caller must ensure that no active operations are ongoing on the bus before invoking this function.

参数:

bus_handle -- Handle to the I3C master bus to be deleted. This handle must have been previously obtained from a successful bus initialization.

返回:

• ESP_OK: The bus was successfully deleted.

• ESP_ERR_INVALID_ARG: The provided bus_handle is invalid (e.g., null or uninitialized).

esp_err_t i3c_master_bus_decorate_dma(i3c_master_bus_handle_t bus_handle, const i3c_master_dma_config_t *dma_config)

Enable DMA for I3C master bus (decorator pattern)

This function enables DMA functionality for an existing I3C master bus. It follows the decorator pattern to avoid linking DMA code when not needed, thus reducing binary size.

参数:

• bus_handle -- [in] Handle to the I3C master bus to be decorated with DMA capability.

• dma_config -- [in] Pointer to the DMA configuration structure. If NULL, DMA will be disabled and fifo will be used.

返回:

• ESP_OK: DMA decorator applied successfully.

• ESP_ERR_INVALID_ARG: Invalid bus handle or configuration.

• ESP_ERR_INVALID_STATE: Bus is already decorated with DMA or bus is in use.

• ESP_ERR_NO_MEM: Memory allocation failed for DMA resources.

esp_err_t i3c_master_bus_wait_all_done(i3c_master_bus_handle_t bus_handle, int timeout_ms)

Wait for all pending I3C transactions done.

参数:

• bus_handle -- [in] I3C bus handle

• timeout_ms -- [in] Wait timeout, in ms. Specially, -1 means to wait forever.

返回:

• ESP_OK: Flush transactions successfully

• ESP_ERR_INVALID_ARG: Flush transactions failed because of invalid argument

• ESP_ERR_TIMEOUT: Flush transactions failed because of timeout

esp_err_t i3c_master_bus_add_i3c_static_device(i3c_master_bus_handle_t bus_handle, const i3c_device_i3c_config_t *dev_config, i3c_master_i3c_device_handle_t *ret_handle)

Add an I3C device to the bus via its static address.

Creates and attaches a device object to the given I3C master bus using the device's static address and characteristics. On success, a device handle is returned for subsequent transactions.

参数:

• bus_handle -- [in] I3C master bus handle

• dev_config -- [in] Pointer to the device configuration (static/dynamic address, BCR/DCR)

• ret_handle -- [out] Returned device handle on success

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_transfer_ccc(i3c_master_bus_handle_t bus_handle, const i3c_master_ccc_transfer_config_t *ccc_trans)

Perform a Common Command Code (CCC) transfer.

Executes a CCC transaction (broadcast or direct) described by the provided transfer descriptor. The call is synchronous and returns when the transfer completes or an error/timeout occurs.

参数:

• bus_handle -- [in] I3C master bus handle

• ccc_trans -- [inout] Transfer descriptor; for read operations, the data buffer receives data

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_i3c_device_transmit(i3c_master_i3c_device_handle_t dev_handle, const uint8_t *write_buffer, size_t write_size, int xfer_timeout_ms)

Transmit data to an I3C device.

Performs a write transfer to the target I3C device.

参数:

• dev_handle -- [in] I3C device handle

• write_buffer -- [in] Pointer to the data to send

• write_size -- [in] Number of bytes to send

• xfer_timeout_ms -- [in] Timeout for the transfer in milliseconds (-1 for wait forever)

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_i3c_device_receive(i3c_master_i3c_device_handle_t dev_handle, uint8_t *read_buffer, size_t read_size, int xfer_timeout_ms)

Receive data from an I3C device.

Performs a read transfer from the target I3C device.

参数:

• dev_handle -- [in] I3C device handle

• read_buffer -- [out] Buffer to store the received data

• read_size -- [in] Number of bytes to read

• xfer_timeout_ms -- [in] Timeout for the transfer in milliseconds (-1 for wait forever)

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_i3c_device_transmit_receive(i3c_master_i3c_device_handle_t dev_handle, const uint8_t *write_buffer, size_t write_size, uint8_t *read_buffer, size_t read_size, int xfer_timeout_ms)

Combined transmit-then-receive transaction with a repeated START.

Writes a small command or register address to the device, then reads data back without releasing the bus (no STOP between phases).

参数:

• dev_handle -- [in] I3C device handle

• write_buffer -- [in] Data to transmit first

• write_size -- [in] Number of bytes to transmit

• read_buffer -- [out] Buffer to receive data

• read_size -- [in] Number of bytes to read

• xfer_timeout_ms -- [in] Timeout for the transaction in milliseconds (-1 for wait forever)

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_i3c_device_get_info(i3c_master_i3c_device_handle_t dev_handle, i3c_device_information_t *info)

Get basic information of an I3C device.

Queries the driver for device attributes such as dynamic address, BCR/DCR and PID.

参数:

• dev_handle -- [in] I3C device handle

• info -- [out] Pointer to a structure to receive the device information

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_i3c_device_ibi_config(i3c_master_i3c_device_handle_t dev_handle, const i3c_ibi_config_t *config)

Configure In-Band Interrupt (IBI) behavior for a device.

Enables/disables IBI reception and optional payload handling for the specified device.

参数:

• dev_handle -- [in] I3C device handle

• config -- [in] Pointer to the IBI configuration

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_i3c_device_register_event_callbacks(i3c_master_i3c_device_handle_t dev_handle, const i3c_master_i3c_event_callbacks_t *cbs, void *user_data)

Register I3C device event callbacks.

Installs callbacks for transaction completion and IBI events. Callbacks are invoked in ISR context; ensure the code is IRAM-safe if required by config.

参数:

• dev_handle -- [in] I3C device handle

• cbs -- [in] Pointer to the callback structure

• user_data -- [in] User-provided context pointer passed back on callbacks

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_bus_rm_i3c_device(i3c_master_i3c_device_handle_t dev_handle)

Remove an I3C device from the bus.

Detaches the specified device from the master bus and releases associated resources.

参数:

dev_handle -- [in] I3C device handle to remove

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_scan_devices_by_entdaa(i3c_master_bus_handle_t bus_handle, i3c_master_i3c_device_table_handle_t *ret_table_handle)

Discover I3C devices via ENTDAA and return a table of device handles.

Runs the ENTDAA (Enter Dynamic Address Assignment) procedure to discover I3C devices on the bus and returns a newly allocated device table handle.

参数:

• bus_handle -- [in] I3C master bus handle

• ret_table_handle -- [out] Pointer to receive the device table handle (allocated on success)

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_free_device_handle_table(i3c_master_i3c_device_table_handle_t table_handle)

Free device handle table allocated by discovery.

Frees the device table handle previously returned by i3c_master_scan_devices_by_entdaa().

参数:

table_handle -- [in] Device table handle to free

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_get_device_count(i3c_master_i3c_device_table_handle_t table_handle, size_t *device_count)

Get the number of devices in the device table.

Returns the count of I3C devices stored in the device table handle.

参数:

• table_handle -- [in] Device table handle

• device_count -- [out] Pointer to store the device count

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_get_device_handle(i3c_master_i3c_device_table_handle_t table_handle, size_t index, i3c_master_i3c_device_handle_t *ret_handle)

Get device handle by index from the device table.

Retrieves the I3C device handle at the specified index in the device table.

参数:

• table_handle -- [in] Device table handle

• index -- [in] Index of the device in the table (0-based)

• ret_handle -- [out] Pointer to store the device handle

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

esp_err_t i3c_master_get_valid_address_slot(i3c_master_bus_handle_t bus_handle, uint8_t start_addr, uint8_t *ret_addr)

Get a valid address slot for dynamic address assignment.

参数:

• bus_handle -- [in] I3C master bus handle

• start_addr -- [in] Start address to search from

• ret_addr -- [out] Returned valid address slot

返回:

ESP_OK on success, otherwise an esp_err_t code indicating the failure

Structures

struct i3c_master_bus_config_t

Configuration structure for I3C master bus.

This structure defines the configuration parameters for the I3C master bus, including GPIO pins, clock source, queue depth, interrupt priority, and other options.

Public Members

gpio_num_t sda_io_num

GPIO number of I3C SDA signal

gpio_num_t scl_io_num

GPIO number of I3C SCL signal

i3c_master_clock_source_t clock_source

Clock source of I3C master bus

size_t trans_queue_depth

Depth of internal transfer queue, increase this value can support more transfers pending in the background, only valid in asynchronous transaction. (Typically max_device_num * per_transaction)

int intr_priority

I3C interrupt priority, if set to 0, driver will select the default priority (1,2,3).

uint32_t i3c_scl_freq_hz_od

I3C SCL frequency for Open-Drain mode

uint32_t i3c_scl_freq_hz_pp

I3C SCL frequency for Push-Pull mode

float i3c_scl_pp_duty_cycle

Duty cycle of I3C Push-Pull SCL signal, range from (0, 1). When set 0, then duty cycle is 0.5

float i3c_scl_od_duty_cycle

Duty cycle of I3C Open-Drain SCL signal, range from (0, 1). When set 0, then duty cycle is 0.5

uint32_t i3c_sda_od_hold_time_ns

I3C Open-Drain sda drive point after scl neg, in nanoseconds, default 25

uint32_t i3c_sda_pp_hold_time_ns

I3C Push-Pull sda drive point after scl neg, in nanoseconds, default 0

uint8_t entdaa_device_num

Maximum number of devices can be discovered by ENTDAA, range from [0x0, 0x7F], 0x0 means no entdaa is used.

i3c_master_internal_pullup_resistor_val_t internal_pullup_resistor_val

I3C internal pull-up resistor value (Please check program guide for the supported pins)

uint32_t enable_async_trans

Enable asynchronous transactions, allowing the master to perform other tasks while a transaction is in progress. Only works when DMA is enabled via i3c_master_bus_decorate_dma().

uint32_t ibi_rstart_trans_en

Enable restart transaction on IBI, the I3C controller continues to execute the command that was previously interrupted by the IBI after the IBI is completed

uint32_t ibi_silent_sir_rejected

If set, do not notify when a Slave Interrupt Request (SIR) is rejected

uint32_t ibi_no_auto_disable

If set, do not auto disable IBI, keep In-Band Interrupt enabled after the controller nack In-Band Interrupt

struct i3c_master_bus_config_t flags

I3C master config flags

struct i3c_master_dma_config_t

Configuration structure for I3C master bus DMA decorator.

This structure defines the DMA configuration parameters for the I3C master bus.

Public Members

size_t max_transfer_size

Maximum transfer size in one transaction, in bytes. This decides the number of DMA nodes

size_t dma_burst_size

DMA burst size, in bytes. If 0, driver will use default value (16 bytes)

struct i3c_device_i3c_config_t

I3C device configuration used when adding a device via static address.

This structure contains addressing and characteristic information of an I3C device as defined by the MIPI I3C specification. It is typically used to describe a device to the bus before or during dynamic address assignment.

Public Members

uint8_t dynamic_addr

7-bit dynamic address to assign for the device by SETDASA

uint8_t static_addr

7-bit static address of the device, used for initial contact or assignment

struct i3c_master_ccc_transfer_config_t

Parameters for a Common Command Code (CCC) transfer.

Describes a single CCC transaction, either broadcast or direct, with optional data phase.

Public Members

i3c_ccc_code_t ccc_command

CCC opcode

i3c_master_transfer_direction_t direction

Direction of data phase: I3C_MASTER_TRANSFER_DIRECTION_READ for read, I3C_MASTER_TRANSFER_DIRECTION_WRITE for write

uint8_t device_address

7-bit target address for direct CCC; ignored for broadcast CCC with specific CCC command

uint8_t *data

Data buffer: receives data for read, provides data for write

size_t data_size

Size of the data buffer in bytes

struct i3c_device_information_t

Basic I3C device information discovered on the bus.

Public Members

uint8_t dynamic_addr

Assigned dynamic address

uint8_t bcr

Bus Characteristics Register (BCR) reported by the device

uint8_t dcr

Device Characteristics Register (DCR) reported by the device

uint64_t pid

Provisional ID (PID). Lower 48 bits are valid as per spec.

struct i3c_ibi_config_t

In-Band Interrupt (IBI) configuration for an I3C device.

Public Members

bool enable_ibi

Enable reception/handling of IBI from this device

bool enable_ibi_payload

Expect/allow one-byte IBI payload from the device

struct i3c_master_i3c_event_callbacks_t

Group of I3C master callbacks, can be used to get status during transaction or doing other small things. But take care potential concurrency issues.

备注

The callbacks are all running under ISR context

备注

When CONFIG_I3C_MASTER_ISR_CACHE_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. The variables used in the function should be in the SRAM as well.

Public Members

i3c_master_i3c_callback_t on_trans_done

I3C master transaction finish callback

i3c_master_ibi_callback_t on_ibi

I3C master IBI callback

I3C 驱动 I2C 从机 API

Header File

• components/esp_driver_i3c/include/driver/i3c_master_i2c.h

• This header file can be included with:

  #include "driver/i3c_master_i2c.h"
  

• This header file is a part of the API provided by the esp_driver_i3c component. To declare that your component depends on esp_driver_i3c, add the following to your CMakeLists.txt:

  REQUIRES esp_driver_i3c
  

  or

  PRIV_REQUIRES esp_driver_i3c
  

Functions

esp_err_t i3c_master_bus_add_i2c_device(i3c_master_bus_handle_t bus_handle, const i3c_device_i2c_config_t *dev_config, i3c_master_i2c_device_handle_t *ret_handle)

Attach an I2C device to the I3C master bus.

This function registers an I2C device for communication on the I3C master bus.

参数:

• bus_handle -- [in] Handle to the I3C master bus.

• dev_config -- [in] Pointer to the configuration structure for the I2C device.

• ret_handle -- [out] Pointer to the location where the handle of the attached I2C device will be stored.

返回:

• ESP_OK: Device attached successfully.

• ESP_ERR_INVALID_ARG: Invalid parameters or device configuration.

• ESP_ERR_NO_MEM: Memory allocation failed.

esp_err_t i3c_master_bus_rm_i2c_device(i3c_master_i2c_device_handle_t dev_handle)

Detach an I2C device from the I3C master bus.

This function removes an I2C device that was previously attached to the I3C master bus using i3c_master_bus_add_i2c_device. It releases any resources associated with the device handle and invalidates the device handle.

参数:

dev_handle -- Handle to the I2C device to be detached. This handle is obtained from i3c_master_bus_add_i2c_device.

返回:

• ESP_OK: Device successfully detached from the bus.

• ESP_ERR_INVALID_ARG: The device handle is invalid or NULL.

esp_err_t i3c_master_i2c_device_transmit(i3c_master_i2c_device_handle_t dev_handle, const uint8_t *write_buffer, size_t write_size, int xfer_timeout_ms)

Transmit data to an I2C device on the I3C master bus.

Sends a block of data to the specified I2C device.

备注

If enable_async_trans is set, this function operates in asynchronous transmission mode. In this mode, the function returns immediately after being called, even if the transmission is not yet completed. The completion status and any related events should be obtained through the corresponding callback.

参数:

• dev_handle -- [in] Handle to the I2C device.

• write_buffer -- [in] Pointer to the buffer containing data to transmit.

• write_size -- [in] Size of the data in bytes.

• xfer_timeout_ms -- [in] Timeout for the operation in milliseconds. Note: -1 means wait forever.

返回:

• ESP_OK: Data transmitted successfully.

• ESP_ERR_TIMEOUT: Transfer timed out.

• ESP_ERR_INVALID_ARG: Invalid parameters.

esp_err_t i3c_master_i2c_device_receive(i3c_master_i2c_device_handle_t dev_handle, uint8_t *read_buffer, size_t read_size, int xfer_timeout_ms)

Receive data from an I2C device on the I3C master bus.

Reads a block of data from the specified I2C device.

备注

If enable_async_trans is set, this function operates in asynchronous transmission mode. In this mode, the function returns immediately after being called, even if the transmission is not yet completed. The completion status and any related events should be obtained through the corresponding callback.

参数:

• dev_handle -- [in] Handle to the I2C device.

• read_buffer -- [out] Pointer to the buffer where received data will be stored.

• read_size -- [in] Number of bytes to read.

• xfer_timeout_ms -- [in] Timeout for the operation in milliseconds. Note: -1 means wait forever.

返回:

• ESP_OK: Data received successfully.

• ESP_ERR_TIMEOUT: Transfer timed out.

• ESP_ERR_INVALID_ARG: Invalid parameters.

esp_err_t i3c_master_i2c_device_transmit_receive(i3c_master_i2c_device_handle_t dev_handle, const uint8_t *write_buffer, size_t write_size, uint8_t *read_buffer, size_t read_size, int xfer_timeout_ms)

Perform a transmit-then-receive operation with an I2C device on the I3C master bus.

First sends data to the specified I2C device, then reads a block of data from it.

备注

If enable_async_trans is set, this function operates in asynchronous transmission mode. In this mode, the function returns immediately after being called, even if the transmission is not yet completed. The completion status and any related events should be obtained through the corresponding callback.

参数:

• dev_handle -- [in] Handle to the I2C device.

• write_buffer -- [in] Pointer to the buffer containing data to transmit.

• write_size -- [in] Size of the data in bytes to transmit.

• read_buffer -- [out] Pointer to the buffer where received data will be stored.

• read_size -- [in] Number of bytes to read.

• xfer_timeout_ms -- [in] Timeout for the operation in milliseconds. Note: -1 means wait forever.

返回:

• ESP_OK: Transmit and receive operations completed successfully.

• ESP_ERR_TIMEOUT: Transfer timed out.

• ESP_ERR_INVALID_ARG: Invalid parameters.

esp_err_t i3c_master_i2c_device_register_event_callbacks(i3c_master_i2c_device_handle_t dev_handle, const i3c_master_i2c_event_callbacks_t *cbs, void *user_data)

Register event callbacks for an I2C device operating on an I3C master bus.

This function allows the user to register callback functions for handling specific events related to an I2C device on the I3C master bus. The registered callbacks will be invoked during corresponding events, enabling custom handling of device-specific behaviors.

参数:

• dev_handle -- Handle to the I2C device This handle is obtained when the device is added to the I3C bus.

• cbs -- Pointer to a structure containing the event callback functions The cbs parameter should point to a valid i3c_master_i2c_event_callbacks_t structure that specifies the callbacks for various I2C-related events.

• user_data -- User-defined data to be passed to the callbacks This pointer is passed to all callbacks as a parameter, allowing the user to associate context or state with the callbacks.

返回:

• ESP_OK: The operation completed successfully.

• ESP_ERR_INVALID_ARG: One or more parameters are invalid.

• ESP_ERR_NO_MEM: Insufficient memory to register the callbacks.

Structures

struct i3c_device_i2c_config_t

Configuration structure for I2C device on an I3C bus.

This structure defines the configuration parameters for an I2C device when connected to an I3C bus. It includes the device address, clock speed, and additional configuration flags.

备注

I3C bus can't handle I2C device which has CLOCK STRETCH feature.

Public Members

uint8_t device_address

Device address. Must be 7-bit in I3C-I2C mode

uint32_t scl_freq_hz

I2C Device SCL line frequency. I2C Devices config flags

struct i3c_master_i2c_event_callbacks_t

Group of I3C-I2C master callbacks, can be used to get status during transaction or doing other small things. But take care potential concurrency issues.

备注

The callbacks are all running under ISR context

备注

When CONFIG_I3C_MASTER_ISR_CACHE_SAFE is enabled, the callback itself and functions called by it should be placed in IRAM. The variables used in the function should be in the SRAM as well.

Public Members

i3c_master_i2c_callback_t on_trans_done

I3C-I2C master transaction finish callback

I3C 驱动类型

Header File

• components/esp_hal_i3c/include/hal/i3c_master_types.h

• This header file can be included with:

  #include "hal/i3c_master_types.h"
  

• This header file is a part of the API provided by the esp_hal_i3c component. To declare that your component depends on esp_hal_i3c, add the following to your CMakeLists.txt:

  REQUIRES esp_hal_i3c
  

  or

  PRIV_REQUIRES esp_hal_i3c
  

Macros

I3C_MASTER_IBI_DATA_SIZE_MAX

Type Definitions

typedef soc_periph_i3c_master_clk_src_t i3c_master_clock_source_t

I2C group clock source.

Enumerations

enum i3c_ccc_code_t

I3C Common Command Code (CCC) enumeration.

This enumeration defines all I3C CCC command codes as per MIPI I3C specification.

Values:

enumerator I3C_CCC_ENEC

Enable Events Command.

enumerator I3C_CCC_DISEC

Disable Events Command.

enumerator I3C_CCC_ENTAS0

Enable Target Activity State 0.

enumerator I3C_CCC_ENTAS1

Enable Target Activity State 1.

enumerator I3C_CCC_ENTAS2

Enable Target Activity State 2.

enumerator I3C_CCC_ENTAS3

Enable Target Activity State 3.

enumerator I3C_CCC_RSTDAA

Reset Dynamic Address Assignment.

enumerator I3C_CCC_ENTDAA

Enter Dynamic Address Assignment.

enumerator I3C_CCC_DEFTGTS

Define List of Targets.

enumerator I3C_CCC_SETMWL

Set Max Write Length.

enumerator I3C_CCC_SETMRL

Set Max Read Length.

enumerator I3C_CCC_ENTTM

Enter Test Mode.

enumerator I3C_CCC_SETBUSCON

Set Bus Context.

enumerator I3C_CCC_ENDXFER

End Data Transfer.

enumerator I3C_CCC_ENTHDR0

Enter HDR Mode 0 (DDR)

enumerator I3C_CCC_ENTHDR1

Enter HDR Mode 1 (TSP)

enumerator I3C_CCC_ENTHDR2

Enter HDR Mode 2 (TSL)

enumerator I3C_CCC_ENTHDR3

Enter HDR Mode 3.

enumerator I3C_CCC_ENTHDR4

Enter HDR Mode 4.

enumerator I3C_CCC_ENTHDR5

Enter HDR Mode 5.

enumerator I3C_CCC_ENTHDR6

Enter HDR Mode 6.

enumerator I3C_CCC_ENTHDR7

Enter HDR Mode 7.

enumerator I3C_CCC_SETXTIME

Set Exchange Timing Information.

enumerator I3C_CCC_SETAASA

Set All Addresses to Static Addresses.

enumerator I3C_CCC_RSTACT

Target Reset Action.

enumerator I3C_CCC_DEFGRPA

Define List of Group Address.

enumerator I3C_CCC_RSTGRPA

Reset Group Address(es)

enumerator I3C_CCC_MLANE

Multi-Lane Data Transfer Control.

enumerator I3C_CCC_ENEC_DIRECT

Enable Events Command (Direct)

enumerator I3C_CCC_DISEC_DIRECT

Disable Events Command (Direct)

enumerator I3C_CCC_ENTAS0_DIRECT

Enable Target Activity State 0 (Direct)

enumerator I3C_CCC_ENTAS1_DIRECT

Enable Target Activity State 1 (Direct)

enumerator I3C_CCC_ENTAS2_DIRECT

Enable Target Activity State 2 (Direct)

enumerator I3C_CCC_ENTAS3_DIRECT

Enable Target Activity State 3 (Direct)

enumerator I3C_CCC_RSTDAA_DIRECT

Reset Dynamic Address Assignment (Direct)

enumerator I3C_CCC_SETDASA

Set Dynamic Address from Static Address.

enumerator I3C_CCC_SETNEWDA

Set New Dynamic Address.

enumerator I3C_CCC_SETMWL_DIRECT

Set Max Write Length (Direct)

enumerator I3C_CCC_SETMRL_DIRECT

Set Max Read Length (Direct)

enumerator I3C_CCC_GETMWL

Get Max Write Length.

enumerator I3C_CCC_GETMRL

Get Max Read Length.

enumerator I3C_CCC_GETPID

Get Provisional ID.

enumerator I3C_CCC_GETBCR

Get Bus Characteristics Register.

enumerator I3C_CCC_GETDCR

Get Device Characteristics Register.

enumerator I3C_CCC_GETSTATUS

Get Device Status.

enumerator I3C_CCC_GETACCMST

Get Accept Controller Role.

enumerator I3C_CCC_SETBRGTGT

Set Bridge Targets.

enumerator I3C_CCC_GETMXDS

Get Max Data Speed.

enumerator I3C_CCC_GETCAPS

Get Optional Feature Capabilities.

enumerator I3C_CCC_SETROUTE

Set Route.

enumerator I3C_CCC_D2DXFER

Device to Device(s) Tunneling Control.

enumerator I3C_CCC_SETXTIME_DIRECT

Set Exchange Timing Information (Direct)

enumerator I3C_CCC_GETXTIME

Get Exchange Timing Information.

enumerator I3C_CCC_RSTACT_DIRECT

Target Reset Action (Direct)

enumerator I3C_CCC_SETGRPA

Set Group Address.

enumerator I3C_CCC_RSTGRPA_DIRECT

Reset Group Address (Direct)

enumerator I3C_CCC_MLANE_DIRECT

Multi-Lane Data Transfer Control (Direct)

enum i3c_master_internal_pullup_resistor_val_t

I3C internal pull-up resistor value.

Values:

enumerator I3C_MASTER_INTERNAL_PULLUP_RESISTOR_DISABLED

Internal pull-up resistor disabled

enumerator I3C_MASTER_INTERNAL_PULLUP_RESISTOR_0_3K

Internal pull-up resistor 0.3K

enumerator I3C_MASTER_INTERNAL_PULLUP_RESISTOR_0_6K

Internal pull-up resistor 0.6K

enumerator I3C_MASTER_INTERNAL_PULLUP_RESISTOR_1_2K

Internal pull-up resistor 1.2K

enumerator I3C_MASTER_INTERNAL_PULLUP_RESISTOR_2_4K

Internal pull-up resistor 2.4K

I3C HAL 类型

Header File

• components/esp_driver_i3c/include/driver/i3c_master_types.h

• This header file can be included with:

  #include "driver/i3c_master_types.h"
  

• This header file is a part of the API provided by the esp_driver_i3c component. To declare that your component depends on esp_driver_i3c, add the following to your CMakeLists.txt:

  REQUIRES esp_driver_i3c
  

  or

  PRIV_REQUIRES esp_driver_i3c
  

Structures

struct i3c_master_i2c_device_event_data_t

Structure representing event data for I3C/I2C master operations.

Public Members

i3c_master_event_t event

The event type that occurred (e.g., transfer complete, error).

uint8_t *data

Pointer to the data buffer for the event (e.g., received data).

size_t data_size

The size of the data received, in bytes.

struct i3c_master_i3c_device_event_data_t

Structure representing event data for I3C master operations.

Public Members

i3c_master_event_t event

The event type that occurred (e.g., transfer complete, error).

uint8_t *data

Pointer to the data buffer for the event (e.g., received data).

size_t data_size

The size of the data received, in bytes.

struct i3c_master_ibi_info_t

In-Band Interrupt (IBI) event information.

Describes an IBI issued by an I3C target device, including optional payload.

• ibi_id: Raw IBI identifier reported by the controller. It typically encodes the issuer's dynamic address; it is raw value, dynamic address + r/w bit.

• ibi_sts: Controller-reported IBI status flags/fields that indicate the IBI type/state.

• data_length: Number of valid bytes in the payload buffer ibi_data, range 0..32.

• ibi_data: Optional payload bytes associated with the IBI. Only the first data_length bytes are valid.

Public Members

uint8_t ibi_id

Raw IBI identifier as reported by the controller

uint8_t ibi_sts

IBI status field reported by the controller

uint8_t data_length

Number of valid bytes in ibi_data (0..32)

uint8_t ibi_data[I3C_MASTER_IBI_DATA_SIZE_MAX]

IBI payload data buffer (up to 32 bytes)

Type Definitions

typedef struct i3c_master_bus_t *i3c_master_bus_handle_t

Type of I3C master bus handle.

typedef struct i3c_master_device_t i3c_master_device_t

Forward declaration of base device structure.

typedef struct i3c_master_device_t *i3c_master_device_handle_t

Type of base device handle containing common members.

typedef struct i3c_master_i2c_dev_t *i3c_master_i2c_device_handle_t

Type of I2C device handle on I3C master bus.

typedef struct i3c_master_i3c_dev_t *i3c_master_i3c_device_handle_t

Type of I3C device handle on I3C master bus.

typedef struct i3c_master_i3c_device_table_t i3c_master_i3c_device_table_t

Type alias for I3C device table structure.

typedef struct i3c_master_i3c_device_table_t *i3c_master_i3c_device_table_handle_t

Type of I3C device table handle.

typedef bool (*i3c_master_i2c_callback_t)(i3c_master_i2c_device_handle_t i2c_dev, const i3c_master_i2c_device_event_data_t *evt_data, void *arg)

Type definition for a callback function used in I3C/I2C master operations.

This callback function is invoked when an event occurs during I3C/I2C master communication.

Param i2c_dev:

Handle to the I2C device associated with the event.

Param evt_data:

Pointer to the structure containing event details and relevant data.

Param arg:

User-provided argument passed during callback registration.

Return:

Whether a high priority task has been waken up by this function.

typedef bool (*i3c_master_i3c_callback_t)(i3c_master_i3c_device_handle_t i3c_dev, const i3c_master_i3c_device_event_data_t *evt_data, void *arg)

Type definition for a callback function used in I3C master operations.

typedef bool (*i3c_master_ibi_callback_t)(i3c_master_i3c_device_handle_t i3c_dev, const i3c_master_ibi_info_t *evt_data, void *arg)

IBI callback function type.

Invoked when the target device issues an IBI. This callback runs in ISR context.

Param i3c_dev:

[in] Handle to the I3C device that issued the IBI.

Param evt_data:

[in] Pointer to the IBI event information structure.

Param arg:

[in] User-provided context pointer supplied at registration.

Return:

true if a higher-priority task was woken and a context switch is requested; false otherwise.

Enumerations

enum i3c_master_transfer_direction_t

Enumeration for I3C transfer direction.

Values:

enumerator I3C_MASTER_TRANSFER_DIRECTION_WRITE

enumerator I3C_MASTER_TRANSFER_DIRECTION_READ

enum i3c_master_event_t

Enumeration for I3C event.

Values:

enumerator I3C_MASTER_EVENT_TRANS_DONE

I3C bus transaction done

enumerator I3C_MASTER_EVENT_NACK

I3C bus nack

enum i3c_addr_slot_status_t

I3C address slot status in address pool.

Values:

enumerator I3C_ADDR_SLOT_FREE

Address slot is free.

enumerator I3C_ADDR_SLOT_RESERVED

Address slot is reserved. Might be used as CCC command

enumerator I3C_ADDR_SLOT_I2CDEV

Address slot is I2C device.

enumerator I3C_ADDR_SLOT_I3CDEV

Address slot is I3C device.

---

此文档对您有帮助吗？

• 反馈已收到，谢谢！
• 如果您有其他意见，欢迎填写乐鑫文档反馈表。

• 我们重视您的反馈。
• 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。