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

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

[Liew Rui Yan]

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.

While at it, fix a Sphinx syntax error in the "contents" directive in
design.rst (missing space after :depth:) that prevents the table of
contents from being rendered on docs.kernel.org.

Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
Link: https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t
---
 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               | 6 +++++-
 4 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/mm/damon/lru_sort.rst b/Documentation/admin-guide/mm/damon/lru_sort.rst
index 06a46812a728..0198dfe87f4d 100644
--- a/Documentation/admin-guide/mm/damon/lru_sort.rst
+++ b/Documentation/admin-guide/mm/damon/lru_sort.rst
@@ -353,3 +353,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 c5b4d8a1b001..a37ce6fdff05 100644
--- a/Documentation/admin-guide/mm/damon/reclaim.rst
+++ b/Documentation/admin-guide/mm/damon/reclaim.rst
@@ -331,6 +331,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 468c122c4259..46c5dd96aa2e 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 0a3b77ec458f..3694c541e65a 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -5,7 +5,7 @@ Design
 ======
 
 .. contents:: :local:
-   :depth:2
+   :depth: 2
 
 .. _damon_design_execution_model_and_data_structures:
 
@@ -960,6 +960,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
 --------------------
-- 
2.53.0

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

[SeongJae Park]

Hello Liew,

On Sat, 14 Mar 2026 17:20:22 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

> 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.

Thank you for doing this!

> 
> While at it, fix a Sphinx syntax error in the "contents" directive in
> design.rst (missing space after :depth:) that prevents the table of
> contents from being rendered on docs.kernel.org.

And thank you for fixing this!  But, the broken "contents" directive is added
by a commit on damon/next tree [1] that not yet planned to be upstreamed.  That
is, seems this patch is based on damon/next tree.  As a result, this patch
cannot be cleanly applied on mm-new.  We prefer making patches based on mm-new
unless there is a reason.

> 
> Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
> Link: https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t

I think it would be nice to give a context about the link.

Other than that,

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

Assuming you agree to my above suggestions, I added this patch to the top area
of damon/next after dropping the "contents" directive fix and adding a simple
sentence describing the context of the link.  The change made to this patch for
that is as below.  If you don't mind, I will post it as v2 of this patch by
tomorrow morning in Pacific Time.  Please let me know if you have any comments
about the plan.

'''
diff --git a/Docs-mm-damon-document-exclusivity-of-special-purpos.patch b/Docs-mm-damon-document-exclusivity-of-special-purpos.patch
index 9e74de3b..db466405 100644
--- a/Docs-mm-damon-document-exclusivity-of-special-purpos.patch
+++ b/Docs-mm-damon-document-exclusivity-of-special-purpos.patch
@@ -11,26 +11,31 @@ 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.
 
-While at it, fix a Sphinx syntax error in the "contents" directive in
-design.rst (missing space after :depth:) that prevents the table of
-contents from being rendered on docs.kernel.org.
+This change is motivated from another discussion [1].
+
+[1] https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t
+
+TODO: move below changelog to the comment section when posting
+Change from v1
+(https://lore.kernel.org/20260314092145.7496-1-aethernet65535@gmail.com)
+- Drop contents directive fix
+- Reword description
 
-Link: https://patch.msgid.link/20260314092145.7496-1-aethernet65535@gmail.com
 Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
-Link: https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t
+Reviewed-by: SeongJae Park <sj@kernel.org>
 Signed-off-by: SeongJae Park <sj@kernel.org>
 ---
  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               | 6 +++++-
- 4 files changed, 20 insertions(+), 1 deletion(-)
+ 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 06a46812a728c..0198dfe87f4d5 100644
+index 73980bacc3a02..56690646cf398 100644
 --- a/Documentation/admin-guide/mm/damon/lru_sort.rst
 +++ b/Documentation/admin-guide/mm/damon/lru_sort.rst
-@@ -353,3 +353,8 @@ the LRU-list based page granularity reclamation. ::
+@@ -351,3 +351,8 @@ the LRU-list based page granularity reclamation. ::
      # echo 400 > wmarks_mid
      # echo 200 > wmarks_low
      # echo Y > enabled
@@ -40,10 +45,10 @@ index 06a46812a728c..0198dfe87f4d5 100644
 +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 c5b4d8a1b0014..a37ce6fdff050 100644
+index 552a7786b0829..6f580f637134a 100644
 --- a/Documentation/admin-guide/mm/damon/reclaim.rst
 +++ b/Documentation/admin-guide/mm/damon/reclaim.rst
-@@ -331,6 +331,11 @@ granularity reclamation. ::
+@@ -318,6 +318,11 @@ granularity reclamation. ::
      # echo 200 > wmarks_low
      # echo Y > enabled
  
@@ -56,7 +61,7 @@ index c5b4d8a1b0014..a37ce6fdff050 100644
  .. [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 468c122c42594..46c5dd96aa2ed 100644
+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``.
@@ -72,19 +77,10 @@ index 468c122c42594..46c5dd96aa2ed 100644
  
  aggr_interval_us
 diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
-index 0a3b77ec458fe..3694c541e65aa 100644
+index 29fff20b3c2a9..dc37402c0fee9 100644
 --- a/Documentation/mm/damon/design.rst
 +++ b/Documentation/mm/damon/design.rst
-@@ -5,7 +5,7 @@ Design
- ======
- 
- .. contents:: :local:
--   :depth:2
-+   :depth: 2
- 
- .. _damon_design_execution_model_and_data_structures:
- 
-@@ -960,6 +960,10 @@ more detail, please read the usage documents for those
+@@ -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`).
'''  

