[PATCH] Docs/admin-guide/cgroup-v2: document hierarchical cpu.max throttling behavior

[PATCH] Docs/admin-guide/cgroup-v2: document hierarchical cpu.max throttling behavior

[Shaojie Sun]

In a multi-level cgroup hierarchy, each level with cpu.max configured
maintains independent bandwidth accounting.  Unlike other Limits-type
controllers such as memory.max and io.max--where only the most
restrictive limit along the hierarchy applies--cpu.max enforces limits
at each level independently.  A process can thus be throttled
simultaneously by multiple levels, and the resulting throttling may
reflect the combined effect of all of them rather than any single
level's limit alone.

This behavior is already documented in the CFS bandwidth control
documentation (sched-bwc.rst) but was not mentioned in the cgroup-v2
interface description, which has led to confusion about unexpected
throttling statistics when cpu.max is configured at multiple levels.

Add a note to the cpu.max interface documentation in cgroup-v2.rst to
clarify the hierarchical enforcement semantics, and add a label to
sched-bwc.rst so that it can be cross-referenced.

Signed-off-by: Shaojie Sun <sunshaojie@kylinos.cn>
---
 Documentation/admin-guide/cgroup-v2.rst | 14 ++++++++++++++
 Documentation/scheduler/sched-bwc.rst   |  2 ++
 2 files changed, 16 insertions(+)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 14b8c571c0d1..3572d3e7f688 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1204,6 +1204,20 @@ will be referred to. All time durations are in microseconds.
 
 	This file affects only processes under the fair-class scheduler.
 
+	In a multi-level hierarchy, each level with cpu.max configured
+	maintains independent bandwidth accounting with its own period
+	timer.  The cgroup's own quota and ancestor quotas are enforced
+	independently rather than being mutually exclusive: when
+	multiple levels along the path have cpu.max set, a process is
+	subject to all of them simultaneously, and the resulting
+	throttling may reflect the combined effect of multiple levels
+	rather than any single level's limit alone (this differs from
+	other Limits-type controllers such as memory.max and io.max,
+	where the most restrictive limit along the hierarchy is
+	applied).  See :ref:`Documentation/scheduler/sched-bwc.rst
+	<sched-bwc>` for a description of the underlying CFS bandwidth
+	control mechanism and the hierarchical throttling behavior.
+
   cpu.max.burst
 	A read-write single value file which exists on non-root
 	cgroups.  The default is "0".
diff --git a/Documentation/scheduler/sched-bwc.rst b/Documentation/scheduler/sched-bwc.rst
index e881a945c188..97c58739d8cf 100644
--- a/Documentation/scheduler/sched-bwc.rst
+++ b/Documentation/scheduler/sched-bwc.rst
@@ -2,6 +2,8 @@
 CFS Bandwidth Control
 =====================
 
+.. _sched-bwc:
+
 .. note::
    This document only discusses CPU bandwidth control for SCHED_NORMAL.
    The SCHED_RT case is covered in Documentation/scheduler/sched-rt-group.rst
-- 
2.25.1

Re: [PATCH] Docs/admin-guide/cgroup-v2: document hierarchical cpu.max throttling behavior

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 823 bytes --]

Hi.

On Fri, Jul 24, 2026 at 06:25:00PM +0800, Shaojie Sun <sunshaojie@kylinos.cn> wrote:
> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index 14b8c571c0d1..3572d3e7f688 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst

> +	                                       and the resulting
> +	throttling may reflect the combined effect of multiple levels
> +	rather than any single level's limit alone (this differs from
> +	other Limits-type controllers such as memory.max and io.max,
> +	where the most restrictive limit along the hierarchy is
> +	applied).

I'm not sure from the description what the "combined effect" is.
Can you give an example where the cpu.max differs from that Limits-type
semantics?

Thanks,
Michal

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 265 bytes --]

Re: [PATCH] Docs/admin-guide/cgroup-v2: document hierarchical cpu.max throttling behavior

[Shaojie Sun]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset=y, Size: 2181 bytes --]

Hi, Michal.

On Fri, 24 Jul 2026 13:21:46, Michal wrote:
>On Fri, Jul 24, 2026 at 06:25:00PM +0800, Shaojie Sun <sunshaojie@kylinos.cn> wrote:
>> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
>> index 14b8c571c0d1..3572d3e7f688 100644
>> --- a/Documentation/admin-guide/cgroup-v2.rst
>> +++ b/Documentation/admin-guide/cgroup-v2.rst
>
>> +	                                       and the resulting
>> +	throttling may reflect the combined effect of multiple levels
>> +	rather than any single level's limit alone (this differs from
>> +	other Limits-type controllers such as memory.max and io.max,
>> +	where the most restrictive limit along the hierarchy is
>> +	applied).
>
>I'm not sure from the description what the "combined effect" is.
>Can you give an example where the cpu.max differs from that Limits-type
>semantics?

Here is an example to illustrate the difference. Consider:
  Parent:  cpu.max = 50000 100000 (50%)
  Child:   cpu.max = 20000 100000 (20%)
With cpu.max, when the child's processes consume CPU, throttling can be 
triggered by either the child's own limit or the parent's limit 
independently — both levels participate in enforcement. This is visible
in cpu.stat : the throttled_usec counter can accumulate non-zero values
at both the child and parent level. Even when the child's quota is 
smaller than the parent's (20 < 50), the parent's limit still
participates; conversely, when a child's quota is larger than the
parent's, the child's own limit still participates.

Compare this with memory.max. If we had:
  Parent:  memory.max = 50M
  Child:   memory.max = 20M
The effective limit for the child is simply min(20M, 50M) = 20M — only the
most restrictive limit along the path applies. The child will never see an
OOM triggered by the parent's 50M limit before reaching its own 20M.

In short: cpu.max enforcement is per-level independent — every level with 
cpu.max configured can independently throttle the group, and cpu.stat 
counters at multiple levels can all accumulate throttled_usec for the same
workload. memory.max only enforces the tightest limit along the path.

Thanks,
Shaojie Sun