From aa4decd2d9ee506b9878c9c4617f29cc08fc41e9 Mon Sep 17 00:00:00 2001 From: Guopeng Zhang Date: Tue, 22 Sep 2026 17:20:34 +0800 Subject: [PATCH] docs: cgroup-v2: Describe effective CPUs of partition roots The cpuset.cpus.effective description says that the effective CPUs are granted by the parent and are normally a subset of cpuset.cpus. This does not always hold for a valid non-root partition root. Its effective CPUs are the active CPUs in cpuset.cpus.exclusive.effective after CPUs assigned to valid child partition roots are removed. If cpuset.cpus.exclusive differs from cpuset.cpus, the effective CPUs may therefore be outside cpuset.cpus. Remote partitions also do not necessarily get their CPUs from their immediate parent. Suggested-by: Ridong Chen Reviewed-by: Ridong Chen Signed-off-by: Guopeng Zhang Reviewed-by: Waiman Long Signed-off-by: Tejun Heo --- Documentation/admin-guide/cgroup-v2.rst | 57 +++++++++++++++++++++---- 1 file changed, 48 insertions(+), 9 deletions(-) diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index f47b26b3ed7f..bd8c80f3bbc9 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -2536,16 +2536,55 @@ Cpuset Interface Files A read-only multiple values file which exists on all cpuset-enabled cgroups. - It lists the onlined CPUs that are actually granted to this - cgroup by its parent. These CPUs are allowed to be used by - tasks within the current cgroup. + It lists the active CPUs available to tasks in this cgroup. - If "cpuset.cpus" is empty, the "cpuset.cpus.effective" file shows - all the CPUs from the parent cgroup that can be available to - be used by this cgroup. Otherwise, it should be a subset of - "cpuset.cpus" unless none of the CPUs listed in "cpuset.cpus" - can be granted. In this case, it will be treated just like an - empty "cpuset.cpus". + For a cgroup that is not a valid partition root, an empty + "cpuset.cpus" makes "cpuset.cpus.effective" show all CPUs + available from the parent cgroup. Otherwise, it is a subset + of "cpuset.cpus" unless none of the requested CPUs can be + granted. In that case, it is treated like an empty + "cpuset.cpus". + + For example:: + + P (cpuset.cpus.effective=0-3) + | + +-- C0 (member): cpuset.cpus=1-2 + | cpuset.cpus.effective=1-2 + +-- C1 (invalid root): cpuset.cpus=4-5 + | cpuset.cpus.effective=0-3 + \-- C2 (member): cpuset.cpus= + cpuset.cpus.effective=0-3 + + C0 gets CPUs 1-2 because they are available from P. + None of C1's requested CPUs 4-5 are available from P, so C1 uses P's + effective CPUs 0-3 instead. + C2 has an empty "cpuset.cpus" and therefore also uses P's effective + CPUs 0-3. + + For a valid non-root partition root, "cpuset.cpus.effective" contains + the active CPUs from "cpuset.cpus.exclusive.effective" except + those granted to valid child partition roots. If + "cpuset.cpus.exclusive" is set to a value different from + "cpuset.cpus", the effective CPUs need not be a subset of + "cpuset.cpus". + + For example, if CPUs 2-5 are allocated to P for exclusive use, + CPUs 2-4 are active, CPU 5 is offline, and none of CPUs 2-5 are + assigned to a valid child partition root:: + + top (root) + | + \-- P (valid partition root) + cpuset.cpus=0-3 + cpuset.cpus.exclusive=2-5 + cpuset.cpus.exclusive.effective=2-5 + cpuset.cpus.effective=2-4 + + P has 2-5 in "cpuset.cpus.exclusive.effective", including the + offline CPU 5. CPU 5 is excluded from "cpuset.cpus.effective", + leaving 2-4. The result also shows that "cpuset.cpus.effective" + need not be a subset of "cpuset.cpus", which is 0-3. Its value will be affected by CPU hotplug events.