Zephyr 代码评审 — zephyrrtos_china/zephyr PR #1
# PR 评审 — zephyrrtos_china/zephyr #1
> base = `origin/main` · head = `refs/pull/1/head`（由 `refs/pull/1/head` 拉取）
> checkpatch：未运行（CI 负责该检查；需要本页跑请加 `?checkpatch=1`）
```
boards/others/stm32f030_demo/board.cmake | 2 +
.../drivers/adc/adc_power_measure/CMakeLists.txt | 8 +
samples/drivers/adc/adc_power_measure/Kconfig | 27 ++
samples/drivers/adc/adc_power_measure/README.rst | 316 ++++++++++++++
.../drivers/adc/adc_power_measure/RELEASE-NOTES.md | 253 +++++++++++
.../adc/adc_power_measure/boards/frdm_k64f.conf | 1 +
.../adc/adc_power_measure/boards/frdm_k64f.overlay | 25 ++
.../adc/adc_power_measure/boards/frdm_mcxc242.conf | 1 +
.../adc_power_measure/boards/frdm_mcxc242.overlay | 25 ++
.../adc/adc_power_measure/boards/frdm_mcxc444.conf | 7 +
.../adc_power_measure/boards/frdm_mcxc444.overlay | 68 +++
.../adc_power_measure/boards/mimxrt1040_evk.conf | 1 +
.../boards/mimxrt1040_evk.overlay | 34 ++
.../boards/mimxrt595_evk_cm33.conf | 1 +
.../boards/mimxrt595_evk_cm33.overlay | 46 ++
.../adc_power_measure/boards/stm32f030_demo.conf | 53 +++
.../boards/stm32f030_demo.overlay | 117 +++++
samples/drivers/adc/adc_power_measure/prj.conf | 1 +
samples/drivers/adc/adc_power_measure/sample.yaml | 29 ++
samples/drivers/adc/adc_power_measure/src/main.c | 237 ++++++++++
scripts/pylib/power-twister-harness/README.rst | 483 +++++++++++++++++++++
scripts/pylib/power-twister-harness/conftest.py | 37 +-
.../general_adc_platform/GeneralAdcPowerMonitor.py | 233 ++++++++++
.../general_adc_platform/README.rst | 76 ++++
.../general_adc_platform/probe_settings.yaml | 30 ++
.../general_adc_platform/requirements.txt | 2 +
.../power-twister-harness/requirements-dev.txt | 27 ++
scripts/pylib/power-twister-harness/test_power.py | 6 +-
subsys/pm/Kconfig | 16 +
.../pm/power_residency_time/boards/frdm_rw612.conf | 7 +
.../power_residency_time/boards/frdm_rw612.overlay | 17 +
.../power_residency_time/boards/rd_rw612_bga.conf | 6 +
.../boards/rd_rw612_bga.overlay | 17 +
tests/subsys/pm/power_residency_time/src/main.c | 3 +
tests/subsys/pm/power_residency_time/tests.yaml | 2 +
35 files changed, 2208 insertions(+), 6 deletions(-)
```
# Zephyr 代码评审报告
- **范围**: diff `origin/main..refs/pull/1/head`（20 个文件）
- **模式**: diff **Profile**: app **分析**: all
- **Zephyr**: 4.5.99 @ 25206336e4fa
- **规则集**: 40 条（启用 40 条） **tree-sitter**: 0.26.0
- **范围口径**: 基于完整文件（新增/存量问题都报，逐条标注）
## 1. 结论
| 等级 | 数量 | 含义 |
|---|---|---|
| MAJOR | 0 | 明确缺陷或会触发上游 CI 失败，建议改 |
| MINOR | 1 | 约定/一致性问题 |
| INFO | 3 | 启发式提示，需人工确认 |
**判定**：可合入 —— 有 1 项 MINOR 建议在本轮或紧随的提交里修掉
## 2. 问题清单
| # | 等级 | 规则 | 位置 | 置信度 | 改动 | 摘要 |
|---|---|---|---|---|---|---|
| 1 | MINOR | R-KCF-002 | `samples/drivers/adc/adc_power_measure/Kconfig:4` | certain | 新增 | Kconfig 符号缺少 help 说明 |
| 2 | INFO | R-KCF-003 | `samples/drivers/adc/adc_power_measure/Kconfig:21` | heuristic | 新增 | Kconfig 符号没有 depends on / default / select |
| 3 | INFO | R-KCF-003 | `samples/drivers/adc/adc_power_measure/Kconfig:24` | heuristic | 新增 | Kconfig 符号没有 depends on / default / select |
| 4 | INFO | R-KRN-003 | `samples/drivers/adc/adc_power_measure/src/main.c:31` | heuristic | 新增 | 文件级可写 static 变量被多个函数使用，未见同步原语 |
### 1. [MINOR] R-KCF-002 — Kconfig 符号缺少 help 说明
- **位置**: `samples/drivers/adc/adc_power_measure/Kconfig:4`
- **代码**: `config SEQUENCE_SAMPLES`
- **现象**: config SEQUENCE_SAMPLES 缺少 help 说明（同类共 4 处，其余行号：17, 21, 24）
- **同类位置**: `samples/drivers/adc/adc_power_measure/Kconfig` 的 17, 21, 24 行
- **判据**: 上游要求每个新符号有 help；缺了不能合入，且用户看不出这个开关干什么。
- **建议**: 补 `help` 段：一句话讲清启用后果 + 依赖前提 + 默认值理由。
- **参考**: Zephyr Kconfig 约定
### 2. [INFO] R-KCF-003 — Kconfig 符号没有 depends on / default / select
- **位置**: `samples/drivers/adc/adc_power_measure/Kconfig:21`
- **代码**: `config SEQUENCE_32BITS_REGISTERS`
- **现象**: config SEQUENCE_32BITS_REGISTERS 既无 depends on 也无 default/select，缺可见性或安全默认值
- **判据**: 没有可见性或默认值的符号会出现在所有配置里，容易被误开；没有依赖时可能被在不支持的平台上启用。
- **建议**: 至少给 `depends on <所属子系统或 SoC>`；可选的给安全默认值 `default n`。慎用 `select`（会造成隐式依赖链）。
- **参考**: zephyr-rtos skill references/50-review.md P1 第 2 条
- **等级说明**: 启发式推断（跨函数/跨文件），按团队约定降级为 INFO —— 需人工确认后再定级
### 3. [INFO] R-KCF-003 — Kconfig 符号没有 depends on / default / select
- **位置**: `samples/drivers/adc/adc_power_measure/Kconfig:24`
- **代码**: `config SHELL_ADC_PS`
- **现象**: config SHELL_ADC_PS 既无 depends on 也无 default/select，缺可见性或安全默认值
- **判据**: 没有可见性或默认值的符号会出现在所有配置里，容易被误开；没有依赖时可能被在不支持的平台上启用。
- **建议**: 至少给 `depends on <所属子系统或 SoC>`；可选的给安全默认值 `default n`。慎用 `select`（会造成隐式依赖链）。
- **参考**: zephyr-rtos skill references/50-review.md P1 第 2 条
- **等级说明**: 启发式推断（跨函数/跨文件），按团队约定降级为 INFO —— 需人工确认后再定级
### 4. [INFO] R-KRN-003 — 文件级可写 static 变量被多个函数使用，未见同步原语
- **位置**: `samples/drivers/adc/adc_power_measure/src/main.c:31`
- **代码**: `static uint32_t vrefs_mv[] = {DT_FOREACH_CHILD_SEP(ADC_NODE, CHANNEL_VREF, (,))};`
- **现象**: 可写 static 变量 `vrefs_mv` 被 3 个函数引用（defined, cmd_adc_status, main），全文件未见 k_mutex/k_spinlock/atomic/irq_lock
- **证据**: 声明在 31 行；引用函数：defined, cmd_adc_status, main
- **判据**: 跨线程/ISR 共享的可写全局状态若无 k_mutex/k_spinlock/atomic/irq_lock 保护，会出现撕裂读与竞态；volatile 只保证不被优化掉，不保证原子性。
- **建议**: 把共享态收进一个 data 结构 + 明确保护手段：线程间用 k_mutex，与 ISR 共享用 k_spinlock 或 atomic_*；纯计数用 atomic_inc。
- **参考**: zephyr-rtos skill references/50-review.md P0 第 3 条
- **等级说明**: 启发式推断（跨函数/跨文件），按团队约定降级为 INFO —— 需人工确认后再定级
## 3. 结构分析（tree-sitter）
| 文件 | 模块 | 行数 | 函数 | static | 结构体 | 宏 | 最大CC | 平均CC | 最大SLOC | 最深嵌套 | 语法树错误 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| `samples/drivers/adc/adc_power_measure/src/main.c` | samples | 238 | 3 | 2 | 7 | 6 | 14 | 7.67 | 66 | 4 | 2 |
复杂度热点（CC>10 或 SLOC>80，最多 10 条，供评审人优先看）：
| 函数 | 位置 | CC | SLOC | 嵌套 | 参数 | 调用数 |
|---|---|---|---|---|---|---|
| `main()` | `samples/drivers/adc/adc_power_measure/src/main.c:155` | 14 | 66 | 4 | 0 | 23 |
> 语法树提示：合计 2 个 ERROR/缺失节点（最严重 `samples/drivers/adc/adc_power_measure/src/main.c`：2 个）。本引擎未做预处理展开，宏或 `#if` 密集处可能有函数未被 AST 覆盖，因此上表的「函数」数是下界，缺失函数的复杂度不会被统计。
## 4. 机器检查（上游工具）
（未运行上游工具）
## 5. 未验证 / 需人工确认（Lane H）
- **-** `samples/drivers/adc/adc_power_measure/boards/frdm_k64f.overlay`：非 C/Python 源文件（.overlay），只做了通用检查，未做规则扫描与复杂度分析
- **-** `samples/drivers/adc/adc_power_measure/boards/frdm_mcxc242.overlay`：非 C/Python 源文件（.overlay），只做了通用检查，未做规则扫描与复杂度分析
- **-** `samples/drivers/adc/adc_power_measure/boards/frdm_mcxc444.overlay`：非 C/Python 源文件（.overlay），只做了通用检查，未做规则扫描与复杂度分析
- **-** `samples/drivers/adc/adc_power_measure/boards/mimxrt1040_evk.overlay`：非 C/Python 源文件（.overlay），只做了通用检查，未做规则扫描与复杂度分析
- **-** `samples/drivers/adc/adc_power_measure/boards/mimxrt595_evk_cm33.overlay`：非 C/Python 源文件（.overlay），只做了通用检查，未做规则扫描与复杂度分析
- **-** `samples/drivers/adc/adc_power_measure/boards/stm32f030_demo.overlay`：非 C/Python 源文件（.overlay），只做了通用检查，未做规则扫描与复杂度分析
- **-** `samples/drivers/adc/adc_power_measure/sample.yaml`：非 C/Python 源文件（.yaml），只做了通用检查，未做规则扫描与复杂度分析
以下项目**机器判不了**，请评审人逐项给结论（机器结论不能替代这几条）：
| 项目 | 要回答的问题 |
|---|---|
| 设计意图 | 这段代码要解决什么问题？它的失败路径是否是设计允许的行为？ |
| 栈与实时性 | 线程栈尺寸有实测依据吗（CONFIG_THREAD_ANALYZER / 运行时 high-water mark），还是只是猜的？ |
| 优先级与反转 | 新增线程/锁的优先级分配理由；k_mutex 有优先级继承，k_sem/k_msgq 没有 |
| 性能预算 | 新增路径在最坏频率下的耗时是否可接受（有测量而不是估算） |
| API 语义 | 所用内核/驱动 API 的阻塞属性与调用上下文（线程/ISR/系统启动期）是否一致 |
| 版本兼容 | 跨版本差异是否已用 Kconfig/#if 显式隔离，而不是依赖「应该一样」 |
| 测试证据 | 新增行为有能在 native_sim/QEMU 上跑的 ztest 吗；没有的话凭什么相信它是对的 |
## 6. 规则覆盖
- **因 profile 跳过**: 无
- **命中规则**: R-KCF-002, R-KCF-003, R-KRN-003
- **已执行但未命中**: R-CX-001, R-CX-002, R-CX-003, R-CX-004, R-CX-005, R-CX-006, R-DRV-001, R-DRV-002, R-DRV-003, R-DRV-004, R-DT-001, R-DT-002, R-KCF-001, R-KRN-001, R-KRN-002, R-KRN-004, R-KRN-005, R-KRN-006, R-KRN-007, R-MEM-001, R-MEM-002, R-MEM-003, R-MEM-004, R-MEM-005, R-PY-001, R-PY-002, R-PY-003, R-PY-004, R-PY-005, R-PY-006, R-SEC-001, R-SEC-002, R-SEC-003, R-UP-001, R-UP-002, R-UP-003, R-UP-004
> 等级策略：机器规则最高 MAJOR（BLOCK 只能由评审人确认后给出）；启发式规则一律降级 INFO 并标注「待人工确认」。