RK3588 kernel-6.1/drivers/i2c/muxes 目录功能详细分析

1. 文档范围

本文分析目录：

• 源码：rk3588/kernel-6.1/drivers/i2c/muxes
• 文档：linuxDoc/drivers/i2c/

前提： muxes/ 中的驱动都依赖上层 i2c-mux.c（位于 drivers/i2c/） 提供的多路复用框架。本文先说明框架机制，再逐项分析 muxes/ 下 9 个具体驱动/模块的功能、实现差异与 RK3588 使用场景。

2. 为什么需要 I2C Mux

2.1 问题场景

2.2 内核抽象

Linux 不把 mux 做成“透明转发”，而是为每个通道（或逻辑段）注册独立的 i2c_adapter：

1
2
3
4
5
6
7
8

物理 I2C 主控 (i2c-2, rk3x)
    │
    ▼
MUX 芯片 / GPIO / pinctrl / 寄存器
    │
    ├── 子 adapter: i2c-2-mux (chan 0)  → 设备 A、B
    ├── 子 adapter: i2c-3-mux (chan 1)  → 设备 C
    └── 子 adapter: i2c-4-mux (chan 2)  → 设备 D

用户态可见多个 /dev/i2c-*；client 驱动挂在子 adapter 对应的 DT 子节点下。

3. 与 i2c-mux.c 核心的关系

muxes/ 不包含通用 mux 框架，只实现各硬件/机制的 select / deselect 回调。

3.1 核心数据结构（include/linux/i2c-mux.h）

1
2
3
4
5
6
7
8
9

struct i2c_mux_core {
    struct i2c_adapter *parent;      /* 上游物理/父 adapter */
    struct device *dev;
    int (*select)(struct i2c_mux_core *muxc, u32 chan);
    int (*deselect)(struct i2c_mux_core *muxc, u32 chan);
    int num_adapters;
    int max_adapters;
    /* ... flags: LOCKED, ARBITRATOR, GATE ... */
};

3.2 传输路径（i2c-mux.c）

每次在子 adapter 上 i2c_transfer() 时：

1
2
3
4

i2c_mux_master_xfer()
  → muxc->select(muxc, chan_id)     // muxes/*.c 实现
  → i2c_transfer(parent, msgs)    // 在父总线上真正收发
  → muxc->deselect(muxc, chan_id) // 可选，恢复 idle

• 支持 SMBus 透传（i2c_mux_smbus_xfer）；
• 支持 多级 mux（子 adapter 下再挂 mux）；
• 通过 parent->mux_lock 与 lock_ops 避免父子 adapter 重复加锁死锁。

3.3 驱动开发模板

典型 mux 芯片驱动流程：

1
2
3
4

probe
  → i2c_mux_alloc(parent, dev, nchans, priv_size, flags, select, deselect)
  → 对每个 channel: i2c_mux_add_adapter(muxc, force_nr, chan_id, class)
  → DT 子节点 reg = channel 号，core 在子 adapter 上注册 client

4. 目录与构建配置

4.1 文件列表

依赖：全部需要 CONFIG_I2C_MUX（i2c-mux.c 核心）。

4.2 分类概览

1
2
3
4
5
6
7
8

                  i2c-mux.c (核心框架)
                         │
      ┌──────────────────┼──────────────────┐
      │                  │                  │
 芯片型 MUX          控制型 MUX           特殊机制
      │                  │                  │
pca954x, pca9541    gpio, reg,          arb-gpio
ltc4306, mlxcpld    pinctrl, gpmux      demux-pinctrl

5. 各驱动功能详细分析

5.1 i2c-mux-pca954x.c — NXP PCA954x/PCA984x（最常用）

硬件： NXP I2C 多路复用器/开关，自身也是 I2C 从设备，通过写 8 位控制寄存器 选通通道。

支持型号：

核心实现：

设备树示例：

1
2
3
4
5
6
7
8
9

pca9548: mux@70 {
    compatible = "nxp,pca9548";
    reg = <0x70>;
    #address-cells = <1>;
    #size-cells = <0>;

    i2c@0 { reg = <0>; /* 子设备 */ };
    i2c@1 { reg = <1>; };
};

RK3588 关联： 车载/多摄板级 DTS 中常见 GPIO 位控制的 i2c-mux 节点（见 §8）；若硬件使用 PCA9548，则绑定 nxp,pca9548 由本驱动管理。

5.2 i2c-mux-pca9541.c — NXP PCA9541 总线主选择器

硬件语义： 不是“多通道扩展”，而是 两个 I2C 主机争用一条从总线 的仲裁芯片。

功能要点：

• 建模为 单通道 mux：select = 获取总线所有权，deselect = 释放；
• 通过 PCA9541_CONTROL / PCA9541_ISTAT 寄存器协商；
• 超时：ARB_TIMEOUT（125ms 强制）、ARB2_TIMEOUT（250ms 失败）；
• 读写寄存器使用 __i2c_smbus_xfer，同样避免重入锁。

适用： 双 CPU / 双 BMC 共享传感器总线；RK3588 普通嵌入式板较少使用。

5.3 i2c-mux-gpio.c — GPIO 控制的多路复用

硬件： 用 N 根 GPIO 编码选择 2^N 条 I2C 支路（板级 CPLD/逻辑电路）。

核心实现：

设备树：

• i2c-parent：phandle 指向父 adapter；
• 子节点 reg = 该通道的 GPIO 编码值；
• idle-state：空闲时 GPIO 值。

平台： platform_driver，支持 OF 与 ACPI。

5.4 i2c-mux-pinctrl.c — pinctrl 引脚复用型 Mux

场景： SoC 的 I2C 信号可通过 pinctrl 路由到不同引脚组，每组对应一条“逻辑总线”（如 I2C0 走 pinmux A 或 B）。

核心实现：

设备树：

• i2c-parent：父 adapter；
• pinctrl-names / pinctrl-0…：每个 channel 对应一个 state；
• 额外一个 idle state（pinctrl-names 最后一项）。

与 GPIO mux 区别： 切换的是 SoC 引脚复用，不是外部 mux 芯片。

5.5 i2c-mux-reg.c — MMIO 寄存器控制型 Mux

硬件： 板级用一个 内存映射寄存器 的若干位选择 I2C 路由（常见于 PowerPC/QorIQ 等）。

核心实现：

设备树： reg 指定寄存器物理地址；little-endian / big-endian；idle-in-use + idle。

5.6 i2c-mux-gpmux.c — 通用 MUX 子系统接口

设计： 不直接操作 GPIO/寄存器，而是调用 mux_control_select() / mux_control_deselect()（Linux multiplexer 子系统）。

核心实现：

1
2

mux_control_select(mux->control, chan);   // select
mux_control_deselect(mux->control);       // deselect

设备树：

1
2
3

compatible = "i2c-mux";
i2c-parent = <&i2c2>;
/* control-mux 由 mux 子系统绑定 */

优点： 硬件选通逻辑可复用于 SPI/I2C 等其他子系统；抽象层次最高。

5.7 i2c-mux-ltc4306.c — Analog LTC4305/4306

硬件： ADI I2C mux/switch，带 rise time accelerator、upstream/downstream 加速配置。

功能：

与 pca954x 类似： I2C 控制的专用 mux 芯片，适合长走线、电容负载大的场景。

5.8 i2c-mux-mlxcpld.c — Mellanox CPLD Mux

场景： Mellanox 网卡/服务器主板，CPLD 寄存器控制 I2C 路由。

核心实现：

拓扑（驱动注释）： i2c-mlxcpld 桥接 → CPLD mux 寄存器 → 多条虚拟 bus → 外设。

RK3588 产品树通常 不包含 此驱动。

5.9 i2c-demux-pinctrl.c — pinctrl 反多路复用（Demux）

与 mux 的本质区别：

工作流程：

1
2
3
4
5
6

用户写 sysfs current_master = N
  → i2c_demux_deactivate_master()  // 删除旧 adapter
  → of_changeset_apply()           // 应用 DT 变更
  → 获取新 parent adapter
  → pinctrl_select_state()           // 切换引脚
  → i2c_add_adapter()                // 注册新逻辑 adapter

sysfs：

• available_masters：可读所有候选主控；
• current_master：读写当前主控索引。

场景： 同一组引脚在“内部 I2C0”与“外部 I2C 扩展”之间动态切换（Renesas 等平台常见）。

5.10 i2c-arb-gpio-challenge.c — GPIO 挑战-应答仲裁

不是通道扩展，而是 多主机互斥：

select 流程：

1. 拉高 our-gpio；
2. 轮询 their-gpio 是否为低（对方释放）；
3. 超时则放弃并重试；
4. 成功则返回 0，允许在 parent 上传输。

标志： i2c_mux_alloc(..., I2C_MUX_ARBITRATOR, ...)。

场景： 两个主控（如 AP + MCU）共享一条 I2C，无专用 PCA9541 时的软件仲裁方案。

6. Mux 与 Switch 语义对比（以 PCA954x 为代表）

驱动在 pca954x_regval() 中统一处理，对上层均暴露为独立 channel adapter。

7. 锁机制与嵌套 Mux

i2c-mux.c 提供两套 lock_ops：

多级 mux 示例：

1
2
3
4
5

i2c-2 (rk3x)
  └── pca9548 @0x70
        └── channel 2
              └── pca9544 @0x71
                    └── channel 0 → 传感器

传输时依次 select 两级；i2c_adapter_depth() 用于嵌套锁层级。

8. RK3588 平台使用场景

8.1 内置 I2C 控制器

RK3588 自带多路 rockchip,rk3588-i2c，不经过 muxes/ 目录驱动，由 i2c-rk3x.c 直接提供 adapter。

8.2 板级 DTS 中的 i2c-mux 节点

在 RK3588 车载/多摄相关 DTS 中大量出现 逻辑名 i2c-mux 的节点，例如：

• rk3588-vehicle-evb-maxim-max96722-dphy0.dtsi
• rk3588-vehicle-maxim-cameras-s66.dtsi

典型结构：

1
2
3
4
5
6
7
8
9
10
11

/* 父 I2C 上 */
i2c-mux {
    #address-cells = <1>;
    #size-cells = <0>;

    i2c@0 {
        reg = <0>;
        /* Serializer / Camera 等 */
    };
    i2c@1 { reg = <1>; /* ... */ };
};

说明：

