OpenHarmony I2C驱动开发与排障实战：从协议到RK3568设备树配置

1. 从一根线说起I2C 在 OpenHarmony 里到底扮演什么角色很多人第一次接触 I2C脑子里冒出来的画面是两根线挂一堆芯片觉得这玩意儿简单得不行。真到了 OpenHarmony 设备上跑起来发现传感器读不到数、触摸屏没反应、EEPROM 写进去读出来全是 0xFF才开始意识到事情没那么简单。I2C 是 Inter-Integrated Circuit 的缩写中文叫集成电路总线物理层就两根线SCL 时钟线和 SDA 数据线都是开漏输出靠上拉电阻拉到高电平。所有设备挂在同一组总线上每个从设备有唯一的 7 位地址主机发起通信从机响应。就这么个东西在 OpenHarmony 的 HDF 驱动框架里却牵扯到设备树配置、总线控制器驱动、从设备驱动、用户态接口一整条链路。这篇内容适合谁看如果你正在 RK3568、Hi3861、STM32MP157 这类平台上跑 OpenHarmony需要接温湿度传感器、触摸屏、EEPROM、PMIC、RTC 这些 I2C 外设或者你已经接了但通信不稳定、时好时坏、根本扫不到设备那这篇就是写给你的。我会从 I2C 的协议本质讲起把 OpenHarmony 下 I2C 的驱动模型拆开然后一步步走通设备树配置、驱动适配、用户态读写最后重点放在排障上——毕竟实际项目里配通只是开始稳定跑起来才是本事。OpenHarmony 的 I2C 子系统属于 HDFHardware Driver Foundation框架的一部分分三层I2C 核心层提供统一接口I2C 控制器驱动层负责具体 SoC 的寄存器操作I2C 从设备驱动层对接具体的传感器或外设。用户态通过/dev/i2c-x设备节点访问或者在内核态通过 HDF 提供的 API 直接读写。理解这个分层后面排障的时候你才知道该往哪一层看。2. I2C 协议核心机制别被“简单”两个字骗了2.1 起始、停止与应答时序里的门道I2C 的通信过程看起来不复杂主机拉低 SDA 同时 SCL 保持高电平这是起始条件Start主机拉高 SDA 同时 SCL 保持高电平这是停止条件Stop。每个字节传输 8 位高位在前第 9 个时钟周期从机拉低 SDA 表示应答ACK不拉低就是非应答NACK。但实际调试中问题往往出在这些细节上。起始条件建立后主机发送 7 位从机地址加 1 位读写方向位共 8 位。从机如果存在且地址匹配会在第 9 个时钟拉低 SDA 应答。如果从机不存在或者地址不对SDA 保持高电平主机收到 NACK通信终止。很多新手用i2cdetect扫不到设备第一反应是驱动问题其实大概率是地址搞错了——7 位地址和 8 位地址差一位左移datasheet 上写 0x48实际通信时发的是 0x90 或 0x91。注意7 位地址左移一位后最低位是读写位。读操作是 1写操作是 0。有些 datasheet 直接给 8 位地址你要自己判断它是不是已经把读写位算进去了。时钟拉伸Clock Stretching是另一个容易被忽略的机制。从机如果处理不过来可以在应答后拉低 SCL强制主机等待。OpenHarmony 的 I2C 控制器驱动如果没正确处理时钟拉伸就会出现读数据超时或者读到错位数据。RK3568 的 I2C 控制器支持时钟拉伸但需要在设备树里确认clock-frequency设置合理一般 100kHz 和 400kHz 是标准模式1MHz 以上属于快速模式对走线和上拉电阻要求更高。2.2 上拉电阻不是随便焊一个就行I2C 总线是开漏输出没有上拉电阻就没有高电平。上拉电阻的阻值选择直接影响通信质量和功耗。阻值太大上升沿变缓高速通信时波形还没到高电平就被拉低了阻值太小功耗增加而且从机可能拉不低。经验公式是R_min (VDD - VOL_max) / IOL_maxR_max tr / (0.8473 × Cb)其中 tr 是上升时间要求Cb 是总线电容。实际项目中总线电容一般在 100pF 到 400pF 之间标准模式 100kHz 下4.7kΩ 到 10kΩ 是常见选择。快速模式 400kHz 下建议 2.2kΩ 到 4.7kΩ。如果总线上挂了多个设备或者走线很长电容增大上拉电阻要相应减小。我见过一个案例RK3568 开发板上 I2C 总线上拉了 10kΩ接了三个传感器后通信时好时坏换成 2.2kΩ 后立刻稳定。用示波器看波形上升沿从原来的 2μs 缩短到 300ns效果立竿见影。2.3 总线仲裁与时钟同步多主机场景的隐形规则虽然大多数 OpenHarmony 设备上 I2C 都是单主机模式但协议本身支持多主机。多主机同时发起通信时靠总线仲裁决定谁先发。仲裁的原则是谁发低电平谁赢发高电平的退出。时钟同步则是所有主机把自己的 SCL 低电平周期叠加最终 SCL 周期由最慢的主机决定。这个机制在单主机场景下用不到但理解它有助于你明白为什么 I2C 总线上不能随便拉低 SCL——任何设备拉低 SCL 都会影响整个总线的时钟。3. OpenHarmony 下 I2C 驱动模型拆解3.1 HDF 框架里的 I2C 分层OpenHarmony 的 I2C 子系统在 HDF 框架下分三层。最上面是 I2C 核心层提供I2cOpen、I2cClose、I2cTransfer这些统一接口用户态和内核态都通过这层访问。中间是 I2C 控制器驱动层每个 SoC 的 I2C 控制器有自己的驱动负责操作寄存器、处理中断、管理总线时序。最下面是 I2C 从设备驱动层针对具体的传感器或外设实现读写逻辑。这种分层的好处是换一个 SoC 只需要改控制器驱动从设备驱动不用动换一个传感器只需要改从设备驱动控制器驱动不用动。但实际调试时问题可能出在任何一层。用户态读不到数据可能是从设备驱动没注册可能是控制器驱动没初始化也可能是设备树里 I2C 节点没使能。3.2 设备树I2C 设备的“户口本”OpenHarmony 在 RK3568 这类平台上使用设备树描述硬件。I2C 控制器在设备树里是一个节点从设备挂在控制器节点下面。以 RK3568 为例I2C1 控制器的设备树节点大概长这样i2c1: i2cfe5a0000 { 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; clock-frequency 100000; gt911: touchscreen5d { 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; }; };这里有几个关键点。compatible字符串必须和驱动里的匹配表一致否则驱动不会绑定。reg是从设备的 I2C 地址GT911 的地址是 0x5d。status okay表示使能这个控制器如果写成disabled整个 I2C1 都不会工作。clock-frequency是总线时钟频率默认 100kHz如果从设备支持 400kHz 可以改。注意#address-cells 1和#size-cells 0是 I2C 控制器的标准写法表示子节点的地址用一个 cell 表示没有大小字段。如果写错了从设备节点无法正确解析。3.3 从设备驱动的注册与匹配从设备驱动在 HDF 框架下通过HdfDriverEntry注册在Bind函数里创建设备对象在Init函数里初始化硬件。驱动匹配靠的是compatible字符串设备树里的compatible和驱动里的of_match_table必须完全一致。以 GT911 触摸屏为例驱动里会定义static const struct OfDeviceNodeMatch g_gt911MatchTable[] { { .compatible goodix,gt911 }, { }, };如果设备树里写的是goodix,gt911驱动里写的是goodix,GT911大小写不一致匹配失败驱动不会加载。这种问题在排障时很容易被忽略因为系统日志里可能只提示“设备未找到”不会告诉你具体是哪个字符串不匹配。4. 实操从零配通一个 I2C 传感器4.1 硬件准备与接线检查假设我们要在 RK3568 开发板上接一个 SHT30 温湿度传感器I2C 地址 0x44。硬件上需要接四根线VCC、GND、SCL、SDA。SHT30 的 VCC 是 2.4V 到 5.5V开发板一般提供 3.3V。SCL 和 SDA 接开发板的 I2C1 引脚同时确认上拉电阻已经焊好。很多开发板自带上拉电阻但阻值可能偏大如果通信不稳定可以并联一个 2.2kΩ 电阻。接线完成后先用万用表测一下 SCL 和 SDA 对地的电压正常应该是 VCC 电压。如果测出来是 0V说明总线被拉死了可能是某个设备把 SDA 或 SCL 拉低不放需要逐个断开设备排查。4.2 设备树配置与编译在设备树里添加 SHT30 节点挂在 I2C1 下面i2c1 { status okay; clock-frequency 100000; sht30: sht3044 { compatible sensirion,sht30; reg 0x44; status okay; }; };如果 I2C1 的引脚被其他功能占用了需要在 pinctrl 里确认i2c1_xfer这个引脚组没有被覆盖。RK3568 的引脚复用比较灵活同一个引脚可以作 GPIO、I2C、SPI、UART 等设备树里 pinctrl 的配置决定了最终功能。编译设备树./build.sh --product-name rk3568 --build-target kernel编译完成后把生成的boot.img或resource.img烧录到开发板。启动后查看/proc/device-tree/i2cfe5a0000/目录确认status是okayclock-frequency是0x186a0100000 的十六进制。4.3 用户态读写验证OpenHarmony 提供了i2c-tools工具集可以在用户态直接操作 I2C 总线。先用i2cdetect扫描总线i2cdetect -y 1如果 SHT30 正常工作会在 0x44 位置显示44。如果显示--说明设备没响应需要检查地址、接线、上拉电阻。如果显示UU说明设备已经被驱动占用了这是正常现象。读取 SHT30 的数据需要先发送测量命令然后读取 6 个字节。SHT30 的单次测量命令是 0x2C06高精度模式。用i2cget和i2cset组合操作i2cset -y 1 0x44 0x2C 0x06 sleep 0.1 i2cget -y 1 0x44 0x00 w读到的原始数据需要转换温度 -45 175 × (raw_temp / 65535)湿度 100 × (raw_humi / 65535)。如果读出来全是 0xFF 或 0x00说明通信失败需要回到硬件层面排查。4.4 内核态驱动读写示例如果要在内核态驱动里读写 SHT30使用 HDF 提供的 I2C APIint32_t Sht30ReadData(struct HdfDeviceObject *device) { int32_t ret; uint8_t cmd[2] {0x2C, 0x06}; uint8_t data[6] {0}; struct I2cMsg msgs[2] {0}; msgs[0].addr 0x44; msgs[0].flags 0; msgs[0].len 2; msgs[0].buf cmd; msgs[1].addr 0x44; msgs[1].flags I2C_FLAG_READ; msgs[1].len 6; msgs[1].buf data; ret I2cTransfer(device-priv, msgs, 2); if (ret ! HDF_SUCCESS) { HDF_LOGE(SHT30 read failed, ret %d, ret); return ret; } uint16_t rawTemp (data[0] 8) | data[1]; uint16_t rawHumi (data[3] 8) | data[4]; float temperature -45.0f 175.0f * rawTemp / 65535.0f; float humidity 100.0f * rawHumi / 65535.0f; HDF_LOGI(Temperature: %.2f C, Humidity: %.2f %%, temperature, humidity); return HDF_SUCCESS; }这里的关键是I2cMsg数组第一个消息发送命令第二个消息读取数据。两个消息之间没有停止条件这是 I2C 的“重复起始”机制SHT30 需要这种时序。如果分成两次独立的I2cTransfer调用中间会有停止条件SHT30 可能不响应。5. 排障实录I2C 通信失败的常见原因与排查路径5.1 扫不到设备从地址到硬件的逐层排查i2cdetect扫不到设备是最常见的问题。排查顺序应该是先确认地址对不对再确认硬件接线最后看驱动和设备树。地址问题占了一半以上。SHT30 的地址是 0x44但有些模块通过 ADDR 引脚可以改成 0x45。GT911 的地址可能是 0x5d 或 0x14取决于上电时 INT 引脚的状态。如果 datasheet 上写的是 8 位地址要右移一位得到 7 位地址。我遇到过一个小白把 8 位地址 0x90 直接填到设备树里结果怎么都扫不到改成 0x48 后立刻正常。硬件问题占三成。SCL 和 SDA 接反了、上拉电阻没焊、VCC 没供上、GND 没共地这些都会导致扫不到设备。用万用表测 SCL 和 SDA 对地电压正常应该是 VCC。如果一个是 VCC 一个是 0V说明有一个被拉死了。逐个断开从设备看电压是否恢复能定位到具体是哪个设备的问题。剩下两成是设备树或驱动问题。status没改成okay、compatible字符串不匹配、pinctrl 配置冲突这些都会导致控制器不工作。查看内核日志dmesg | grep i2c如果看到i2c i2c-1: bus not busy之类的信息说明控制器初始化了但总线有问题。如果看到of_i2c: invalid reg on /i2cfe5a0000/sht3044说明设备树里的reg属性有问题。5.2 能扫到但读写失败时序与协议层面的坑设备能扫到说明地址和硬件基本没问题但读写失败可能是时序问题。SHT30 发送测量命令后需要等待测量完成如果立刻读取会读到 NACK。GT911 需要先配置寄存器再读取坐标如果配置没写对读出来的坐标全是 0。时钟频率不匹配也是常见原因。有些传感器只支持 100kHz如果设备树里设了 400kHz通信会失败。反过来有些传感器支持 400kHz但设备树里设了 100kHz虽然能通信但速度慢。查看传感器的 datasheet确认支持的频率范围。重复起始条件处理不当也会导致读写失败。前面提到 SHT30 需要重复起始如果驱动里分成两次I2cTransfer中间会有停止条件SHT30 的状态机会复位。解决方法是把两个消息放在同一个I2cTransfer调用里用I2C_FLAG_READ区分读写。5.3 通信不稳定时好时坏的疑难杂症通信时好时坏是最难排查的。可能的原因包括上拉电阻阻值不合适、总线电容过大、电源纹波、电磁干扰、从设备时钟拉伸处理不当。上拉电阻的问题前面讲过用示波器看波形最直观。如果上升沿明显变缓超过 1μs说明上拉电阻太大或总线电容太大。减小上拉电阻或者缩短走线长度可以改善。电源纹波也会影响 I2C 通信。有些传感器对电源质量敏感VCC 上的纹波超过 100mV 就可能导致通信失败。在 VCC 和 GND 之间并联一个 100nF 电容能滤掉高频噪声。电磁干扰在工业环境中很常见。I2C 走线如果和电机驱动线、继电器控制线平行走容易受到干扰。解决方法包括走线尽量短、远离干扰源、使用屏蔽线、在 SCL 和 SDA 上串联 22Ω 到 100Ω 的电阻。5.4 常见问题速查表现象可能原因排查方法解决方案i2cdetect扫不到设备地址错误核对 datasheet确认 7 位地址修正设备树或命令中的地址i2cdetect扫不到设备硬件接线问题测 SCL/SDA 电压检查上拉电阻重新接线补焊上拉电阻i2cdetect扫不到设备设备树未使能查看/proc/device-tree将status改为okay能扫到但读全是 0xFF从设备未响应用逻辑分析仪抓波形检查命令格式和时序能扫到但读全是 0x00数据未准备好增加延时后重试确认测量时间加sleep通信时好时坏上拉电阻不合适示波器看上升沿减小上拉电阻至 2.2kΩ通信时好时坏电源纹波示波器看 VCC并联 100nF 电容通信时好时坏电磁干扰检查走线远离干扰源串联电阻驱动加载失败compatible不匹配查看内核日志统一设备树和驱动字符串驱动加载失败pinctrl 冲突查看引脚复用修正 pinctrl 配置6. 进阶话题多设备共存与性能优化6.1 同一总线挂多个设备的注意事项一条 I2C 总线上挂多个设备很常见但要注意地址不能冲突。每个设备的地址必须唯一如果两个设备地址相同通信会混乱。有些传感器提供地址选择引脚可以通过拉高或拉低改变地址。如果地址无法改变只能挂到不同的 I2C 总线上。总线电容是另一个限制。I2C 规范规定总线电容不超过 400pF每个设备的引脚电容大概 10pF走线电容大概 1pF/cm。如果挂太多设备或者走线太长电容超标通信会不稳定。解决方法是减小上拉电阻或者使用 I2C 多路复用器如 TCA9548A把总线分成多路。6.2 提高 I2C 通信速度的实操方法标准模式 100kHz 对于大多数传感器够用但如果需要高速读取大量数据可以提高到 400kHz 甚至 1MHz。提高速度的前提是硬件支持上拉电阻要减小到 1kΩ 到 2.2kΩ总线电容要控制在 200pF 以内走线要短。软件层面减少不必要的I2cTransfer调用次数。比如读取多个寄存器时如果传感器支持连续读取可以用一个消息读多个字节而不是每个寄存器发一次命令。另外合理使用 DMA 可以减少 CPU 占用但 OpenHarmony 的 I2C 控制器驱动是否支持 DMA 取决于具体 SoC。6.3 逻辑分析仪在 I2C 排障中的实战用法逻辑分析仪是 I2C 排障的利器。抓波形时把探头接到 SCL、SDA、GND设置采样率至少 10 倍于总线频率。100kHz 的总线采样率 1MHz 以上。触发条件设为 SCL 下降沿或 SDA 下降沿。抓到的波形可以解码出具体的通信内容起始条件、地址、读写位、数据、应答位、停止条件。如果看到地址后面跟着 NACK说明从设备没响应。如果看到数据位和预期不符说明时序有问题。如果看到 SCL 被拉低很长时间说明从设备在做时钟拉伸。我遇到过一个问题GT911 触摸屏偶尔读不到坐标用逻辑分析仪抓波形发现主机发送读命令后GT911 没有拉低 SDA 应答而是保持高电平。检查发现是 GT911 的复位时序不对复位脉冲宽度不够导致芯片没有完全初始化。调整复位延时后问题解决。7. 我踩过的坑与实操心得第一个坑是地址搞错。刚开始用 SHT30 的时候datasheet 上写的是 8 位地址 0x88我直接填到设备树里结果怎么都扫不到。后来才明白8 位地址右移一位才是 7 位地址0x88 右移一位是 0x44。这个坑很基础但新手很容易踩。第二个坑是上拉电阻。开发板上自带的 10kΩ 上拉电阻接一个传感器没问题接三个就开始丢数据。用示波器看波形上升沿超过 2μs明显太慢。换成 2.2kΩ 后波形立刻变陡通信稳定。所以不要迷信开发板的自带上拉该换就换。第三个坑是设备树status没改。RK3568 的设备树里很多 I2C 控制器默认是disabled需要手动改成okay。我一开始只加了从设备节点忘了改控制器的status结果从设备节点根本不生效。查看/proc/device-tree才发现控制器还是disabled。第四个坑是重复起始条件。SHT30 需要先发命令再读数据中间不能有停止条件。我一开始用两次I2cTransfer中间自动插入了停止条件SHT30 状态机复位读出来全是 0xFF。后来把两个消息放在同一个I2cTransfer里问题解决。第五个坑是时钟拉伸。有些传感器在处理数据时会拉低 SCL如果控制器驱动不支持时钟拉伸会误判为总线错误。RK3568 的 I2C 控制器支持时钟拉伸但需要在设备树里确认clock-frequency设置合理。如果频率设得太高从设备来不及处理时钟拉伸频繁触发通信效率反而下降。最后分享一个小技巧在设备树里给 I2C 控制器加i2c-scl-falling-time-ns和i2c-sda-falling-time-ns属性可以微调时序改善通信稳定性。这两个参数不是所有 SoC 都支持RK3568 支持。具体值需要根据示波器波形调整一般设 100ns 到 300ns 之间。