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

[SJ Park <sj@kernel.org>]

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