[PATCH] mm/damon/reclaim: improve grammar and style

[PATCH] mm/damon/reclaim: improve grammar and style

[Manuel Ebner]

Fix tenses. Replace 'set as' with 'set to'.
Rewrite complex sentences.

Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
---
@@ -113,8 +113,8 and
@@ -125,19 +125,19
This sentence was difficult to read for me. I don't know if I
improved it. Please advice.
---
 .../admin-guide/mm/damon/reclaim.rst          | 40 +++++++++----------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst
index e4e2ffa52e..d521563633 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 aims 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,11 +88,11 @@ 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
-``N`` disables the auto-tuning.
+interval to 5 milliseconds in minimum, and to 10 seconds in maximum.  Setting this
+to ``N`` disables the auto-tuning.
 
 Disabled by default.
 
@@ -113,8 +113,8 @@ 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.
+DAMON_RECLAIM recordes the amount of memory which it tried to reclaim within a time
+window (quota_reset_interval_ms) and stops when this memory limit is reached.
 This can be used for limiting consumption of CPU and IO.  If this value is
 zero, the limit is disabled.
 
@@ -125,19 +125,19 @@ 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 quota reset interval of time is quota_ms and 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.
 
-1 second by default.
+1000 (1 second) by default.
 
 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 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
@@ -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] mm/damon/reclaim: improve grammar and style

[SJ Park]

On Thu, 15 Oct 2026 10:06:23 +0200 Manuel Ebner <manuelebnerli@mailbox.org> wrote:

> Fix tenses. Replace 'set as' with 'set to'.
> Rewrite complex sentences.

Let's put two sentences in one line, while breaking it for the 75 column limit.

[...]
> @@ -113,8 +113,8 @@ 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.
> +DAMON_RECLAIM recordes the amount of memory which it tried to reclaim within a time

s/recordes/charges/  or s/recordes/records/ ?

I'd prefer charges, but my English is definitely bad, so looking for your
suggestion.

> +window (quota_reset_interval_ms) and stops when this memory limit is reached.

I feel like readers might wonder what is stopped.  How about "stops trying
reclaiming memory when ..." ?

>  This can be used for limiting consumption of CPU and IO.  If this value is
>  zero, the limit is disabled.
>  
> @@ -125,19 +125,19 @@ 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 quota reset interval of time is quota_ms and of size is
> +quota_sz.  That is, DAMON_RECLAIM does not try reclamation for more than

I think this change is just wrong?  quota_ms is not quota reset interval of
time.  Which part of the original sentence was difficult to read?

>  quota_ms milliseconds or quota_sz bytes within quota_reset_interval_ms
>  milliseconds.
>  
> -1 second by default.
> +1000 (1 second) by default.

Isn't this (1 second in milliseconds is 1,000) easy enough to infer for
readers?

>  
>  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 set by other quotas, DAMON_RECLAIM automatically

How about "caps that are set by ..." ?

>  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


Thanks,
SJ

[...]

Re: [PATCH] mm/damon/reclaim: improve grammar and style

[Aveline Noir]

Hi Manuel,

A few suggestions from my view for you here :)

On Thu, 15 Oct 2026 10:06:23 +0200, Manuel Ebner wrote:

> @@ -30,12 +30,12 @@ guests could mitigate this problem.
> -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

"weren't accessed" fixes the grammar, but "page out" still doesn't
agree with the subject. How about "DAMON_RECLAIM identifies memory
regions that have not been accessed for a specified period and
attempts to reclaim their pages.".

>  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

"weren't accessed longer time first" sounds a little strange to me.
Maybe "Within the configured speed limit, it prioritizes regions
that have been idle longer for reclamation." would read better?

> @@ -88,11 +88,11 @@ identifies the region as cold, and reclaims it.
>  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
> -``N`` disables the auto-tuning.
> +interval to 5 milliseconds in minimum, and to 10 seconds in maximum. Setting this
> +to ``N`` disables the auto-tuning.

