[PATCH v2 0/2] docs: cgroup-v2: Correct cpuset CPU descriptions

[PATCH v2 0/2] docs: cgroup-v2: Correct cpuset CPU descriptions

[Guopeng Zhang]

From: Guopeng Zhang <zhangguopeng@kylinos.cn>

The cpuset interface documentation says cpuset.cpus.isolated is empty
unless an isolated partition exists, omitting CPUs isolated at boot with
isolcpus=domain. Its cpuset.cpus.effective description also assumes CPUs
come from the immediate parent and are normally a subset of
cpuset.cpus, which is not always true for valid non-root partition roots.

Update both descriptions to match the existing behavior.

Changes since v1:
- Reword the cpuset.cpus.isolated description as suggested, while
  specifying the domain flag of isolcpus.
- Add examples of the cpuset.cpus.effective relationship for member or
  invalid partition roots and for valid partition roots.
- Add the Suggested-by tags and the Reviewed-by tag.

Guopeng Zhang (2):
  docs: cgroup-v2: Describe boot-isolated CPUs in cpuset.cpus.isolated
  docs: cgroup-v2: Describe effective CPUs of partition roots

 Documentation/admin-guide/cgroup-v2.rst | 59 ++++++++++++++++++++-----
 1 file changed, 48 insertions(+), 11 deletions(-)

-- 
2.43.0

[PATCH v2 1/2] docs: cgroup-v2: Describe boot-isolated CPUs in cpuset.cpus.isolated

[Guopeng Zhang]

From: Guopeng Zhang <zhangguopeng@kylinos.cn>

cpuset.cpus.isolated is documented as empty when no isolated partition
exists. This is not true when CPUs are isolated at boot with
isolcpus=domain. cpuset_init() adds those CPUs to the isolated mask,
and isolcpus=<cpu-list> uses domain isolation by default. They remain
listed after a partition using them is released.

Document the boot-isolated CPUs as well.

Suggested-by: Ridong Chen <ridong.chen@linux.dev>
Reviewed-by: Ridong Chen <ridong.chen@linux.dev>
Signed-off-by: Guopeng Zhang <zhangguopeng@kylinos.cn>
---
 Documentation/admin-guide/cgroup-v2.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 2ec582985b5b..18a01ce4c334 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -2626,8 +2626,9 @@ Cpuset Interface Files
 	A read-only and root cgroup only multiple values file.
 
 	This file shows the set of all isolated CPUs used in existing
-	isolated partitions. It will be empty if no isolated partition
-	is created.
+	isolated partitions or isolated at boot time via the "domain"
+	flag of "isolcpus". The latter remain listed even after any
+	partition using them is released.
 
   cpuset.cpus.partition
 	A read-write single value file which exists on non-root
-- 
2.43.0

[PATCH v2 2/2] docs: cgroup-v2: Describe effective CPUs of partition roots

[Guopeng Zhang]

From: Guopeng Zhang <zhangguopeng@kylinos.cn>

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 <ridong.chen@linux.dev>
Signed-off-by: Guopeng Zhang <zhangguopeng@kylinos.cn>
---
 Documentation/admin-guide/cgroup-v2.rst | 56 ++++++++++++++++++++-----
 1 file changed, 46 insertions(+), 10 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 18a01ce4c334..d21bbae3312a 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -2505,16 +2505,52 @@ 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.
-
-	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".
+	It lists the active CPUs available to tasks in this cgroup.
+
+	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=<empty>
+	                         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 active, available, and not 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-5
+
+	P has 2-5 in "cpuset.cpus.effective" even though its
+	"cpuset.cpus" is 0-3.
 
 	Its value will be affected by CPU hotplug events.
 
-- 
2.43.0

Re: [PATCH v2 2/2] docs: cgroup-v2: Describe effective CPUs of partition roots

[Ridong Chen]

On 9/22/2026 11:21 AM, Guopeng Zhang wrote:
> From: Guopeng Zhang <zhangguopeng@kylinos.cn>
> 
> 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 <ridong.chen@linux.dev>
> Signed-off-by: Guopeng Zhang <zhangguopeng@kylinos.cn>
> ---
>   Documentation/admin-guide/cgroup-v2.rst | 56 ++++++++++++++++++++-----
>   1 file changed, 46 insertions(+), 10 deletions(-)
> 
> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index 18a01ce4c334..d21bbae3312a 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst
> @@ -2505,16 +2505,52 @@ 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.
> -
> -	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".
> +	It lists the active CPUs available to tasks in this cgroup.
> +
> +	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=<empty>
> +	                         cpuset.cpus.effective=0-3
> +

That is clear. Thanks.

> +	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 active, available, and not 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-5
> +
> +	P has 2-5 in "cpuset.cpus.effective" even though its
> +	"cpuset.cpus" is 0-3.
>   
>   	Its value will be affected by CPU hotplug events.
>   

I would suggest offering an example where "cpuset.cpus.effective" differs from 
"cpuset.cpus.exclusive.effective", meaning that 
"cpuset.cpus.exclusive.effective" contains offline CPUs. This would make it much 
clearer that "cpuset.cpus.effective" does not contain offline CPUs.

With that, feel free to add:

Reviewed-by: Ridong Chen <ridong.chen@linux.dev>

Thanks.

-- 
Best regards
Ridong

Re: [PATCH v2 2/2] docs: cgroup-v2: Describe effective CPUs of partition roots

[Guopeng Zhang]

在 2026/9/22 14:36, Ridong Chen 写道:
> 
> 
> On 9/22/2026 11:21 AM, Guopeng Zhang wrote:
>> From: Guopeng Zhang <zhangguopeng@kylinos.cn>
>>
>> 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 <ridong.chen@linux.dev>
>> Signed-off-by: Guopeng Zhang <zhangguopeng@kylinos.cn>
>> ---
>>   Documentation/admin-guide/cgroup-v2.rst | 56 ++++++++++++++++++++-----
>>   1 file changed, 46 insertions(+), 10 deletions(-)
>>
>> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
>> index 18a01ce4c334..d21bbae3312a 100644
>> --- a/Documentation/admin-guide/cgroup-v2.rst
>> +++ b/Documentation/admin-guide/cgroup-v2.rst
>> @@ -2505,16 +2505,52 @@ 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.
>> -
>> -    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".
>> +    It lists the active CPUs available to tasks in this cgroup.
>> +
>> +    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=<empty>
>> +                             cpuset.cpus.effective=0-3
>> +
> 
> That is clear. Thanks.
> 
>> +    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 active, available, and not 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-5
>> +
>> +    P has 2-5 in "cpuset.cpus.effective" even though its
>> +    "cpuset.cpus" is 0-3.
>>         Its value will be affected by CPU hotplug events.
>>   
> 
> I would suggest offering an example where "cpuset.cpus.effective" differs from "cpuset.cpus.exclusive.effective", meaning that "cpuset.cpus.exclusive.effective" contains offline CPUs. This would make it much clearer that "cpuset.cpus.effective" does not contain offline CPUs.
> 
> With that, feel free to add:
> 
> Reviewed-by: Ridong Chen <ridong.chen@linux.dev>
> 
Thanks for the suggestion. I'll update the example in v3 to cover the offline CPU case and add your Reviewed-by.

Thanks,
Guopeng