sched_ext: 修复 scx_bpf_dsq_insert() 注释中的拼写错误

系列基线信息

• 标题: [PATCH] sched_ext: Fix typo in scx_bpf_dsq_insert() comment
• 作者: Liang Luo luoliang@kylinos.cn（麒麟软件）
• 版本: v1（单 patch，1 文件，1 处修改）
• 规模: kernel/sched/ext/ext.c | 2 +-，1 行新增，1 行删除
• 来源频道: sched-ext
• Message-ID: 20260709080205.534892-1-luoliang@kylinos.cn
• 链接: https://lore.kernel.org/sched-ext/20260709080205.534892-1-luoliang@kylinos.cn/
• 整体走向: 2026-07-09 上午 8:02 提交 → 当日 20:23 Andrea Righi 回复 Acked-by → 21:40 Tejun Heo 标记 Applied to sched_ext/for-7.3，周期不到 14 小时。

明确目的

这条讨论的目的非常单一：修正 kernel/sched/ext/ext.c 中 scx_bpf_dsq_insert() 这个 BPF kfunc 上面那块注释里的笔误。原注释在描述 ops.select_cpu() 路径时把参数名写成了 @dsp_id，但实际函数签名和参数列表里这个参数叫 @dsq_id（dispatch queue id），两者不一致会让读内核/BPF 源码的人误以为有一个 dsp_id 参数。

这是一个纯注释/文档层面的修复，不会改任何代码行为、ABI 或 BPF API。

遍历代码

整个 patch 只动了一个 hunk：

@@ -8572,7 +8572,7 @@ __bpf_kfunc_start_defs();

• When called from ops.select_cpu() or ops.enqueue(), it's for direct dispatch
• and @p must match the task being enqueued.

• • When called from ops.select_cpu(), @enq_flags and @dsp_id are stored, and @p

• • When called from ops.select_cpu(), @enq_flags and @dsq_id are stored, and @p
  • will be directly inserted into the corresponding dispatch queue after
  • ops.select_cpu() returns. If @p is inserted into SCX_DSQ_LOCAL, it will be
  • inserted into the local DSQ of the CPU returned by ops.select_cpu().

具体步骤：

1. 进入 `kernel/sched/ext/ext.c` 第 8572 行附近，这一行紧跟 `__bpf_kfunc_start_defs();` 的标记，是 `scx_bpf_dsq_insert` 这个 BPF kfunc 的注释段。
2. 注释的语义是：当 `scx_bpf_dsq_insert` 在 `select_cpu` 路径下被调用时，`@enq_flags` 和目标 DSQ id 会被暂存，等 `ops.select_cpu()` 返回后再把 `@p` 直接插入到对应 DSQ；如果目标 DSQ 是 `SCX_DSQ_LOCAL`，会插入到 `select_cpu` 返回的 CPU 的本地 DSQ。
3. 这个描述里把目标 DSQ 的 id 参数名写成了 `@dsp_id`，与函数签名/参数列表里的真实名字 `@dsq_id` 不一致。
4. 修复只把注释里这一处的 `@dsp_id` 替换成 `@dsq_id`，行为不变。

## ASCII 流程图

+----------------------------------------------------+
| scx_bpf_dsq_insert() — BPF kfunc 注释上下文 |
+----------------------------------------------------+
|
v
caller 是 ops.select_cpu() 吗？
| |
yes no
| |
v v
暂存 @enq_flags 注释走 enqueue 分支
暂存 @dsq_id （本 patch 不涉及）
(等待 select_cpu |
返回) v
| 直接插入 @p 到目标 DSQ
v
插入 @p 到 @dsq_id 对应 DSQ
(SCX_DSQ_LOCAL -> 返回 CPU 的本地 DSQ)
|
v
注释中的变量名必须与签名一致

旧注释: ... and @dsp_id are stored ...
^^^^^^
笔误
新注释: ... and @dsq_id are stored ...
^^^^^^
修正后与签名一致

另一个角度，看 patch 在注释块中所处的位置：

/* ======== 注释块 顶部 ======== */
 * ops.select_cpu() / ops.enqueue() 直调路径说明
 *

• • ... @enq_flags and @dsp_id are stored ... <-- patch 改这一行

• • ... @enq_flags and @dsq_id are stored ...
  • will be directly inserted into ...
  • ... SCX_DSQ_LOCAL -> local DSQ of returned CPU
    /* ======== 注释块 底部 ======== */
    __bpf_kfunc_start_defs(); <-- 真实 kfunc 紧随其后
    ... 函数签名: dsq_id ...

## 概念类比

这就像一份正式合同里反复出现一个名字，一会儿写成「甲方代表人：张三」，下一页又写成「甲方代表人：张桑」。意思双方都懂，但合同上对不上号就会让法务、律师抠字眼、影响可信度。BPF kfunc 的注释就是 BPF 程序员和内核之间的"合同"：注释里讲的 `@dsq_id` 必须在参数列表里能找到对应名字，否则读代码的人会以为漏了一个参数或者函数偷偷多了一个 `dsp_id` 形参，进而怀疑自己看错了 commit 树。

## Highlight 突出问题

- **不修不影响功能，但会误导读者**：这种"参数名漂移"是内核/sched_ext 文档里非常常见的低危噪音。`grep "@dsp_id" kernel/sched/ext/` 还能不能命中别处是后续 review 的关注点；如果 ext.c 其他地方、文档 `Documentation/scheduler/sched-ext.rst` 或头文件注释中也残留了 `@dsp_id`，那同一个 typo 修复应该一起做。
- **`__bpf_kfunc_start_defs();` 周围的注释质量参差**：sched_ext 经常是 BPF 程序员第一手接触的内核子系统，注释准确性直接影响外部 BPF 程序的正确性。Tejun 直接 ack-and-apply 通常意味着这种纯注释修复没有行为风险，但仍然可以借机触发一次"kfunc 注释与签名一致性"的扫荡。
- **后续验证点**：在 `for-7.3` 合入后，`git log --oneline kernel/sched/ext/ext.c | grep -i dsq_id` 应能看到这条 commit；可顺带 `git grep -n "@dsp_id"` 检查 ext.c、include/linux/sched/ext.h、`Documentation/scheduler/sched-ext.rst` 还有没有同样 typo。
- **风险与争议**：几乎无行为风险。唯一需要小心的是 `Acked-by` 行是否被 patchwork 正确拾取（Andrea Righi 的 `arighi@nvidia.com` 是他当前邮件），以及 `Signed-off-by` 名字与作者邮箱匹配（从 commit body 看一致）。

## 版本演进

本系列只有 v1，单 patch 直接被 Tejun Heo 接受并合入 `sched_ext/for-7.3` 分支，无 v2。

## 与其他相关 patch 系列的关联

本 patch 是局部注释修复，未涉及任何 API/数据结构变化，因此：

- 与近期 sched_ext 行为类 patch（例如 DSQ vtable 重构、select_cpu 路径优化等）无功能冲突。
- 与 Documentation/scheduler/sched-ext.rst 端的对齐工作互补：建议社区顺手 `git grep "@dsp_id"` 拉一遍，避免留尾巴。
- Tejun 在 `for-7.3` 分支合并，意味着会随 7.3 合并窗口进入 mainline。

## 一句话总结

这是一个一行注释笔误修复：把 `scx_bpf_dsq_insert()` 注释里误写的 `@dsp_id` 改回真正的形参名 `@dsq_id`，无功能影响，已被 Tejun Heo 合入 `sched_ext/for-7.3`。