• 节点名 i2c-mux 是 DT 拓扑约定，表示其下每个 i2c@N 对应一条逻辑子总线；
• 实际选通可能由 板级 GPIO、SerDes 内部逻辑或外部 PCA954x 完成；
• 若 compatible = "i2c-mux" 且使用 MUX 子系统，内核加载 i2c-mux-gpmux.c；
• 若为 nxp,pca9548 等，加载 i2c-mux-pca954x.c；
• 部分方案可能在 驱动/固件内部 完成通道切换，DT 仅描述拓扑，不绑定上述 mux 驱动之一。

8.3 RK3588 常用驱动优先级建议

9. 调试与排障

9.1 确认子 adapter

1
2
3

ls /sys/bus/i2c/devices/
# 可见 i2c-N-mux (chan_id M) 或独立编号
ls /dev/i2c-*

9.2 在正确通道上探测

1
2

# 应对子 adapter 编号，而非仅父 bus
i2cdetect -y <子adapter编号>

9.3 常见问题

9.4 PCA954x 专用

1
2
3

# 查看/设置空闲通道策略（若 sysfs 存在）
cat /sys/.../idle_state
echo -2 > .../idle_state   # MUX_IDLE_DISCONNECT

10. 功能对照总表

11. 结论

drivers/i2c/muxes 目录提供 9 种 I2C 拓扑扩展/仲裁实现，均通过 i2c-mux.c 统一为：

1. select：传输前选通通道或获取总线；
2. deselect：传输后恢复 idle（可选）；
3. i2c_mux_add_adapter：为每个 channel 导出独立 i2c_adapter。

对 RK3588 开发：

• 物理层 由 i2c-rk3x.c 提供父 adapter；
• 拓扑层 根据硬件选用 pca954x、gpio、gpmux 或 pinctrl 等；
• 车载多摄 DTS 中 i2c-mux 节点描述子总线结构，需结合具体 compatible 与原理图确认实际加载的 mux 驱动。

12. 推荐阅读顺序

1. drivers/i2c/i2c-mux.c — 框架与锁
2. include/linux/i2c-mux.h — API
3. muxes/i2c-mux-pca954x.c — 最典型芯片实现
4. muxes/i2c-mux-gpio.c 或 i2c-mux-gpmux.c — 板级常见方案
5. Documentation/devicetree/bindings/i2c/ 下各 binding
6. RK3588 板级 DTS 中带 i2c-mux 的 dtsi

13. 相关文档

• rk3588-kernel-6.1-drivers-i2c目录功能详细分析_zh.md — 整个 drivers/i2c 目录
• rk3588-kernel-6.1-i2c总线架构分析.md — 架构与 rk3x 传输链

文档版本：基于 rk3588/kernel-6.1 源码树 drivers/i2c/muxes 分析。

RK3588 kernel-6.1/drivers/i2c 目录功能详细分析

1. 文档范围

本文对以下目录做功能级详细分析：

• 源码路径：rk3588/kernel-6.1/drivers/i2c
• 文档路径：linuxDoc/drivers/i2c/

分析目标：

1. 说明该目录在 Linux 内核中的职责与分层结构；
2. 逐项解释核心文件、算法层、复用器层、总线控制器层的具体功能；
3. 重点说明 RK3588 平台 使用的 Rockchip I2C 控制器驱动（i2c-rk3x.c）；
4. 给出设备树绑定、传输调用链与排障思路。

同目录已有 rk3588-kernel-6.1-i2c总线架构分析.md，侧重架构与调用链；本文在其基础上扩展目录全貌与各模块职责。

2. 目录总览

drivers/i2c 共约 177 个源文件，按 Makefile 分为五层：

整体架构可概括为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

用户态 (i2c-tools / 应用)
    │
    ▼
i2c-dev.c (/dev/i2c-N)  或  内核 client 驱动
    │
    ▼
i2c-core (i2c_transfer / i2c_smbus_*)
    │
    ├── i2c-mux.c (可选，多路复用)
    │
    ▼
adapter->algo->master_xfer()
    │
    ▼
busses/i2c-xxx.c (硬件控制器，如 i2c-rk3x.c)
    │
    ▼
物理 SDA/SCL ──► I2C 从设备 (传感器/PMIC/触摸/Codec 等)

3. 构建与 Kconfig 配置体系

3.1 顶层 Makefile

1
2
3
4
5
6
7
8
9
10

obj-$(CONFIG_I2C)           += i2c-core.o
i2c-core-objs               := i2c-core-base.o i2c-core-smbus.o
i2c-core-$(CONFIG_ACPI)     += i2c-core-acpi.o
i2c-core-$(CONFIG_I2C_SLAVE) += i2c-core-slave.o
i2c-core-$(CONFIG_OF)       += i2c-core-of.o

obj-$(CONFIG_I2C_SMBUS)     += i2c-smbus.o
obj-$(CONFIG_I2C_CHARDEV)   += i2c-dev.o
obj-$(CONFIG_I2C_MUX)       += i2c-mux.o
obj-y                       += algos/ busses/ muxes/

说明：

• i2c-core 是必选核心模块（CONFIG_I2C），其余按 Kconfig 裁剪；
• algos/、busses/、muxes/ 始终进入编译树，具体 .o 由各自子目录 Makefile + Kconfig 决定；
• RK3588 板级配置通常使能：I2C、I2C_CHARDEV、I2C_MUX、OF、I2C_RK3X（或等效选项名）。

3.2 主要 Kconfig 选项

4. 核心层（Core）功能详解

核心由 i2c-core 复合模块组成，是所有 I2C 操作的统一入口。

4.1 i2c-core-base.c — 总线与传输主框架

主要功能：

传输调用链（内核 client 驱动路径）：

1
2
3
4
5

client 驱动 (如 xxx_probe 里读写寄存器)
    → i2c_smbus_* / i2c_transfer()
        → __i2c_transfer()
            → adap->algo->master_xfer()   // 如 rk3x_i2c_xfer
                → 硬件寄存器 + 中断/DMA

4.2 i2c-core-smbus.c — SMBus 协议实现

• 在 I2C 消息之上实现 SMBus 块读写、PEC（CRC8）、Quick Command 等；
• 若 adapter 未实现 smbus_xfer，则由 core 用 I2C 消息模拟 SMBus 时序；
• 被 hwmon、电源管理、传感器等大量驱动依赖。

4.3 i2c-core-of.c — Device Tree 支持

RK3588 上绝大多数 I2C 从设备（触摸、PMIC、Codec）通过 DT 子节点自动枚举，不依赖 i2c_register_board_info()。

4.4 i2c-core-acpi.c — ACPI 支持

• 在 x86/ACPI 平台解析 ACPI I2C 设备；
• RK3588 为 ARM64 + DT，通常不编译或未使用此路径。

4.5 i2c-core-slave.c — 从模式框架

• i2c_slave_register() / i2c_slave_unregister()；
• 要求 adapter->algo->reg_slave 由控制器实现；
• RK3588 的 i2c-rk3x.c 以实现 Master 为主，从模式非主要用途。

4.6 i2c-boardinfo.c — 静态板级信息

• i2c_register_board_info(busnum, info, len)：在 arch 初始化阶段静态声明设备；
• 多用于无 DT 的旧 ARM/x86 板；RK3588 以 DT 为主，此路径较少使用。

4.7 i2c-core.h

• core 内部头文件，声明 __i2c_board_list、i2c_devinfo 等仅 core 使用的符号。

5. 用户态接口层

5.1 i2c-dev.c — /dev/i2c-*

功能：

• 每个已注册的 i2c_adapter 对应一个字符设备 i2c-N（N = adap->nr）；
• 通过 ioctl 支持：
  • I2C_RDWR：组合读写；
  • I2C_SMBUS：SMBus 访问；
  • I2C_FUNCS：查询 adapter 能力；
  • I2C_SLAVE / I2C_SLAVE_FORCE：绑定从地址；
  • I2C_RETRIES、I2C_TIMEOUT 等；
• 用户态工具：i2cdetect、i2cget、i2cset、i2cdump（i2c-tools 包）。

典型用途： bring-up 阶段探测总线、读写 EEPROM、验证硬件连线。

6. SMBus 扩展模块

6.1 i2c-smbus.c

在 i2c-core-smbus 基础协议之上，增加：

依赖 CONFIG_I2C_SMBUS，PC 服务器平台更常见；嵌入式 SoC 按需使能。

7. I2C 多路复用（Mux）层

7.1 i2c-mux.c — 复用框架

设计思想： 一条物理 I2C 上挂 MUX 芯片，每个通道对应一条逻辑总线。

• 为每个 channel 创建子 i2c_adapter；
• select(chan) / deselect(chan) 切换硬件通道；
• 传输时：select → i2c_transfer(parent) → deselect；
• 支持 多级 mux（mux 后再挂 mux）。

7.2 muxes/ 目录 — 具体 MUX 芯片驱动

RK3588 板子上若多个同地址设备分属不同通道，会在 DTS 中出现 i2c-mux-pca954x 等节点，用户态会看到 i2c-5、i2c-6 等多个 adapter。

8. 算法层（algos/）

用于没有专用硬件控制器、或硬件仅提供 GPIO 线位的场景。

常与 i2c-gpio.c（busses/）配合：用两个 GPIO 模拟 I2C 总线。

RK3588 内置硬件 I2C 控制器，正常产品路径不走 algo-bit，但 bring-up 或特殊板可能仍用 GPIO I2C。

9. 总线控制器层（busses/）

9.1 规模与分类

• 约 140 个 .c 源文件；
• Kconfig 中约 128 个 config I2C_* 选项；
• 按平台/总线类型可粗分为：

每个控制器驱动典型实现：

1. platform_driver / pci_driver probe；
2. 映射 MMIO、申请 IRQ、获取 clock/reset/pinctrl；
3. 填充 struct i2c_adapter + struct i2c_algorithm；
4. i2c_add_numbered_adapter() 注册；
5. master_xfer() 中完成实际收发。

10. RK3588 平台：Rockchip i2c-rk3x.c 详细分析

10.1 设备树绑定

RK3588 在 rk3588s.dtsi 中定义多个 I2C 控制器，例如：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

i2c0: i2c@fd880000 {
    compatible = "rockchip,rk3588-i2c", "rockchip,rk3399-i2c";
    reg = <0x0 0xfd880000 0x0 0x1000>;
    clocks = <&cru CLK_I2C0>, <&cru PCLK_I2C0>;
    clock-names = "i2c", "pclk";
    interrupts = <GIC_SPI 317 IRQ_TYPE_LEVEL_HIGH>;
    pinctrl-names = "default";
    pinctrl-0 = <&i2c0m0_xfer>;
    resets = <&cru SRST_I2C0>, <&cru SRST_P_I2C0>;
    reset-names = "i2c", "apb";
    #address-cells = <1>;
    #size-cells = <0>;
    status = "disabled";
};

