linux-kernel - [PATCH] Documentation: cgroup: clarify controller enabling semantics

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250527085335.256045-2-vishalc@linux.ibm.com>
Date: Tue, 27 May 2025 14:23:36 +0530
From: Vishal Chourasia <vishalc@...ux.ibm.com>
To: Tejun Heo <tj@...nel.org>, Johannes Weiner <hannes@...xchg.org>,
        Michal Koutný <mkoutny@...e.com>,
        Jonathan Corbet <corbet@....net>, cgroups@...r.kernel.org,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Cc: Vishal Chourasia <vishalc@...ux.ibm.com>
Subject: [PATCH] Documentation: cgroup: clarify controller enabling semantics

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@...ux.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.
 
   # cat cgroup.controllers
   cpu io memory
-- 
2.49.0