[PATCH] Docs/admin-guide/mm/damon/lru_sort: fix grammar and stlye

[PATCH] Docs/admin-guide/mm/damon/lru_sort: fix grammar and stlye

[Manuel Ebner]

mention 'least-recently-used' AKA lru at the beginning
set as -> set to

Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
---
 .../admin-guide/mm/damon/lru_sort.rst         | 51 ++++++++++---------
 1 file changed, 26 insertions(+), 25 deletions(-)

diff --git a/Documentation/admin-guide/mm/damon/lru_sort.rst b/Documentation/admin-guide/mm/damon/lru_sort.rst
index 0c04d238ed..3b6d122887 100644
--- a/Documentation/admin-guide/mm/damon/lru_sort.rst
+++ b/Documentation/admin-guide/mm/damon/lru_sort.rst
@@ -4,8 +4,9 @@
 DAMON-based LRU-lists Sorting
 =============================
 
-DAMON-based LRU-lists Sorting (DAMON_LRU_SORT) is a static kernel module that
-aimed to be used for proactive and lightweight data access pattern based
+DAMON-based least-recently-used-lists (short LRU-lists) Sorting
+(DAMON_LRU_SORT) is a static kernel module that aims to be used
+for proactive and lightweight data access pattern based
 (de)prioritization of pages on their LRU-lists for making LRU-lists a more
 trustworthy data access pattern source.
 
@@ -17,7 +18,7 @@ systems, LRU lists are normally not proactively sorted but partially and
 reactively sorted for special events including specific user requests, system
 calls and memory pressure.  As a result, LRU lists are sometimes not so
 perfectly prepared to be used as a trustworthy access pattern source for some
-situations including reclamation target pages selection under sudden memory
+situations including reclamation of target pages selection under sudden memory
 pressure.
 
 Because DAMON can identify access patterns of best-effort accuracy while
@@ -28,9 +29,9 @@ pattern source with low and controlled overhead.
 How It Works?
 =============
 
