[PATCH 0/3] docs/mm/damon/design: add explanation of nr_snapshots

[PATCH 0/3] docs/mm/damon/design: add explanation of nr_snapshots

[Liew Rui Yan]

Add an explanation of nr_snapshots to avoid misunderstandings.

Liew Rui Yan (3):
  docs/mm/damon/design: accurate semantics of nr_snapshots
  docs/mm/damon/design: difference between watermarks and nr_snapshots
  docs/mm/damon/design: fix typo of max_nr_snapshots

 Documentation/mm/damon/design.rst | 7 ++++---
 include/linux/damon.h             | 5 +++--
 2 files changed, 7 insertions(+), 5 deletions(-)

-- 
2.55.0

[PATCH 1/3] docs/mm/damon/design: accurate semantics of nr_snapshots

[Liew Rui Yan]

Change "tried to be applied" -> "tried to be completely applied" to
maintain consistency between the documentation and the code.

Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
---
 Documentation/mm/damon/design.rst | 2 +-
 include/linux/damon.h             | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index aed6cb1cf483..939298f2a9b9 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -847,7 +847,7 @@ scheme's execution.
 - ``sz_applied``: Total size of regions that the scheme is applied.
 - ``qt_exceeds``: Total number of times the quota of the scheme has exceeded.
 - ``nr_snapshots``: Total number of DAMON snapshots that the scheme is tried to
-  be applied.
+  be completely applied.
 - ``max_nr_snapshots``: Upper limit of ``nr_snapshots``.
 
 "A scheme is tried to be applied to a region" means DAMOS core logic determined
