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

Changes from v1:
- v1: https://lore.kernel.org/damon/20260811101841.804596-1-aethernet65535@gmail.com
- Patch 1 word order adjustment: Repositioned "completely" ("tried to be
  completely applied" -> "completely tried to be applied").
- Patch 2: Use two spaces between sentences.
- Patch 3: Add the "Reviewed-by:" of SJ, because he added this in v1.

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 | 4 ++--
 include/linux/damon.h             | 3 ++-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index aed6cb1cf483..1739aeec6eb9 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -846,8 +846,8 @@ scheme's execution.
 - ``nr_applied``: Total number of regions that the scheme is applied.
 - ``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.
+- ``nr_snapshots``: Total number of DAMON snapshots that the scheme is
+  completely tried to be 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..33914594fb48 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 completely
+ *		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

[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

[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>
Reviewed-by: SJ Park <sj@kernel.org>
---
 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 0/3] docs/mm/damon/design: add explanation of nr_snapshots

[Liew Rui Yan]

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

This patch series still contain some error, I will resend them later.
Please skip reviewing these patches.  Apologize for the noise.

[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

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

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

[SJ Park]

On Wed, 12 Aug 2026 01:02:52 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:

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

Sounds good!

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


Thanks,
SJ