Hi,
The following is the proposed text for "cpuset.cpus.reserve" and "cpuset.cpus.partition" of the new cpuset partition in Documentation/admin-guide/cgroup-v2.rst.
cpuset.cpus.reserve A read-write multiple values file which exists only on root cgroup.
It lists all the CPUs that are reserved for adjacent and remote partitions created in the system. See the next section for more information on what an adjacent or remote partitions is.
Creation of adjacent partition does not require touching this control file as CPU reservation will be done automatically. In order to create a remote partition, the CPUs needed by the remote partition has to be written to this file first.
A "+" prefix can be used to indicate a list of additional CPUs that are to be added without disturbing the CPUs that are originally there. For example, if its current value is "3-4", echoing ""+5" to it will change it to "3-5".
Once a remote partition is destroyed, its CPUs have to be removed from this file or no other process can use them. A "-" prefix can be used to remove a list of CPUs from it. However, removing CPUs that are currently used in existing partitions may cause those partitions to become invalid. A single "-" character without any number can be used to indicate removal of all the free CPUs not allocated to any partitions to avoid accidental partition invalidation.
cpuset.cpus.partition A read-write single value file which exists on non-root cpuset-enabled cgroups. This flag is owned by the parent cgroup and is not delegatable.
It accepts only the following input values when written to.
========== ===================================== "member" Non-root member of a partition "root" Partition root "isolated" Partition root without load balancing ========== =====================================
A cpuset partition is a collection of cgroups with a partition root at the top of the hierarchy and its descendants except those that are separate partition roots themselves and their descendants. A partition has exclusive access to the set of CPUs allocated to it. Other cgroups outside of that partition cannot use any CPUs in that set.
There are two types of partitions - adjacent and remote. The parent of an adjacent partition must be a valid partition root. Partition roots of adjacent partitions are all clustered around the root cgroup. Creation of adjacent partition is done by writing the desired partition type into "cpuset.cpus.partition".
A remote partition does not require a partition root parent. So a remote partition can be formed far from the root cgroup. However, its creation is a 2-step process. The CPUs needed by a remote partition ("cpuset.cpus" of the partition root) has to be written into "cpuset.cpus.reserve" of the root cgroup first. After that, "isolated" can be written into "cpuset.cpus.partition" of the partition root to form a remote isolated partition which is the only supported remote partition type for now.
All remote partitions are terminal as adjacent partition cannot be created underneath it.
The root cgroup is always a partition root and its state cannot be changed. All other non-root cgroups start out as "member".
When set to "root", the current cgroup is the root of a new partition or scheduling domain.
When set to "isolated", the CPUs in that partition will be in an isolated state without any load balancing from the scheduler. Tasks placed in such a partition with multiple CPUs should be carefully distributed and bound to each of the individual CPUs for optimal performance.
The value shown in "cpuset.cpus.effective" of a partition root is the CPUs that are dedicated to that partition and not available to cgroups outside of that partittion.
A partition root ("root" or "isolated") can be in one of the two possible states - valid or invalid. An invalid partition root is in a degraded state where some state information may be retained, but behaves more like a "member".
All possible state transitions among "member", "root" and "isolated" are allowed.
On read, the "cpuset.cpus.partition" file can show the following values.
============================= ===================================== "member" Non-root member of a partition "root" Partition root "isolated" Partition root without load balancing "root invalid (<reason>)" Invalid partition root "isolated invalid (<reason>)" Invalid isolated partition root ============================= =====================================
In the case of an invalid partition root, a descriptive string on why the partition is invalid is included within parentheses.
For an adjacent partition root to be valid, the following conditions must be met.
1) The "cpuset.cpus" is exclusive with its siblings , i.e. they are not shared by any of its siblings (exclusivity rule). 2) The parent cgroup is a valid partition root. 3) The "cpuset.cpus" is not empty and must contain at least one of the CPUs from parent's "cpuset.cpus", i.e. they overlap. 4) The "cpuset.cpus.effective" cannot be empty unless there is no task associated with this partition.
For a remote partition root to be valid, the following conditions must be met.
1) The same exclusivity rule as adjacent partition root. 2) The "cpuset.cpus" is not empty and all the CPUs must be present in "cpuset.cpus.reserve" of the root cgroup and none of them are allocated to another partition. 3) The "cpuset.cpus" value must be present in all its ancestors to ensure proper hierarchical cpu distribution.
External events like hotplug or changes to "cpuset.cpus" can cause a valid partition root to become invalid and vice versa. Note that a task cannot be moved to a cgroup with empty "cpuset.cpus.effective".
For a valid partition root with the sibling cpu exclusivity rule enabled, changes made to "cpuset.cpus" that violate the exclusivity rule will invalidate the partition as well as its sibling partitions with conflicting cpuset.cpus values. So care must be taking in changing "cpuset.cpus".
A valid non-root parent partition may distribute out all its CPUs to its child partitions when there is no task associated with it.
Care must be taken to change a valid partition root to "member" as all its child partitions, if present, will become invalid causing disruption to tasks running in those child partitions. These inactivated partitions could be recovered if their parent is switched back to a partition root with a proper set of "cpuset.cpus".
Poll and inotify events are triggered whenever the state of "cpuset.cpus.partition" changes. That includes changes caused by write to "cpuset.cpus.partition", cpu hotplug or other changes that modify the validity status of the partition. This will allow user space agents to monitor unexpected changes to "cpuset.cpus.partition" without the need to do continuous polling.
Cheers, Longman