diff --git a/include/linux/damon.h b/include/linux/damon.h
index 0c8b7ddef9ab..d642ce4fc83c 100644
--- a/include/linux/damon.h
+++ b/include/linux/damon.h
@@ -357,7 +357,8 @@ struct damos_watermarks {
  *		Total bytes that passed ops layer-handled DAMOS filters.
  * @qt_exceeds: Total number of times the quota of the scheme has exceeded.
  * @nr_snapshots:
- *		Total number of DAMON snapshots that the scheme has tried.
+ *		Total number of DAMON snapshots that the scheme is tried to be
+ *		completely applied.
  *
  * "Tried an action to a region" in this context means the DAMOS core logic
  * determined the region as eligible to apply the action.  The access pattern
-- 
2.55.0

Re: [PATCH 1/3] docs/mm/damon/design: accurate semantics of nr_snapshots

[SJ Park]

On Tue, 11 Aug 2026 18:18:39 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

> Change "tried to be applied" -> "tried to be completely applied" to
> maintain consistency between the documentation and the code.

It feels bit confusing to me.  The completion in this context is for "trial",
not "application".  For example, someone might wrongly think the number could
be incremented even if a scheme was "tried" to be completely "applied" to the
snapshot, but failed due to a quota.

What about "completely tried to be applied"?

> 
> Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
> ---
>  Documentation/mm/damon/design.rst | 2 +-
>  include/linux/damon.h             | 3 ++-
>  2 files changed, 3 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
> index aed6cb1cf483..939298f2a9b9 100644
> --- a/Documentation/mm/damon/design.rst
> +++ b/Documentation/mm/damon/design.rst
> @@ -847,7 +847,7 @@ scheme's execution.
>  - ``sz_applied``: Total size of regions that the scheme is applied.
>  - ``qt_exceeds``: Total number of times the quota of the scheme has exceeded.
>  - ``nr_snapshots``: Total number of DAMON snapshots that the scheme is tried to
> -  be applied.
> +  be completely applied.
>  - ``max_nr_snapshots``: Upper limit of ``nr_snapshots``.
>  
>  "A scheme is tried to be applied to a region" means DAMOS core logic determined
> diff --git a/include/linux/damon.h b/include/linux/damon.h
> index 0c8b7ddef9ab..d642ce4fc83c 100644
> --- a/include/linux/damon.h
> +++ b/include/linux/damon.h
> @@ -357,7 +357,8 @@ struct damos_watermarks {
>   *		Total bytes that passed ops layer-handled DAMOS filters.
>   * @qt_exceeds: Total number of times the quota of the scheme has exceeded.
>   * @nr_snapshots:
> - *		Total number of DAMON snapshots that the scheme has tried.
> + *		Total number of DAMON snapshots that the scheme is tried to be
> + *		completely applied.
>   *
>   * "Tried an action to a region" in this context means the DAMOS core logic
>   * determined the region as eligible to apply the action.  The access pattern
> -- 
> 2.55.0


Thanks,
SJ

Re: [PATCH 1/3] docs/mm/damon/design: accurate semantics of nr_snapshots

[Liew Rui Yan]

On Tue, 11 Aug 2026 06:46:33 -0700 SJ Park <sj@kernel.org> wrote:

> On Tue, 11 Aug 2026 18:18:39 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:
> 
> > Change "tried to be applied" -> "tried to be completely applied" to
> > maintain consistency between the documentation and the code.
> 
> It feels bit confusing to me.  The completion in this context is for "trial",
> not "application".  For example, someone might wrongly think the number could
> be incremented even if a scheme was "tried" to be completely "applied" to the
> snapshot, but failed due to a quota.
> 
> What about "completely tried to be applied"?

Thank you for your clarification.

"Tried to be __completely applied__" means that even if only a portion
is tried, it will still increase. "__Completely tried__ to be applied"
means that it will only increase if it is fully tried.  Right?

I will change this in next revision.

Best regards,
Rui Yan

[PATCH 2/3] docs/mm/damon/design: difference between watermarks and nr_snapshots

[Liew Rui Yan]

Explain the difference between nr_snapshots reaches max_nr_snapshots and
watermarks.

Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
---
 Documentation/mm/damon/design.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 939298f2a9b9..1fcf0b8c044b 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -872,7 +872,8 @@ the action to the region will fail.
 
 Unlike normal stats, ``max_nr_snapshots`` is set by users.  If it is set as
 non-zero and ``nr_snapshots`` be same to or greater than ``nr_snapshots``, the
-scheme is deactivated.
+scheme is deactivated. Note that, unlike watermarks, even if a scheme's
+``nr_snapshots`` reaches ``max_nr_snapshots``, monitoring will not stop.
 
 To know how user-space can read the stats via :ref:`DAMON sysfs interface
 <sysfs_interface>`, refer to :ref:s`stats <sysfs_stats>` part of the
-- 
2.55.0

Re: [PATCH 2/3] docs/mm/damon/design: difference between watermarks and nr_snapshots

[SJ Park]

On Tue, 11 Aug 2026 18:18:40 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

> Explain the difference between nr_snapshots reaches max_nr_snapshots and
> watermarks.
> 
> Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
> ---
>  Documentation/mm/damon/design.rst | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
> index 939298f2a9b9..1fcf0b8c044b 100644
> --- a/Documentation/mm/damon/design.rst
> +++ b/Documentation/mm/damon/design.rst
> @@ -872,7 +872,8 @@ the action to the region will fail.
>  
>  Unlike normal stats, ``max_nr_snapshots`` is set by users.  If it is set as
>  non-zero and ``nr_snapshots`` be same to or greater than ``nr_snapshots``, the
> -scheme is deactivated.
> +scheme is deactivated. Note that, unlike watermarks, even if a scheme's

Let's use two spaces between sentences, like other pargraphs in this file.

> +``nr_snapshots`` reaches ``max_nr_snapshots``, monitoring will not stop.
>  
>  To know how user-space can read the stats via :ref:`DAMON sysfs interface
>  <sysfs_interface>`, refer to :ref:s`stats <sysfs_stats>` part of the
> -- 
> 2.55.0


Thanks,
SJ

[PATCH 3/3] docs/mm/damon/design: fix typo of max_nr_snapshots

[Liew Rui Yan]

Fixes a typo (nr_snapshots -> max_nr_snapshots) and corrects a grammar
error.

Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
---
 Documentation/mm/damon/design.rst | 4 ++--
 include/linux/damon.h             | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 1fcf0b8c044b..62ba6cc2e999 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -871,8 +871,8 @@ action is ``pageout`` while all pages of the region are unreclaimable, applying
 the action to the region will fail.
 
 Unlike normal stats, ``max_nr_snapshots`` is set by users.  If it is set as
-non-zero and ``nr_snapshots`` be same to or greater than ``nr_snapshots``, the
-scheme is deactivated. Note that, unlike watermarks, even if a scheme's
+non-zero and ``nr_snapshots`` equals or is greater than ``max_nr_snapshots``,
+the scheme is deactivated. Note that, unlike watermarks, even if a scheme's
 ``nr_snapshots`` reaches ``max_nr_snapshots``, monitoring will not stop.
 
 To know how user-space can read the stats via :ref:`DAMON sysfs interface
diff --git a/include/linux/damon.h b/include/linux/damon.h
index d642ce4fc83c..75ece3d03be2 100644
--- a/include/linux/damon.h
+++ b/include/linux/damon.h
@@ -549,7 +549,7 @@ struct damos_migrate_dests {
  *
  * After applying the &action to each region, &stat is updated.
  *
- * If &max_nr_snapshots is set as non-zero and &stat.nr_snapshots be same to or
+ * If &max_nr_snapshots is set as non-zero and &stat.nr_snapshots equals or is
  * greater than it, the scheme is deactivated.
  */
 struct damos {
-- 
2.55.0

Re: [PATCH 3/3] docs/mm/damon/design: fix typo of max_nr_snapshots

[SJ Park]

On Tue, 11 Aug 2026 18:18:41 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

> Fixes a typo (nr_snapshots -> max_nr_snapshots) and corrects a grammar
> error.

Looks good to me, thank you for fixing these.

> 
> Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>

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


Thanks,
SJ

[...]

Re: [PATCH 0/3] docs/mm/damon/design: add explanation of nr_snapshots

[SJ Park]

Hi Liew,


'hkml patch check' [1] says you forgot Cc-ing below people who are recommended
by get_maintainer.pl.  Please Cc all recipients who
get_maitnainer.pl is recommending, from the next time.  'hkml patch format' [2]
could also help you doing so.

I added the missing recipients to this mail's recipients.  Because this series
is a minor change for only DAMON documentation, I didn't add them to the
patches.  People who are interested in reviewing the patches can find them from
lore.kernel.org.

- Andrew Morton <akpm@linux-foundation.org>
- David Hildenbrand <david@kernel.org>
- Lorenzo Stoakes <ljs@kernel.org>
- "Liam R. Howlett" <liam@infradead.org>
- Vlastimil Babka <vbabka@kernel.org>
- Mike Rapoport <rppt@kernel.org>
- Suren Baghdasaryan <surenb@google.com>
- Michal Hocko <mhocko@suse.com>
- Jonathan Corbet <corbet@lwn.net>
- Shuah Khan <skhan@linuxfoundation.org>
- linux-doc@vger.kernel.org
- linux-kernel@vger.kernel.org

On Tue, 11 Aug 2026 18:18:38 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

> Add an explanation of nr_snapshots to avoid misunderstandings.

Thank you for this patch series, Liew.

> 
> Liew Rui Yan (3):
>   docs/mm/damon/design: accurate semantics of nr_snapshots
>   docs/mm/damon/design: difference between watermarks and nr_snapshots
>   docs/mm/damon/design: fix typo of max_nr_snapshots

I requested changes to patches 1 and 2 via replies.

[1] https://github.com/sjp38/hackermail/blob/master/USAGE.md#checking-patches
[2] https://github.com/sjp38/hackermail/blob/master/USAGE.md#formatting-patches


Thanks,
SJ

[...]

Re: [PATCH 0/3] docs/mm/damon/design: add explanation of nr_snapshots

[Liew Rui Yan]

Hi SJ,


On Tue, 11 Aug 2026 06:56:53 -0700 SJ Park <sj@kernel.org> wrote:

> Hi Liew,
> 
> 
> 'hkml patch check' [1] says you forgot Cc-ing below people who are recommended
> by get_maintainer.pl.  Please Cc all recipients who
> get_maitnainer.pl is recommending, from the next time.  'hkml patch format' [2]
> could also help you doing so.
> 

Thank you for reminding me! I will CC all email addresses output by
get_maitnainer.pl from the next time.

> [...]
>
> On Tue, 11 Aug 2026 18:18:38 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:
> 
> > Add an explanation of nr_snapshots to avoid misunderstandings.
> 
> Thank you for this patch series, Liew.
> 
> > 
> > Liew Rui Yan (3):
> >   docs/mm/damon/design: accurate semantics of nr_snapshots
> >   docs/mm/damon/design: difference between watermarks and nr_snapshots
> >   docs/mm/damon/design: fix typo of max_nr_snapshots
> 
> I requested changes to patches 1 and 2 via replies.

I will make changes in the next revision:

patch-1: "tried to be __completely applied__" -> "__completely tried__
to be applied".

patch-2: use two spaces between sentences.

> 
> [1] https://github.com/sjp38/hackermail/blob/master/USAGE.md#checking-patches
> [2] https://github.com/sjp38/hackermail/blob/master/USAGE.md#formatting-patches


Best regards,
Rui Yan