Skip to contentSkip to conversation

docs/sched_ext: document that cgroup CPU knobs are scheduler-dependent

PATCH Superseded Tao Cui 2 participants 2 messages Aug 19

Subsystems (3)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Tao Cui

author
#0 lore raw

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

From: Tao Cui <[email protected]>

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.

---
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/[email protected]

 Documentation/scheduler/sched-ext.rst | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
Documentation/scheduler/sched-ext.rst +18 -0
index 0e97fd019994..b742af4d3127 100644
@@ -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
 ---------------
 
Signature · 1 line
2.43.0
reviewer
#1 lore raw

Hello,

On Wed, Aug 19, 2026 at 09:21:57AM +0800, Tao Cui wrote:
...

Documentation/scheduler/sched-ext.rst optional. The following modified excerpt is from · line 257

Quoted 10 lines
Documentation/scheduler/sched-ext.rst +10 -0
+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.

SCX doesn't have nr_throttled routing right now even for scheds that implement cpu.max (scx_lavd is the only one right now AFAIK). I'd keep the documentation more concise and generic. I don't think listing schedulers that don't implement the feature or specifically pointing to nr_throttled is all that useful given that most schedulers don't implement it right now.

Thanks.

Signature · 1 line
tejun