要点：

• 主 compatible：rockchip,rk3588-i2c（SoC 特有属性）；
• 回退 compatible：rockchip,rk3399-i2c（驱动 of_match 中已注册，共用 rk3399_soc_data）；
• RK3588S 芯片上约有 8 路 I2C（i2c0～i2c7 等，具体以 dtsi 为准）；
• 板级 dts 通过 status = "okay"、clock-frequency、子节点使能外设。

10.2 驱动支持的 SoC 列表（rk3x_i2c_match[]）

RK3588 无独立 rk3588_soc_data 条目，通过 DT 字符串回退到 rk3399 实现（v1 时序计算、双时钟 i2c+pclk）。

10.3 硬件寄存器与传输模式

主要寄存器：

传输路径：

10.4 状态机与中断

1
2
3

STATE_IDLE → STATE_WRITE / STATE_READ → STATE_STOP → STATE_IDLE
                ↑__________________________|
                         IRQ 推进

• rk3x_i2c_irq()：读 REG_IPD，按状态调用 handle_write/read/stop；
• 上层 rk3x_i2c_xfer_common() 通过 wait_event_timeout(i2c->wait, !i2c->busy) 同步；
• Atomic 路径：rk3x_i2c_xfer_polling() 关中断轮询 rk3x_i2c_irq()，用于 atomic 上下文。

10.5 时序计算（v1，RK3399/RK3588 路径）

• rk3x_i2c_v1_calc_timings()：根据 clock-frequency（100k/400k/1M 等）和 DT 中的 scl-rise-ns、scl-fall-ns 计算 motion_low/high 分频；
• 满足 I2C 规范：tHD;sta、tSU;sta、tSU;sto、tSU;dat 等；
• rk3x_i2c_clk_notifier_cb()：时钟频率变化时重新 rk3x_i2c_adapt_div()，避免 DVFS 后时序违规。

10.6 特殊功能

10.7 i2c_algorithm 能力

1
2
3
4
5
6
7

static u32 rk3x_i2c_func(struct i2c_adapter *adap)
{
    return I2C_FUNC_I2C |
           I2C_FUNC_SMBUS_EMUL |
           I2C_FUNC_PROTOCOL_MANGLING |
           I2C_FUNC_NOSTART;
}

支持标准 I2C、SMBus 模拟、无 START 优化；具体 SMBus 由 core 层模拟完成。

10.8 Probe 流程摘要

1
2
3
4
5
6
7
8

rk3x_i2c_probe()
  → 解析 bus id (of_alias / ACPI)
  → i2c_parse_fw_timings()
  → ioremap、request_irq、clk/reset
  → 可选 GRF、Thunder Boot 回调
  → adap.algo = &rk3x_i2c_algorithm
  → i2c_add_numbered_adapter()
  → of_i2c_register_devices() [core 自动]

11. 辅助与测试模块

生产内核通常不使能这些选项。

12. 与 RK3588 外设的典型关系

1
2
3
4
5
6
7
8
9
10
11

rk3588s.dtsi (i2c0..i2c7)
    │
    ├── 板级 .dts 使能 &i2c2 等
    │       ├── pmic@xx        (电源管理)
    │       ├── codec@xx       (音频)
    │       ├── touchscreen@xx (触摸)
    │       └── eeprom@xx      (配置存储)
    │
    └── 可选 i2c-mux@xx
            ├── channel@0 → 传感器
            └── channel@1 → 摄像头 SCCB

• Client 驱动位于 drivers/i2c/clients 之外的其他目录（如 drivers/input/touchscreen、drivers/mfd、drivers/hwmon）；
• drivers/i2c 只提供总线基础设施，不包含具体芯片驱动。

13. 调试与排障指南

13.1 确认 Adapter 是否注册

1
2

ls /sys/bus/i2c/devices/
ls /dev/i2c-*          # 需 CONFIG_I2C_CHARDEV

13.2 用户态探测

1
2

i2cdetect -y 2         # 扫描 i2c-2 总线
i2cget -y 2 0x50 0x00  # 读设备 0x50 寄存器 0

13.3 内核日志

• 打开 CONFIG_I2C_DEBUG_CORE / CONFIG_I2C_DEBUG_BUS；
• 关注 timeout、NACK、SCL hold by slave（rk3x 特有）；
• trace_event i2c i2c_transfer（若使能 trace）。

13.4 常见问题对照

14. 功能模块对照总表

15. 结论

rk3588/kernel-6.1/drivers/i2c 目录实现的是 Linux 通用 I2C 子系统：

1. Core 定义总线模型、传输 API、OF 枚举、SMBus、恢复与调试基础设施；
2. i2c-dev 提供用户态访问；
3. i2c-mux 与 muxes/ 处理复杂拓扑；
4. algos/ 提供软件位带等通用算法；
5. busses/ 包含各平台硬件控制器，其中 RK3588 使用 i2c-rk3x.c，DT 兼容 rockchip,rk3588-i2c + rockchip,rk3399-i2c。

对 RK3588 开发与排障：

• 外设驱动问题 → 查具体 client 驱动与 DT 节点；
• 整条总线异常 → 重点分析 i2c-rk3x.c 的 xfer 状态机、时钟分频、中断与 pinctrl；
• 用户态验证 → i2c-dev + i2c-tools。

16. 推荐阅读顺序

1. drivers/i2c/Makefile、Kconfig — 模块组成
2. i2c-core-base.c — i2c_transfer、i2c_register_adapter
3. i2c-core-of.c — DT 设备注册
4. i2c-dev.c — 用户态接口
5. busses/i2c-rk3x.c — RK3588 硬件实现
6. arch/arm64/boot/dts/rockchip/rk3588s.dtsi — 控制器与外设节点
7. i2c-mux.c + 所用 muxes/* — 若板级有 MUX

文档版本：基于 rk3588/kernel-6.1 源码树分析。

RK3588 kernel-6.1/drivers/i2c/i2c-boardinfo.c 功能详细分析

1. 文档范围与说明

说明： 用户路径写作「i2c-boardinfo.c 目录」，实际为 单个源文件，位于：

• rk3588/kernel-6.1/drivers/i2c/i2c-boardinfo.c

并非独立子目录。该文件与 i2c-core-base.c 等共同构成 i2c 子系统，在 Makefile 中按 CONFIG_I2C_BOARDINFO 单独编译为 i2c-boardinfo.o。

文档路径： linuxDoc/drivers/i2c/

分析目标：

• 该文件在 I2C 子系统中的职责；
• 对外 API、内部数据结构与总线编号协调机制；
• 与 adapter 注册、设备创建的时序关系；
• 与 Device Tree（OF）方式的对比；
• RK3588 平台是否使用及实践建议。

2. 功能定位（一句话）

i2c-boardinfo.c 实现 「板级静态 I2C 设备表」的登记与延迟实例化：在 I2C 适配器（adapter）尚未注册之前，由板级/架构初始化代码预先声明「某总线号上会有哪些从设备」；待对应 i2c_adapter 注册成功后，由 core 扫描该表并创建 i2c_client。

这是 无 Device Tree 或早期 ARM/PowerPC/MIPS 板级代码 时代的经典机制；现代 RK3588 + DT 产品路径 几乎不调用 本文件提供的 API。

3. 编译与配置

3.1 Makefile

1
2

obj-$(CONFIG_I2C_BOARDINFO) += i2c-boardinfo.o
obj-$(CONFIG_I2C)           += i2c-core.o

• i2c-boardinfo.o 与 i2c-core.o 分离链接，减小 core 模块体积的可选裁剪（理论上可 CONFIG_I2C_BOARDINFO=n，实际默认开启）。

3.2 Kconfig

1
2
3

config I2C_BOARDINFO
    bool
    default y

• 无用户可见菜单项，默认始终使能；
• include/linux/i2c.h 中：若未使能，则 i2c_register_board_info() 为空 inline，直接返回 0。

4. 源文件结构概览

整个文件约 94 行，仅包含：

无 probe/remove、无平台驱动、无设备树解析——纯数据登记层。

5. 核心数据结构

5.1 struct i2c_devinfo（i2c-core.h，内部）

1
2
3
4
5

struct i2c_devinfo {
    struct list_head    list;
    int                 busnum;       /* 目标 I2C 总线号 */
    struct i2c_board_info board_info; /* 设备描述模板 */
};

• 仅 i2c core 可访问（不对外导出结构体定义给任意驱动）；
• 每个 i2c_register_board_info() 传入的数组元素对应链表中的一个 i2c_devinfo 节点。

5.2 struct i2c_board_info（include/linux/i2c.h，公开）

设备创建模板，主要字段：

便捷宏：

1
2

#define I2C_BOARD_INFO(dev_type, dev_addr) \
    .type = dev_type, .addr = (dev_addr)

6. 对外 API：i2c_register_board_info()

6.1 函数原型

1
2
3

int i2c_register_board_info(int busnum,
                            struct i2c_board_info const *info,
                            unsigned len);

6.2 参数语义

6.3 调用时机（内核文档要求）

必须在 任何 I2C adapter 驱动注册之前 完成，典型位置：

• 板级 arch_initcall() / device_initcall() 之前的初始化；
• arch/*/boards/*/setup.c 中静态表 + 注册函数。

反例： adapter 已 i2c_add_numbered_adapter() 之后再 i2c_register_board_info() — 设备不会自动补注册（除非该 adapter 再次触发扫描，而标准路径只在注册时扫描一次）。

6.4 实现逻辑（逐步）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

int i2c_register_board_info(int busnum, struct i2c_board_info const *info, unsigned len)
{
    down_write(&__i2c_board_lock);

    /* 更新「动态分配总线号」的起始边界 */
    if (busnum >= __i2c_first_dynamic_bus_num)
        __i2c_first_dynamic_bus_num = busnum + 1;

    for (; len; len--, info++) {
        devinfo = kzalloc(sizeof(*devinfo), GFP_KERNEL);
        devinfo->busnum = busnum;
        devinfo->board_info = *info;   /* 结构体浅拷贝 */

        /* resources 指针单独深拷贝 */
        if (info->resources)
            devinfo->board_info.resources = kmemdup(...);

        list_add_tail(&devinfo->list, &__i2c_board_list);
    }

    up_write(&__i2c_board_lock);
    return status;  /* 0 或 -ENOMEM */
}

