> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# I3C

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

<Note>
  I3C 仅支持 **aDSP 传感器通信**。不支持 Linux 用例。
</Note>

## 概述

### 总线特性

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

### 高级特性

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

### 数据阶段模式

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

<img src="https://mintcdn.com/qualcomm-prod/tRWO8v_Df_ujnDuD/Ubuntu/images/peripheral-interfaces/I3C_SDA_SCL_signals.png?fit=max&auto=format&n=tRWO8v_Df_ujnDuD&q=85&s=75bc1f8899f5dff043ce20e87c50c1ba" width="1098" height="305" data-path="Ubuntu/images/peripheral-interfaces/I3C_SDA_SCL_signals.png" />

## 数据包帧结构

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

## 总线初始化

<Steps>
  <Step title="控制器初始化">
    I3C 控制器驱动初始化控制器，包括固件加载和配置设置。
  </Step>

  <Step title="配置与设备数据库读取">
    驱动读取 I3C 配置和设备数据库：

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

  <Step title="设备枚举">
    驱动枚举总线上的设备并分配本地地址。
  </Step>

  <Step title="总线配置">
    驱动将总线配置写入控制器：

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

  <Step title="客户端软件配置">
    客户端软件接收 I2C/I3C 设备和热加入设备的设备列表与配置。
  </Step>
</Steps>

## 软件配置

### 固件加载

用于 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
```

**串行引擎配置示例：**

```c theme={null}
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
```

**覆盖示例：**

```c theme={null}
{
  .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  |

## 调试

### 启用调试日志

```bash theme={null}
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"
```

### 检查设备枚举

```bash theme={null}
ls -la /sys/bus/i3c/devices/
cat /sys/bus/i3c/devices/*/name
cat /sys/bus/i3c/devices/*/address
```

### 检查 GPIO 和时钟

```bash theme={null}
cat /sys/kernel/debug/pinctrl/*/pinmux-pins | grep -A 5 "i3c"
cat /sys/kernel/debug/gpio
```

### 启用 I3C 跟踪

```bash theme={null}
echo 1 > /sys/kernel/debug/tracing/events/i3c/enable
cat /sys/kernel/debug/tracing/trace
echo 0 > /sys/kernel/debug/tracing/events/i3c/enable
```

## 故障排查

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

  <Accordion title="地址阶段时序问题（400 kHz）">
    **症状：** 枚举期间设备无响应。

    确认地址阶段的 SCL 频率为 400 kHz。必要时在固件配置中调整时钟分频设置。
  </Accordion>

  <Accordion title="数据阶段时序问题（12.5 MHz）">
    **症状：** 数据损坏或读/写失败。

    检查总线电容 — 必要时降低。确认数据阶段的 SCL 频率为 12.5 MHz。
  </Accordion>

  <Accordion title="热加入不工作">
    * 确认配置中已启用热加入
    * 将设备添加到允许热加入列表（厂商 ID + 设备 ID）
    * 检查 IBI 配置和设备上电时序
  </Accordion>

  <Accordion title="I2C/I3C 混合总线问题">
    * 确认总线模式（纯 I3C 还是传统 I2C）
    * 检查 I2C 和 I3C 设备之间的地址冲突
    * 确认开漏与推挽模式切换正确
  </Accordion>

  <Accordion title="未收到 IBI（带内中断）">
    * 在配置中为特定设备启用 IBI
    * 配置正确的预期数据字节数
    * 确认中断处理程序已注册
  </Accordion>

  <Accordion title="信号完整性问题">
    **症状：** 间歇性通信失败。

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

### 常见错误码

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

### 收集日志以获取支持

```bash theme={null}
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 串行引擎文档