Re: [PATCH] Documentation: cgroup: clarify controller enabling semantics

[Waiman Long <llong@redhat.com>]

On 5/28/25 11:23 AM, Waiman Long wrote:
> On 5/27/25 4:53 AM, Vishal Chourasia wrote:
>> The documentation for cgroup controller management has been updated to
>> be more consistent regarding following concepts:
>>
>> What does it mean to have controllers
>> 1) available in a cgroup, vs.
>> 2) enabled in a cgroup
>>
>> Which has been clearly defined below in the documentation.
>>
>> "Enabling a controller in a cgroup indicates that the distribution of
>> the target resource across its immediate children will be controlled.
>> Consider the following sub-hierarchy"
>>
>> As an example, consider
>>
>> /sys/fs/cgroup # cat cgroup.controllers
>> cpuset cpu io memory hugetlb pids misc
>> /sys/fs/cgroup # cat cgroup.subtree_control # No controllers by default
>> /sys/fs/cgroup # echo +cpu +memory > cgroup.subtree_control
>> /sys/fs/cgroup # cat cgroup.subtree_control
>> cpu memory                   # cpu and memory enabled in /sys/fs/cgroup
>> /sys/fs/cgroup # mkdir foo_cgrp
>> /sys/fs/cgroup # cd foo_cgrp/
>> /sys/fs/cgroup/foo_cgrp # cat cgroup.controllers
>> cpu memory                   # cpu and memory available in 'foo_cgrp'
>> /sys/fs/cgroup/foo_cgrp # cat cgroup.subtree_control  # empty by default
>> /sys/fs/cgroup/foo_cgrp # ls
>> cgroup.controllers      cpu.max.burst           memory.numa_stat
>> cgroup.events           cpu.pressure            memory.oom.group
>> cgroup.freeze           cpu.stat                memory.peak
>> cgroup.kill             cpu.stat.local          memory.pressure
>> cgroup.max.depth        cpu.weight              memory.reclaim
>> cgroup.max.descendants  cpu.weight.nice         memory.stat
>> cgroup.pressure         io.pressure memory.swap.current
>> cgroup.procs            memory.current memory.swap.events
>> cgroup.stat             memory.events           memory.swap.high
>> cgroup.subtree_control  memory.events.local     memory.swap.max
>> cgroup.threads          memory.high             memory.swap.peak
>> cgroup.type             memory.low memory.zswap.current
>> cpu.idle                memory.max              memory.zswap.max
>> cpu.max                 memory.min memory.zswap.writeback
>>
>> Once a controller is available in a cgroup it can be used to resource
>> control processes of the cgroup.
>>
>> Signed-off-by: Vishal Chourasia <vishalc@linux.ibm.com>
>> ---
>>   Documentation/admin-guide/cgroup-v2.rst | 4 ++--
>>   1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/admin-guide/cgroup-v2.rst 
>> b/Documentation/admin-guide/cgroup-v2.rst
>> index 1a16ce68a4d7..0e1686511c45 100644
>> --- a/Documentation/admin-guide/cgroup-v2.rst
>> +++ b/Documentation/admin-guide/cgroup-v2.rst
>> @@ -438,8 +438,8 @@ Controlling Controllers
>>   Enabling and Disabling
>>   ~~~~~~~~~~~~~~~~~~~~~
>>   -Each cgroup has a "cgroup.controllers" file which lists all
>> -controllers available for the cgroup to enable::
>> +Each cgroup has a cgroup.controllers file, which lists all the 
>> controllers
>> +available for that cgroup and which can be enabled for its children.
>
> I believe breaking the sentence into two separate components is 
> actually making it less correct. There are implicit controllers that 
> are always enabled and do not show up in cgroup.controllers. Prime 
> examples are perf_event and freezer. IOW, only controllers that are 
> available and need to be explicitly enabled will show up.

A correction: The cgroup.controllers file shows the controllers that are 
available in the current cgroup and which have to be explicitly enabled 
in cgroup.subtree_control to make them available in the child cgroups.

Cheers,
Longman