[PATCH v2 0/2] Docs/admin-guide/mm/damon/reclaim: improve language

[PATCH v2 0/2] Docs/admin-guide/mm/damon/reclaim: improve language

[Manuel Ebner]

I went through the mails and divided the diffs and suggestions into
two patches. That's why some changes of [PATCH 1] get deleted or
written over in [PATCH 2].

I keept lines with barely over 80 chars and didn't fix wrong upper-case
in headings. I prefer uppercase Nouns(sic).

@SJ
I hope I got everything. If you have the urge to change or add anything
feel free to do so.

[v2]
 Include suggestions from SJ and Aveline
 Split [v1] into
  [1/2 v2] Docs/admin-guide/mm/damon/reclaim: improve grammar and style
  [2/2 v2] Docs/admin-guide/mm/damon/reclaim: rewrite complex parts
 Fixed an upper case and a missing double space -> [1/2 v2]

[v1]
 https://lore.kernel.org/all/20261015080623.808458-2-manuelebnerli@mailbox.org/

[PATCH v2 1/2] Docs/admin-guide/mm/damon/reclaim: improve grammar and style

[Manuel Ebner]

Fix upper case. Fix tenses. Replace 'set as' with 'set to'. Add space after
sentence to make it double space.

Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
CC: Aveline Noir <jm5905938@gmail.com>
---
@ -113,8 +113,8
Choose as you wish.

@ 20
should be:
-Free Pages Reporting [3]_ based
+Free pages reporting [3]_ based
or
+'*Free Pages Reporting'* [3]_ based
* the right kind of quoting/ kernel-doc highlighting.
Choose as you wish.
---
 .../admin-guide/mm/damon/reclaim.rst          | 36 +++++++++----------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst
index e4e2ffa52e..0bab2299ea 100644
--- a/Documentation/admin-guide/mm/damon/reclaim.rst
+++ b/Documentation/admin-guide/mm/damon/reclaim.rst
@@ -4,7 +4,7 @@
 DAMON-based Reclamation
 =======================
 
-DAMON-based Reclamation (DAMON_RECLAIM) is a static kernel module that aimed to
+DAMON-based reclamation (DAMON_RECLAIM) is a static kernel module that aimes to
 be used for proactive and lightweight reclamation under light memory pressure.
 It doesn't aim to replace the LRU-list based page_granularity reclamation, but
 to be selectively used for different level of memory pressure and requirements.
@@ -30,12 +30,12 @@ guests could mitigate this problem.
 How It Works?
 =============
 
-DAMON_RECLAIM finds memory regions that didn't accessed for specific time
+DAMON_RECLAIM finds memory regions that weren't accessed for specific time
 duration and page out.  To avoid it consuming too much CPU for the paging out
 operation, a speed limit can be configured.  Under the speed limit, it pages
-out memory regions that didn't accessed longer time first.  System
+out memory regions that weren't accessed longer time first.  System
 administrators can also configure under what situation this scheme should
-automatically activated and deactivated with three memory pressure watermarks.
+automatically be activated and deactivated with three memory pressure watermarks.
 
 Interface: Module Parameters
 ============================
@@ -55,10 +55,10 @@ enabled
 
 Enable or disable DAMON_RECLAIM.
 
-You can enable DAMON_RECLAIM by setting the value of this parameter as ``Y``.
-Setting it as ``N`` disables DAMON_RECLAIM.  Note that DAMON_RECLAIM could do
+You can enable DAMON_RECLAIM by setting the value of this parameter to ``Y``.
+Setting it to ``N`` disables DAMON_RECLAIM.  Note that DAMON_RECLAIM could do
 no real monitoring and reclamation due to the watermarks-based activation
-condition.  Refer to below descriptions for the watermarks parameter for this.
+condition.  Refer to below descriptions of the watermarks parameter for this.
 
 commit_inputs
 -------------
@@ -66,9 +66,9 @@ commit_inputs
 Make DAMON_RECLAIM reads the input parameters again, except ``enabled``.
 
 Input parameters that updated while DAMON_RECLAIM is running are not applied
-by default.  Once this parameter is set as ``Y``, DAMON_RECLAIM reads values
+by default.  Once this parameter is set to ``Y``, DAMON_RECLAIM reads values
 of parameters except ``enabled`` again.  Once the re-reading is done, this
-parameter is set as ``N``.  If invalid parameters are found while the
+parameter is set to ``N``.  If invalid parameters are found while the
 re-reading, DAMON_RECLAIM will be disabled.
 
 Once ``Y`` is written to this parameter, the user must not write to any
@@ -88,7 +88,7 @@ identifies the region as cold, and reclaims it.
 autotune_monitoring_intervals
 -----------------------------
 
