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

[Waiman Long <llong@redhat.com>]

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.

Cheers,
Longman