OpenHarmony I2C驱动开发实战：从协议原理到排障优化

1. I2C 总线到底是个什么东西

1.1 从两根线说起：I2C 的物理层本质

I2C 这玩意儿，全称叫 Inter-Integrated Circuit，中文一般叫“集成电路总线”。名字听着挺唬人，但说白了它就是两根线：一根 SCL（串行时钟线），一根 SDA（串行数据线）。就这两根线，能挂一堆设备，主设备想跟谁说话就跟谁说话，靠的是每个从设备身上那个独一无二的地址。

我第一次接触 I2C 是在一块 OpenHarmony 的开发板上，当时要接一个温湿度传感器，看原理图就两根线拉出来，心里还想“这么简单？”。结果一上手才发现，简单是简单，但坑也是真不少。I2C 的物理层有个特别关键的设计：开漏输出加外部上拉电阻。什么意思呢？就是总线上的设备只能把线拉低，不能主动拉高。线要变高，全靠上拉电阻把电平拽上去。这个设计的好处是天然支持多设备“线与”逻辑——只要有一个设备拉低，整条线就是低电平，不会出现两个设备一个输出高一个输出低导致短路烧片子的情况。

上拉电阻的阻值选择是个经验活。常见的有 4.7kΩ、2.2kΩ、10kΩ。阻值太大，上升沿变缓，高速通信时波形还没到高电平就被拉低了，通信直接失败；阻值太小，低电平时灌电流太大，有些驱动能力弱的芯片扛不住。我一般先用 4.7kΩ 试，跑 100kHz 基本没问题，要跑 400kHz 甚至 1MHz 就得换 2.2kΩ 甚至 1.5kΩ。这个后面排障章节还会细说。

1.2 协议层：起始、停止、应答，三板斧走天下

I2C 的协议层其实就三个核心动作：起始条件（Start）、停止条件（Stop）、应答（ACK/NACK）。起始条件是 SCL 高电平期间 SDA 从高变低；停止条件是 SCL 高电平期间 SDA 从低变高。数据位在 SCL 低电平期间变化，在 SCL 高电平期间被采样。这个时序规则必须刻在脑子里，后面用逻辑分析仪抓波形的时候，一眼就能看出问题。

每次传输完 8 个数据位，接收方要拉低 SDA 一个时钟周期作为应答（ACK），表示“我收到了”。如果接收方不拉低，那就是 NACK，通常表示从设备没响应或者数据传完了。我在调试 GT911 触摸屏的时候，就遇到过主机发完地址后一直收不到 ACK，逻辑分析仪一看，SDA 一直是高电平，说明从设备根本没应答。后来查出来是触摸屏的复位时序不对，芯片压根没起来。

1.3 为什么 OpenHarmony 开发离不开 I2C

OpenHarmony 作为一个面向万物互联的操作系统，要支持各种各样的外设：传感器、触摸屏、EEPROM、RTC、IO 扩展芯片等等。这些外设大部分都是通过 I2C 挂到主控上的。你去看 RK3568 这类主控的引脚定义，I2C 控制器通常有 4 到 6 组，每组能挂多个设备。在 OpenHarmony 的 HDF（Hardware Driver Foundation）驱动框架里，I2C 驱动是标准化的，你只需要在设备树里配好寄存器地址、中断号、引脚复用，然后在驱动代码里调用 HDF 提供的 I2C 读写接口就行了。

但问题在于，设备树配置错了、上拉电阻没焊、地址冲突了、时序不满足，这些都会导致 I2C 通信失败。而 OpenHarmony 的日志系统有时候不会直接告诉你“I2C 挂了”，而是报一个“设备初始化失败”或者“传感器数据读取超时”，你得自己一层层往下扒。所以这篇文章，我就把 I2C 从原理到实操到排障，完整地捋一遍。

2. OpenHarmony 下 I2C 驱动的整体设计思路

2.1 HDF 框架下的 I2C 驱动分层

OpenHarmony 的驱动框架叫 HDF，全称 Hardware Driver Foundation。它的核心思想是驱动与内核解耦，驱动跑在用户态，通过 IPC 跟内核态通信。I2C 驱动在 HDF 里分三层：I2C Core 层、I2C Controller 层、I2C Device 层。

I2C Core 层提供统一的接口，比如I2cOpen、I2cClose、I2cTransfer。Controller 层负责具体主控的 I2C 控制器初始化，比如 RK3568 的 I2C 控制器寄存器配置。Device 层就是具体外设的驱动，比如 SSD1306 OLED 屏的驱动、DS18B20 温度传感器的驱动。