Maybe "between 5 milliseconds and 10 seconds" would read more
naturally here.

> @@ -113,8 +113,8 @@ 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.
> +DAMON_RECLAIM recordes the amount of memory which it tried to reclaim within a time
> +window (quota_reset_interval_ms) and stops when this memory limit is reached.

Agree with SJ that "charges" fits better here, since this is quota
accounting. 

> -While keeping the caps that set by other quotas, DAMON_RECLAIM automatically
> +While keeping the caps set by other quotas, DAMON_RECLAIM automatically
>  increases and decreases the effective level of the quota aiming this level of
>  memory pressure is incurred.

Maybe "While respecting the limits imposed by other quotas," would
be another option I think.

Thanks,
Aveline

Re: [PATCH] mm/damon/reclaim: improve grammar and style

[SJ Park]

On Fri, 16 Oct 2026 20:34:51 +0800 Aveline Noir <jm5905938@gmail.com> wrote:

> Hi Manuel,
> 
> A few suggestions from my view for you here :)
> 
> On Thu, 15 Oct 2026 10:06:23 +0200, Manuel Ebner wrote:
> 
> > @@ -30,12 +30,12 @@ guests could mitigate this problem.
> > -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
> 
> "weren't accessed" fixes the grammar, but "page out" still doesn't
> agree with the subject. How about "DAMON_RECLAIM identifies memory
> regions that have not been accessed for a specified period and
> attempts to reclaim their pages.".

That's entire sentence rewriting.  We could consider doing that, but maybe
that's better to be done via another patch.  Let's focus on simple grammar and
style in this patch.

How about simply 's/page out/pages out those/'?

> 
> >  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
> 
> "weren't accessed longer time first" sounds a little strange to me.
> Maybe "Within the configured speed limit, it prioritizes regions
> that have been idle longer for reclamation." would read better?

Let's do such rewriting with another patch.

> 
> > @@ -88,11 +88,11 @@ identifies the region as cold, and reclaims it.
> >  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
> > -``N`` disables the auto-tuning.
> > +interval to 5 milliseconds in minimum, and to 10 seconds in maximum. Setting this
> > +to ``N`` disables the auto-tuning.
> 
> Maybe "between 5 milliseconds and 10 seconds" would read more
> naturally here.

I concern if readers could confuse if the range is inclusive or exclusive.  I'd
prefer the current sentence.

> 
> > @@ -113,8 +113,8 @@ 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.
> > +DAMON_RECLAIM recordes the amount of memory which it tried to reclaim within a time
> > +window (quota_reset_interval_ms) and stops when this memory limit is reached.
> 
> Agree with SJ that "charges" fits better here, since this is quota
> accounting. 

Makes sense to me.  What do you think, Manuel?

> 
> > -While keeping the caps that set by other quotas, DAMON_RECLAIM automatically
> > +While keeping the caps set by other quotas, DAMON_RECLAIM automatically
> >  increases and decreases the effective level of the quota aiming this level of
> >  memory pressure is incurred.
> 
> Maybe "While respecting the limits imposed by other quotas," would
> be another option I think.

I feel like that's out of the scope of this patch.

If both of you agree to my abovely suggested/agreed changes ('s/page out/ pages
out those/' and 's/records/charges/'), I will update this patch in damon/next
tree with those changes.


Thanks,
SJ

[...]

Re: [PATCH] mm/damon/reclaim: improve grammar and style

[Aveline Noir]

Hi SJ,

On Fri, 16 Oct 2026 07:29:21 -0700, SJ Park wrote:

> If both of you agree to my abovely suggested/agreed changes ('s/page out/ pages
> out those/' and 's/records/charges/'), I will update this patch in damon/next
> tree with those changes.

Both changes sound good to me. Keeping this patch focused makes sense.

Thx for taking a look :)

Aveline