要点：

1. 浅拷贝 board_info：type、addr、platform_data 等指针不会复制指向的内容；文档明确警告 __initdata 中的 platform_data 若仅 init 段有效，后续可能失效。
2. resources 例外：通过 kmemdup 深拷贝，避免原数组释放后悬空。
3. 失败处理：遇 -ENOMEM 中断循环，已入链节点不会回滚（部分注册）。

6.5 返回值

• 0：成功（或 len==0 仅更新 bus 号边界）；
• -ENOMEM：分配 i2c_devinfo 或 kmemdup 失败。

7. 全局变量与总线号协调

7.1 __i2c_board_list

• 类型：struct list_head；
• 内容：所有尚未被 adapter 消费掉的 i2c_devinfo（注册后不删除节点，靠 busnum 匹配多次扫描时重复尝试创建，由 i2c_new_client_device 地址冲突检测处理）。

7.2 __i2c_first_dynamic_bus_num

作用： 划分 静态声明的总线号 与 动态分配的总线号。

目的： 避免 i2c_add_adapter() 动态分配的 i2c-5 与板级静态声明的 busnum=5 冲突。

7.3 __i2c_board_lock

• 类型：struct rw_semaphore；
• 写锁：i2c_register_board_info()；
• 读锁：i2c_scan_static_board_info()；
• 写锁：i2c_init() 中调整 __i2c_first_dynamic_bus_num。

8. 设备实例化路径（与 core 协作）

本文件只登记；真正创建设备在 i2c-core-base.c。

8.1 时序图

1
2
3
4
5
6
7
8
9
10
11
12
13
14

[启动早期]
  arch/board setup.c
      i2c_register_board_info(0, devices[], N)
          → 写入 __i2c_board_list

[稍后]
  i2c-rk3x probe / 其他 adapter probe
      i2c_add_numbered_adapter(adap)   /* adap->nr == 0 */
          → i2c_register_adapter()
              → of_i2c_register_devices(adap)     /* DT 子节点，RK3588 主路径 */
              → i2c_acpi_register_devices(adap)   /* ACPI */
              → if (adap->nr < __i2c_first_dynamic_bus_num)
                    i2c_scan_static_board_info(adap)  /* boardinfo 路径 */
              → bus_for_each_drv(...)  /* 通知已注册的 i2c_driver */

8.2 i2c_scan_static_board_info()（core 内）

1
2
3
4
5
6
7
8
9
10

static void i2c_scan_static_board_info(struct i2c_adapter *adapter)
{
    down_read(&__i2c_board_lock);
    list_for_each_entry(devinfo, &__i2c_board_list, list) {
        if (devinfo->busnum == adapter->nr &&
            IS_ERR(i2c_new_client_device(adapter, &devinfo->board_info)))
            dev_err(..., "Can't create device at 0x%02x\n", ...);
    }
    up_read(&__i2c_board_lock);
}

• 匹配 devinfo->busnum == adapter->nr；
• 调用 i2c_new_client_device() → device_register() → 与 i2c_driver 匹配 probe。

8.3 条件：何时扫描 boardinfo

1
2

if (adap->nr < __i2c_first_dynamic_bus_num)
    i2c_scan_static_board_info(adap);

• 仅 编号小于动态边界的 adapter 会扫描静态表；
• 纯动态号 adapter（i2c_add_adapter 且 nr 较大）跳过 boardinfo。

9. 与其他设备注册方式对比

9.1 RK3588 实际路径

在 rk3588/kernel-6.1/arch/arm64 下 无 i2c_register_board_info() 调用。

典型 DTS（rk3588s.dtsi + 板级 dtsi）：

1
2
3
4
5
6
7
8
9
10

&i2c2 {
    status = "okay";
    clock-frequency = <400000>;

    pmic@20 {
        compatible = "rockchip,rk806";
        reg = <0x20>;
        ...
    };
};

i2c-rk3x 注册 adapter 后，仅 of_i2c_register_devices() 根据子节点创建 client。

9.2 仍使用 boardinfo 的平台（源码树内示例）

10. 典型板级用法示例（历史参考）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

/* 设备表 */
static struct i2c_board_info board_i2c_devices[] __initdata = {
    I2C_BOARD_INFO("ds1338", 0x68),
    {
        I2C_BOARD_INFO("eeprom", 0x50),
        .platform_data = &eeprom_cfg,
    },
};

/* 板级 init */
static int __init board_init(void)
{
    i2c_register_board_info(0, board_i2c_devices,
                            ARRAY_SIZE(board_i2c_devices));
    return 0;
}
arch_initcall(board_init);

对应 adapter 须 i2c_add_numbered_adapter() 且 adap->nr == 0。

11. 设计约束与注意事项

11.1 platform_data 生命周期

注释明确：不会复制 platform_data 指向的内容。若表在 __initdata，init 结束后内存可能被回收 → client probe 时访问非法。

正确做法： platform_data 指向全局/静态存储，或在 adapter 注册前仍为有效内存。

11.2 无注销接口

• 无 i2c_unregister_board_info()；
• 链表节点常驻；adapter 删除时不会根据 boardinfo 自动移除 client（client 由 driver model 管理）。

11.3 与 DT 并存

同一 adapter 上可同时：

1. of_i2c_register_devices() 创建 DT 子节点设备；
2. i2c_scan_static_board_info() 创建静态表设备。

须避免 地址冲突；RK3588 应只使用 DT 一种来源。

11.4 len == 0 的用途

仅更新 __i2c_first_dynamic_bus_num，用于 预留总线编号，确保后续动态 adapter 不会占用该号。

12. 导出符号策略

1
2
3
4
5
6
7
8

DECLARE_RWSEM(__i2c_board_lock);
EXPORT_SYMBOL_GPL(__i2c_board_lock);

LIST_HEAD(__i2c_board_list);
EXPORT_SYMBOL_GPL(__i2c_board_list);

int __i2c_first_dynamic_bus_num;
EXPORT_SYMBOL_GPL(__i2c_first_dynamic_bus_num);

注释写明：仅 i2c core 使用，不保证给其他模块。模块版本仅限 GPL。

公开给用户/板级代码的只有：

• i2c_register_board_info()（include/linux/i2c.h）

13. 调试与验证

13.1 确认 boardinfo 是否参与

1
2
3
4
5
6

# RK3588 预期：无 boardinfo 注册
grep -r i2c_register_board_info arch/arm64/

# 查看某总线上 client 来源
ls /sys/bus/i2c/devices/
cat /sys/bus/i2c/devices/2-0020/of_node/compatible   # DT 设备有 of_node

13.2 若移植遗留 boardinfo 代码

• 确认 busnum 与 aliases / adap->nr 一致；
• 确认在 i2c-rk3x probe 之前 调用（通常需改 arch init，RK 上不推荐）；
• 用 dmesg 查看 Can't create device at 0x..（地址冲突或 probe 失败）。

14. 功能对照总表

15. 结论

i2c-boardinfo.c 是 I2C 子系统中体量很小但历史上很重要的一层：

1. 职责单一：在 adapter 出现之前，把 (busnum, i2c_board_info) 登记到全局链表；
2. 延迟绑定：adapter 注册时由 i2c_scan_static_board_info() 实例化 i2c_client；
3. 总线号协调：通过 __i2c_first_dynamic_bus_num 避免与动态分配、DT alias 冲突；
4. RK3588：产品使用 纯 DT（of_i2c_register_devices），不依赖 本文件；阅读 RK I2C Bring-up 可 跳过 boardinfo，重点放在 DTS + i2c-rk3x.c + client 驱动。

若在维护旧架构移植代码时遇到 i2c_register_board_info()，应评估是否可改为 DTS 描述，以与当前 Rockchip 内核一致。

16. 推荐阅读顺序

1. i2c-boardinfo.c（全文）
2. drivers/i2c/i2c-core.h — i2c_devinfo
3. include/linux/i2c.h — i2c_board_info、i2c_register_board_info
4. i2c-core-base.c — i2c_scan_static_board_info、i2c_register_adapter
5. i2c-core-of.c — RK3588 实际设备枚举路径

17. 相关文档

• rk3588-kernel-6.1-drivers-i2c目录功能详细分析_zh.md
• rk3588-kernel-6.1-drivers-i2c-busses目录功能详细分析_zh.md
• rk3588-kernel-6.1-i2c总线架构分析.md

文档版本：基于 rk3588/kernel-6.1 源码树 drivers/i2c/i2c-boardinfo.c 分析。

RK3588 kernel-6.1/drivers/i2c/i2c-core-acpi.c 功能详细分析

1. 文档范围与说明

路径说明： 用户表述为「i2c-core-acpi.c 目录」，实际为 单个源文件：

• rk3588/kernel-6.1/drivers/i2c/i2c-core-acpi.c（约 825 行）

该文件在 Makefile 中作为 i2c-core 复合模块 的可选组成部分编译：

1

i2c-core-$(CONFIG_ACPI) += i2c-core-acpi.o

文档保存路径： linuxDoc/drivers/i2c/

定位： 为 x86/ACPI 固件平台 提供 I2C 子系统的 ACPI 支持：从 ACPI 命名空间解析 I2cSerialBus 资源、枚举从设备、解析 IRQ/总线速率，并可选实现 ACPI Operation Region（固件通过 AML 访问 I2C）。

与 RK3588 的关系： Rockchip ARM64 产品内核通常 不启用 CONFIG_ACPI（rockchip_linux_defconfig 中无 ACPI 配置），因此 本文件在 RK3588 默认构建中通常不参与链接；设备枚举走 i2c-core-of.c。本文仍完整分析其机制，便于对比 x86 与 ARM/DT 路径。

2. 功能总览

3. 编译与配置依赖

3.1 依赖链

1
2
3
4

CONFIG_I2C=y
    └── CONFIG_ACPI=y          → 编译 i2c-core-acpi.o 并链接进 i2c-core.ko
            └── CONFIG_ACPI_I2C_OPREGION=y（默认 y）
                    → 启用 Operation Region 代码（文件内 #ifdef 块）

3.2 Kconfig（drivers/i2c/Kconfig）

1
2
3
4

config ACPI_I2C_OPREGION
    bool "ACPI I2C Operation region support"
    depends on I2C=y && ACPI
    default y

说明：允许 BIOS/UEFI 固件中的 AML 代码通过 General Serial Bus（GSBUS） 地址空间访问 I2C 从设备（如智能电池）。