-If this parameter is set as ``Y``, DAMON_RECLAIM automatically tunes DAMON's
+If this parameter is set to ``Y``, DAMON_RECLAIM automatically tunes DAMON's
 sampling and aggregation intervals.  The auto-tuning aims to capture meaningful
 amount of access events in each DAMON-snapshot, while keeping the sampling
 interval 5 milliseconds in minimum, and 10 seconds in maximum.  Setting this as
@@ -113,10 +113,10 @@ quota_sz
 
 Limit of size of memory for the reclamation in bytes.
 
-DAMON_RECLAIM charges amount of memory which it tried to reclaim within a time
-window (quota_reset_interval_ms) and makes no more than this limit is tried.
-This can be used for limiting consumption of CPU and IO.  If this value is
-zero, the limit is disabled.
+DAMON_RECLAIM records the amount of memory which it tried to reclaim within a time
+window (quota_reset_interval_ms) and stops trying to reclaim memory when this limit
+is reached.  This can be used for limiting consumption of CPU and IO.  If this value
+is zero, the limit is disabled.
 
 128 MiB by default.
 
@@ -137,7 +137,7 @@ quota_mem_pressure_us
 
 Desired level of memory pressure-stall time in microseconds.
 
-While keeping the caps that set by other quotas, DAMON_RECLAIM automatically
+While keeping the caps that are set by other quotas, DAMON_RECLAIM automatically
 increases and decreases the effective level of the quota aiming this level of
 memory pressure is incurred.  System-wide ``some`` memory PSI in microseconds
 per quota reset interval (``quota_reset_interval_ms``) is collected and
@@ -219,7 +219,7 @@ monitoring.  This can be used to set lower-bound of the monitoring quality.
 But, setting this too high could result in increased monitoring overhead.
 Please refer to the DAMON documentation (:doc:`usage`) for more detail.
 
-Note that this must be 3 or higher. Please refer to the :ref:`Monitoring
+Note that this must be 3 or higher.  Please refer to the :ref:`Monitoring
 <damon_design_monitoring>` section of the design document for the rationale
 behind this lower bound.
 
@@ -263,7 +263,7 @@ This parameter is for setting and getting the :ref:`address unit
 
 ``monitor_region_start`` and ``monitor_region_end`` should be provided in this
 unit.  For example, let's suppose ``addr_unit``, ``monitor_region_start`` and
-``monitor_region_end`` are set as ``1024``, ``0`` and ``10``, respectively.
+``monitor_region_end`` are set to ``1024``, ``0`` and ``10``, respectively.
 Then DAMON_RECLAIM will work for 10 KiB length of physical address range that
 starts from address zero (``[0 * 1024, 10 * 1024)`` in bytes).
 
@@ -280,7 +280,7 @@ skip_anon
 
 Skip anonymous pages reclamation.
 
-If this parameter is set as ``Y``, DAMON_RECLAIM does not reclaim anonymous
+If this parameter is set to ``Y``, DAMON_RECLAIM does not reclaim anonymous
 pages.  By default, ``N``.
 
 
-- 
2.55.0

Re: [PATCH v2 1/2] Docs/admin-guide/mm/damon/reclaim: improve grammar and style

[SJ Park]

On Tue, 27 Oct 2026 20:05:04 +0100 Manuel Ebner <manuelebnerli@mailbox.org> wrote:

> Fix upper case. Fix tenses. Replace 'set as' with 'set to'. Add space after
> sentence to make it double space.
> 
> Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
> CC: Aveline Noir <jm5905938@gmail.com>
> ---
> @ -113,8 +113,8
> Choose as you wish.
> 
> @ 20
> should be:
> -Free Pages Reporting [3]_ based
> +Free pages reporting [3]_ based
> or
> +'*Free Pages Reporting'* [3]_ based
> * the right kind of quoting/ kernel-doc highlighting.
> Choose as you wish.
> ---
>  .../admin-guide/mm/damon/reclaim.rst          | 36 +++++++++----------
>  1 file changed, 18 insertions(+), 18 deletions(-)
> 
> diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst
> index e4e2ffa52e..0bab2299ea 100644
> --- a/Documentation/admin-guide/mm/damon/reclaim.rst
> +++ b/Documentation/admin-guide/mm/damon/reclaim.rst
[...]
> @@ -30,12 +30,12 @@ guests could mitigate this problem.
>  How It Works?
>  =============
>  
> -DAMON_RECLAIM finds memory regions that didn't accessed for specific time
> +DAMON_RECLAIM finds memory regions that weren't accessed for specific time
>  duration and page out.  To avoid it consuming too much CPU for the paging out
>  operation, a speed limit can be configured.  Under the speed limit, it pages
> -out memory regions that didn't accessed longer time first.  System
> +out memory regions that weren't accessed longer time first.  System
>  administrators can also configure under what situation this scheme should
> -automatically activated and deactivated with three memory pressure watermarks.
> +automatically be activated and deactivated with three memory pressure watermarks.

