sched_ext 文档：cgroup CPU 控件依赖调度器实现

系列概况

标题：[PATCH v4] docs/sched_ext: document that cgroup CPU knobs are scheduler-dependent
作者：Tao Cui cuitao@kylinos.cn
版本：v4（单封 patch，非系列）
规模：1 file changed, 15 insertions(+)，无删除
修改文件：Documentation/scheduler/sched-ext.rst
代码统计：Documentation/scheduler/sched-ext.rst | 15 +++++++++++++++
Message-ID：20260824132116.560347-1-cui.tao@linux.dev
完整性：完整；Andrea Righi 提了措辞建议，作者据此改出 v4，Tejun Heo 已合入 sched_ext/for-7.3-fixes

补丁目的

sched_ext 把调度器实现搬到 BPF 里。cgroup v2 的 cpu.max、cpu.weight、cpu.idle 等 CPU 控制器在 fair 调度器下由内核强制执行；但在 sched_ext 下，是否生效取决于加载的 BPF 调度器实现了哪些回调。这份纯文档补丁在 sched-ext.rst 的 Basics 章节里新增 Scheduler-Dependent Knobs 小节，告知读者：

fair 调度器会强制执行这些 cgroup 设置。
在 sched_ext 下，调度器核心通过 ops.cgroup_init() 把初始值交给 BPF 调度器。
后续修改走 ops.cgroup_set_*() 系列回调。
进程级 nice 的变更通过 ops.set_weight() 转成 weight 通知。
任何 BPF 调度器都可以选择忽略，因此这些控件可能"静默无效"。

旧流程的问题

旧文档只在示例 BPF 程序附近顺带提到"调度器负责 cgroup 支持"，对运维和容器用户来说不够直观，会让人误以为 cpu.max=200000 100000 在 scx_simple 下也会自动限流。


       [cgroup: cpu.max / cpu.weight / cpu.idle]
                       |
                       v
 [kernel: enforce uniformly]
                       |
                       v
                [process: throttled]

新流程

新文档把链路显式分成三段：cgroup 文件 ->调度器核心（转发）-> BPF 调度器（选择性生效）。

   [cgroup: cpu.max / cpu.weight / cpu.idle]
                   |
                   v
        +-----------------------+
        |   scheduler core      |
        |   (sched_ext core)    |
        +-----------------------+
            |  cgroup_init() <- initial values
            |  cgroup_set_weight()       <- later changes
            |  cgroup_set_bandwidth()
            |  set_weight()              <- per-task nice
            v
        +-----------------------+
        |  loaded BPF scheduler |
        |  (scx_simple/custom)  |
        +-----------------------+
                    |
              +-----+-----+
              |           |
              v           v
        full impl    partial / none
        throttled    silently ignored

关键实现

改动只落在 Documentation/scheduler/sched-ext.rst，位置在 Basics 小节末尾、.name = "simple" 示例之后，插入 15 行 RST：

+Scheduler-Dependent Knobs
+-------------------------
+
+The fair-class scheduler enforces CPU controller settings such as
+``cpu.max``, ``cpu.weight`` and ``cpu.idle``. For sched_ext tasks, the
+scheduler core communicates these settings to the BPF scheduler
+through ``ops.cgroup_init()`` and reports subsequent changes through
+the corresponding ``ops.cgroup_set_*()`` callbacks. Similarly, per-task
+nice changes are converted to weights and reported through
+``ops.set_weight()``.
+
+Each BPF scheduler is responsible for implementing the scheduling
+semantics of these settings and may choose to ignore them. Consult the
+loaded scheduler's documentation before relying on these controls.

几个值得注意的点：

ops.cgroup_init() 明确只承载"初始值"，后续修改走 ops.cgroup_set_*()，避免读者混淆。
进程级 nice走 ops.set_weight()，与 cgroup v2 的 cpu.weight.nice 是两条独立路径，这是 v3 -> v4 重点修的措辞。
没有代码改动，所以不需要 Fixes: 标签；也没有附 Reviewed-by / Acked-by，直接被 maintainer 接收。

类比

把它想成外卖平台：

用户在 App（cgroup v2 文件）里勾选"少糖、不要香菜、出餐快"（= cpu.max / cpu.weight / cpu.idle）。
平台（scheduler core）只负责把订单需求转发给商家（ops.cgroup_init() + ops.cgroup_set_*()）。
接单的商家（加载的 BPF 调度器）可以照做，也可以直接忽略。顾客看不到报错，只是"味道没变"。

这次文档改动相当于在外卖 App 上加了行小字："本平台仅转发需求，是否满足以商家为准。" 用户读到才会意识到：设了 cpu.max 不等于限住了进程。

Highlight：风险与注意点

静默失效：cgroup 设置在某个 BPF 调度器下完全不起作用时，没有任何日志或 warning，本次文档更新正是为这一坑补漏。
文档与实现脱节风险：未来若新增 ops.cgroup_set_idle() 等回调，本节必须同步更新，否则会再次误导读者。
进程 nice 与 cgroup cpu.weight.nice 的语义并不等同：fair 调度器会把 nice 转成 weight 后做层级合并；BPF 调度器只把 nice 直接喂给 ops.set_weight()，层级合并由 BPF 程序自行决定。
落地分支是 sched_ext/for-7.3-fixes 而非 next/feature，说明 Tejun 把这视为面向最终用户明确性的修复，会随下一个 7.x 修复版本一起发布。
没有附带示例 BPF 程序如何处理这些回调，未来若再加一段"示例 BPF 调度器应如何响应 cgroup 变更"会更完整。

版本变化

v3 -> v4（仅一封 patch）：

按 Andrea 的反馈重写段落：明确 ops.cgroup_init() 走初始值，ops.cgroup_set_*() 走后续变更。
把 per-task nice（ops.set_weight()）与 cgroup cpu.weight.nice 区分开。
行数仍是 +15，但术语更精确、读者更难误用。

一句话总结

这是一份针对 sched_ext 的纯文档小补丁：把 cgroup CPU 控件"是否生效由加载的 BPF 调度器决定"这件事写到 sched-ext.rst 的 Basics 章节，避免用户误以为设了 cpu.max 就一定能限流；Andrea给出措辞建议后 v4 修订完毕，Tejun 已合入 sched_ext/for-7.3-fixes。

[PATCH v4] docs/sched_ext: document that cgroup CPU knobs are scheduler-dependent

LLM 分析