1. Patchew
  2. linux
  3. [PATCH RESEND 0/3] Memory reclaim documentation fixes
  4. View patch

[PATCH RESEND 1/3] docs: cgroup: Explain reclaim protection target

Michal Koutný posted 3 patches 3 months ago
There is a newer version of this series
[PATCH RESEND 1/3] docs: cgroup: Explain reclaim protection target
Posted by Michal Koutný 3 months ago 
The protection target is necessary to understand how effective reclaim
protection applies in the hierarchy.

Signed-off-by: Michal Koutný <mkoutny@suse.com>
---
 Documentation/admin-guide/cgroup-v2.rst | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 0e6c67ac585a0..a6def773a3072 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -53,7 +53,8 @@ v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgrou
      5-2. Memory
        5-2-1. Memory Interface Files
        5-2-2. Usage Guidelines
-       5-2-3. Memory Ownership
+       5-2-3. Reclaim Protection
+       5-2-4. Memory Ownership
      5-3. IO
        5-3-1. IO Interface Files
        5-3-2. Writeback
@@ -1317,7 +1318,7 @@ PAGE_SIZE multiple when read back.
 	smaller overages.
 
 	Effective min boundary is limited by memory.min values of
-	all ancestor cgroups. If there is memory.min overcommitment
+	ancestor cgroups. If there is memory.min overcommitment
 	(child cgroup or cgroups are requiring more protected memory
 	than parent will allow), then each child cgroup will get
 	the part of parent's protection proportional to its
@@ -1343,7 +1344,7 @@ PAGE_SIZE multiple when read back.
 	smaller overages.
 
 	Effective low boundary is limited by memory.low values of
-	all ancestor cgroups. If there is memory.low overcommitment
+	ancestor cgroups. If there is memory.low overcommitment
 	(child cgroup or cgroups are requiring more protected memory
 	than parent will allow), then each child cgroup will get
 	the part of parent's protection proportional to its
@@ -1934,6 +1935,23 @@ memory - is necessary to determine whether a workload needs more
 memory; unfortunately, memory pressure monitoring mechanism isn't
 implemented yet.
 
+Reclaim Protection
+~~~~~~~~~~~~~~~~~~
+
+The protection configured with "memory.low" or "memory.min" applies relatively
+to the target of the reclaim (i.e. any of memory cgroup limits, proactive
+memory.reclaim or global reclaim apparently located in the root cgroup).
+
+  root ... - A - B - C
+              \    ` D
+               ` E
+
+The protection value configured for B applies unchanged to the reclaim
+targeting A (i.e. caused by competition with the sibling E).  When the reclaim
+targets ancestors of A, the effective protection of B is capped by the
+protection value configured for A (and any other intermediate ancestors between
+A and the target).
+
 
 Memory Ownership
 ~~~~~~~~~~~~~~~~
-- 
2.51.1
Re: [PATCH RESEND 1/3] docs: cgroup: Explain reclaim protection target
Posted by Jonathan Corbet 3 months ago 
Michal Koutný <mkoutny@suse.com> writes:

> The protection target is necessary to understand how effective reclaim
> protection applies in the hierarchy.
>
> Signed-off-by: Michal Koutný <mkoutny@suse.com>
> ---
>  Documentation/admin-guide/cgroup-v2.rst | 24 +++++++++++++++++++++---
>  1 file changed, 21 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
> index 0e6c67ac585a0..a6def773a3072 100644
> --- a/Documentation/admin-guide/cgroup-v2.rst
> +++ b/Documentation/admin-guide/cgroup-v2.rst
> @@ -53,7 +53,8 @@ v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgrou
>       5-2. Memory
>         5-2-1. Memory Interface Files
>         5-2-2. Usage Guidelines
> -       5-2-3. Memory Ownership
> +       5-2-3. Reclaim Protection
> +       5-2-4. Memory Ownership

I always have to ask...do we really need the manually maintained TOC
here? 

