[PATCH v2] Docs/mm/damon: document exclusivity of special-purpose modules

SeongJae Park
2026-03-15T16:30:00Z

From: Liew Rui Yan <aethernet65535@gmail.com>

Add a section in design.rst to explain that DAMON special-purpose kernel
modules (LRU_SORT, RECLAIM, STAT) run in an exclusive manner and return
-EBUSY if another is already running.

Update lru_sort.rst, reclaim.rst and stat.rst by adding cross-references
to this exclusivity rule at the end of their respective Example
sections.

This change is motivated from another discussion [1].

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

Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
Reviewed-by: SeongJae Park <sj@kernel.org>
Signed-off-by: SeongJae Park <sj@kernel.org>
---
Change from v1
(https://lore.kernel.org/20260314092145.7496-1-aethernet65535@gmail.com)
- Drop contents directive fix
- Reword description

Documentation/admin-guide/mm/damon/lru_sort.rst | 5 +++++
Documentation/admin-guide/mm/damon/reclaim.rst | 5 +++++
Documentation/admin-guide/mm/damon/stat.rst | 5 +++++
Documentation/mm/damon/design.rst | 4 ++++
4 files changed, 19 insertions(+)

diff --git a/Documentation/admin-guide/mm/damon/lru_sort.rst b/Documentation/admin-guide/mm/damon/lru_sort.rst
index 73980bacc3a02..56690646cf398 100644
--- a/Documentation/admin-guide/mm/damon/lru_sort.rst
+++ b/Documentation/admin-guide/mm/damon/lru_sort.rst
@@ -351,3 +351,8 @@ the LRU-list based page granularity reclamation. ::
# echo 400 > wmarks_mid
# echo 200 > wmarks_low
# echo Y > enabled
+
+Note that this module (damon_lru_sort) cannot run simultaneously with other
+DAMON-based special-purpose modules. Refer to :ref:`DAMON design special
+purpose modules exclusivity <damon_design_special_purpose_modules_exclusivity>`
+for more details.
diff --git a/Documentation/admin-guide/mm/damon/reclaim.rst b/Documentation/admin-guide/mm/damon/reclaim.rst
index 552a7786b0829..6f580f637134a 100644
--- a/Documentation/admin-guide/mm/damon/reclaim.rst
+++ b/Documentation/admin-guide/mm/damon/reclaim.rst
@@ -318,6 +318,11 @@ granularity reclamation. ::
# echo 200 > wmarks_low
# echo Y > enabled

+Note that this module (damon_reclaim) cannot run simultaneously with other
+DAMON-based special-purpose modules. Refer to :ref:`DAMON design special
+purpose modules exclusivity <damon_design_special_purpose_modules_exclusivity>`
+for more details.
+
.. [1] https://research.google/pubs/pub48551/
.. [2] https://lwn.net/Articles/787611/
.. [3] Documentation/mm/free_page_reporting.rst
diff --git a/Documentation/admin-guide/mm/damon/stat.rst b/Documentation/admin-guide/mm/damon/stat.rst
index e5a5a2c4f803a..c4b14daeb2dd6 100644
--- a/Documentation/admin-guide/mm/damon/stat.rst
+++ b/Documentation/admin-guide/mm/damon/stat.rst
@@ -45,6 +45,11 @@ You can enable DAMON_STAT by setting the value of this parameter as ``Y``.
Setting it as ``N`` disables DAMON_STAT. The default value is set by
``CONFIG_DAMON_STAT_ENABLED_DEFAULT`` build config option.

+Note that this module (damon_stat) cannot run simultaneously with other
+DAMON-based special-purpose modules. Refer to :ref:`DAMON design special
+purpose modules exclusivity <damon_design_special_purpose_modules_exclusivity>`
+for more details.
+
.. _damon_stat_aggr_interval_us:

aggr_interval_us
diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 29fff20b3c2a9..dc37402c0fee9 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -853,6 +853,10 @@ more detail, please read the usage documents for those
(:doc:`/admin-guide/mm/damon/stat`, :doc:`/admin-guide/mm/damon/reclaim` and
:doc:`/admin-guide/mm/damon/lru_sort`).

+.. _damon_design_special_purpose_modules_exclusivity:
+
+Note that these modules currently run in an exclusive manner. If one of those
+is already running, others will return ``-EBUSY`` upon start requests.

Sample DAMON Modules
--------------------

base-commit: 1e6fb24fdfceeb8dfa1a97a0270e4aeffa0a6d6d
--
2.47.3