Let's keep 80 columns limit.  Same for below.

[...]
> @@ -113,10 +113,10 @@ quota_sz
>  
>  Limit of size of memory for the reclamation in bytes.
>  
> -DAMON_RECLAIM charges amount of memory which it tried to reclaim within a time
> -window (quota_reset_interval_ms) and makes no more than this limit is tried.
> -This can be used for limiting consumption of CPU and IO.  If this value is
> -zero, the limit is disabled.
> +DAMON_RECLAIM records the amount of memory which it tried to reclaim within a time

Didn't we agree to keep use "charge" ?

Other than the above two things, looks good to me.


Thanks,
SJ

[...]

[PATCH v2 2/2] Docs/admin-guide/mm/damon/reclaim: rewrite complex parts

[Manuel Ebner]

Rewrite and refine complex sentences.

Suggested-by: Aveline Noir <jm5905938@gmail.com>
Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
---
 Documentation/admin-guide/mm/damon/reclaim.rst | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst
index 0bab2299ea..a18c8e2165 100644
--- a/Documentation/admin-guide/mm/damon/reclaim.rst
+++ b/Documentation/admin-guide/mm/damon/reclaim.rst
@@ -30,12 +30,13 @@ guests could mitigate this problem.
 How It Works?
 =============
 
-DAMON_RECLAIM finds memory regions that weren't accessed for specific time
-duration and page out.  To avoid it consuming too much CPU for the paging out
-operation, a speed limit can be configured.  Under the speed limit, it pages
-out memory regions that weren't accessed longer time first.  System
-administrators can also configure under what situation this scheme should
-automatically be activated and deactivated with three memory pressure watermarks.
+DAMON_RECLAIM identifies memory regions that have not been accessed for a
+specified period and attempts to pages out those.  To avoid it consuming
+too much CPU for the paging out operation, a speed limit can be configured.
+Within the configured speed limit, it prioritizes regions that have been
+idle longer for reclamation.  System administrators can also configure under
+what situation this scheme should automatically be activated and deactivated
+with three memory pressure watermarks.
 
 Interface: Module Parameters
 ============================
@@ -137,7 +138,7 @@ quota_mem_pressure_us
 
 Desired level of memory pressure-stall time in microseconds.
 
-While keeping the caps that are set by other quotas, DAMON_RECLAIM automatically
+While respecting the limits imposed by other quotas, DAMON_RECLAIM automatically
 increases and decreases the effective level of the quota aiming this level of
 memory pressure is incurred.  System-wide ``some`` memory PSI in microseconds
 per quota reset interval (``quota_reset_interval_ms``) is collected and
-- 
2.55.0

Re: [PATCH v2 2/2] Docs/admin-guide/mm/damon/reclaim: rewrite complex parts

[SJ Park]

Hello Manuel,


Seems you sent a new version [1] of this?  I will skip reviewing this.

[1] https://lore.kernel.org/20261027212345.2586628-2-manuelebnerli@mailbox.org


Thanks,
SJ

[...]

[PATCH v2 2/2] Docs/admin-guide/mm/damon/reclaim: rewrite complex parts

[Manuel Ebner]

Rewrite complex sentences.

Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
Suggested-by: Aveline Noir <jm5905938@gmail.com>
---
Two more minor changes
@ 31
/s/attempts to pages out those/attempts to page out those/
@ 126
+ 'is' to fix grammar

 .../admin-guide/mm/damon/reclaim.rst          | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst
index 0bab2299ea..033686f410 100644
--- a/Documentation/admin-guide/mm/damon/reclaim.rst
+++ b/Documentation/admin-guide/mm/damon/reclaim.rst
@@ -30,12 +30,13 @@ guests could mitigate this problem.
 How It Works?
 =============
 
-DAMON_RECLAIM finds memory regions that weren't accessed for specific time
-duration and page out.  To avoid it consuming too much CPU for the paging out
-operation, a speed limit can be configured.  Under the speed limit, it pages
-out memory regions that weren't accessed longer time first.  System
-administrators can also configure under what situation this scheme should
-automatically be activated and deactivated with three memory pressure watermarks.
+DAMON_RECLAIM identifies memory regions that have not been accessed for a
+specified period and attempts to page out those.  To avoid it consuming
+too much CPU for the paging out operation, a speed limit can be configured.
+Within the configured speed limit, it prioritizes regions that have been
+idle longer for reclamation.  System administrators can also configure under
+what situation this scheme should automatically be activated and deactivated
+with three memory pressure watermarks.
 
 Interface: Module Parameters
 ============================