3.3 无 ACPI 时的桩函数（i2c-core.h）

1
2
3
4
5
6
7

#ifdef CONFIG_ACPI
void i2c_acpi_register_devices(struct i2c_adapter *adap);
int i2c_acpi_get_irq(struct i2c_client *client, bool *wake_capable);
#else
static inline void i2c_acpi_register_devices(struct i2c_adapter *adap) { }
static inline int i2c_acpi_get_irq(...) { return 0; }
#endif

RK3588 无 ACPI 时，上述调用在编译期被优化为空操作。

4. 核心数据结构

4.1 struct i2c_acpi_lookup

查找/填充 i2c_board_info 时的临时上下文：

4.2 struct i2c_acpi_handler_data（Operation Region）

1
2
3
4

struct i2c_acpi_handler_data {
    struct acpi_connection_info info;
    struct i2c_adapter *adapter;
};

绑定到 adapter 父设备的 ACPI handle，供 i2c_acpi_space_handler 使用。

4.3 struct gsb_buffer

ACPI GSBUS 访问协议缓冲区布局（status/len/data），与 AML _REG 读写格式对应。

5. ACPI 资源模型：I2cSerialBus

5.1 i2c_acpi_get_i2c_resource()

从 struct acpi_resource 中筛选：

1. type == ACPI_RESOURCE_TYPE_SERIAL_BUS
2. serial_bus.type == ACPI_RESOURCE_SERIAL_TYPE_I2C

成功则得到 struct acpi_resource_i2c_serialbus *，包含：

导出符号，供其他驱动（如 DesignWare I2C、平台驱动）解析 ACPI 资源。

5.2 i2c_acpi_client_count()

统计某 acpi_device 的 CRS（Current Resource Settings）中有多少个 I2cSerialBus 资源，用于需要多 client 的驱动。

6. 设备查找与注册流程

6.1 核心查找：i2c_acpi_do_lookup()

对单个 acpi_device 执行：

1
2
3
4
5
6

acpi_bus_get_status()           /* 设备必须 present */
acpi_dev_ready_for_enumeration()
过滤 i2c_acpi_ignored_device_ids  /* 如 ACPI_VIDEO_HID 误报 I2C */
acpi_dev_get_resources(..., i2c_acpi_fill_info, ...)
    → 填充 info->addr、adapter_handle、speed
acpi_get_handle(device, resource_source)  /* 解析 adapter 连接 */

失败返回 -EINVAL / -ENODEV。

6.2 i2c_acpi_get_info()

在 i2c_acpi_do_lookup 基础上：

• 若指定 adapter，校验 ACPI_HANDLE(&adapter->dev) == lookup.adapter_handle；
• 否则确认 adapter ACPI 设备存在且 status.present；
• 设置 info->fwnode = acpi_fwnode_handle(adev)；
• acpi_set_modalias() 填充 info->type（用于驱动匹配）。

6.3 Adapter 注册时批量枚举：i2c_acpi_register_devices()

调用点（i2c-core-base.c → i2c_register_adapter()）：

1
2
3

of_i2c_register_devices(adap);
i2c_acpi_install_space_handler(adap);
i2c_acpi_register_devices(adap);

实现逻辑：

1
2
3
4
5
6
7
8
9
10
11
12
13

void i2c_acpi_register_devices(struct i2c_adapter *adap)
{
    if (!has_acpi_companion(&adap->dev))
        return;

    /* 从 ACPI 根向下 walk，深度最多 32 层 */
    acpi_walk_namespace(ACPI_TYPE_DEVICE, ACPI_ROOT_OBJECT,
                        I2C_ACPI_MAX_SCAN_DEPTH,
                        i2c_acpi_add_device, NULL, adap, NULL);

    /* 清除父设备依赖，避免 adapter 无法 suspend */
    acpi_dev_clear_dependencies(ACPI_COMPANION(adap->dev.parent));
}

i2c_acpi_add_device 对每个 handle：

1. i2c_acpi_get_info() 得到 i2c_board_info；
2. i2c_acpi_register_device() → i2c_new_client_device()；
3. acpi_device_set_enumerated() 标记已枚举，避免重复。

6.4 与 OF 枚举的并行关系

同一 adapter 注册时 同时 执行：

三者互不排斥，但同一地址不应在 DT 与 ACPI 中重复声明。

6.5 时序图（x86）

1
2
3
4
5
6
7

PCI/platform I2C adapter probe
  → i2c_add_numbered_adapter()
      → of_i2c_register_devices()      [通常为空]
      → i2c_acpi_register_devices()
            acpi_walk_namespace → 各 I2C 从设备
            i2c_new_client_device()
      → i2c_driver 匹配 → probe

7. 运行时热插拔：i2c_acpi_notifier

在 i2c_init() 注册：

1

acpi_reconfig_notifier_register(&i2c_acpi_notifier);

用于 ACPI 动态重配置（较少见，多用于服务器/特殊平台）。

8. IRQ 与电源相关

8.1 i2c_acpi_get_irq()

调用点： i2c_device_probe()（i2c-core-base.c），当 client 无 DT irq 且存在 ACPI companion 时：

1
2
3
4
5

} else if (ACPI_COMPANION(dev)) {
    irq = i2c_acpi_get_irq(client, &wake_capable);
    if (irq > 0 && wake_capable)
        client->flags |= I2C_CLIENT_WAKE;
}

解析顺序：

1. 扫描 ACPI 资源中的中断资源 → i2c_dev_irq_from_resources()；
2. 若无，尝试 acpi_dev_gpio_irq_wake_get()（ACPI GPIO 中断扩展）；
3. 返回 IRQ 号或负错误码。

8.2 i2c_acpi_waive_d0_probe()

当 i2c_driver 设置 I2C_DRV_ACPI_WAIVE_D0_PROBE 且 ACPI 设备电源状态允许时，跳过 dev_pm_domain_attach() 的 D0 探测，避免某些固件枚举顺序导致的 probe 失败。

9. 总线速率：i2c_acpi_find_bus_speed()

用途： 部分 I2C adapter 驱动（如 i2c-designware）在 probe 时若 DT 未给 clock-frequency，则调用此函数从 ACPI 推断速率。

算法：

1. acpi_walk_namespace 扫描所有 I2C 从设备；
2. 仅统计连接到当前 adapter handle 的设备；
3. 取 最慢 的 connection_speed 作为 min_speed；
4. 特殊 quirk：存在 MSSL1680（Silead 触摸）时 强制 400kHz（i2c_acpi_force_400khz_device_ids）。

导出符号，供 i2c-designware-common.c、i2c-amd-mp2-plat.c 等使用。

10. 辅助 API

10.1 i2c_acpi_find_adapter_by_handle()

通过 bus_find_device(..., device_match_acpi_handle) 在 i2c_bus_type 上查找 adapter。用于 ACPI 设备需绑定到特定 adapter 的场景（如 i2c-mux-gpio ACPI 路径）。

10.2 i2c_acpi_new_device_by_fwnode()

当单个 ACPI 设备含有 多个 I2cSerialBus 资源时，默认枚举只创建第一个；本 API 按 index 创建第 N 个资源的 client。

使用示例： Intel Cherry Trail 平台 intel/chtwc_int33fe.c（电池、FUSB302 等）、serial-multi-instantiate 驱动。

10.3 忽略列表 i2c_acpi_ignored_device_ids

1

{ ACPI_VIDEO_HID, 0 },  /* 显卡 ACPI 设备误带 I2C 资源，忽略 */

11. ACPI Operation Region（CONFIG_ACPI_I2C_OPREGION）

11.1 目的

UEFI/BIOS 中的 AML 字节码 可通过 Operation Region 在运行时访问硬件。本驱动在 adapter 父设备 的 ACPI handle 上安装 GSBUS（General Serial Bus） 地址空间处理器，使固件能经 I2C adapter 读写从设备（典型：智能电池 SMBus）。

11.2 安装与拆除

1
2

i2c_acpi_install_space_handler(adapter);   /* adapter 注册时 */
i2c_acpi_remove_space_handler(adapter);    /* adapter 删除时 */

• 父设备必须有 ACPI companion；
• acpi_install_address_space_handler(..., ACPI_ADR_SPACE_GSBUS, i2c_acpi_space_handler, ...)。

11.3 i2c_acpi_space_handler()

根据 AML 访问类型转发到 Linux I2C/SMBus API：

每次访问临时构造 i2c_client（仅 addr/flags/adapter），不注册到驱动模型。

11.4 与 core 文档的对应

顶层 Kconfig 说明：

Operation Regions allow firmware (BIOS) code to access I2C slave devices, such as smart batteries through an I2C host controller driver.

12. 与 i2c-core-base.c 的集成点汇总

13. 导出符号一览

内部函数（i2c-core.h 声明给 core）：i2c_acpi_register_devices、i2c_acpi_get_irq、i2c_acpi_install/remove_space_handler。

14. RK3588 平台说明

14.1 默认是否编译

14.2 何时需要了解本文件

• 维护 跨平台 驱动（同一驱动同时支持 ACPI 与 OF）；
• 阅读 Intel/AMD x86 上 I2C 问题（枚举缺失、速率错误、电池 OP region）；
• 内核配置误开 ACPI 时的行为分析（ARM 上一般应关闭）。

14.3 与 RK3588 相关的唯一间接引用

i2c-rk3x.c 中含 rk3x_i2c_acpi_get_bus_id()，用于 ACPI 平台 下从 ACPI UID 获取 bus number；在纯 DT 的 RK3588 上使用 of_alias_get_id()，不经过 i2c-core-acpi.c 的枚举逻辑。

15. 三种设备声明方式对比（复习）

16. 调试建议（x86/ACPI 平台）

1
2
3
4
5
6
7
8
9
10