[1] https://origin.kernel.org/doc/html/latest/mm/damon/maintainer-profile.html#scm-trees


Thanks,
SJ

[...]

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

[Liew Rui Yan]

On Sun, Mar 15, 2026 at 12:25 AM SeongJae Park <sj@kernel.org> wrote:
>
> Hello Liew,
>
Hello SeongJae,

>
> And thank you for fixing this!  But, the broken "contents" directive is added
> by a commit on damon/next tree [1] that not yet planned to be upstreamed.  That
> is, seems this patch is based on damon/next tree.  As a result, this patch
> cannot be cleanly applied on mm-new.  We prefer making patches based on mm-new
> unless there is a reason.
>
Okay, I will make sure to follow this in my future submissions.

> >
> > Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
> > Link: https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t
>
> I think it would be nice to give a context about the link.
>
That makes perfect sense.

>
> Reviewed-by: SeongJae Park <sj@kernel.org>
>
Thank you again, this marks my first contribution to Linux, and I truly
appreciate your guidance!

>
> Assuming you agree to my above suggestions, I added this patch to the top area
> of damon/next after dropping the "contents" directive fix and adding a simple
> sentence describing the context of the link.  The change made to this patch for
> that is as below.  If you don't mind, I will post it as v2 of this patch by
> tomorrow morning in Pacific Time.  Please let me know if you have any comments
> about the plan.
>
The plan sounds great to me. Thank you for taking care of the v2
submission!

Best regards,
Rui Yan

