Skip to contentSkip to conversation

docs/mm/damon/design: add explanation of nr_snapshots

PATCH In review Liew Rui Yan 2 participants 11 messages Aug 11 – Aug 12

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

cover docs/mm/damon/design: add explanation of nr_snapshots

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(-)
Signature · 1 line
2.55.0
#1 lore raw

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

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

---
 Documentation/mm/damon/design.rst | 2 +-
 include/linux/damon.h             | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)
Documentation/mm/damon/design.rst +1 -1
index aed6cb1cf483..939298f2a9b9 100644
@@ -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
include/linux/damon.h +2 -1
index 0c8b7ddef9ab..d642ce4fc83c 100644
@@ -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
Signature · 1 line
2.55.0
maintainer
#2 lore raw

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

Quoted 2 lines · On Tue, 11 Aug 2026 18:18:39 +0800 Liew Rui Yan <[email protected]>…

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"?

Quoted 36 lines
---
 Documentation/mm/damon/design.rst | 2 +-
 include/linux/damon.h             | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)
Documentation/mm/damon/design.rst +1 -1
index aed6cb1cf483..939298f2a9b9 100644
@@ -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
include/linux/damon.h +2 -1
index 0c8b7ddef9ab..d642ce4fc83c 100644
@@ -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
Signature · 1 line
2.55.0

Thanks,
SJ

#3 lore raw

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

Quoted 11 lines · On Tue, 11 Aug 2026 06:46:33 -0700 SJ Park <[email protected]> wrote:
Quoted 2 lines · On Tue, 11 Aug 2026 18:18:39 +0800 Liew Rui Yan <[email protected]>…

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

#4 lore raw

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

In reply to Liew Rui Yan

Explain the difference between nr_snapshots reaches max_nr_snapshots and watermarks.

---
 Documentation/mm/damon/design.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/mm/damon/design.rst +2 -1
index 939298f2a9b9..1fcf0b8c044b 100644
@@ -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
Signature · 1 line
2.55.0
maintainer
#5 lore raw

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

Quoted 13 lines · On Tue, 11 Aug 2026 18:18:40 +0800 Liew Rui Yan <[email protected]>…

Explain the difference between nr_snapshots reaches max_nr_snapshots and watermarks.

---
 Documentation/mm/damon/design.rst | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/mm/damon/design.rst +0 -0
index 939298f2a9b9..1fcf0b8c044b 100644

Documentation/mm/damon/design.rst the action to the region will fail. · line 875

Quoted 5 lines
Documentation/mm/damon/design.rst +1 -1
@@ -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.

Quoted 6 lines
Documentation/mm/damon/design.rst +1 -0
+``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
Signature · 1 line
2.55.0

Thanks,
SJ

#6 lore raw

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

In reply to Liew Rui Yan

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

---
 Documentation/mm/damon/design.rst | 4 ++--
 include/linux/damon.h             | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)
Documentation/mm/damon/design.rst +2 -2
index 1fcf0b8c044b..62ba6cc2e999 100644
@@ -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
include/linux/damon.h +1 -1
index d642ce4fc83c..75ece3d03be2 100644
@@ -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 {
Signature · 1 line
2.55.0
maintainer
#8 lore raw
In reply to Liew Rui Yan

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 <[email protected]>
- David Hildenbrand <[email protected]>
- Lorenzo Stoakes <[email protected]>
- "Liam R. Howlett" <[email protected]>
- Vlastimil Babka <[email protected]>
- Mike Rapoport <[email protected]>
- Suren Baghdasaryan <[email protected]>
- Michal Hocko <[email protected]>
- Jonathan Corbet <[email protected]>
- Shuah Khan <[email protected]>
- [email protected]
- [email protected]

Quoted 1 line · On Tue, 11 Aug 2026 18:18:38 +0800 Liew Rui Yan <[email protected]>…

Add an explanation of nr_snapshots to avoid misunderstandings.

Thank you for this patch series, Liew.

Quoted 5 lines

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

[...]

#9 lore raw

Hi SJ,

Quoted 8 lines · On Tue, 11 Aug 2026 06:56:53 -0700 SJ Park <[email protected]> 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.

Quoted 9 lines

[...]

Quoted 1 line · On Tue, 11 Aug 2026 18:18:38 +0800 Liew Rui Yan <[email protected]>…

Add an explanation of nr_snapshots to avoid misunderstandings.

Thank you for this patch series, Liew.

Quoted 1 line
Quoted 6 lines
Quoted 4 lines

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.

Quoted 3 lines

[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

maintainer
#10 lore raw
Quoted 31 lines · On Wed, 12 Aug 2026 01:02:52 +0800 Liew Rui Yan <[email protected]>…

Hi SJ,

Quoted 8 lines · On Tue, 11 Aug 2026 06:56:53 -0700 SJ Park <[email protected]> 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.

Quoted 14 lines

[...]

Quoted 1 line · On Tue, 11 Aug 2026 18:18:38 +0800 Liew Rui Yan <[email protected]>…

Add an explanation of nr_snapshots to avoid misunderstandings.

Thank you for this patch series, Liew.

Quoted 5 lines

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

Quoted 8 lines
Quoted 1 line

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!

Quoted 8 lines
Quoted 4 lines

[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