@@ -125,8 +126,8 @@ quota_reset_interval_ms
 
 The time/size quota charge reset interval in milliseconds.
 
-The charge reset interval for the quota of time (quota_ms) and size
-(quota_sz).  That is, DAMON_RECLAIM does not try reclamation for more than
+The charge reset interval for the quota of time is quota_ms and for the quota of
+size is quota_sz.  That is, DAMON_RECLAIM does not try reclamation for more than
 quota_ms milliseconds or quota_sz bytes within quota_reset_interval_ms
 milliseconds.
 
@@ -137,7 +138,7 @@ quota_mem_pressure_us
 
 Desired level of memory pressure-stall time in microseconds.
 
-While keeping the caps that are set by other quotas, DAMON_RECLAIM automatically
+While respecting the limits imposed by other quotas, DAMON_RECLAIM automatically
 increases and decreases the effective level of the quota aiming this level of
 memory pressure is incurred.  System-wide ``some`` memory PSI in microseconds
 per quota reset interval (``quota_reset_interval_ms``) is collected and
-- 
2.55.0

Re: [PATCH v2 2/2] Docs/admin-guide/mm/damon/reclaim: rewrite complex parts

[SJ Park]

Hello Manuel,


On Tue, 27 Oct 2026 22:23:46 +0100 Manuel Ebner <manuelebnerli@mailbox.org> wrote:

> Rewrite complex sentences.

Any special reason to keep this as a separated one?  I think it is ok to merge
this into the first patch.

> 
> Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
> Suggested-by: Aveline Noir <jm5905938@gmail.com>
> ---
> Two more minor changes
> @ 31
> /s/attempts to pages out those/attempts to page out those/
> @ 126
> + 'is' to fix grammar
> 
>  .../admin-guide/mm/damon/reclaim.rst          | 19 ++++++++++---------
>  1 file changed, 10 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst
> index 0bab2299ea..033686f410 100644
> --- a/Documentation/admin-guide/mm/damon/reclaim.rst
> +++ b/Documentation/admin-guide/mm/damon/reclaim.rst
> @@ -30,12 +30,13 @@ guests could mitigate this problem.
>  How It Works?
>  =============
>  
> -DAMON_RECLAIM finds memory regions that weren't accessed for specific time
> -duration and page out.  To avoid it consuming too much CPU for the paging out
> -operation, a speed limit can be configured.  Under the speed limit, it pages
> -out memory regions that weren't accessed longer time first.  System
> -administrators can also configure under what situation this scheme should
> -automatically be activated and deactivated with three memory pressure watermarks.
> +DAMON_RECLAIM identifies memory regions that have not been accessed for a
> +specified period and attempts to page out those.  To avoid it consuming
> +too much CPU for the paging out operation, a speed limit can be configured.
> +Within the configured speed limit, it prioritizes regions that have been
> +idle longer for reclamation.  System administrators can also configure under
> +what situation this scheme should automatically be activated and deactivated
> +with three memory pressure watermarks.
>  
>  Interface: Module Parameters
>  ============================
> @@ -125,8 +126,8 @@ quota_reset_interval_ms
>  
>  The time/size quota charge reset interval in milliseconds.
>  
> -The charge reset interval for the quota of time (quota_ms) and size
> -(quota_sz).  That is, DAMON_RECLAIM does not try reclamation for more than
> +The charge reset interval for the quota of time is quota_ms and for the quota of
> +size is quota_sz.  That is, DAMON_RECLAIM does not try reclamation for more than
>  quota_ms milliseconds or quota_sz bytes within quota_reset_interval_ms
>  milliseconds.

I think the original sentence was not that confusing.  Also, this changes the
nuance of the sentence?  What the sentence is saying is
"quota_reset_interval_ms is the charge reset interval for ...".  If this was
really confusing, maybe we can add "quota_reset_interval_ms is " part.

But, I start feeling we might trying too much polishing...?

>  
> @@ -137,7 +138,7 @@ quota_mem_pressure_us
>  
>  Desired level of memory pressure-stall time in microseconds.
>  
> -While keeping the caps that are set by other quotas, DAMON_RECLAIM automatically
> +While respecting the limits imposed by other quotas, DAMON_RECLAIM automatically
>  increases and decreases the effective level of the quota aiming this level of
>  memory pressure is incurred.  System-wide ``some`` memory PSI in microseconds
>  per quota reset interval (``quota_reset_interval_ms``) is collected and

I'm not sure if the original sentence was really difficult to understand.

I'd prefer dropping this change.


Thanks,
SJ

[...]