On Sun, Mar 15, 2026 at 12:25 AM SeongJae Park <sj@kernel.org> wrote:
>
> Hello Liew,
>
> On Sat, 14 Mar 2026 17:20:22 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:
>
> > 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.
>
> Thank you for doing this!
>
> >
> > While at it, fix a Sphinx syntax error in the "contents" directive in
> > design.rst (missing space after :depth:) that prevents the table of
> > contents from being rendered on docs.kernel.org.
>
> And thank you for fixing this!  But, the broken "contents" directive is added
> by a commit on damon/next tree [1] that not yet planned to be upstreamed.  That
> is, seems this patch is based on damon/next tree.  As a result, this patch
> cannot be cleanly applied on mm-new.  We prefer making patches based on mm-new
> unless there is a reason.
>
> >
> > Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
> > Link: https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t
>
> I think it would be nice to give a context about the link.
>
> Other than that,
>
> Reviewed-by: SeongJae Park <sj@kernel.org>
>
> Assuming you agree to my above suggestions, I added this patch to the top area
> of damon/next after dropping the "contents" directive fix and adding a simple
> sentence describing the context of the link.  The change made to this patch for
> that is as below.  If you don't mind, I will post it as v2 of this patch by
> tomorrow morning in Pacific Time.  Please let me know if you have any comments
> about the plan.
>
> '''
> diff --git a/Docs-mm-damon-document-exclusivity-of-special-purpos.patch b/Docs-mm-damon-document-exclusivity-of-special-purpos.patch
> index 9e74de3b..db466405 100644
> --- a/Docs-mm-damon-document-exclusivity-of-special-purpos.patch
> +++ b/Docs-mm-damon-document-exclusivity-of-special-purpos.patch
> @@ -11,26 +11,31 @@ 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.
>
> -While at it, fix a Sphinx syntax error in the "contents" directive in
> -design.rst (missing space after :depth:) that prevents the table of
> -contents from being rendered on docs.kernel.org.
> +This change is motivated from another discussion [1].
> +
> +[1] https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t
> +
> +TODO: move below changelog to the comment section when posting
> +Change from v1
> +(https://lore.kernel.org/20260314092145.7496-1-aethernet65535@gmail.com)
> +- Drop contents directive fix
> +- Reword description
>
> -Link: https://patch.msgid.link/20260314092145.7496-1-aethernet65535@gmail.com
>  Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
> -Link: https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t
> +Reviewed-by: SeongJae Park <sj@kernel.org>
>  Signed-off-by: SeongJae Park <sj@kernel.org>
>  ---
>   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               | 6 +++++-
> - 4 files changed, 20 insertions(+), 1 deletion(-)
> + 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 06a46812a728c..0198dfe87f4d5 100644
> +index 73980bacc3a02..56690646cf398 100644
>  --- a/Documentation/admin-guide/mm/damon/lru_sort.rst
>  +++ b/Documentation/admin-guide/mm/damon/lru_sort.rst
> -@@ -353,3 +353,8 @@ the LRU-list based page granularity reclamation. ::
> +@@ -351,3 +351,8 @@ the LRU-list based page granularity reclamation. ::
>       # echo 400 > wmarks_mid
>       # echo 200 > wmarks_low
>       # echo Y > enabled
> @@ -40,10 +45,10 @@ index 06a46812a728c..0198dfe87f4d5 100644
>  +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 c5b4d8a1b0014..a37ce6fdff050 100644
> +index 552a7786b0829..6f580f637134a 100644
>  --- a/Documentation/admin-guide/mm/damon/reclaim.rst
>  +++ b/Documentation/admin-guide/mm/damon/reclaim.rst
> -@@ -331,6 +331,11 @@ granularity reclamation. ::
> +@@ -318,6 +318,11 @@ granularity reclamation. ::
>       # echo 200 > wmarks_low
>       # echo Y > enabled
>
> @@ -56,7 +61,7 @@ index c5b4d8a1b0014..a37ce6fdff050 100644
>   .. [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 468c122c42594..46c5dd96aa2ed 100644
> +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``.
> @@ -72,19 +77,10 @@ index 468c122c42594..46c5dd96aa2ed 100644
>
>   aggr_interval_us
>  diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
> -index 0a3b77ec458fe..3694c541e65aa 100644
> +index 29fff20b3c2a9..dc37402c0fee9 100644
>  --- a/Documentation/mm/damon/design.rst
>  +++ b/Documentation/mm/damon/design.rst
> -@@ -5,7 +5,7 @@ Design
> - ======
> -
> - .. contents:: :local:
> --   :depth:2
> -+   :depth: 2
> -
> - .. _damon_design_execution_model_and_data_structures:
> -
> -@@ -960,6 +960,10 @@ more detail, please read the usage documents for those
> +@@ -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`).
> '''
>
> [1] https://origin.kernel.org/doc/html/latest/mm/damon/maintainer-profile.html#scm-trees
>
>
> Thanks,
> SJ
>
> [...]

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

[SeongJae Park]

On Sun, 15 Mar 2026 04:37:34 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

> On Sun, Mar 15, 2026 at 12:25 AM SeongJae Park <sj@kernel.org> wrote:
> >
> > Hello Liew,
> >
> Hello SeongJae,
> 
> >
> > And thank you for fixing this!  But, the broken "contents" directive is added
> > by a commit on damon/next tree [1] that not yet planned to be upstreamed.  That
> > is, seems this patch is based on damon/next tree.  As a result, this patch
> > cannot be cleanly applied on mm-new.  We prefer making patches based on mm-new
> > unless there is a reason.
> >
> Okay, I will make sure to follow this in my future submissions.
> 
> > >
> > > Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
> > > Link: https://lore.kernel.org/damon/20260314002119.79742-1-sj@kernel.org/T/#t
> >
> > I think it would be nice to give a context about the link.
> >
> That makes perfect sense.
> 
> >
> > Reviewed-by: SeongJae Park <sj@kernel.org>
> >
> Thank you again, this marks my first contribution to Linux, and I truly
> appreciate your guidance!

It's my honor to help your first contribution! :)

> 
> >
> > Assuming you agree to my above suggestions, I added this patch to the top area
> > of damon/next after dropping the "contents" directive fix and adding a simple
> > sentence describing the context of the link.  The change made to this patch for
> > that is as below.  If you don't mind, I will post it as v2 of this patch by
> > tomorrow morning in Pacific Time.  Please let me know if you have any comments
> > about the plan.
> >
> The plan sounds great to me. Thank you for taking care of the v2
> submission!

Great, I may post it tomorrow morning.


Thanks,
SJ

[...]