# 查看 ACPI companion
ls -l /sys/bus/i2c/devices/*/firmware_node

# 查看已枚举 client
ls /sys/bus/i2c/devices/

# 内核日志
dmesg | grep -i "i2c.*acpi\|enumerate I2C slaves"

# 禁用 ACPI I2C 枚举（调试）：通常通过不编译 CONFIG_ACPI 或修复 DSDT

17. 结论

i2c-core-acpi.c 是 Linux I2C 子系统在 ACPI/UEFI 固件体系 下的核心适配层，主要完成：

1. 从 ACPI I2cSerialBus 资源解析地址、adapter 关联、速率、10 位地址；
2. 在 I2C adapter 注册 时遍历 ACPI 命名空间 自动创建 i2c_client；
3. 支持 热插拔重配置、多资源 client、IRQ/GPIO 唤醒；
4. 可选 Operation Region 让固件 AML 经 GSBUS 访问 I2C；
5. 为 adapter 驱动提供 总线速率推断 等辅助能力。

对 RK3588：默认 无 ACPI，I2C 完全依赖 Device Tree + i2c-rk3x.c；本文件属于架构对比与 x86 维护知识，而非 RK 产品路径的必读本。

18. 推荐阅读顺序

1. i2c-core-acpi.c — i2c_acpi_register_devices、i2c_acpi_do_lookup
2. i2c-core-base.c — i2c_register_adapter、i2c_device_probe
3. include/linux/i2c.h — I2C_DRV_ACPI_WAIVE_D0_PROBE
4. drivers/i2c/busses/i2c-designware-common.c — i2c_acpi_find_bus_speed 使用示例
5. Documentation/firmware-guide/acpi/ — I2cSerialBus 规范（内核文档）

19. 相关文档

• rk3588-kernel-6.1-drivers-i2c目录功能详细分析_zh.md
• rk3588-kernel-6.1-i2c-boardinfo.c功能详细分析_zh.md
• rk3588-kernel-6.1-drivers-i2c-busses目录功能详细分析_zh.md

文档版本：基于 rk3588/kernel-6.1 源码树 drivers/i2c/i2c-core-acpi.c 分析。

RK3588 kernel-6.1/drivers/i2c/i2c-core-base.c 功能详细分析

1. 文档范围与说明

路径说明： 用户表述为「i2c-core-base.c 目录」，实际为 单个源文件：

• rk3588/kernel-6.1/drivers/i2c/i2c-core-base.c（约 2723 行）

编译关系： 作为 i2c-core 复合模块的主干，始终参与链接（CONFIG_I2C=y 时）：

1
2
3
4

i2c-core-objs := i2c-core-base.o i2c-core-smbus.o
i2c-core-$(CONFIG_ACPI)  += i2c-core-acpi.o
i2c-core-$(CONFIG_OF)    += i2c-core-of.o
i2c-core-$(CONFIG_I2C_SLAVE) += i2c-core-slave.o

文档保存路径： linuxDoc/drivers/i2c/

定位： Linux I2C 子系统的 核心实现：总线/设备模型、adapter 与 client 生命周期、i2c_transfer 传输路径、总线锁、总线恢复、驱动注册与（遗留）地址探测、Host Notify、debugfs/sysfs 等。SMBus 高层 API 在 i2c-core-smbus.c；DT 设备枚举在 i2c-core-of.c；ACPI 在 i2c-core-acpi.c。

与 RK3588 的关系： 本文件是 RK3588 I2C 栈的必经核心。i2c-rk3x.c 通过 i2c_add_numbered_adapter() 注册 adapter，经 of_i2c_register_devices() 创建 client，应用/驱动最终调用 i2c_transfer() → rk3x_i2c_xfer()。

2. 功能总览（按模块）

3. 源码在 I2C 子系统中的位置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

           ┌─────────────────────────────────────┐
           │         用户空间 / 其它内核模块        │
           │  i2c-dev.c  │  各 i2c_driver 驱动     │
           └─────────────┬───────────────────────┘
                         │
           ┌─────────────▼───────────────────────┐
           │      i2c-core-base.c（本文）         │
           │  bus_type、adapter/client、transfer   │
           └─┬─────────┬─────────┬───────────────┘
             │         │         │
i2c-core-smbus.c   i2c-core-of.c  i2c-core-acpi.c
(SMBus API)        (DT 枚举)      (ACPI 枚举, x86)
             │
┌────────────▼────────────┐
│  busses/i2c-rk3x.c 等    │
│  algo->master_xfer      │
└─────────────────────────┘

4. 子系统初始化（i2c_init）

入口： postcore_initcall(i2c_init) — 必须 早于 部分 subsys_initcall 中注册的 I2C 驱动。

主要步骤：

1. of_alias_get_highest_id("i2c") — 根据 DT alias 调整动态总线号起点 __i2c_first_dynamic_bus_num；
2. bus_register(&i2c_bus_type) — 注册 i2c 总线；
3. debugfs_create_dir("i2c", NULL) — 创建 /sys/kernel/debug/i2c/；
4. 注册 dummy_driver（占位，保证总线上有驱动可做匹配）；
5. 注册 OF/ACPI 重配置 notifier（动态 DT/ACPI 热插拔）。

全局状态：

• static DEFINE_MUTEX(core_lock) — 保护 i2c_adapter_idr 与探测序列化；
• static DEFINE_IDR(i2c_adapter_idr) — 总线号 → i2c_adapter 映射；
• static bool is_registered — 防止 adapter 在 bus 注册前添加。

5. 设备模型：i2c_bus_type 与 probe 路径

5.1 总线定义

1
2
3
4
5
6
7

struct bus_type i2c_bus_type = {
    .name     = "i2c",
    .match    = i2c_device_match,   /* OF / ACPI / i2c_device_id */
    .probe    = i2c_device_probe,
    .remove   = i2c_device_remove,
    .shutdown = i2c_device_shutdown,
};

匹配顺序（i2c_device_match）： OF 表 → ACPI 表 → i2c_device_id 表 → 按设备名匹配。

5.2 i2c_device_probe() 要点（RK3588 走 DT 分支）

Host Notify： I2C_CLIENT_HOST_NOTIFY 时通过 adapter 上 irq_domain 将 SMBus 通知映射为 client 的 client->irq。

6. Adapter 注册与删除

6.1 两种注册 API

i2c_add_adapter() 若 adapter 的 dev.of_node 有 i2c alias，则转为 numbered 注册。

6.2 i2c_register_adapter() 流程

1
2
3
4
5
6
7
8
9
10
11
12

i2c_register_adapter(adap)
  ├─ 校验 adap->algo、设置 lock_ops、timeout
  ├─ i2c_setup_host_notify_irq_domain()
  ├─ device_register() → sysfs: /sys/bus/i2c/devices/i2c-N
  ├─ debugfs_create_dir()
  ├─ i2c_setup_smbus_alert()          [i2c-core-smbus.c]
  ├─ pm_runtime_enable()
  ├─ i2c_init_recovery()              [GPIO / 通用 SCL 恢复]
  ├─ of_i2c_register_devices()        [DT 子设备, RK3588 主路径]
  ├─ i2c_acpi_*()                     [x86, 通常无]
  ├─ i2c_scan_static_board_info()     [CONFIG_I2C_BOARDINFO, RK 通常无]
  └─ bus_for_each_drv → i2c_do_add_adapter → i2c_detect()

6.3 i2c_del_adapter() 流程

注销 adapter 前：卸载所有 client（含 dummy）、移除 ACPI OP region handler、注销设备、释放 Host Notify domain、从 idr 删除。

6.4 devm_i2c_add_adapter()

设备资源管理封装：adapter 随 parent dev 自动 i2c_del_adapter。

7. Client 创建与注销

7.1 i2c_new_client_device()

调用者： of_i2c_register_devices()、i2c_acpi_register_devices()、驱动 detect、sysfs new_device 等。

流程摘要：

1. 从 i2c_board_info 填充 addr、flags、name、fwnode、of_node；
2. i2c_check_addr_validity() — 7 位禁止 0x00，10 位 ≤ 0x3ff；
3. i2c_lock_addr() — 防止并发重复实例化同一 7 位地址；
4. i2c_check_addr_ex() — 统计同地址已有 client 数量（用于命名后缀）；
5. device_register() → 触发 i2c_device_probe()；
6. 设备名规则：i2c-%04x 或 bus-addr-index（见 i2c_dev_set_name）。

7.2 其它 client API

7.3 Dummy 驱动

dummy_driver 在 core 初始化时注册，使未绑定具体驱动的 client 仍可存在于总线上（供 i2c_transfer 直接访问或 mux 使用）。

8. 数据传输核心：i2c_transfer

8.1 调用链（RK3588 典型）

1
2
3
4
5
6
7
8
9

驱动 i2c_master_send() / i2c_transfer()
  → i2c_transfer(adap, msgs, num)
       → __i2c_lock_bus_helper(adap)     /* rt_mutex, 支持 mux 树深度 */
       → __i2c_transfer(adap, msgs, num)
            → __i2c_check_suspended()
            → i2c_check_for_quirks()      /* adap->quirks */
            → adap->algo->master_xfer()   /* rk3x: rk3x_i2c_xfer */
            → 失败 -EAGAIN 时按 adap->retries/timeout 重试
       → i2c_unlock_bus()

8.2 __i2c_transfer 细节

• 要求 adap->algo->master_xfer 存在，否则 -EOPNOTSUPP；
• 原子上下文： 若 i2c_in_atomic_xfer_mode() 且存在 master_xfer_atomic，则走原子路径（RK3x：rk3x_i2c_xfer_polling）；
• Tracepoint： i2c_transfer trace 启用时记录 read/write/reply；
• 仲裁丢失： 返回 -EAGAIN 时在 adap->timeout 内重试。

8.3 Adapter Quirks（i2c_check_for_quirks）

限制单次传输：max_num_msgs、max_read_len、max_write_len、组合消息 I2C_AQ_COMB 等。主机驱动可在 adap->quirks 中声明硬件限制。

8.4 i2c_transfer_buffer_flags()

对单条消息的便捷封装：根据 I2C_M_RD 设置读写方向。

8.5 DMA 安全缓冲

i2c_get_dma_safe_msg_buf() / i2c_put_dma_safe_msg_buf()：

• 当 msg->buf 非 DMA 安全且长度 ≥ threshold 时分配 bounce buffer；
• 读完成后 memcpy 回原始 buffer；
• RK3x 等 DMA 主机驱动在传输前可调用以避免 DMA 映射失败。

9. 总线锁与 MUX 树

9.1 默认锁实现

1
2
3
4
5

static const struct i2c_lock_operations i2c_adapter_lock_ops = {
    .lock_bus    = i2c_adapter_lock_bus,    /* rt_mutex_lock_nested */
    .trylock_bus = i2c_adapter_trylock_bus,
    .unlock_bus  = i2c_adapter_unlock_bus,
};

i2c_adapter_depth() 沿 i2c_parent_is_i2c_adapter() 向上计数，用于 lockdep 嵌套子类，避免 mux 父子 adapter 死锁。

9.2 地址占用检查

