Zephyr RTOS首PR纪实：9行代码修复传感器驱动类型与I2C检查

拿到一个开源项目的第一个 Contribution，激动劲还没过，屁股还坐得有点疼。昨天我往 Zephyr RTOS 提交了人生第一个 PR，统计下来真正动到的逻辑只有 9 行，可我从早上九点开始折腾，一直到晚上十点才把 PR 推到 GitHub 上，中间还经历了本地编译失败、CI 红灯、提交信息重写这些新手村必修课。这篇就当是给自己留个存档，也给那些正盯着 Zephyr 源码、想迈出第一步但又有点发怵的朋友一点参考。

先说清楚，这 9 行不是什么高深的内核调度改动，也不是新增驱动，只是修了一个传感器驱动里很基础的 bug：类型用错、I2C 返回值没查干净、日志格式符不匹配。单看每一处都很小，但把它们凑在一起，就足够让一个新手在一堆构建系统、代码风格、提交规范里迷失一整天。这篇文章我不打算只贴 diff，而是想把一整天的完整过程拆给你看：我怎么发现的、怎么定位的、为什么最终这样改、本地怎么验证、提交 PR 后又踩了哪些 CI 和 review 的坑。如果你也想给 Zephyr 或类似的大型嵌入式项目提 PR，这篇应该能帮你少走不少弯路。

1. 起因：一次编译，牵出一个不起眼但很真实的驱动问题

1.1 那天我是怎么发现问题的

最近我在做一块自定义板子的传感器接入，用 Zephyr 的 sensor API 读温度和湿度。板子还没到手，我先在native_posix上把整个驱动流程跑起来，想着反正 sensor 框架和 I2C 模拟都能在主机上跑通，等板子回来直接改 dts 就行。结果一跑示例应用，日志里出现了非常诡异的现象：温度值在某个区间跳变特别大，明明室温 25 度左右，读数一会儿正常一会儿变成几百万；湿度更是离谱，直接冒出来负数。

我当时第一反应是怀疑 I2C 总线时序或设备树配置有问题，因为在native_posix下 I2C 是靠模拟设备实现的，数据来源也是写死的，按理说不该出现这种随机性。后来我用west build -t run反复跑，在 sensor sample 里把sensor_sample读到的四个通道值全部打出来，发现每次运行的结果都一样，也就是说不是随机噪声，是代码在某个路径上稳定地算错了。

然后把LOG_DBG开关打开，调到CONFIG_SENSOR_LOG_LEVEL_DBG=y，重新编译后终于看到驱动内部的原始寄存器值。所有原始uint32_t数值都是正常的，问题出在从原始值转换到struct sensor_value的那几步。这一下范围就小了很多，基本锁定了驱动源码里sample_fetch附近的类型处理逻辑。

1.2 顺藤摸瓜：从警告日志摸到源码

进入drivers/sensor/drv_htu/drv_htu.c，我先看到的是编译过程里其实已经给过提示，只是一开始我没注意：

warning: conversion from 'uint16_t' to 'int16_t' may change value [-Wconversion]

Zephyr 默认在某些目标上会开比较严格的编译选项，-Wconversion这类在部分配置下会直接报错，但在native_posix的默认构建里它只是警告，不影响出固件。问题就在这里：警告不代表安全，它恰恰在告诉你有一个潜在的符号位陷阱。

代码大概是这样的：

