[PATCH] Docs/mm/damon: document min_nr_regions constraint and rationale

[PATCH] Docs/mm/damon: document min_nr_regions constraint and rationale

[Liew Rui Yan]

The current DAMON implementation requires 'min_nr_regions' to be at
least 3. However, this constraint is not explicitly documented in the
admin-guide documents, nor is its design rationale explained in the
design document.

Add a section in design.rst to explain the rationale: the virtual
address space monitoring design needs to handle at least three regions
to accommodate two large unmapped areas. While this is specific to
'vaddr', DAMON currently enforces it across all operation sets for
consistency.

Also update reclaim.rst and lru_sort.rst by adding cross-references to
this constraint within their respective 'min_nr_regions' parameter
description sections, ensuring users are aware of the lower bound.

This change is motivated from a recent discussion [1].

[1] https://lore.kernel.org/damon/20260319151528.86490-1-sj@kernel.org/T/#t

Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
---
 Documentation/admin-guide/mm/damon/lru_sort.rst | 4 ++++
 Documentation/admin-guide/mm/damon/reclaim.rst  | 4 ++++
 Documentation/mm/damon/design.rst               | 7 +++++++
 3 files changed, 15 insertions(+)

diff --git a/Documentation/admin-guide/mm/damon/lru_sort.rst b/Documentation/admin-guide/mm/damon/lru_sort.rst
index 20a8378d5a94..3d08baf9802c 100644
--- a/Documentation/admin-guide/mm/damon/lru_sort.rst
+++ b/Documentation/admin-guide/mm/damon/lru_sort.rst
@@ -221,6 +221,10 @@ But, setting this too high could result in increased monitoring overhead.
 Please refer to the DAMON documentation (:doc:`usage`) for more detail.  10 by
 default.
 
+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.
+
 max_nr_regions
 --------------
 
diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst
index 8eba3da8dcee..153bf42645dd 100644
--- a/Documentation/admin-guide/mm/damon/reclaim.rst
+++ b/Documentation/admin-guide/mm/damon/reclaim.rst
@@ -204,6 +204,10 @@ 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
+<damon_design_monitoring>` section of the design document for the rationale
+behind this lower bound.
+
 max_nr_regions
 --------------
 
diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index dd64f5d7f319..68a25e07203c 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -165,6 +165,13 @@ monitoring attributes, ``sampling interval``, ``aggregation interval``,
 ``update interval``, ``minimum number of regions``, and ``maximum number of
 regions``.
 
+Note that ``minimum number of regions`` must be 3 or higher. This is because the
+virtual address space monitoring is designed to handle at least three regions to
+accommodate two large unmapped areas commonly found in normal virtual address
+spaces. While this restriction might not be strictly necessary for other
+operation sets like ``paddr``, it is currently enforced across all DAMON
+operations for consistency.
+
 To know how user-space can set the attributes via :ref:`DAMON sysfs interface
 <sysfs_interface>`, refer to :ref:`monitoring_attrs <sysfs_monitoring_attrs>`
 part of the documentation.
-- 
2.53.0

Re: [PATCH] Docs/mm/damon: document min_nr_regions constraint and rationale

[Liew Rui Yan]

The current DAMON implementation requires 'min_nr_regions' to be at
least 3. However, this constraint is not explicitly documented in the
admin-guide documents, nor is its design rationale explained in the
design document.

Add a section in design.rst to explain the rationale: the virtual
address space monitoring design needs to handle at least three regions
to accommodate two large unmapped areas. While this is specific to
'vaddr', DAMON currently enforces it across all operation sets for
consistency.

Also update reclaim.rst and lru_sort.rst by adding cross-references to
this constraint at the end of their respective parameter description or
usage sections, ensuring users are aware of the lower bound.

This change is motivated from a recent discussion [1].

[1] https://lore.kernel.org/damon/20260319151528.86490-1-sj@kernel.org/T/#t

Re: [PATCH] Docs/mm/damon: document min_nr_regions constraint and rationale

[Liew Rui Yan]

Hi SeongJae,

I'm sorry for the noise; please ignore my previous reply. I accidentally
sent the commit message instead of my intended message.

What I wanted to ask is regarding tasks 3 and 4 from our earlier plan
[1]: should I wait to start both of them later? Or is it only task 3
that needs to wait until your fix is merged or abandoned?

Also, I'm preparing to post an RFC patch for 'damon_hot_score'
optimization soon. It aims to provide a significant performance
improvement.

[1] https://lore.kernel.org/damon/20260319151528.86490-1-sj@kernel.org/T/#t

Best regards,
Rui Yan

Re: [PATCH] Docs/mm/damon: document min_nr_regions constraint and rationale

[SeongJae Park]

On Fri, 20 Mar 2026 13:41:45 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

> Hi SeongJae,
> 
> I'm sorry for the noise; please ignore my previous reply. I accidentally
> sent the commit message instead of my intended message.

No problem!

> 
> What I wanted to ask is regarding tasks 3 and 4 from our earlier plan
> [1]: should I wait to start both of them later? Or is it only task 3
> that needs to wait until your fix is merged or abandoned?

I want only task 3 to wait :)

> 
> Also, I'm preparing to post an RFC patch for 'damon_hot_score'
> optimization soon. It aims to provide a significant performance
> improvement.

Thank you, I'll check!

> 
> [1] https://lore.kernel.org/damon/20260319151528.86490-1-sj@kernel.org/T/#t

FYI, you don't really need to add the 'damon/' and '/T/#t' part on the link.


Thanks,
SJ

[...]

Re: [PATCH] Docs/mm/damon: document min_nr_regions constraint and rationale

[SeongJae Park]

Hello Liew,


Thank you for this patch!

On Fri, 20 Mar 2026 13:24:28 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

> The current DAMON implementation requires 'min_nr_regions' to be at
> least 3. However, this constraint is not explicitly documented in the
> admin-guide documents, nor is its design rationale explained in the
> design document.
> 
> Add a section in design.rst to explain the rationale: the virtual
> address space monitoring design needs to handle at least three regions
> to accommodate two large unmapped areas. While this is specific to
> 'vaddr', DAMON currently enforces it across all operation sets for
> consistency.
> 
> Also update reclaim.rst and lru_sort.rst by adding cross-references to
> this constraint within their respective 'min_nr_regions' parameter
> description sections, ensuring users are aware of the lower bound.
> 
> This change is motivated from a recent discussion [1].
> 
> [1] https://lore.kernel.org/damon/20260319151528.86490-1-sj@kernel.org/T/#t
> 
> Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>

Reviewed-by: SeongJae Park <sj@kernel.org>


Thanks,
SJ

[...]