• i2c_check_addr_busy() — 本 adapter 及 mux 父/子 链上是否已有该地址；
• i2c_encode_flags_to_addr() — 10 位地址、I2C_CLIENT_SLAVE 等标志编码到唯一键值。

10. 总线恢复（Bus Recovery）

当 SDA 被拉低导致总线挂死时，adapter 可配置 adap->bus_recovery_info：

初始化： i2c_register_adapter() 内 i2c_init_recovery()；失败则清除 bus_recovery_info（非致命）。

RK3588 i2c-rk3x 是否在 DT 中启用 recovery 取决于板级 dtsi；core 提供通用框架。

11. Host Notify 与 SMBus Alert

12. 驱动注册与遗留探测

12.1 i2c_register_driver() / i2c_del_driver()

• 将 i2c_driver 挂到 i2c_bus_type；
• 对已存在的每个 adapter 调用 i2c_do_add_adapter() → i2c_detect()。

12.2 i2c_detect()（遗留机制）

当驱动提供 address_list + detect() 时：

1. 对列表中每个 7 位地址创建临时 client；
2. i2c_default_probe() — SMBus Quick Write 或 Byte Read（避免损坏 EEPROM）；
3. 调用 driver->detect() 填充 i2c_board_info；
4. i2c_new_client_device() 实例化。

RK3588： 现代平台 几乎不用 class-based detect；设备由 DT 声明。仍保留以兼容旧 x86/工业板。

12.3 i2c_clients_command()

向 adapter 下所有已绑定 client 广播 driver->command()（电源管理等）。

13. Sysfs 与 Debugfs

13.1 Adapter 属性（/sys/bus/i2c/devices/i2c-N/）

13.2 Client 属性

name、modalias — 支持 udev 冷插拔 modprobe。

13.3 Debugfs

/sys/kernel/debug/i2c/i2c-N/ — 各 adapter 子目录（具体节点由主机驱动或 core 扩展添加）。

14. 设备树时序解析

i2c_parse_fw_timings(dev, &timings, use_defaults) 从 DT 读取：

• clock-frequency、i2c-scl-falling-time、i2c-scl-rising-time 等；
• 供 主机驱动（如 DesignWare、部分 SoC）计算分频，非 RK3x 专用。

RK3x 通常在驱动内直接读 clock-frequency；若需统一时序可调用此 API。

15. 与兄弟文件的分工

16. RK3588 端到端路径示例

以 i2c-rk3x + 摄像头传感器为例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

1. platform_driver probe (i2c-rk3x.c)
     adap->algo->master_xfer = rk3x_i2c_xfer
     i2c_add_numbered_adapter(&i2c->adap)   // nr 来自 DT alias

2. i2c_register_adapter() [i2c-core-base.c]
     of_i2c_register_devices(adap)          [i2c-core-of.c]
       → 解析 i2cN 下子节点
       → i2c_new_client_device()          [i2c-core-base.c]

3. i2c_device_probe()                      [i2c-core-base.c]
     of_irq_get → client->irq
     sensor i2c_driver->probe()

4. 传感器驱动读写
     i2c_transfer(adap, msgs, 2)
       → rk3x_i2c_xfer()                   [i2c-rk3x.c 硬件寄存器]

关键配置： CONFIG_I2C=y、CONFIG_I2C_RK3X=y、CONFIG_I2C_CHARDEV（可选 /dev/i2c-N）。

17. 主要导出符号分类

17.1 传输与适配器

i2c_transfer, __i2c_transfer, i2c_transfer_buffer_flags, i2c_get_adapter, i2c_put_adapter, i2c_recover_bus, i2c_generic_scl_recovery, i2c_handle_smbus_host_notify, i2c_get_dma_safe_msg_buf, i2c_put_dma_safe_msg_buf

17.2 设备生命周期

i2c_add_adapter, i2c_add_numbered_adapter, i2c_del_adapter, devm_i2c_add_adapter, i2c_new_client_device, i2c_unregister_device, i2c_new_dummy_device, devm_i2c_new_dummy_device, i2c_new_ancillary_device, i2c_find_device_by_fwnode, i2c_find_adapter_by_fwnode, i2c_get_adapter_by_fwnode

17.3 驱动模型

i2c_bus_type, i2c_client_type, i2c_adapter_type, i2c_register_driver, i2c_del_driver, i2c_verify_client, i2c_verify_adapter, i2c_match_id, i2c_get_match_data, i2c_for_each_dev, i2c_clients_command

17.4 其它

i2c_freq_mode_string, i2c_check_7bit_addr_validity_strict, i2c_dev_irq_from_resources, i2c_adapter_depth, i2c_parse_fw_timings, i2c_probe_func_quick_read, i2c_get_device_id

18. 调试建议

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 查看总线与设备
ls /sys/bus/i2c/devices/
cat /sys/bus/i2c/devices/i2c-*/name

# 查看 client 与驱动绑定
ls -l /sys/bus/i2c/devices/*-*

# 内核日志
dmesg | grep -iE 'i2c-core|i2c-[0-9]|rk3x'

# 启用 transfer 跟踪（需 CONFIG_EVENT_TRACING）
# echo 1 > /sys/kernel/debug/tracing/events/i2c/enable

# debugfs
ls /sys/kernel/debug/i2c/

常见问题定位：

19. 结论

i2c-core-base.c 是 Linux I2C 子系统的 中枢实现，涵盖：

1. 子系统与总线注册（postcore_initcall）；
2. Adapter/Client 设备模型 与 driver core 集成；
3. i2c_transfer 统一传输入口 及锁、quirk、trace、重试；
4. 总线恢复、Host Notify、DMA bounce buffer；
5. 驱动注册与遗留 detect、sysfs 动态设备、debugfs；
6. 与 OF/ACPI/SMBus 子模块的衔接调用点。

对 RK3588：所有 SoC 内置 I2C（i2c-rk3x）与 DT 声明的外设均 必须经过本文件；理解 i2c_register_adapter → of_i2c_register_devices → i2c_new_client_device → i2c_transfer 链路是分析板级 I2C 问题的关键。

20. 推荐阅读顺序

1. i2c-core-base.c — i2c_register_adapter、i2c_transfer、i2c_new_client_device
2. i2c-core-of.c — RK3588 设备枚举
3. busses/i2c-rk3x.c — 硬件 master_xfer
4. include/linux/i2c.h — 公共 API 与结构体
5. Documentation/i2c/ — 实例化设备、总线恢复说明

21. 相关文档

• rk3588-kernel-6.1-drivers-i2c目录功能详细分析_zh.md
• rk3588-kernel-6.1-i2c-core-acpi.c功能详细分析_zh.md
• rk3588-kernel-6.1-i2c-boardinfo.c功能详细分析_zh.md
• rk3588-kernel-6.1-drivers-i2c-busses目录功能详细分析_zh.md
• rk3588-kernel-6.1-i2c总线架构分析.md

文档版本：基于 rk3588/kernel-6.1 源码树 drivers/i2c/i2c-core-base.c（约 2723 行）分析。

RK3588 kernel-6.1/drivers/i2c/i2c-core-of.c 功能详细分析

1. 文档范围与说明

路径说明： 用户表述为「i2c-core-of.c 目录」，实际为 单个源文件：

• rk3588/kernel-6.1/drivers/i2c/i2c-core-of.c（约 220 行）

编译关系： 在启用 Open Firmware / Device Tree 支持时编入 i2c-core.ko：

1

i2c-core-$(CONFIG_OF) += i2c-core-of.o

ARM64 Rockchip 内核 必然启用 CONFIG_OF，故本文件在 RK3588 上 始终参与链接。

文档保存路径： linuxDoc/drivers/i2c/

定位： I2C 子系统的 Device Tree 支持层：将 DTS 中挂在 I2C adapter 下的子节点解析为 i2c_board_info，并调用 i2c_new_client_device() 实例化 i2c_client；同时提供 OF 匹配辅助 与（可选）动态 DT 热插拔 通知。

与 RK3588 的关系： 这是 RK3588 上 I2C 从设备枚举的主路径。i2c-rk3x.c 注册 adapter 后，板级 dtsi 中 &i2cN { ... } 下的 compatible + reg 子节点均经本文件创建 client，再与对应 i2c_driver 匹配 probe。

2. 功能总览

3. 在 I2C 栈中的位置

1
2
3
4
5
6
7
8
9
10
11
12
13
14

板级 DTS (&i2c2 { hym8563@51 { compatible; reg; }; })
        │
        ▼
i2c-rk3x probe → i2c_add_numbered_adapter()
        │
        ▼
i2c_register_adapter()                    [i2c-core-base.c]
        │
        ├── of_i2c_register_devices()     [i2c-core-of.c]  ← 本文
        │       for_each_available_child_of_node
        │       → of_i2c_get_board_info()
        │       → i2c_new_client_device() [i2c-core-base.c]
        │
        └── i2c_device_probe()            [驱动绑定]

与 ACPI（i2c_acpi_register_devices）和 boardinfo（i2c_scan_static_board_info）并列，RK3588 仅走 OF 路径。

4. of_i2c_get_board_info() — DT 节点 → i2c_board_info

1
2

int of_i2c_get_board_info(struct device *dev, struct device_node *node,
                          struct i2c_board_info *info);

4.1 解析流程

4.2 of_modalias_node() 行为

取 compatible 属性 第一个 字符串；若含 ,，则 modalias 为 逗号后 部分（去掉厂商前缀）。

示例：

1

compatible = "haoyu,hym8563";

→ info->type = "hym8563"（与 MODULE_DEVICE_TABLE(of, ...) 中条目或驱动名对应）。

4.3 reg 属性与地址标志（dt-bindings/i2c/i2c.h）

1
2

#define I2C_TEN_BIT_ADDRESS    (1 << 31)   /* 10 位寻址 */
#define I2C_OWN_SLAVE_ADDRESS  (1 << 30)   /* 本机为 slave 设备 */

RK3588 板级 DTS 通常仅使用 7 位地址，例如 reg = <0x51>。

4.4 错误返回

5. of_i2c_register_devices() — 核心枚举入口

1

void of_i2c_register_devices(struct i2c_adapter *adap);

调用点： i2c_register_adapter()（i2c-core-base.c），在 adapter device_register() 之后、ACPI/boardinfo 扫描之前执行。

5.1 前置条件

1
2

if (!adap->dev.of_node)
    return;