-DAMON_LRU_SORT finds hot pages (pages of memory regions that showing access
+DAMON_LRU_SORT finds hot pages (pages of memory regions that show access
 rates that higher than a user-specified threshold) and cold pages (pages of
-memory regions that showing no access for a time that longer than a
+memory regions that show no access for a time that longer than a
 user-specified threshold) using DAMON, and prioritizes hot pages while
 deprioritizing cold pages on their LRU-lists.  To avoid it consuming too much
 CPU for the prioritizations, a CPU time usage limit can be configured.  Under
@@ -63,10 +64,10 @@ enabled
 
 Enable or disable DAMON_LRU_SORT.
 
-You can enable DAMON_LRU_SORT by setting the value of this parameter as ``Y``.
-Setting it as ``N`` disables DAMON_LRU_SORT.  Note that DAMON_LRU_SORT could do
+You can enable DAMON_LRU_SORT by setting the value of this parameter to ``Y``.
+Setting it to ``N`` disables DAMON_LRU_SORT.  Note that DAMON_LRU_SORT could do
 no real monitoring and LRU-lists sorting 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
 -------------
@@ -74,9 +75,9 @@ commit_inputs
 Make DAMON_LRU_SORT reads the input parameters again, except ``enabled``.
 
 Input parameters that updated while DAMON_LRU_SORT is running are not applied
-by default.  Once this parameter is set as ``Y``, DAMON_LRU_SORT reads values
+by default.  Once this parameter is set to ``Y``, DAMON_LRU_SORT 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_LRU_SORT will be disabled.
 
 Once ``Y`` is written to this parameter, the user must not write to any
@@ -86,37 +87,37 @@ violate this rule, the kernel may exhibit undefined behavior.
 active_mem_bp
 -------------
 
-Desired active to [in]active memory ratio in bp (1/10,000).
+Desired active to (in)active memory ratio in bp (1/10,000).
 
 While keeping the caps that set by other quotas, DAMON_LRU_SORT automatically
 increases and decreases the effective level of the quota aiming the LRU
-[de]prioritizations of the hot and cold memory resulting in this active to
-[in]active memory ratio.  Value zero means disabling this auto-tuning feature.
+(de)prioritizations of the hot and cold memory resulting in this active to
+(in)active memory ratio.  Value zero means disabling this auto-tuning feature.
 
 Disabled by default.
 
 autotune_monitoring_intervals
 -----------------------------
 
-If this parameter is set as ``Y``, DAMON_LRU_SORT automatically tunes DAMON's
+If this parameter is set to ``Y``, DAMON_LRU_SORT 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.
 
 filter_young_pages
 ------------------
 
-Filter [non-]young pages accordingly for LRU [de]prioritizations.
+Filter (non-)young pages accordingly for LRU (de)prioritizations.
 
 If this is set, check page level access (youngness) once again before each
-LRU [de]prioritization operation.  LRU prioritization operation is skipped
+LRU (de)prioritization operation.  LRU prioritization operation is skipped
 if the page has not accessed since the last check (not young).  LRU
 deprioritization operation is skipped if the page has accessed since the
 last check (young).  The feature is enabled or disabled if this parameter is
-set as ``Y`` or ``N``, respectively.
+set to ``Y`` or ``N``, respectively.
 
 Disabled by default.
 
@@ -235,7 +236,7 @@ max_nr_regions
 Maximum number of monitoring regions.
 
 The maximum number of monitoring regions of DAMON for the cold memory
-monitoring.  This can be used to set upper-bound of the monitoring overhead.
+monitoring.  This can be used to set the upper-bound of the monitoring overhead.
 However, setting this too low could result in bad monitoring quality.  Please
 refer to the DAMON documentation (:doc:`usage`) for more detail.  1000 by
 defaults.
@@ -268,7 +269,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_LRU_SORT will work for 10 KiB length of physical address range that
 starts from address zero (``[0 * 1024, 10 * 1024)`` in bytes).
 
@@ -291,22 +292,22 @@ If DAMON_LRU_SORT is enabled, this becomes the PID of the worker thread.  Else,
 nr_lru_sort_tried_hot_regions
 -----------------------------
 
-Number of hot memory regions that tried to be LRU-sorted.
+Number of hot memory regions that try to be LRU-sorted.
 
 bytes_lru_sort_tried_hot_regions
 --------------------------------
 
-Total bytes of hot memory regions that tried to be LRU-sorted.
+Total bytes of hot memory regions that try to be LRU-sorted.
 
 nr_lru_sorted_hot_regions
 -------------------------
 
-Number of hot memory regions that successfully be LRU-sorted.
+Number of hot memory regions that are successfully LRU-sorted.
 
 bytes_lru_sorted_hot_regions
 ----------------------------
 
-Total bytes of hot memory regions that successfully be LRU-sorted.
+Total bytes of hot memory regions that are successfully LRU-sorted.
 
 nr_hot_quota_exceeds
 --------------------
-- 
2.55.0

Re: [PATCH] Docs/admin-guide/mm/damon/lru_sort: fix grammar and stlye

[SJ Park]

Hi Manuel,

On Tue, 13 Oct 2026 21:13:27 +0200 Manuel Ebner <manuelebnerli@mailbox.org> wrote:

> mention 'least-recently-used' AKA lru at the beginning

I think the readers would know what LRU means, and therefore
'least-recently-used' is not needed.

> set as -> set to

This commit message is using incomplete sentences and describing only a few of
changes.  Please make it to use complete sentences and cover all changes.

> 
> Signed-off-by: Manuel Ebner <manuelebnerli@mailbox.org>
> ---
>  .../admin-guide/mm/damon/lru_sort.rst         | 51 ++++++++++---------
>  1 file changed, 26 insertions(+), 25 deletions(-)
> 
> diff --git a/Documentation/admin-guide/mm/damon/lru_sort.rst b/Documentation/admin-guide/mm/damon/lru_sort.rst
> index 0c04d238ed..3b6d122887 100644
> --- a/Documentation/admin-guide/mm/damon/lru_sort.rst
> +++ b/Documentation/admin-guide/mm/damon/lru_sort.rst
> @@ -4,8 +4,9 @@
>  DAMON-based LRU-lists Sorting
>  =============================
>  
> -DAMON-based LRU-lists Sorting (DAMON_LRU_SORT) is a static kernel module that
> -aimed to be used for proactive and lightweight data access pattern based
> +DAMON-based least-recently-used-lists (short LRU-lists) Sorting
> +(DAMON_LRU_SORT) is a static kernel module that aims to be used
> +for proactive and lightweight data access pattern based

As I mentioned above, I don't think the above change is needed.

>  (de)prioritization of pages on their LRU-lists for making LRU-lists a more
>  trustworthy data access pattern source.
>  
> @@ -17,7 +18,7 @@ systems, LRU lists are normally not proactively sorted but partially and
>  reactively sorted for special events including specific user requests, system
>  calls and memory pressure.  As a result, LRU lists are sometimes not so
>  perfectly prepared to be used as a trustworthy access pattern source for some
> -situations including reclamation target pages selection under sudden memory
> +situations including reclamation of target pages selection under sudden memory
>  pressure.

I cannot find what's wrong with the original sentence.  Could you expalin?
Also, I think the updated sentence is rather easier to misread.

>  
>  Because DAMON can identify access patterns of best-effort accuracy while
> @@ -28,9 +29,9 @@ pattern source with low and controlled overhead.
>  How It Works?
>  =============
>  
> -DAMON_LRU_SORT finds hot pages (pages of memory regions that showing access
> +DAMON_LRU_SORT finds hot pages (pages of memory regions that show access
>  rates that higher than a user-specified threshold) and cold pages (pages of

rates that "are" higher?

> -memory regions that showing no access for a time that longer than a
> +memory regions that show no access for a time that longer than a
>  user-specified threshold) using DAMON, and prioritizes hot pages while
>  deprioritizing cold pages on their LRU-lists.  To avoid it consuming too much
>  CPU for the prioritizations, a CPU time usage limit can be configured.  Under
> @@ -63,10 +64,10 @@ enabled
>  
>  Enable or disable DAMON_LRU_SORT.
>  
> -You can enable DAMON_LRU_SORT by setting the value of this parameter as ``Y``.
> -Setting it as ``N`` disables DAMON_LRU_SORT.  Note that DAMON_LRU_SORT could do
> +You can enable DAMON_LRU_SORT by setting the value of this parameter to ``Y``.
> +Setting it to ``N`` disables DAMON_LRU_SORT.  Note that DAMON_LRU_SORT could do
>  no real monitoring and LRU-lists sorting 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
>  -------------
> @@ -74,9 +75,9 @@ commit_inputs
>  Make DAMON_LRU_SORT reads the input parameters again, except ``enabled``.
>  
>  Input parameters that updated while DAMON_LRU_SORT is running are not applied
> -by default.  Once this parameter is set as ``Y``, DAMON_LRU_SORT reads values
> +by default.  Once this parameter is set to ``Y``, DAMON_LRU_SORT 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_LRU_SORT will be disabled.
>  
>  Once ``Y`` is written to this parameter, the user must not write to any
> @@ -86,37 +87,37 @@ violate this rule, the kernel may exhibit undefined behavior.
>  active_mem_bp
>  -------------
>  
> -Desired active to [in]active memory ratio in bp (1/10,000).
> +Desired active to (in)active memory ratio in bp (1/10,000).

I think use of brackets is also fine.  Let me know if I'm missing something.

>  
>  While keeping the caps that set by other quotas, DAMON_LRU_SORT automatically
>  increases and decreases the effective level of the quota aiming the LRU
> -[de]prioritizations of the hot and cold memory resulting in this active to
> -[in]active memory ratio.  Value zero means disabling this auto-tuning feature.
> +(de)prioritizations of the hot and cold memory resulting in this active to
> +(in)active memory ratio.  Value zero means disabling this auto-tuning feature.

Ditto.

>  
>  Disabled by default.
>  
>  autotune_monitoring_intervals
>  -----------------------------
>  
> -If this parameter is set as ``Y``, DAMON_LRU_SORT automatically tunes DAMON's
> +If this parameter is set to ``Y``, DAMON_LRU_SORT 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.
>  
>  filter_young_pages
>  ------------------
>  
> -Filter [non-]young pages accordingly for LRU [de]prioritizations.
> +Filter (non-)young pages accordingly for LRU (de)prioritizations.

Ditto.

>  
>  If this is set, check page level access (youngness) once again before each
> -LRU [de]prioritization operation.  LRU prioritization operation is skipped
> +LRU (de)prioritization operation.  LRU prioritization operation is skipped

Ditto.

>  if the page has not accessed since the last check (not young).  LRU
>  deprioritization operation is skipped if the page has accessed since the
>  last check (young).  The feature is enabled or disabled if this parameter is
> -set as ``Y`` or ``N``, respectively.
> +set to ``Y`` or ``N``, respectively.
>  
>  Disabled by default.
>  
> @@ -235,7 +236,7 @@ max_nr_regions
>  Maximum number of monitoring regions.
>  
>  The maximum number of monitoring regions of DAMON for the cold memory
> -monitoring.  This can be used to set upper-bound of the monitoring overhead.
> +monitoring.  This can be used to set the upper-bound of the monitoring overhead.
>  However, setting this too low could result in bad monitoring quality.  Please
>  refer to the DAMON documentation (:doc:`usage`) for more detail.  1000 by
>  defaults.
> @@ -268,7 +269,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_LRU_SORT will work for 10 KiB length of physical address range that
>  starts from address zero (``[0 * 1024, 10 * 1024)`` in bytes).
>  
> @@ -291,22 +292,22 @@ If DAMON_LRU_SORT is enabled, this becomes the PID of the worker thread.  Else,
>  nr_lru_sort_tried_hot_regions
>  -----------------------------
>  
> -Number of hot memory regions that tried to be LRU-sorted.
> +Number of hot memory regions that try to be LRU-sorted.

that were tried to be ?

>  
>  bytes_lru_sort_tried_hot_regions
>  --------------------------------
>  
> -Total bytes of hot memory regions that tried to be LRU-sorted.
> +Total bytes of hot memory regions that try to be LRU-sorted.

that were tried to be ?

>  
>  nr_lru_sorted_hot_regions
>  -------------------------
>  
> -Number of hot memory regions that successfully be LRU-sorted.
> +Number of hot memory regions that are successfully LRU-sorted.

that were ?

>  
>  bytes_lru_sorted_hot_regions
>  ----------------------------
>  
> -Total bytes of hot memory regions that successfully be LRU-sorted.
> +Total bytes of hot memory regions that are successfully LRU-sorted.

that were ?

>  
>  nr_hot_quota_exceeds
>  --------------------
> -- 
> 2.55.0


Thanks,
SJ