>       5-3. IO
>         5-3-1. IO Interface Files
>         5-3-2. Writeback
> @@ -1317,7 +1318,7 @@ PAGE_SIZE multiple when read back.
>  	smaller overages.
>  
>  	Effective min boundary is limited by memory.min values of
> -	all ancestor cgroups. If there is memory.min overcommitment
> +	ancestor cgroups. If there is memory.min overcommitment
>  	(child cgroup or cgroups are requiring more protected memory
>  	than parent will allow), then each child cgroup will get
>  	the part of parent's protection proportional to its
> @@ -1343,7 +1344,7 @@ PAGE_SIZE multiple when read back.
>  	smaller overages.
>  
>  	Effective low boundary is limited by memory.low values of
> -	all ancestor cgroups. If there is memory.low overcommitment
> +	ancestor cgroups. If there is memory.low overcommitment
>  	(child cgroup or cgroups are requiring more protected memory
>  	than parent will allow), then each child cgroup will get
>  	the part of parent's protection proportional to its
> @@ -1934,6 +1935,23 @@ memory - is necessary to determine whether a workload needs more
>  memory; unfortunately, memory pressure monitoring mechanism isn't
>  implemented yet.
>  
> +Reclaim Protection
> +~~~~~~~~~~~~~~~~~~
> +
> +The protection configured with "memory.low" or "memory.min" applies relatively
> +to the target of the reclaim (i.e. any of memory cgroup limits, proactive
> +memory.reclaim or global reclaim apparently located in the root cgroup).
> +
> +  root ... - A - B - C
> +              \    ` D
> +               ` E

This will not render properly, you want it in a literal block.  The
easiest way is to just make the line above read:

   ...located in the root cgroup)::

Thanks,

jon
Re: [PATCH RESEND 1/3] docs: cgroup: Explain reclaim protection target
Posted by Michal Koutný 2 months, 3 weeks ago 
On Mon, Nov 10, 2025 at 01:00:41PM -0700, Jonathan Corbet <corbet@lwn.net> wrote:
> > @@ -53,7 +53,8 @@ v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgrou
> >       5-2. Memory
> >         5-2-1. Memory Interface Files
> >         5-2-2. Usage Guidelines
> > -       5-2-3. Memory Ownership
> > +       5-2-3. Reclaim Protection
> > +       5-2-4. Memory Ownership
> 
> I always have to ask...do we really need the manually maintained TOC
> here? 

Tejun [1] (and maybe some others) like it.

Thanks,
Michal

[1] https://lore.kernel.org/r/aMwo-IW35bsdc1BM@slm.duckdns.org/
Re: [PATCH RESEND 1/3] docs: cgroup: Explain reclaim protection target
Posted by Tejun Heo 2 months, 3 weeks ago 
On Fri, Nov 14, 2025 at 07:29:28PM +0100, Michal Koutný wrote:
> On Mon, Nov 10, 2025 at 01:00:41PM -0700, Jonathan Corbet <corbet@lwn.net> wrote:
> > > @@ -53,7 +53,8 @@ v1 is available under :ref:`Documentation/admin-guide/cgroup-v1/index.rst <cgrou
> > >       5-2. Memory
> > >         5-2-1. Memory Interface Files
> > >         5-2-2. Usage Guidelines
> > > -       5-2-3. Memory Ownership
> > > +       5-2-3. Reclaim Protection
> > > +       5-2-4. Memory Ownership
> > 
> > I always have to ask...do we really need the manually maintained TOC
> > here? 
> 
> Tejun [1] (and maybe some others) like it.

I'm not married to it but I think a lot of people including me just read the
source docs without ever formatting them. It is kinda nice to have ToC for
them. Maybe section numbers are too error-prone, I don't know.

Thanks.

-- 
tejun

Patchew 2.1-devel-b67e4c2

© 2016 - 2026 Red Hat, Inc.