static int drv_htu_sample_fetch(const struct device *dev, enum sensor_channel chan) { struct drv_htu_data *data = dev->data; uint8_t buf[6] = {0}; uint16_t raw_temp; int ret; ret = i2c_burst_read_dt(&data->bus, DRV_HTU_REG_AUTO, buf, sizeof(buf)); if (ret) { return ret; } raw_temp = (buf[3] << 8) | buf[4]; >error: passing argument 1 of 'sensor_value_from_double' makes pointer from integer without a cast

再往下看，channel_get函数里给sensor_value赋值时，用的是>struct drv_htu_data { - uint16_t temp_raw; + int16_t temp_raw; uint16_t hum_raw; }; static int drv_htu_sample_fetch(const struct device *dev, enum sensor_channel chan) { struct drv_htu_data *data = dev->data; uint8_t buf[6] = {0}; - uint16_t raw_temp; int ret; ret = i2c_burst_read_dt(&data->bus, DRV_HTU_REG_AUTO, buf, sizeof(buf)); - if (ret) { + if (ret < 0) { return ret; } - raw_temp = (buf[3] << 8) | buf[4]; - >- val->val1 =># 先用最容易出问题的 native_posix 验证逻辑 west build -b native_posix samples/sensors/drv_htu_sample --pristine # 再用一个 ARM 目标验证真实编译路径 west build -b qemu_cortex_m3 samples/sensors/drv_htu_sample --pristine # 顺便看一下真实板卡配置 west build -b stm32f4_disco samples/sensors/drv_htu_sample --pristine

这里--pristine很关键。Zephyr 的增量构建偶尔会因为 Kconfig 和 devicetree 的依赖关系没触发重编而让你以为自己改对了，实际用的是旧对象文件。加--pristine强制全量重新生成，才能排除这种假阳性。我实测下来，第一次改完在native_posix上只跑增量构建是过了的，换到qemu_cortex_m3才暴露出一个因为CONFIG_SENSOR_LOG_LEVEL_DBG引发的类型不匹配错误。

所以给嵌入式项目提 PR，最忌讳的就是只在某一个 target 上验证通过就提交。维护者很可能在多个架构的 CI 矩阵里跑你的改动，你在本地多花十分钟，就能省掉一次“CI 红灯—修改—重提”的循环。

3.2 用 twister 跑测试用例

构建通过只能说明“编过了”，逻辑对不对还得用测试说话。Zephyr 的twister是官方测试框架，能跨 target 批量跑用例。我先在仓库里搜了一圈和这个驱动相关的测试：

./scripts/twister -T tests/drivers/sensor/drv_htu -p native_posix -p qemu_cortex_m3 --inline-logs

跑的过程中遇到了一个常见问题：部分测试用例在native_posix上依赖设备树里模拟的 I2C 设备，但我本地没有把对应的 overlay 加进去，导致几个用例直接FAILED，报的是I2C device not ready。这不是我代码的问题，是测试环境的问题。解决办法是把 sample 目录下的drv_htu.overlay复制到测试目录里重新建一次，或者直接指定-DEXTRA_DTS_OVERLAY。

不过也有一只用例是真的抓到了我代码的问题：在温度值为负数时，val->val1的预期结果和实际输出差了一个固定的偏置。这就是前面说的除法顺序问题——原始值经过符号扩展后，先除再乘和先乘再除会产生不同的截断效果。用twister跑一遍，这类边界条件就能被很快暴露出来。

跑完twister的结论是：native_posix上 6 个用例全部通过，qemu_cortex_m3上有 1 个用例因为CONFIG_SENSOR_DRV_HTU_ENABLE_DEBUG_LOG未开导致日志断言没过，我把 Kconfig 默认开着之后重新跑就绿了。这个坑后面在 CI 里也一样踩了一次，后面细说。

4. 提交PR的完整流程：从fork到merge

4.1 fork 仓库与分支管理

本地验证搞定之后，终于进入提交环节。Zephyr 的仓库很大，直接往主仓库推分支不现实，首先要去 GitHub 上 fork 一份到自己的账号下。这里有个习惯问题：fork 之后本地仓库的 origin 应该是你自己的 fork，upstream 才是 Zephyr 官方仓库。不然你git fetch拉下来的永远是你自己那份，永远看不到最新主干。

我的操作顺序是这样的：

# 假设你已经 clone 过 zephyr 仓库，并且配置了 remote git remote add upstream https://github.com/zephyrproject-rtos/zephyr.git git fetch upstream git checkout -b fix/drv_htu_signed_temp upstream/main

这个分支名其实也斟酌了一下。Zephyr 社区不太喜欢那种fix-bug的笼统分支名，最好能一眼看出“改的是哪个模块、解决什么问题”。fix/drv_htu_signed_temp就是把驱动名和问题类型都带上了。分支名虽然不会影响合并结果，但维护者看 PR 列表时，一个清晰的分支名会给你加印象分。

还有一条很重要的经验：绝对不要在 main 分支上改代码。很多新手直接 checkout main 然后 commit，结果 main 被 fork 之后就越走越远，后续再想从 upstream 拉新代码就会冲突成一片。保持 main 永远和 upstream 同步，只在新分支上干活，这是 Git 工作流里最基本也最值钱的一条。

4.2 commit 规范：Signed-off-by、Fixes 和提交信息

在 Zephyr 里，commit message不是随手写两句就行的。它的格式非常固定，首先每个 commit 必须带Signed-off-by开头，这是 Developer Certificate of Origin（DCO）协议的要求，等于你在声明这段代码确实是你写的、你有权提交。没有这行，CI 里的 DCO 检查会直接失败。

我提交时用的命令是：

git add drivers/sensor/drv_htu/drv_htu.c git commit -s -m "drivers: sensor: drv_htu: fix temperature sign handling"

commit message 我写成了四段式：

drivers: sensor: drv_htu: fix temperature sign handling The driver stores the raw temperature register value in a uint16_t variable, which causes negative temperatures to be interpreted as large positive values. Use int16_t for the raw temperature data and convert the buffer bytes explicitly before assigning to the data structure. Also fix the return value check for i2c_burst_read_dt so that only negative errno values are treated as errors. Fixes: https://github.com/zephyrproject-rtos/zephyr/issues/XXXX Signed-off-by: Your Name <your.email@example.com>

主题行用了 Zephyr 最常见的subsystem: module: 具体改动格式，这样在 git log 里一眼就能看出改动范围。正文部分没有堆砌细节，而是把“现状—问题—修复思路”讲清楚，维护者 review 时不需要再自己翻 diff 猜代码意图。Fixes:那一行如果关联了 GitHub issue，一定要用完整 URL，社区工具会自动建立链接。

这里还有个细节：commit 粒度要尽量控制在“一改一件事”。我当时第一版 commit 除了修符号问题，还把格式化日志的 PRIu32 改了，维护者后来 review 时专门提了一句“这个改动和主题不直接相关，建议拆开或者从 message 里说明”。后来我在 commit message 里加了一句“also fix format specifier”，才算解释过去。

4.3 创建 PR：模板怎么填，描述怎么写

push 到自己的 fork 之后，GitHub 页面上会有一个醒目的 “Compare & pull request” 按钮。点进去之后千万不要直接用默认的标题和空描述，Zephyr 的 PR 模板会要求你填写几个固定部分：问题描述、复现步骤、预期行为、实际行为、修复方案、测试验证。

我第一次填的时候写得特别啰嗦，后来参考了其他 PR 的结构，精简成这个样子：

**Summary** Fix negative temperature readings on drv_htu sensor driver by storing the raw temperature value as int16_t instead of uint16_t. **Description of the problem** Negative temperatures were reported as large positive values due to unsigned integer storage and missing conversion before sign extension. **Description of the solution** - change>./scripts/checkpatch.pl --no-tree -g HEAD

我这次就是忘了先跑这一步，白白等了一轮 CI。如果你准备给 Zephyr 提 PR，强烈建议在 commit 之后、push 之前先跑一遍checkpatch.pl，可以省掉很多无意义的来回。它虽然不能检查出所有问题，但像行尾空格、空行数量、宏定义格式、注释风格这些低级问题，基本都能拦住。

5.2 DCO、license检查和maintainer的review意见

checkpatch 修复之后，我重新git commit --amend并git push -f，CI 重新跑。这次绿了，但又冒出来一个叫Signed-off-by的检查失败。我当时很纳闷，明明已经加了-s参数，怎么会缺？

查了日志才明白，原来是我用git commit -s时，本地 Git 配置的user.name和user.email并不是我 GitHub 账号的邮箱。Zephyr 的 DCO 机器人要求Signed-off-by里的邮箱必须和 GitHub 账号绑定的邮箱匹配。解决办法是去 GitHub 设置里把邮箱加进账号，或者改本地 Git 配置：

git config user.email "your-github-email@example.com"

改完之后git commit --amend --reset-author再 force push，DCO 才算通过。

再往后，一位维护者在 PR 下留言了。他先肯定了这个方向是对了，同时提了三条意见：

• 建议把 diff 里的(int16_t)((buf[3] << 8) | buf[4])定义一个临时变量，不要让强制转换和表达式混在一起，代码更易读；
• 询问我为什么i2c_burst_read_dt的返回值检查要从if (ret)改成if (ret < 0)，要求我在 commit message 中补一句说明；
• 提醒我更新drv_htu.h里对应的temp_raw注释，避免文档和实现不一致。

我逐条回复，说明ret < 0是因为该 API 只返回负 errno 或 0，正数不会出现但写得更严谨能避免未来 I2C controller 实现变化时的隐患；同时按照他的建议改成了临时变量的写法。整个过程没有遇到“维护者怼人”的情况，反倒是他们很乐意看到新人在认真改问题。遇到 review 意见，千万不要觉得是在挑刺，那是在帮你提高代码质量。

5.3 合并前后的最后一步：提交信息微调与force push

采纳 review 意见之后，我需要修改 commit。这个阶段不能再新增一个“fix review comments”的 commit，而是要把改动 amend 进原来的 commit 里，保持整个 PR 只有一个 commit。这一步很考验 Git 基本功：

# 先把改动的文件加入暂存区 git add drivers/sensor/drv_htu/drv_htu.c drivers/sensor/drv_htu/drv_htu.h # 修改 commit，保留原来的 message，并补充说明 git commit --amend # 本地确认 commit 和 diff 都正确 git show --stat HEAD git diff HEAD^ # force push 到自己的分支 git push --force-with-lease origin fix/drv_htu_signed_temp

--force-with-lease比--force安全，它会在远端分支不是你之前 push 的状态时直接报错，防止覆盖别人的提交。这种习惯在开源协作里特别重要，因为你 fork 的分支可能会被其他人用到，至少你该尽量避免毁掉别人的历史。

amend 之后 CI 又跑了一轮，这次全绿。维护者再看了不到十分钟就 approve 并入队了，最终以 squash merge 方式合进主干。我本地的分支随后被删除，整个 PR 从创建到合并算下来，CI 跑了三轮、review 来回两轮，而代码只有 9 行。

6. 给想提首个PR的人：我的避坑清单和心态建议

6.1 新人提PR最常见的5个坑

整理一下这次经历里所有值得注意的点，做成一张速查表给后面的人用：

这五条几乎覆盖了新手第一次提 PR 的大多数失败场景。其实都不难，但每一件都需要提前准备，而不是等 CI 红灯亮了才去查。

6.2 流程之外：心态、时间和沟通建议

最后说点流程之外的体会。

给开源项目提 PR，尤其是 Zephyr 这种代码量大、规范多、CI 严格的项目，最大的门槛不是代码能力，而是对流程的耐心。9 行改动本身可能一小时就写完了，但之后你可能要花大半天去熟悉代码风格、提交规则、CI 检查项、review 周期。这不是浪费时间，它恰恰是开源协作真正的价值：你不仅在提交代码，还在学习一个成熟社区如何保证质量。

如果你是第一次提 PR，建议从这类小而有意义的改动入手，比如修一个驱动里的类型转换、补一个返回值检查、修正过时的注释。别上来就啃大功能，否则 review 沟通成本会让新手很容易放弃。也别怕被维护者提意见，那恰恰说明你的 PR 被认真对待了。

这次经历之后，我对“PR 大小”的看法变了很多。以前总觉得代码改动行数多才显得厉害，现在明白了：真正重要的不是你写了多少行，而是每一行是否解决了问题、是否让别人容易 review。9 行改动折腾一整天，听起来很亏，但这 9 行是经过编译、测试、CI、人工 review 四重验证才落进主干的，这本身就是它最大的价值。