[PATCH v3] Documentation: cgroup: add section explaining controller availability

[PATCH v3] Documentation: cgroup: add section explaining controller availability

[Vishal Chourasia]

Add "Availability" section to Control Group v2 docs. It describes the
meaning of a controller being available in a cgroup, complementing the
existing "Enabling and Disabling" section.

This update improves the clarity of cgroup controller management by
explicitly distinguishing between:

1. Availability – when a controller is supported by the kernel and
   listed in "cgroup.controllers", making its interface files accessible
   in the cgroup's directory.
2. Enabling – when a controller is enabled via explicitly writing the
   name of the controller to "cgroup.subtree_control" to control
   distribution of resource across the cgroup's immediate children.

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 enabled by default
/sys/fs/cgroup # echo +cpu +memory > cgroup.subtree_control # enabling "cpu" and "memory"
/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

In this example, "cpu" and "memory" are enabled in the root cgroup,
making them available in "foo_cgrp". This exposes the corresponding
interface files in "foo_cgrp/", allowing resource control of processes
in that cgroup. However, these controllers are not yet enabled in
"foo_cgrp" itself.

Once a controller is available in a cgroup it can be used to resource
control processes of the cgroup.

Acked-by: Michal Koutný <mkoutny@suse.com>
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Vishal Chourasia <vishalc@linux.ibm.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 0cc35a14afbe..31acc64e656f 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -435,6 +435,15 @@ both cgroups.
 Controlling Controllers
 -----------------------
 
+Availablity
+~~~~~~~~~~~
+
+A controller is available in a cgroup when it is supported by the kernel (i.e.,
+compiled in, not disabled and not attached to a v1 hierarchy) and listed in the
+"cgroup.controllers" file. Availability means the controller's interface files
+are exposed in the cgroup’s directory, allowing the distribution of the target
+resource to be observed or controlled within that cgroup.
+
 Enabling and Disabling
 ~~~~~~~~~~~~~~~~~~~~~~
 
-- 
2.49.0

Re: [PATCH v3] Documentation: cgroup: add section explaining controller availability

[Tejun Heo]

On Fri, Jun 06, 2025 at 09:40:05AM +0530, Vishal Chourasia wrote:
> Add "Availability" section to Control Group v2 docs. It describes the
> meaning of a controller being available in a cgroup, complementing the
> existing "Enabling and Disabling" section.
> 
> This update improves the clarity of cgroup controller management by
> explicitly distinguishing between:
> 
> 1. Availability – when a controller is supported by the kernel and
>    listed in "cgroup.controllers", making its interface files accessible
>    in the cgroup's directory.
> 2. Enabling – when a controller is enabled via explicitly writing the
>    name of the controller to "cgroup.subtree_control" to control
>    distribution of resource across the cgroup's immediate children.
> 
> 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 enabled by default
> /sys/fs/cgroup # echo +cpu +memory > cgroup.subtree_control # enabling "cpu" and "memory"
> /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
> 
> In this example, "cpu" and "memory" are enabled in the root cgroup,
> making them available in "foo_cgrp". This exposes the corresponding
> interface files in "foo_cgrp/", allowing resource control of processes
> in that cgroup. However, these controllers are not yet enabled in
> "foo_cgrp" itself.
> 
> Once a controller is available in a cgroup it can be used to resource
> control processes of the cgroup.
> 
> Acked-by: Michal Koutný <mkoutny@suse.com>
> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
> Signed-off-by: Vishal Chourasia <vishalc@linux.ibm.com>

Applied to cgroup/for-6.17.

Thanks.

-- 
tejun