sched_ext: repair kernel-doc comments

系列基线信息

字段	内容
标题	`[PATCH] sched_ext: repair kernel-doc comments`
作者	Randy Dunlap
版本	v1（无版本号标注）
规模	1 patch, 1 file, 6 insertions, 3 deletions
Message-ID	`20260723173118.327466-1-rdunlap@infradead.org`
来源	sched-ext 频道

明确目的

修复 kernel/sched/ext/ext.c 中 6 处 kernel-doc 注释缺陷，消除构建时产生的文档警告。

具体两类问题：

缺少参数描述：finish_dispatch、scx_rcu_cpu_stall、scx_hardlockup 三个函数的 kernel-doc 注释遗漏了函数参数说明（@sch、@stalled_mask、@cpu），导致 kernel-doc 报 "function parameter not described" 警告。
函数名不匹配：scx_bpf_dsq_insert、scx_bpf_dsq_move_to_local、scx_bpf_reenqueue_local 三个 BPF kfunc 的 kernel-doc 注释用的是公开别名名，而实际 C 定义名带有 ___v2 后缀（版本化内部名），kernel-doc 按 C 定义名查找注释时找不到匹配，报 "expecting prototype for X, Prototype was for Y___v2" 警告。

遍历代码

补丁改动集中在 kernel/sched/ext/ext.c，分两组：

第一组：补齐缺失参数

finish_dispatch：添加 @sch: the scheduler — 该函数接收一个 sch 参数但注释中未提及。
scx_rcu_cpu_stall：添加 @stalled_mask: bit mask of stalled CPUs — RCU stall 处理器需要知道哪些 CPU 卡住了。
scx_hardlockup：添加 @cpu: the target CPU — 硬锁检测器需要知道目标 CPU 号。

第二组：修正函数名

将 scx_bpf_dsq_insert → scx_bpf_dsq_insert___v2
将 scx_bpf_dsq_move_to_local → scx_bpf_dsq_move_to_local___v2
将 scx_bpf_reenqueue_local → scx_bpf_reenqueue_local___v2

这些 BPF kfunc 使用了 sched_ext 的版本化机制（___v2 后缀），C 代码中的实际符号名带后缀，但 kernel-doc 注释写的是 BPF 侧看到的公开别名。kernel-doc 解析器按 C 定义名匹配注释，所以注释也必须用 ___v2 名才能对上。

ASCII 流程图

kernel-doc 解析流程（修复前后对比）

  ┌─────────────────────────────────────────────────────┐
  │  C 函数定义: scx_bpf_dsq_insert___v2()              │
  │  kernel-doc 注释: /**                                │
  │   * scx_bpf_dsq_insert - ...   ← 修复前: 名不匹配   │
  │   * scx_bpf_dsq_insert___v2 - ... ← 修复后: 匹配    │
  │   */                                                │
  └─────────────────────────────────────────────────────┘

  修复前:                               修复后:

  C 定义名 ──→ kernel-doc ──→ ✗ 名不匹配   C 定义名 ──→ kernel-doc ──→ ✓ 名匹配
  scx_bpf_dsq_insert___v2  ≠  scx_bpf_dsq_insert
  scx_bpf_dsq_insert___v2  ＝  scx_bpf_dsq_insert___v2

  缺参数的修复:

  ┌──────────────────────┐         ┌──────────────────────────────┐
  │ finish_dispatch()    │         │ finish_dispatch()            │
  │ 参数: sch, rq, p,   │   →     │ 参数: sch, rq, p,           │
  │       qseq_at_dispatch│         │       qseq_at_dispatch       │
  │ 注释: @rq @p @qseq  │  +@sch  │ 注释: @sch @rq @p @qseq    │
  │ 缺: @sch             │         │ 全部覆盖                     │
  └──────────────────────┘         └──────────────────────────────┘

概念类比

想象一个医院病历系统：每位病人入院时，护士必须在病历表格上填写所有必填字段（姓名、年龄、症状等），并且病历封面上的病人编号必须和系统登记的编号完全一致。

缺参数就像护士漏填了"年龄"这一栏——系统检测到必填字段空缺就报警告。
函数名不匹配就像病历封面写的编号是"门诊别名-001"，但系统登记的是"内部编号-001-v2"——两个编号对不上，系统找不到对应记录。

补丁做的事情就是：补齐遗漏的表格字段，把封面编号改成和系统登记编号一致。

Highlight 窌出问题

版本化 kfunc 的文档命名惯例：sched_ext 的 BPF kfunc 使用 ___vN 后缀做版本化，BPF 程序调用时看到的是去掉后缀的公开名，但 kernel-doc 要求注释名与 C 定义名一致。这是一个容易混淆的惯例——未来新增版本化 kfunc 时，开发者很可能再次写错注释名，建议在代码或文档中加一条明确注释说明此规则。
@aux 参数的处理：scx_bpf_dsq_move_to_local___v2 的注释中已有 @aux 描述为 "implicit BPF argument"，这类隐式参数不属于 BPF 侧可见接口，kernel-doc 强制要求描述它们可能导致文档可读性下降，需权衡是否应豁免隐式参数。
补丁已合并但标题被改：Tejun Heo 合并时将标题大写化（capitalized），说明 maintainer 对 commit message 格式有自己的偏好，后续贡献者应注意标题首词大写。

版本演进

仅 v1，无多版本迭代。补丁直接被 maintainer 合入 sched_ext/for-7.3 分支。

与其他相关 patch 系列的关联

无显式关联系列。此类 kernel-doc 修复属于日常维护工作， Randy Dunlap 长期在内核各子系统做文档注释修复，本补丁是他在 sched_ext 子系统的一次例行扫描结果。

一句话总结

补齐 3 个函数的缺失参数描述、修正 3 个版本化 kfunc 的 kernel-doc 函数名，消除 sched_ext 的 6 处构建警告。

[PATCH] sched_ext: repair kernel-doc comments

LLM 分析