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

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