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

[PATCH v3] 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: it may
implement the corresponding callback partially or not at all. 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>
---
v2 -> v3: Drop the scheduler list and the nr_throttled example, keep
the section concise and generic, per review.

v2: https://lore.kernel.org/r/20260819012157.220932-1-cui.tao@linux.dev

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

diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
index 35b550671ca7..b594d93dd6aa 100644
--- a/Documentation/scheduler/sched-ext.rst
+++ b/Documentation/scheduler/sched-ext.rst
@@ -242,6 +242,18 @@ 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: it
+may implement the corresponding callback partially or not at all. The
+same applies to other knobs like nice levels. When relying on these
+knobs, check the documentation or source of the loaded scheduler.
+
 Dispatch Queues
 ---------------
 
-- 
2.43.0

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

[Andrea Righi]

Hi Tao,

On Mon, Aug 24, 2026 at 05:15:01PM +0800, Tao Cui wrote:
> 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: it may
> implement the corresponding callback partially or not at all. 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>
> ---
> v2 -> v3: Drop the scheduler list and the nr_throttled example, keep
> the section concise and generic, per review.
> 
> v2: https://lore.kernel.org/r/20260819012157.220932-1-cui.tao@linux.dev
> 
>  Documentation/scheduler/sched-ext.rst | 12 ++++++++++++
>  1 file changed, 12 insertions(+)
> 
> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
> index 35b550671ca7..b594d93dd6aa 100644
> --- a/Documentation/scheduler/sched-ext.rst
> +++ b/Documentation/scheduler/sched-ext.rst
> @@ -242,6 +242,18 @@ 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.

Existing cpu.weight and bandwidth values are delivered via ops.cgroup_init(),
ops.cgroup_set_*() callbacks handle later changes.

Moreover, cpu.idle state is not included in scx_cgroup_init_args, so apparently
BPF schedulers don't receive an initial value (only subsequent writes). This
should be probably fixed separately.

> +Whether and how a knob takes effect is up to the loaded scheduler: it
> +may implement the corresponding callback partially or not at all. The
> +same applies to other knobs like nice levels. When relying on these
> +knobs, check the documentation or source of the loaded scheduler.
> +

"nice levels" can be a bit ambiguous, per-task nice changes are converted to
weights and reported through ops.set_weight(), writes to the cgroup file
cpu.weight.nice are reported through ops.cgroup_set_weight().

Maybe we can rephrase the whole paragraph as following, or something along these
lines:

  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.

Thanks,
-Andrea

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

[Tao Cui]

Hello, Andrea,

在 2026/8/24 19:55, Andrea Righi 写道:
> Hi Tao,
> 
> On Mon, Aug 24, 2026 at 05:15:01PM +0800, Tao Cui wrote:
>> 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: it may
>> implement the corresponding callback partially or not at all. 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>
>> ---
>> v2 -> v3: Drop the scheduler list and the nr_throttled example, keep
>> the section concise and generic, per review.
>>
>> v2: https://lore.kernel.org/r/20260819012157.220932-1-cui.tao@linux.dev
>>
>>  Documentation/scheduler/sched-ext.rst | 12 ++++++++++++
>>  1 file changed, 12 insertions(+)
>>
>> diff --git a/Documentation/scheduler/sched-ext.rst b/Documentation/scheduler/sched-ext.rst
>> index 35b550671ca7..b594d93dd6aa 100644
>> --- a/Documentation/scheduler/sched-ext.rst
>> +++ b/Documentation/scheduler/sched-ext.rst
>> @@ -242,6 +242,18 @@ 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.
> 
> Existing cpu.weight and bandwidth values are delivered via ops.cgroup_init(),
> ops.cgroup_set_*() callbacks handle later changes.
> 
> Moreover, cpu.idle state is not included in scx_cgroup_init_args, so apparently
> BPF schedulers don't receive an initial value (only subsequent writes). This
> should be probably fixed separately.
> 
>> +Whether and how a knob takes effect is up to the loaded scheduler: it
>> +may implement the corresponding callback partially or not at all. The
>> +same applies to other knobs like nice levels. When relying on these
>> +knobs, check the documentation or source of the loaded scheduler.
>> +
> 
> "nice levels" can be a bit ambiguous, per-task nice changes are converted to
> weights and reported through ops.set_weight(), writes to the cgroup file
> cpu.weight.nice are reported through ops.cgroup_set_weight().
> 
> Maybe we can rephrase the whole paragraph as following, or something along these
> lines:
> 
>   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.
> 

Thanks for the review. v4 adopts your wording: ops.cgroup_init()
for the initial values, ops.cgroup_set_*() only for subsequent
changes, and per-task nice disambiguated from cpu.weight.nice via
ops.set_weight().

On the missing cpu.idle initial value in scx_cgroup_init_args: I can
look into a separate fix for that.

Thanks,
Tao

> Thanks,
> -Andrea