Adapter 的 struct device 必须已关联 DT 节点（i2c-rk3x 在 probe 中设置 adap.dev.of_node = pdev->dev.of_node）。无 of_node 则 不枚举任何子设备。

5.2 遍历哪一层子节点？

1
2
3
4
5

bus = of_get_child_by_name(adap->dev.of_node, "i2c-bus");
if (!bus)
    bus = of_node_get(adap->dev.of_node);

for_each_available_child_of_node(bus, node) { ... }

for_each_available_child_of_node 会跳过：

• status = "disabled" 的节点；
• 未通过 OF 可用性检查的节点。

5.3 OF_POPULATED 防重复

1
2

if (of_node_test_and_set_flag(node, OF_POPULATED))
    continue;

已实例化的节点不会再次注册。注销时 i2c_unregister_device() 会 of_node_clear_flag(..., OF_POPULATED)。

注册失败时清除标志：

1

of_node_clear_flag(node, OF_POPULATED);

5.4 与 RK3588 DTS 的对应关系

SoC dtsi 中控制器模板（rk3588s.dtsi）：

1
2
3
4
5
6

i2c0: i2c@fd880000 {
    compatible = "rockchip,rk3588-i2c", "rockchip,rk3399-i2c";
    #address-cells = <1>;
    #size-cells = <0>;
    status = "disabled";
};

板级 overlay（rk3588s-tablet.dtsi）：

1
2
3
4
5
6
7
8
9
10

&i2c2 {
    status = "okay";

    hym8563: hym8563@51 {
        compatible = "haoyu,hym8563";
        reg = <0x51>;
        wakeup-source;
        ...
    };
};

枚举结果：

• i2c_new_client_device() 在 i2c-2 总线上创建 client；
• sysfs 设备名类似 2-0051（bus 号 + 地址）；
• client->dev.of_node 指向 hym8563@51 节点。

6. of_i2c_register_device() — 单节点实例化

1
2

static struct i2c_client *of_i2c_register_device(struct i2c_adapter *adap,
                                                 struct device_node *node);

1. of_i2c_get_board_info(&adap->dev, node, &info)；
2. i2c_new_client_device(adap, &info) → 进入 driver core，触发 i2c_device_probe()。

供 of_i2c_register_devices() 与 动态 notifier 共用。

7. i2c_of_match_device() — 驱动与 client 匹配

1
2
3

const struct of_device_id *
i2c_of_match_device(const struct of_device_id *matches,
                    struct i2c_client *client);

7.1 匹配顺序

1. of_match_device(matches, &client->dev) — 标准 OF 匹配（client->dev.of_node 存在时）；
2. i2c_of_match_device_sysfs() — 回退：通过 sysfs 手动 new_device 创建的 client 无 of_node，用 client->name 与 compatible 字符串比较（支持 vendor,model 的短名匹配）。

7.2 在 core 中的使用

RK3588 驱动应提供 of_match_table，例如：

1
2
3
4
5

static const struct of_device_id rk3x_i2c_of_match[] = {
    { .compatible = "rockchip,rk3588-i2c" },
    { .compatible = "rockchip,rk3399-i2c" },
    { }
};

8. 动态 Device Tree（CONFIG_OF_DYNAMIC）

当内核启用 动态 OF（运行时 overlay / 配置扩展）时，编译 of_i2c_notify() 与全局 i2c_of_notifier。

注册： i2c_init() → of_reconfig_notifier_register(&i2c_of_notifier)。

8.1 OF_RECONFIG_CHANGE_ADD

1
2
3

of_find_i2c_adapter_by_node(rd->dn->parent)  /* 父节点必须是 adapter 的 of_node */
→ 清除 FWNODE_FLAG_NOT_DEVICE（便于 fw_devlink）
→ of_i2c_register_device()

要求新节点的 父 DT 节点 对应已注册的 i2c_adapter。

8.2 OF_RECONFIG_CHANGE_REMOVE

1
2

of_find_i2c_device_by_node(rd->dn)
→ i2c_unregister_device()

8.3 RK3588 说明

产品 rockchip_linux_defconfig 通常 不强调 CONFIG_OF_DYNAMIC；量产固件多在启动时加载完整 DTB。该路径主要用于 开发/测试 overlay，了解即可。

9. 与 I2C MUX 的协作

i2c-mux.c 在 i2c_mux_add_adapter() 中为每个 channel 创建子 adapter，并设置：

1

priv->adap.dev.of_node = child;  /* mux 节点下对应 channel 的子节点 */

随后 i2c_add_numbered_adapter() / i2c_add_adapter() 同样会调用 of_i2c_register_devices()，从而枚举 该 channel 下 DT 子设备。

典型 DTS 结构：

1
2
3
4
5
6
7
8
9
10
11
12
13

&i2c4 {
    i2c-mux@70 {
        compatible = "nxp,pca9548";
        reg = <0x70>;
        #address-cells = <1>;
        #size-cells = <0>;

        i2c@0 {
            reg = <0>;
            sensor@48 { compatible = "..."; reg = <0x48>; };
        };
    };
};

MUX 框架负责 channel adapter 的 of_node 指向 i2c@N 节点；具体传感器仍由 i2c-core-of.c 枚举。

10. 与 i2c-core-base.c 的衔接

IRQ / 时钟 / pinctrl 不在 i2c-core-of.c 解析，由 各 i2c_driver 的 probe 通过 dev->of_node 自行读取（如 devm_request_irq、devm_clk_get）。

11. 三种实例化方式对比（RK3588）

12. RK3588 端到端示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

启动
  rk3x_i2c_probe(i2c@fea90000)          /* i2c1 */
    adap.dev.of_node = pdev->dev.of_node
    i2c_add_numbered_adapter()           /* nr=1, 来自 aliases */

  i2c_register_adapter()
    of_i2c_register_devices(adap)
      节点: &i2c1 下无子设备 → 无 client

  rk3x_i2c_probe(i2c@feaa00000)          /* i2c2, tablet dtsi 有子节点 */
    of_i2c_register_devices()
      hym8563@51  → client 2-0051, type "hym8563"
      cw2015@62   → client 2-0062
      bq25703@6b  → client 2-006b

  hym8563 i2c_driver probe
    of_match_device("haoyu,hym8563")
    of_irq_get / clk / pinctrl from of_node

Aliases（rk3588s.dtsi）：

1
2
3
4
5

aliases {
    i2c0 = &i2c0;
    ...
    i2c8 = &i2c8;
};

保证 i2c_add_numbered_adapter 的 adap->nr 与 DTS i2cN 编号一致。

13. 导出符号与桩函数

14. 调试与常见问题

14.1 检查枚举结果

1
2
3
4
5

ls /sys/bus/i2c/devices/
# 例如 2-0051 -> ../../../devices/platform/feaa0000.i2c/i2c-2/2-0051

cat /sys/bus/i2c/devices/2-0051/name
cat /sys/bus/i2c/devices/2-0051/of_node/name   # 需 CONFIG_SYSFS 关联

14.2 设备未出现

14.3 驱动未 probe

• i2c_of_match_device 失败：检查 compatible 与驱动 of_match_table；
• 模块未加载：modalias / depmod；
• probe defer：依赖时钟/_regulator 未就绪（与 of.c 无直接关系）。

14.4 内核日志

1

dmesg | grep -iE 'of_i2c|i2c-[0-9]|Failed to create I2C device'

15. 源码结构速查（全文约 220 行）

1
2
3
4
5

L22-63   of_i2c_get_board_info()      导出：DT → i2c_board_info
L65-83   of_i2c_register_device()     单设备注册
L85-114  of_i2c_register_devices()  adapter 子节点批量枚举
L116-160 i2c_of_match_device*()      OF/sysfs 匹配
L162-220 of_i2c_notify / i2c_of_notifier  [CONFIG_OF_DYNAMIC]

16. 结论

i2c-core-of.c 体量小，却是 ARM/DT 平台 I2C 设备发现的枢纽：

1. 将 DTS 子节点的 compatible + reg 转为 i2c_board_info；
2. 在 adapter 注册时 自动创建 i2c_client；
3. 通过 OF_POPULATED 避免重复实例化；
4. 支持可选的 动态 DT 热插拔；
5. 增强 i2c_of_match_device 以兼容 sysfs 创建设备。

对 RK3588：板级所有 I2C 外设（RTC、PMIC、Codec、触摸、传感器、MUX 下设备等）均依赖本文件与 i2c-core-base.c 的配合；分析硬件 bring-up 问题时应 优先核对 DTS 与 dmesg 中 of_i2c 相关日志。

17. 推荐阅读顺序

1. i2c-core-of.c — of_i2c_register_devices、of_i2c_get_board_info
2. i2c-core-base.c — i2c_register_adapter、i2c_new_client_device
3. arch/arm64/boot/dts/rockchip/*.dtsi — 板级 &i2cN 子节点
4. busses/i2c-rk3x.c — adapter 注册与 of_node 绑定
5. Documentation/devicetree/bindings/i2c/ — 绑定文档

18. 相关文档

• rk3588-kernel-6.1-i2c-core-base.c功能详细分析_zh.md
• rk3588-kernel-6.1-i2c-core-acpi.c功能详细分析_zh.md
• rk3588-kernel-6.1-i2c-boardinfo.c功能详细分析_zh.md
• rk3588-kernel-6.1-drivers-i2c-muxes目录功能详细分析_zh.md
• rk3588-kernel-6.1-i2c总线架构分析.md

文档版本：基于 rk3588/kernel-6.1 源码树 drivers/i2c/i2c-core-of.c 分析。

RK3588 kernel-6.1/drivers/i2c/i2c-core-slave.c 功能详细分析

1. 文档范围与说明

路径说明： 用户表述为「i2c-core-slave.c 目录」，实际为 单个源文件：

• rk3588/kernel-6.1/drivers/i2c/i2c-core-slave.c（约 128 行）

编译关系： 仅在启用 CONFIG_I2C_SLAVE 时编入 i2c-core.ko：

1

i2c-core-$(CONFIG_I2C_SLAVE) += i2c-core-slave.o

文档保存路径： linuxDoc/drivers/i2c/

定位： I2C 子系统的 从机（Slave）模式核心薄层：在已有 i2c_client 与 i2c_adapter 框架上，提供 注册/注销从机回调、向从机后端投递总线事件、以及 从 DT 检测控制器是否应工作在从机模式 的通用 API。具体从机行为由 后端驱动（如 i2c-slave-eeprom.c）和 主机控制器驱动的 reg_slave/unreg_slave 实现。

与 RK3588 的关系：