docs/mm/damon/design: add explanation of nr_snapshots
Subsystems (4)
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
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
@@ -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
@@ -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
SJ Park
maintainerRe: [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
Signed-off-by Liew Rui Yan <[email protected]>--- 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@@ -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 determinedinclude/linux/damon.h +2
-1@@ -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
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
PATCH 2/3 docs/mm/damon/design: difference between watermarks and nr_snapshots
In reply to Liew Rui YanExplain 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
@@ -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
SJ Park
maintainerRe: [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_snapshotsreachesmax_nr_snapshotsand watermarks.Signed-off-by Liew Rui Yan <[email protected]>--- Documentation/mm/damon/design.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)Documentation/mm/damon/design.rst +0
-0
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 theSignature · 1 line
2.55.0
Thanks,
SJ
PATCH 3/3 docs/mm/damon/design: fix typo of max_nr_snapshots
In reply to Liew Rui YanFixes 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
@@ -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
@@ -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
Re: [PATCH 3/3] docs/mm/damon/design: fix typo of max_nr_snapshots
Quoted 2 lines · On Tue, 11 Aug 2026 18:18:41 +0800 Liew Rui Yan <[email protected]>…
Fixes a typo (
nr_snapshots->max_nr_snapshots) and corrects a grammar error.
Looks good to me, thank you for fixing these.
Quoted 2 lines
Signed-off-by Liew Rui Yan <[email protected]>
Thanks,
SJ
[...]
SJ Park
maintainerHi 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_snapshotsto avoid misunderstandings.
Thank you for this patch series, Liew.
Quoted 5 lines
Liew Rui Yan (3):
docs/mm/damon/design: accurate semantics ofnr_snapshotsdocs/mm/damon/design: difference between watermarks andnr_snapshotsdocs/mm/damon/design: fix typo ofmax_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
[...]
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_snapshotsto 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 ofnr_snapshotsdocs/mm/damon/design: difference between watermarks andnr_snapshotsdocs/mm/damon/design: fix typo ofmax_nr_snapshotsI 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
SJ Park
maintainerQuoted 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_snapshotsto avoid misunderstandings.Thank you for this patch series, Liew.
Quoted 5 lines
Liew Rui Yan (3):
docs/mm/damon/design: accurate semantics ofnr_snapshotsdocs/mm/damon/design: difference between watermarks andnr_snapshotsdocs/mm/damon/design: fix typo ofmax_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
__completelyapplied__" -> "__completelytried__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-patchesBest regards,
Rui Yan
Thanks,
SJ