[PATCH] Documentation: cgroup: clarify controller enabling semantics

[PATCH] Documentation: cgroup: clarify controller enabling semantics

[Vishal Chourasia]

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

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

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 855 bytes --]

Hello.

On Tue, May 27, 2025 at 02:23:36PM +0530, Vishal Chourasia <vishalc@linux.ibm.com> wrote:
> --- 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

Honestly, I see little difference between the two resulting formulations.
Could you perhaps add an example where the documentation confused you or
behavior was not what you expected based on the docs?

Thanks,
Michal

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 880 bytes --]

On Tue, May 27, 2025 at 02:23:36PM +0530, Vishal Chourasia wrote:
> 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.

Keep the double colon (literal code block).

>  
>    # cat cgroup.controllers
>    cpu io memory
> -- 
> 2.49.0
> 

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Vishal Chourasia]

On Tue, May 27, 2025 at 11:58:50AM +0200, Michal Koutný wrote:
> Hello.
> 
> On Tue, May 27, 2025 at 02:23:36PM +0530, Vishal Chourasia <vishalc@linux.ibm.com> wrote:
> > --- 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
> 
> Honestly, I see little difference between the two resulting formulations.
> Could you perhaps add an example where the documentation confused you or
> behavior was not what you expected based on the docs?
Hello Michal,

The part that was confused me, was the meaning behind controller being
available vs. enabled in a cgroup.

Though, the documentation does mention what it means for a controller to
be enabled in a cgroup later in the text. But at the point of the
change it is unclear.

Thanks
Vishal


> 
> Thanks,
> Michal

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

[Vishal Chourasia]

On Tue, May 27, 2025 at 11:58:50AM +0200, Michal Koutný wrote:
> Hello.
> 
> On Tue, May 27, 2025 at 02:23:36PM +0530, Vishal Chourasia <vishalc@linux.ibm.com> wrote:
> > --- 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
> 
> Honestly, I see little difference between the two resulting formulations.
> Could you perhaps add an example where the documentation confused you or
> behavior was not what you expected based on the docs?

You are right, there is little difference. I wanted to highlight the
point, that, Availablity means controller can be used to resource
control a cgroup, while Enablement means controller is now "availble" to
children of the cgroup.

Regards,
Vishal

> 
> Thanks,
> Michal

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

[Waiman Long]

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

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

[Waiman Long]

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

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

[Michal Koutný]

[-- Attachment #1: Type: text/plain, Size: 540 bytes --]

On Wed, May 28, 2025 at 06:48:37PM +0530, Vishal Chourasia <vishalc@linux.ibm.com> wrote:
> The part that was confused me, was the meaning behind controller being
> available vs. enabled in a cgroup.
> 
> Though, the documentation does mention what it means for a controller to
> be enabled in a cgroup later in the text. But at the point of the
> change it is unclear.

There's a picture [1] that may be more descriptive than the docs (on
which it is based).

HTH,
Michal

[1] https://paste.opensuse.org/pastes/987b665209bb

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

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

[Vishal Chourasia]

On Tue, May 27, 2025 at 05:04:29PM +0700, Bagas Sanjaya wrote:
> On Tue, May 27, 2025 at 02:23:36PM +0530, Vishal Chourasia wrote:
> > 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.
> 
> Keep the double colon (literal code block).
Sure, thanks!

Vishal
> 
> >  
> >    # cat cgroup.controllers
> >    cpu io memory
> > -- 
> > 2.49.0
> > 
> 
> Thanks.
> 
> -- 
> An old man doll... just what I always wanted! - Clara

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

[Vishal Chourasia]

Hi Longman,
On Wed, May 28, 2025 at 11:45:29AM -0400, Waiman Long wrote:
> 
> On 5/28/25 11:23 AM, Waiman Long wrote:
> > 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.
 
Thank you for pointing it out.

Vishal
> 
> Cheers,
> Longman
> 

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

[Vishal Chourasia]

On Wed, May 28, 2025 at 07:05:06PM +0200, Michal Koutný wrote:
> On Wed, May 28, 2025 at 06:48:37PM +0530, Vishal Chourasia <vishalc@linux.ibm.com> wrote:
> > The part that was confused me, was the meaning behind controller being
> > available vs. enabled in a cgroup.
> > 
> > Though, the documentation does mention what it means for a controller to
> > be enabled in a cgroup later in the text. But at the point of the
> > change it is unclear.
> 
> There's a picture [1] that may be more descriptive than the docs (on
> which it is based).
Thanks for the reference. 

I didn't get the part about "io controller enabling memory controller
too". Is it referring to the fact that multiple controller can work
together in a cgroup? Because, enabling just the io controller does not
automatically enable memory controller too.

Okay, what do you suggest, should I send out V2 taking corrections from
others?

Regards,
Vishal

> 
> HTH,
> Michal
> 
> [1] https://paste.opensuse.org/pastes/987b665209bb