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

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

[Tao Cui]

From: Tao Cui <cuitao@kylinos.cn>

The fair class enforces cpu controller knobs such as cpu.max,
cpu.weight and cpu.idle in the kernel. sched_ext only passes them to
the BPF scheduler through the ops.cgroup_set_*() callbacks. Whether
and how a knob takes effect is up to the loaded scheduler: if it
doesn't implement the corresponding callback, the knob is ignored.
For example, none of scx_simple, scx_flatcg and scx_central implements
ops.cgroup_set_bandwidth(), so with them cpu.max has no effect -- the
cgroup runs at unlimited CPU with nr_throttled staying at 0.

The same applies to other knobs like nice levels.

Document this in the basics section so users and container
orchestrators know what to expect from a BPF scheduler.

Signed-off-by: Tao Cui <cuitao@kylinos.cn>
---
RFC -> v2: v1 added a pr_warn_once() for the missing
ops.cgroup_set_bandwidth() implementation. Drop the warning and
document the scheduler-dependent behavior in sched-ext.rst instead,
as suggested in review.

v1: https://lore.kernel.org/r/20260818135328.174152-1-cui.tao@linux.dev

 Documentation/scheduler/sched-ext.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
index 0e97fd019994..b742af4d3127 100644
--- a/Documentation/scheduler/sched-ext.rst
+++ b/Documentation/scheduler/sched-ext.rst
@@ -242,6 +242,24 @@ optional. The following modified excerpt is from
             .name                   = "simple",
     };
 
+Scheduler-Dependent Knobs
+-------------------------
+
+The fair class enforces cpu controller knobs such as ``cpu.max``,
+``cpu.weight`` and ``cpu.idle`` in the kernel. sched_ext only passes
+them to the BPF scheduler through ``ops.cgroup_set_weight()``,
+``ops.cgroup_set_idle()``, ``ops.cgroup_set_bandwidth()`` and friends.
+Whether and how a knob takes effect is up to the loaded scheduler: if
+it doesn't implement the corresponding callback, the knob is ignored.
+For example, none of scx_simple, scx_flatcg and scx_central implements
+``ops.cgroup_set_bandwidth()``, so with them ``cpu.max`` has no effect
+-- the cgroup runs at unlimited CPU with ``nr_throttled`` staying
+at 0.
+
+The same applies to other knobs like nice levels: the scheduler may
+honor them partially or not at all. When relying on these knobs, check
+the documentation or source of the loaded scheduler.
+
 Dispatch Queues
 ---------------
 
-- 
2.43.0