sched_ext：补全 finish_dispatch() 内核文档中缺失的 @slice 和 @vtime 描述

系列概况

标题: [PATCH] sched_ext: Fix missing @slice and @vtime descriptions in finish_dispatch() kernel-doc
作者: Liang Luo luoliang@kylinos.cn
版本: v1（单补丁，无 version 字段）
规模: 1 个文件，新增 2 行，无删除
修改文件: kernel/sched/ext/ext.c
代码统计: 2 insertions(+), 0 deletions(-)
Message-ID: 20260825055053.2295139-1-luoliang@kylinos.cn
完整性: 完整——包含 commit 引用、签名行、kernel-doc 警告描述、修复方法

补丁目的

commit 13f1eae3b662（"sched_ext: Synchronize slice and dsq_vtime writes"）给 finish_dispatch() 加了 slice 和 vtime 两个 u64 参数，但函数头上方的 kernel-doc 注释没有同步更新。运行 scripts/kernel-doc -none kernel/sched/ext/ext.c 会产生两条 warning：

Warning: function parameter 'slice' not described in 'finish_dispatch'
Warning: function parameter 'vtime' not described in 'finish_dispatch'

本补丁就是给这两行补上描述，文案与同文件里 dispatch_to_local_dsq() 上方那对参数完全一致，保证 kernel-doc 与函数签名重新对齐。

旧流程的问题

补丁前 finish_dispatch() 的 kernel-doc 块只描述了 4 个参数：

* @p: task to finish dispatching
* @qseq_at_dispatch: qseq when @p started getting dispatched
* @dsq_id: destination DSQ ID
* @enq_flags: %SCX_ENQ_*

但实际函数签名里多了 u64 slice 和 u64 vtime，注释和签名不一致，导致 kernel-doc 工具报"参数未描述"。这种"注释漂移"会让读者对照文档理解代码时遗漏关键参数语义。

新流程

在 @dsq_id 与 @enq_flags 之间插入两行：

* @slice: slice carried by the insert verdict, 0 keeps the current value
* @vtime: vtime carried by the insert verdict, committed on PRIQ inserts

kernel-doc 警告从 2 条降为 0 条，函数体逻辑零变化。

关键实现

改动发生在 kernel/sched/ext/ext.c 第 2806 行附近的注释块里，hunk 头显示上下文是 finish_dispatch() 上方：

 * @qseq_at_dispatch: qseq when @p started getting dispatched
 * @dsq_id: destination DSQ ID
+ * @slice: slice carried by the insert verdict, 0 keeps the current value
+ * @vtime: vtime carried by the insert verdict, committed on PRIQ inserts
 * @enq_flags: %SCX_ENQ_*

注意几点：

描述文字直接复用 dispatch_to_local_dsq() 中已有的措辞，避免同一参数出现两套解释。
注释位置在函数体上方，函数签名与运行时行为完全不变。
修补触发的两条 warning 文案很明确，作者在 commit message 里原文照抄，便于评审核对。

+--------------------------+            +--------------------------+
| dispatch_to_local_dsq()  |            |     finish_dispatch()    |
|  has kernel-doc for:      |    ===>    |  kernel-doc after patch: |
|   @slice / @vtime         |            |   adds @slice / @vtime   |
+--------------------------+            +--------------------------+
            |                                         |
            +-------------> shared text <-------------+

                   apply kernel-doc -none ext.c
                                |
                  +-------------+-------------+
                  |                           |
        before patch (2 warnings)    after patch (0 warnings)
        ---------------------        ---------------------
        - slice not described        + slice described
        - vtime not described        + vtime described

  message #1  Liang Luo       ---v1 patch----------------> lore
  message #2  sashiko-bot    <--review (Low)--------------
  message #3  Liang Luo       ---replies (false alarm)---->
  message #4  Tejun Heo       ---applies to -fixes branch--

类比

想象快递站门口的告示牌：原先只列了「收件人、签收时间、目的地、备注」四列。后来快递流程真的新增了「重量」和「保价金额」两栏，但告示牌忘更新。新员工对照告示牌核对包裹时一直报错——明明表格里有这两项，告示牌却没解释它们。补丁就是把告示牌补上这两行说明，让告示牌与真实流程重新对齐，员工核对不再报错。

Highlight：风险与注意点

自动评审基于旧树误报：Sashiko-bot 拿到的是改动前的旧版本，对照的是没有 slice/vtime 参数的签名，因此报出 "Excess function parameter" 风险。作者明确指出当前 mainline 已经有这两个参数（来自 13f1eae3b662），并用本地 scripts/kernel-doc -none kernel/sched/ext/ext.c 验证：补丁前 2 条警告，补丁后 0 条警告，没有引入 "Excess" 问题。
注释与签名漂移是常见 bug 源：功能参数改了却忘了同步文档，会让读者和工具产生两套理解。最佳实践是改函数签名时就改 kernel-doc，并附 make W=1 或 kernel-doc 的输出作为补丁佐证。
行尾换行与上下文：本补丁插入位置容易让人误以为是 dispatch_to_local_dsq() 注释块的修改，但实际 @@ hunk 头显示上下文是 finish_dispatch() 上方，评审核对时应紧盯 hunk 头，不要被 diff 行附近显示的另一函数名带偏。
后续跟进点：维护者 Tejun 已将其 applied 到 sched_ext/for-7.3-fixes，可见 7.3 周期内会随 -fixes 系列合入；不需要进一步迭代。

一句话总结

一个 2 行的 kernel-doc 补丁，把 finish_dispatch() 新增的 @slice 与 @vtime 参数描述补齐，让 kernel-doc 警告从 2 条降到 0 条，已被 Tejun Heo applied 进 sched_ext/for-7.3-fixes。

[PATCH] sched_ext: Fix missing @slice and @vtime descriptions in finish_dispatch() kernel-doc

LLM 分析