sched_ext: Fix incorrect SCX_PICK_IDLE_CPU_* flag prefix in kernel-doc

系列基线信息

字段	值
标题	`[PATCH] sched_ext: Fix incorrect SCX_PICK_IDLE_CPU_* flag prefix in kernel-doc`
作者	Liang Luo (luoliang@kylinos.cn)
版本	单 patch，无版本号
规模	1 文件，3 处修改（+3/-3）
Message-ID	`20260724080824.2483100-1-luoliang@kylinos.cn`
来源	sched-ext 频道
状态	已被 Tejun Heo 合入 `sched_ext/for-7.3`

明确目的

修正 kernel/sched/ext/idle.c 中三处 kernel-doc 注释的枚举前缀引用错误：将 %SCX_PICK_IDLE_CPU_* 改为 %SCX_PICK_IDLE_*。

实际枚举 scx_pick_idle_cpu_flags 的成员前缀是 SCX_PICK_IDLE_（如 SCX_PICK_IDLE_CORE、SCX_PICK_IDLE_IN_NODE），而注释中写的 SCX_PICK_IDLE_CPU_* 并不存在于任何定义中，是文档笔误。

遍历代码

改动集中在一个文件 kernel/sched/ext/idle.c，涉及三个 kfunc 的 kernel-doc @flags 参数描述：

scx_bpf_pick_idle_cpu_node()（第 1352 行）：
- @flags: %SCX_PICK_IDLE_CPU_* → @flags: %SCX_PICK_IDLE_*
scx_bpf_pick_idle_cpu()（第 1399 行）：
- @flags: %SCX_PICK_IDLE_CPU_* → @flags: %SCX_PICK_IDLE_*
scx_bpf_pick_any_cpu_node()（第 1450 行）：
- @flags: %SCX_PICK_IDLE_CPU_* → @flags: %SCX_PICK_IDLE_*

值得注意的是，同文件中 scx_bpf_pick_idle_cpu_node() 的另一个位置已经正确使用了 %SCX_PICK_IDLE_*，说明这三处是遗漏的一致性错误。

// 修正前（错误）
* @flags: %SCX_PICK_IDLE_CPU_* flags   // ← 不存在的枚举前缀

// 修正后（正确）
* @flags: %SCX_PICK_IDLE_* flags        // ← 与 enum scx_pick_idle_cpu_flags 成员一致

ASCII 流程图

enum scx_pick_idle_cpu_flags
  |
  +-- SCX_PICK_IDLE_CORE      ← 实际成员前缀: SCX_PICK_IDLE_
  +-- SCX_PICK_IDLE_IN_NODE   ← 实际成员前缀: SCX_PICK_IDLE_

kernel-doc 注释 (idle.c)
  |
  +-- scx_bpf_pick_idle_cpu_node()   @flags →  SCX_PICK_IDLE_CPU_*  (错误)
  +-- scx_bpf_pick_idle_cpu()        @flags →  SCX_PICK_IDLE_CPU_*  (错误)
  +-- scx_bpf_pick_any_cpu_node()    @flags →  SCX_PICK_IDLE_CPU_*  (错误)
  +-- scx_bpf_pick_idle_cpu_node()   @flags →  SCX_PICK_IDLE_*      (正确，已存在)

修正后: 三处 SCX_PICK_IDLE_CPU_* → SCX_PICK_IDLE_*

概念类比

想象一本药品说明书：药片的有效成分标注为"阿莫西林"，但说明书中有几处写成了"阿莫西林胶囊素"——这个成分名根本不存在。读者按错误名称去查成分表，什么都找不到。修正就是把说明书里所有不一致的名称统一回真正的成分名"阿莫西林"，与药品包装标签一致。

这里 %SCX_PICK_IDLE_CPU_* 就是不存在的"胶囊素"，而 %SCX_PICK_IDLE_* 才是枚举定义中真正的前缀。

Highlight 突出问题

kernel-doc % 引用会生成超链接：%SCX_PICK_IDLE_CPU_* 在生成的文档中会尝试链接到一个不存在的枚举常量，导致文档工具报 warning 或断链。虽然改动只影响注释，但这类文档错误如果长期存在，会让使用者误解可传入的 flags 集合。
同文件中已有正确用法：说明此错误是当初批量添加注释时的复制粘贴遗漏，而非设计意图——后续新增 kfunc 时应对照枚举定义检查 @flags 描述。
_CPU_* vs _* 容易混淆：枚举名是 scx_pick_idle_cpu_flags（含 CPU），但其成员前缀是 SCX_PICK_IDLE_（不含 CPU），这种命名不一致本身就容易诱发改错。如果未来有重构，可以考虑让枚举成员前缀和枚举名更一致。

版本演进

单版 patch，无版本迭代。直接被 maintainer 合入。

与其他相关 patch 系列的关联

无。这是一个独立的文档修正，不依赖或阻塞其他系列。

一句话总结

修正 idle.c 中三处 kernel-doc 把 %SCX_PICK_IDLE_CPU_* 错写成不存在的枚举前缀，改为与实际枚举成员一致的 %SCX_PICK_IDLE_*。

[PATCH] sched_ext: Fix incorrect SCX_PICK_IDLE_CPU_* flag prefix in kernel-doc

LLM 分析