[PATCH RESEND 0/3] Memory reclaim documentation fixes

[PATCH RESEND 0/3] Memory reclaim documentation fixes

[Michal Koutný]

I think the reclaim target is a concept that is not just an
implementation detail and hence it should be documented how it applies
to protection configuration (the first patch). Second patch is a "best
practice" bit of information, it may be squashed with the first one. The
last patch just makes docs indefinite until the idea is implemented.

Originally sent in [1], this is rebased and resent since I still think
it'd be good to have the concept somewhere documented. (E.g. for the
guys who are implementing protection for the dmem controller [2] to
arrive at similar behavior.)

[1] https://lore.kernel.org/lkml/20200729140537.13345-1-mkoutny@suse.com/
[2] https://lore.kernel.org/r/20251110-dmemcg-aggressive-protect-v3-5-219ffcfc54e9@gmx.de

Michal Koutný (3):
  docs: cgroup: Explain reclaim protection target
  docs: cgroup: Note about sibling relative reclaim protection
  docs: cgroup: No special handling of unpopulated memcgs

 Documentation/admin-guide/cgroup-v2.rst | 31 ++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 6 deletions(-)


base-commit: 1c353dc8d962de652bc7ad2ba2e63f553331391c
-- 
2.51.1

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

[Michal Koutný]

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

[Jonathan Corbet]

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

[Michal Koutný]

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

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/

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

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

[Tejun Heo]

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

[PATCH RESEND 2/3] docs: cgroup: Note about sibling relative reclaim protection

[Michal Koutný]

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

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index a6def773a3072..be3d805a929ef 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1952,6 +1952,10 @@ 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).
 
+To express indifference about relative sibling protection, it is suggested to
+use memory_recursiveprot. Configuring all descendants of a parent with finite
+protection to "max" works but it may unnecessarily skew memory.events:low
+field.
 
 Memory Ownership
 ~~~~~~~~~~~~~~~~
-- 
2.51.1

[PATCH RESEND 3/3] docs: cgroup: No special handling of unpopulated memcgs

[Michal Koutný]

The current kernel doesn't handle unpopulated cgroups any special
regarding reclaim protection. Furthermore, this wasn't a case even when
this was introduced in
    bf8d5d52ffe89 ("memcg: introduce memory.min")
Drop the incorrect documentation. (Implementation taking into account
the inner-node constraint may be added later.)

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

diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index be3d805a929ef..84985bb20c452 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1327,9 +1327,6 @@ PAGE_SIZE multiple when read back.
 	Putting more memory than generally available under this
 	protection is discouraged and may lead to constant OOMs.
 
-	If a memory cgroup is not populated with processes,
-	its memory.min is ignored.
-
   memory.low
 	A read-write single value file which exists on non-root
 	cgroups.  The default is "0".
-- 
2.51.1