I3C - Qualcomm Dragonwing Documentation

改进型内部集成电路（I3C）接口为连接的 I3C 设备提供了一种快速、低成本、低功耗的 2 线数字接口。

I3C 仅支持 aDSP 传感器通信。不支持 Linux 用例。

概述

总线特性

2 线串行接口（SDA + SCL），支持高达 12.5 MHz
与同一总线上的传统 I2C 设备向后兼容
地址阶段：400 kHz
数据阶段：12.5 MHz

高级特性

带内中断（IBI）支持
热加入（动态添加设备）
同步定时与异步时间戳
写操作期间的 8 位数据奇偶校验
目标设备的动态寻址
单倍数据速率（SDR）模式
符合 MIPI I3C 规范的 CCC（通用命令码）

数据阶段模式

模式	用途
推挽	支持 I3C 的设备
开漏	含 I2C 设备的混合总线

数据包帧结构

组成部分	描述
S / Sr	起始或重复起始条件
I3C 动态地址	枚举期间分配的 7 位动态地址
R/W	方向位（1=读，0=写）
ACK	应答（SDA 拉低）
Data	8 位数据载荷
T	转换位（ACK/NACK 的替代）
P	停止条件

总线初始化

控制器初始化

I3C 控制器驱动初始化控制器，包括固件加载和配置设置。

配置与设备数据库读取

驱动读取 I3C 配置和设备数据库：

I2C 静态地址设备列表
I3C 静态地址设备列表
预期的 I3C 动态设备（厂商 ID、设备 ID、预定义动态地址、关联驱动）
可选的允许热加入设备

设备枚举

驱动枚举总线上的设备并分配本地地址。

总线配置

驱动将总线配置写入控制器：

工作频率
纯 I3C / 传统 I2C 模式
SDR/HDR 启用/禁用
支持 IBI 的设备及预期数据字节数

客户端软件配置

客户端软件接收 I2C/I3C 设备和热加入设备的设备列表与配置。

软件配置

固件加载

用于 QUP v3 串行引擎的 I3C 固件在 aDSP 启动期间随 SSC QUP 一起加载。 配置文件：

/ADSP.HT.5.5.c8/adsp_proc/core/settings/buses/qup_fw/config/<chipset>/fw_devcfg.c
/ADSP.HT.5.5.c8/adsp_proc/core/settings/buses/qup_fw/config/<chipset>/fw_devcfg.xml

串行引擎配置示例：

se_cfg se0_cfg = { 0x80000, SE_PROTOCOL_I3C, GSI, TRUE, TRUE };
se_cfg se1_cfg = { 0x84000, SE_PROTOCOL_I3C, GSI, TRUE, TRUE };

GPIO 配置

每个串行引擎的默认 GPIO 配置位于：

/ADSP.HT.5.5.c8/adsp_proc/core/settings/buses/qup_common/config/<chipset>/adsp/ssc/qup_instance_mapping.c

覆盖示例：

{
  .instance_id = 1,
  .qup = QUP_SSC,
  .se_index = 0,
  .se_data = NULL,
  .protocol_io_cfg = {
    TLMM_MAP(TLMM_GPIO_KEEPER,  TLMM_GPIO_2MA, TLMM_GPIO_KEEPER),   // SLEEP
    TLMM_MAP(TLMM_GPIO_NO_PULL, TLMM_GPIO_6MA, TLMM_GPIO_KEEPER),   // SPI
    TLMM_MAP(TLMM_GPIO_NO_PULL, TLMM_GPIO_2MA, TLMM_GPIO_NO_PULL),  // UART
    TLMM_MAP(TLMM_GPIO_PULL_UP, TLMM_GPIO_2MA, TLMM_GPIO_NO_PULL),  // I2C
    TLMM_MAP(TLMM_GPIO_PULL_UP, TLMM_GPIO_2MA, TLMM_GPIO_KEEPER)    // I3C
  },
  .se_exclusive = TRUE,
}