这种分层的好处是，你换一个主控平台，只要 Controller 层适配好了，Device 层的驱动代码基本不用动。我在 RK3568 和另一块国产主控之间移植一个 EEPROM 驱动，Device 层代码一行没改，只改了设备树和 Controller 的配置。

2.2 设备树：I2C 设备的“户口本”

在 Linux 和 OpenHarmony 里，设备树（Device Tree）是描述硬件拓扑的核心文件。I2C 设备在设备树里是这样挂的：先定义一个 I2C 控制器节点，然后在它下面挂子节点，每个子节点就是一个 I2C 设备。

以 RK3568 为例，I2C1 控制器的设备树大概长这样：

i2c1: i2c@fe5a0000 { compatible = "rockchip,rk3568-i2c"; reg = <0x0 0xfe5a0000 0x0 0x1000>; interrupts = <GIC_SPI 51 IRQ_TYPE_LEVEL_HIGH>; clocks = <&cru CLK_I2C1>, <&cru PCLK_I2C1>; clock-names = "i2c", "pclk"; pinctrl-names = "default"; pinctrl-0 = <&i2c1_xfer>; #address-cells = <1>; #size-cells = <0>; status = "okay"; eeprom@50 { compatible = "atmel,24c02"; reg = <0x50>; status = "okay"; }; };

这里有几个关键点：reg = <0x50>是从设备地址，7 位地址模式下 0x50 就是 EEPROM 的地址。compatible字段用来匹配驱动，内核会根据这个字符串找到对应的驱动代码。status = "okay"表示启用这个设备，如果写成"disabled"就不加载。

注意：设备树里的 I2C 地址是 7 位地址，但有些数据手册给的是 8 位地址（包含读写位）。比如 AT24C02 的 8 位地址是 0xA0（写）和 0xA1（读），7 位地址就是 0x50。设备树里必须填 7 位地址，填错了驱动根本匹配不上。

2.3 为什么选 HDF 而不是直接写内核驱动

有人可能会问，为什么不直接在 Linux 内核里写 I2C 驱动？答案很简单：OpenHarmony 的目标是轻量级、可裁剪、跨平台。内核态驱动一旦崩溃，整个系统就挂了。HDF 把驱动放到用户态，驱动崩了最多重启驱动进程，系统还能跑。而且 HDF 提供了一套统一的驱动开发接口，你写一次驱动，可以在不同主控上复用，不用每个平台都重写一遍。

当然代价也是有的：用户态驱动通过 IPC 跟内核通信，性能比内核态驱动差一些。但对于 I2C 这种低速总线（通常 100kHz 到 400kHz），IPC 的开销完全可以接受。我实测过，用 HDF 的 I2C 接口读一个 EEPROM 的 256 字节数据，耗时大概 3 到 5 毫秒，跟内核态驱动差别不大。

3. I2C 实操：从设备树配置到读写代码

3.1 设备树配置的完整流程

配置一个 I2C 设备，在设备树里要干这几件事：

第一步，确认引脚复用。RK3568 的 I2C1 默认引脚是 GPIO0_B3 和 GPIO0_B4，但这两个引脚可能被其他功能占用了。你需要在pinctrl节点里确认i2c1_xfer这个引脚组有没有被其他设备引用。如果被占用了，要么换一组 I2C，要么把其他设备关掉。

第二步，配置控制器节点。把status改成"okay"，确认clock-frequency设置正确。默认是 100kHz，如果要跑 400kHz，得加上clock-frequency = <400000>;。

第三步，添加从设备子节点。每个从设备一个子节点，reg填 7 位地址，compatible填驱动匹配字符串。如果有中断引脚，还要加interrupt-parent和interrupts。

第四步，编译设备树。在 OpenHarmony 的编译系统里，设备树文件通常放在device/rockchip/rk3568/目录下，编译命令是./build.sh --product-name rk3568 --build-target kernel。编译完把生成的.dtb文件烧录到板子上。

我踩过的一个坑是：设备树改了但没重新编译内核，直接烧了旧的.dtb，结果驱动一直加载失败。后来养成习惯，每次改完设备树，先make dtbs单独编译设备树，确认没报错再烧录。

3.2 I2C 读写代码的编写要点

在 HDF 框架下，I2C 读写的基本流程是这样的：

// 打开 I2C 控制器 DevHandle i2cHandle = I2cOpen(1); // 1 是 I2C 控制器编号 if (i2cHandle == NULL) { HDF_LOGE("I2cOpen failed"); return HDF_FAILURE; } // 准备读写消息 struct I2cMsg msgs[2]; uint8_t regAddr = 0x00; uint8_t dataBuf[16]; // 第一条消息：写寄存器地址 msgs[0].addr = 0x50; // 从设备地址 msgs[0].buf = &regAddr; msgs[0].len = 1; msgs[0].flags = 0; // 写操作 // 第二条消息：读数据 msgs[1].addr = 0x50; msgs[1].buf = dataBuf; msgs[1].len = 16; msgs[1].flags = I2C_FLAG_READ; // 读操作 // 执行传输 int32_t ret = I2cTransfer(i2cHandle, msgs, 2); if (ret != 2) { HDF_LOGE("I2cTransfer failed, ret = %d", ret); } // 关闭 I2C 控制器 I2cClose(i2cHandle);

这里的关键是I2cMsg结构体。addr是从设备地址，buf是数据缓冲区，len是数据长度，flags表示读还是写。对于 EEPROM 这种需要先写寄存器地址再读数据的设备，要用两条消息组合传输，中间不能有停止条件。HDF 的I2cTransfer会自动处理这种组合传输，不会在两条消息之间插入停止条件。

实操心得：I2cTransfer的返回值是成功传输的消息条数。如果你传了 2 条消息，返回值是 2 才算成功。返回值是 1 或者 0，说明中间某条消息失败了。这时候要检查从设备地址对不对、上拉电阻有没有焊、总线是不是被拉死了。

3.3 用逻辑分析仪抓 I2C 波形

排障 I2C 最有效的工具是逻辑分析仪。我用的是一款 8 通道的 USB 逻辑分析仪，配合开源的 PulseView 软件，能直接解码 I2C 协议。接线很简单：通道 0 接 SCL，通道 1 接 SDA，GND 接板子 GND。

抓到的波形里，你能看到起始条件、地址字节、读写位、ACK/NACK、数据字节、停止条件。如果地址字节后面没有 ACK，说明从设备没响应。如果数据字节后面没有 ACK，说明从设备收到了但可能内部出错了。如果 SCL 一直被拉低，说明总线被某个设备拉死了，通常是某个设备在通信过程中复位了，SCL 线卡在低电平。

我遇到过一次 SSD1306 OLED 屏不亮的问题，逻辑分析仪抓波形发现地址字节是 0x78，但 OLED 的 7 位地址应该是 0x3C，左移一位是 0x78。看起来没错，但就是没 ACK。后来查原理图发现，OLED 的复位引脚接到了一个 GPIO，但设备树里没配这个 GPIO，芯片一直处于复位状态。把复位 GPIO 配上之后，波形立刻正常了。

4. I2C 排障实战：常见问题与解决思路

4.1 总线被拉死：SCL 或 SDA 一直低电平

这是 I2C 最经典的故障。现象是：主机发起始条件后，SCL 或 SDA 一直保持低电平，后续通信全部失败。原因通常是某个从设备在通信过程中异常复位，导致它一直拉着 SDA 或 SCL 不放。

解决办法有几个：第一，给从设备加复位控制。在设备树里配一个 GPIO 作为复位引脚，驱动初始化时先拉低再拉高，确保从设备处于已知状态。第二，主机发送 9 个时钟脉冲。如果是从设备拉着 SDA 不放，主机可以手动切换 SCL 引脚为 GPIO 模式，发送 9 个时钟脉冲，让从设备把剩余的数据位发完，然后发停止条件。第三，加 I2C 多路复用器。如果总线上挂了多个设备，其中一个出问题会影响整条总线，可以用 PCA9548 这类多路复用器把总线分成多路，隔离故障设备。

我在一个项目里遇到过 DS18B20 挂在 I2C 总线上导致总线死锁的问题。DS18B20 其实是 1-Wire 协议，但有人把它接到 I2C 总线上当温度传感器用。结果 DS18B20 的时序跟 I2C 不兼容，通信几次之后就把 SDA 拉死了。后来换了一个真正的 I2C 温度传感器才解决。

4.2 地址冲突：两个设备用了同一个地址

I2C 总线上每个设备的地址必须唯一。但有些设备的地址是固定的，比如某些 EEPROM 的地址就是 0x50，不能改。如果你挂了两片同型号的 EEPROM，地址就冲突了。

解决办法：第一，选带地址选择引脚的型号。比如 AT24C02 有 A0、A1、A2 三个引脚，可以配置 8 个不同的地址。第二，用 I2C 多路复用器。把两个地址冲突的设备挂到不同的复用通道上，主机通过切换通道来访问不同的设备。第三，换型号。如果实在没法改地址，只能换一个地址不同的芯片。

排查技巧：在 Linux 系统里，可以用i2cdetect -y 1命令扫描 I2C1 总线上的所有设备地址。如果某个地址显示为UU，说明这个地址被驱动占用了；如果显示为数字，说明扫描到了设备但没驱动；如果什么都没显示，说明这个地址上没有设备响应。

4.3 时序不满足：上升沿太慢导致通信失败

I2C 的上升沿时间跟上拉电阻和总线电容有关。总线电容包括 PCB 走线电容、引脚电容、设备输入电容，通常几十 pF 到几百 pF。上升沿时间Tr约等于0.8473 × R × C。如果 R 是 10kΩ，C 是 200pF，Tr 就是 1.69 微秒。对于 100kHz 的 I2C，时钟周期是 10 微秒，高电平时间至少 4 微秒，1.69 微秒的上升沿还能接受。但如果跑 400kHz，时钟周期只有 2.5 微秒，高电平时间只有 0.6 微秒，1.69 微秒的上升沿就完全来不及了。

解决办法：减小上拉电阻。把 10kΩ 换成 4.7kΩ 甚至 2.2kΩ，上升沿时间能缩短一半以上。但要注意，电阻太小会导致低电平灌电流增大，有些芯片的 SDA/SCL 引脚驱动能力有限，灌电流太大会导致低电平不够低。一般 3.3V 系统用 2.2kΩ 到 4.7kΩ 比较合适，5V 系统用 4.7kΩ 到 10kΩ。

我实测过一组数据：同样 200pF 总线电容，10kΩ 上拉时上升沿 1.7 微秒，4.7kΩ 时 0.8 微秒，2.2kΩ 时 0.37 微秒。跑 400kHz 必须用 2.2kΩ 以下。

4.4 常见问题速查表

5. I2C 进阶：多路复用与自由数据模式

5.1 I2C 多路复用器的使用

当总线上设备太多，或者地址冲突无法解决时，I2C 多路复用器就是救星。PCA9548 是一款 8 通道 I2C 多路复用器，主机通过写它的控制寄存器来选择哪个通道导通。每个通道上可以挂地址相同的设备，因为同一时刻只有一个通道导通。

在设备树里配置 PCA9548 是这样的：

i2c1: i2c@fe5a0000 { ... pca9548@70 { compatible = "nxp,pca9548"; reg = <0x70>; #address-cells = <1>; #size-cells = <0>; i2c@0 { #address-cells = <1>; #size-cells = <0>; reg = <0>; eeprom@50 { compatible = "atmel,24c02"; reg = <0x50>; }; }; i2c@1 { #address-cells = <1>; #size-cells = <0>; reg = <1>; eeprom@50 { compatible = "atmel,24c02"; reg = <0x50>; }; }; }; };

这样两片地址都是 0x50 的 EEPROM 就能同时挂在 I2C1 上了，一片在通道 0，一片在通道 1。驱动访问的时候，内核会自动处理通道切换。

注意：PCA9548 的地址也是可配的，A0、A1、A2 引脚可以设置 0x70 到 0x77 共 8 个地址。如果总线上有多个 PCA9548，记得把地址错开。

5.2 I2C 自由数据模式

有些 I2C 控制器支持“自由数据模式”（Free Data Mode），也叫“无寄存器模式”。这种模式下，主机可以直接读写从设备的数据，不需要先写寄存器地址。比如某些 ADC 芯片，读出来的就是转换结果，没有寄存器概念。

在 HDF 里，自由数据模式通过I2cMsg的flags字段控制。如果flags设为I2C_FLAG_NO_START，表示这次传输不发送起始条件，直接接着上一次传输继续。如果设为I2C_FLAG_READ，表示读操作。组合使用可以实现各种灵活的传输方式。

我调试过一款 I2C 接口的编码器，它支持自由数据模式，主机发一个起始条件加地址，然后直接连续读 4 个字节就是角度值。用标准模式反而读不出来，因为芯片不认寄存器地址。

5.3 I2C 与 SMBus、PMBus 的区别

SMBus 是 I2C 的一个子集，主要用于电源管理和系统监控。PMBus 又是 SMBus 的扩展，专门用于电源管理。三者的电气特性基本兼容，但协议细节有差异。SMBus 的时钟频率固定在 100kHz，超时时间固定 35ms，而 I2C 没有这些限制。PMBus 在 SMBus 基础上增加了电源管理相关的命令集。

在 OpenHarmony 里，SMBus 设备通常也用 I2C 驱动来访问，因为电气层兼容。但要注意 SMBus 的超时机制，如果 I2C 传输超过 35ms，SMBus 设备可能会复位。我遇到过一款电源管理芯片，用 I2C 驱动读寄存器，偶尔会失败，后来发现是传输时间超过了 SMBus 的超时限制，把clock-frequency从 100kHz 降到 50kHz 就稳定了。

6. 我在 OpenHarmony I2C 调试中踩过的坑

6.1 设备树引脚复用冲突

RK3568 的引脚复用非常灵活，一个物理引脚可以配置成 GPIO、I2C、SPI、UART 等多种功能。但如果你在设备树里把同一个引脚配给了两个功能，内核会报错或者静默选择其中一个。我遇到过一次 I2C3 死活不通，查了半天发现 I2C3 的 SCL 引脚被配成了 PWM 输出。把 PWM 节点关掉之后，I2C3 立刻正常了。

排查方法：在设备树里搜索引脚编号，看有没有多个节点引用了同一个引脚。或者用cat /sys/kernel/debug/pinctrl/pinctrl-rockchip-pinmux查看引脚复用状态。

6.2 时钟频率配置错误

RK3568 的 I2C 控制器时钟源是 198MHz，分频系数是clk_rate / (clock-frequency * 8)。如果clock-frequency设成 100kHz，分频系数是 247.5，取整后实际频率是 100.2kHz，没问题。但如果设成 400kHz，分频系数是 61.875，取整后实际频率是 399.2kHz，也还行。但如果设成 1MHz，分频系数是 24.75，取整后实际频率是 990kHz，偏差就有点大了。

更坑的是，有些主控的 I2C 控制器不支持任意频率，只能选几个固定档位。如果你设了一个不支持的值，驱动可能会静默改成最接近的档位，或者直接报错。我建议先用 100kHz 调通，再逐步提高频率，每次都用逻辑分析仪确认实际波形。

6.3 中断引脚配置遗漏

很多 I2C 设备有中断输出引脚，比如 GT911 触摸屏、某些加速度计。如果设备树里没配中断引脚，驱动就只能轮询，效率低而且可能丢事件。GT911 的中断引脚必须配，否则触摸事件响应会很慢。

配置中断引脚的设备树片段：

gt911@5d { compatible = "goodix,gt911"; reg = <0x5d>; interrupt-parent = <&gpio0>; interrupts = <RK_PB5 IRQ_TYPE_EDGE_FALLING>; reset-gpios = <&gpio0 RK_PB6 GPIO_ACTIVE_LOW>; irq-gpios = <&gpio0 RK_PB5 GPIO_ACTIVE_HIGH>; };

这里interrupts指定了中断引脚和触发方式，reset-gpios和irq-gpios分别指定复位和中断 GPIO。GT911 的上电时序很讲究：先拉低复位，再拉低中断，然后释放复位，最后释放中断，芯片才能进入 I2C 模式。如果时序不对，I2C 地址可能变成 0x14 而不是 0x5d。

6.4 电源域和 IO 电压不匹配

有些 I2C 设备是 1.8V 供电，有些是 3.3V 供电。如果主控的 I2C 引脚是 3.3V 电平，从设备是 1.8V 电平，直接连会烧从设备。必须加电平转换芯片，比如 TXS0102、PCA9306。我见过有人直接把 1.8V 的摄像头模组接到 3.3V 的 I2C 上，上电就冒烟了。

排查方法：上电前先用万用表测主控 I2C 引脚的电平，再测从设备的数据手册确认 IO 电压。如果不匹配，要么加电平转换，要么把主控的 IO 电压也改成 1.8V（如果主控支持）。

7. 总结与个人经验分享

I2C 这东西，说简单也简单，两根线搞定；说复杂也复杂，时序、地址、上拉、复用、电源，任何一个环节出问题都能让你调一整天。我在 OpenHarmony 上调试 I2C 设备，最大的体会就是：逻辑分析仪是必备工具，设备树是核心配置，上拉电阻是隐形杀手。

逻辑分析仪能让你看到总线上实际发生了什么，而不是靠猜。设备树配错了，驱动根本不会加载，日志里可能只有一行“probe failed”，你得自己去核对每个字段。上拉电阻看起来不起眼，但阻值选错了，波形就是不对，通信就是不稳定。

最后分享一个小技巧：如果你怀疑某个 I2C 设备有问题，先把它从总线上摘下来，只留主控和上拉电阻，用逻辑分析仪看主控发出的起始条件和地址字节。如果主控波形正常，再一个一个把设备挂回去，每挂一个测一次。这样能快速定位是哪个设备把总线拉死的。

另外，OpenHarmony 的 HDF 框架虽然抽象层次高，但底层还是标准的 I2C 协议。你把 I2C 的时序图、地址格式、ACK 机制搞清楚了，不管是在 OpenHarmony 还是在裸机、Linux、RTOS 上，调试思路都是一样的。工具在变，协议不变。