TLMM_MAP(active_pull, drive_strength, sleep_pull) — I3C 使用上拉激活、2 mA 驱动、keeper 休眠。

API

头文件	用途
`api/buses/i2c_api.h`	I3C/I2C API
`api/buses/qup_common.h`	QUP 通用 API

调试

启用调试日志

mount -t debugfs none /sys/kernel/debug

echo -n "file i3c_master.c +p" > /sys/kernel/debug/dynamic_debug/control
echo -n "file qup_i3c.c +p" > /sys/kernel/debug/dynamic_debug/control
echo -n "file qup_common.c +p" > /sys/kernel/debug/dynamic_debug/control

dmesg | grep -i "i3c\|qup\|ssc"

检查设备枚举

ls -la /sys/bus/i3c/devices/
cat /sys/bus/i3c/devices/*/name
cat /sys/bus/i3c/devices/*/address

检查 GPIO 和时钟

cat /sys/kernel/debug/pinctrl/*/pinmux-pins | grep -A 5 "i3c"
cat /sys/kernel/debug/gpio

启用 I3C 跟踪

echo 1 > /sys/kernel/debug/tracing/events/i3c/enable
cat /sys/kernel/debug/tracing/trace
echo 0 > /sys/kernel/debug/tracing/events/i3c/enable

故障排查

设备未被枚举

确认 SDA/SCL 物理连接和上拉电阻（1–4.7 kΩ）
检查设备树中的 I3C 节点配置
查看 dmesg | grep -i i3c 中的枚举错误
确认厂商 ID 和设备 ID 与预期值匹配

地址阶段时序问题（400 kHz）

症状： 枚举期间设备无响应。确认地址阶段的 SCL 频率为 400 kHz。必要时在固件配置中调整时钟分频设置。

数据阶段时序问题（12.5 MHz）

症状： 数据损坏或读/写失败。检查总线电容 — 必要时降低。确认数据阶段的 SCL 频率为 12.5 MHz。

热加入不工作

确认配置中已启用热加入
将设备添加到允许热加入列表（厂商 ID + 设备 ID）
检查 IBI 配置和设备上电时序

I2C/I3C 混合总线问题

确认总线模式（纯 I3C 还是传统 I2C）
检查 I2C 和 I3C 设备之间的地址冲突
确认开漏与推挽模式切换正确

未收到 IBI（带内中断）

在配置中为特定设备启用 IBI
配置正确的预期数据字节数
确认中断处理程序已注册

信号完整性问题

症状： 间歇性通信失败。

测量 SDA 和 SCL 的上升/下降时间
调整上拉电阻值
添加串联端接电阻
缩短总线长度或降低电容

常见错误码

错误	描述	解决方案
`ENXIO`	未找到设备	确认连接和枚举
`ETIMEDOUT`	传输超时	检查时钟信号和设备电源
`EIO`	I/O 错误	检查信号质量和上拉电阻
`EBUSY`	资源忙	检查总线仲裁冲突
`EPROTO`	协议错误	验证时序参数和协议合规性

收集日志以获取支持

dmesg > i3c_dmesg.log
cat /proc/interrupts > i3c_interrupts.log
lsmod > loaded_modules.log
tar -czf i3c_debug_$(date +%Y%m%d_%H%M%S).tar.gz *.log

资源

MIPI I3C 规范
Qualcomm Linux 接口指南
QUP v3 串行引擎文档

​概述

​总线特性

​高级特性

​数据阶段模式

​数据包帧结构

​总线初始化

​软件配置

​固件加载

​GPIO 配置

​API

​调试

​启用调试日志

​检查设备枚举

​检查 GPIO 和时钟

​启用 I3C 跟踪

​故障排查

​常见错误码

​收集日志以获取支持

​资源

概述

总线特性

高级特性

数据阶段模式

数据包帧结构

总线初始化

软件配置

固件加载

GPIO 配置

API

调试

启用调试日志

检查设备枚举

检查 GPIO 和时钟

启用 I3C 跟踪

故障排查

常见错误码

收集日志以获取支持

资源