Skip to contentSkip to conversation

Docs/mm/damon/design: clarify when qt_exceeds increases

RFC PATCH In review Liew Rui Yan 3 participants 6 messages Sep 8 – Sep 10

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

RFC PATCH 1/1 Docs/mm/damon/design: clarify when qt_exceeds increases

qt_exceeds counts how many times the quota of a scheme has exceeded.

The value can confuse users when the effective size quota is zero, because a zero effective size quota does not always mean the quotas are unset.

If the quotas are unset, that is, both ms and bytes are zero and no quota goal is set, qt_exceeds never increases. But if the user uses the temporal auto-tuning algorithm, the effective size quota becomes zero once the goal is [over-]achieved. In that case the quotas are still set, so qt_exceeds keeps increasing once per quota reset interval while the goal stays achieved.

Clarify this on the design document.

---

By the way, I found a thing in the design document that confused me.

temporal: More straightforward algorithm. Tries to achieve the goal as fast as possible, using maximum allowed quota, but only for a temporal short time. ---> When the quota is under-achieved, this algorithm keeps tuning quota to a maximum allowed one. Once the quota is [over]-achieved <---, this sets the quota zero. Useful for deterministic control required environments.

I'm not sure if "goal" was accidentally written as "quota" here. Would this be better?

When the goal is under-achieved, this algorithm keeps tuning quota to a maximum allowed one. Once the goal is [over-]achieved, [...]

---
 Documentation/mm/damon/design.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/mm/damon/design.rst +10 -0
index d036340dae8a..e083b74d618b 100644
@@ -863,6 +863,16 @@ scheme's execution.
   completely tried to be applied.
 - ``max_nr_snapshots``: Upper limit of ``nr_snapshots``.
 
+``qt_exceeds`` is increased for schemes with set quotas when the quota is found
+full at a quota reset interval boundary.  While the quotas are unset,
+``qt_exceeds`` never increased.  However, a zero effective size quota does not
+always mean the quotas are unset, if the ``temporal`` :ref:`auto-tuning
+algorithm <damon_design_damos_quotas_auto_tuning>` is used, the effective size
+quota is set to zero once the goal is [over-]achieved.  Since a set quota of
+zero effective size is always considered full, ``qt_exceeds`` keeps being
+increased once per quota reset interval in that case, until the goal is
+under-achieved again.
+
 "A scheme is tried to be applied to a region" means DAMOS core logic determined
 the region is eligible to apply the scheme's :ref:`action
 <damon_design_damos_action>`.  The :ref:`access pattern
Signature · 1 line
2.55.0
#1 lore raw
Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [Low] Grammar and punctuation errors in the newly added documentation paragraph. --

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Grammar and punctuation errors in the newly added documentation paragraph. --

commit 25ab17e2d03e88ea28912107d200a293e1a57614
Author: Liew Rui Yan <[email protected]>

Docs/mm/damon/design: clarify when qt_exceeds increases

This commit updates the DAMON design documentation to clarify how qt_exceeds behaves when quotas are unset versus when they have a zero effective size quota due to the temporal auto-tuning algorithm.

Documentation/mm/damon/design.rst scheme's execution. · line 869

Quoted 12 lines
Documentation/mm/damon/design.rst +4 -0
index d036340dae8af..e083b74d618b5 100644
@@ -863,6 +863,16 @@ scheme's execution.
   completely tried to be applied.
 - ``max_nr_snapshots``: Upper limit of ``nr_snapshots``.
 
+``qt_exceeds`` is increased for schemes with set quotas when the quota is found
+full at a quota reset interval boundary.  While the quotas are unset,
+``qt_exceeds`` never increased.  However, a zero effective size quota does not
+always mean the quotas are unset, if the ``temporal`` :ref:`auto-tuning

[Severity: Low]
This isn't a bug, but would it be clearer to use the present tense ("never increases" or "is never increased") instead of "never increased" to match the surrounding text?

Additionally, would it be better to separate the comma splice before "if the ``temporal``" into two sentences?

Quoted 7 lines
Documentation/mm/damon/design.rst +6 -0
+algorithm <damon_design_damos_quotas_auto_tuning>` is used, the effective size
+quota is set to zero once the goal is [over-]achieved.  Since a set quota of
+zero effective size is always considered full, ``qt_exceeds`` keeps being
+increased once per quota reset interval in that case, until the goal is
+under-achieved again.
+
 "A scheme is tried to be applied to a region" means DAMOS core logic determined
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
#2 lore raw
Quoted 21 lines · On Tue, 08 Sep 2026 17:55:47 +0000 [email protected] wrote:

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Grammar and punctuation errors in the newly added documentation paragraph. --

commit 25ab17e2d03e88ea28912107d200a293e1a57614
Author: Liew Rui Yan <[email protected]>

Docs/mm/damon/design: clarify when qt_exceeds increases

This commit updates the DAMON design documentation to clarify how qt_exceeds behaves when quotas are unset versus when they have a zero effective size quota due to the temporal auto-tuning algorithm.

Quoted 8 lines
Documentation/mm/damon/design.rst +0 -0
index d036340dae8af..e083b74d618b5 100644
@@ -863,6 +863,16 @@ scheme's execution.
   completely tried to be applied.
 - ``max_nr_snapshots``: Upper limit of ``nr_snapshots``.
 
Quoted 9 lines

Documentation/mm/damon/design.rst scheme's execution. · line 869

Quoted 4 lines
Documentation/mm/damon/design.rst +4 -0
+``qt_exceeds`` is increased for schemes with set quotas when the quota is found
+full at a quota reset interval boundary.  While the quotas are unset,
+``qt_exceeds`` never increased.  However, a zero effective size quota does not
+always mean the quotas are unset, if the ``temporal`` :ref:`auto-tuning

[Severity: Low]
This isn't a bug, but would it be clearer to use the present tense ("never increases" or "is never increased") instead of "never increased" to match the surrounding text?

Thank you for pointing this out!

Yes, "never increases" may be clearer.

Quoted 3 lines

Additionally, would it be better to separate the comma splice before "if the ``temporal``" into two sentences?

If this is okay, I will change to:

[...] quotas are unset. Specifically, when the ``temporal`` [...]

Quoted 12 lines
Quoted 8 lines
Documentation/mm/damon/design.rst +6 -0
+algorithm <damon_design_damos_quotas_auto_tuning>` is used, the effective size
+quota is set to zero once the goal is [over-]achieved.  Since a set quota of
+zero effective size is always considered full, ``qt_exceeds`` keeps being
+increased once per quota reset interval in that case, until the goal is
+under-achieved again.
+
 "A scheme is tried to be applied to a region" means DAMOS core logic determined
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1

Best regards,
Rui Yan

maintainer
#3 lore raw
In reply to Liew Rui Yan

Hi Liew,

Quoted 6 lines · On Wed, 9 Sep 2026 01:50:23 +0800 Liew Rui Yan <[email protected]>…

qt_exceeds counts how many times the quota of a scheme has exceeded.

The value can confuse users when the effective size quota is zero, because a zero effective size quota does not always mean the quotas are unset.

Quoted 8 lines

If the quotas are unset, that is, both ms and bytes are zero and no quota goal is set, qt_exceeds never increases. But if the user uses the temporal auto-tuning algorithm, the effective size quota becomes zero once the goal is [over-]achieved. In that case the quotas are still set, so qt_exceeds keeps increasing once per quota reset interval while the goal stays achieved.

Clarify this on the design document.

Thank you for keep working on this with patience.

Quoted 13 lines

---

By the way, I found a thing in the design document that confused me.

temporal: More straightforward algorithm. Tries to achieve the goal as fast as possible, using maximum allowed quota, but only for a temporal short time. ---> When the quota is under-achieved, this algorithm keeps tuning quota to a maximum allowed one. Once the quota is [over]-achieved <---, this sets the quota zero. Useful for deterministic control required environments.

Quoted 5 lines

I'm not sure if "goal" was accidentally written as "quota" here. Would this be better?

When the goal is under-achieved, this algorithm keeps tuning quota to a maximum allowed one. Once the goal is [over-]achieved, [...]

Good eyes! Yes, seems it was only mistakenly written in the way. Please feel free to send a separate patch or include it into the next version of this patch, whatever better for you.

Quoted 16 lines
---
 Documentation/mm/damon/design.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/mm/damon/design.rst +3 -0
index d036340dae8a..e083b74d618b 100644
@@ -863,6 +863,16 @@ scheme's execution.
   completely tried to be applied.
 - ``max_nr_snapshots``: Upper limit of ``nr_snapshots``.
 
+``qt_exceeds`` is increased for schemes with set quotas when the quota is found
+full at a quota reset interval boundary.  While the quotas are unset,
+``qt_exceeds`` never increased.  However, a zero effective size quota does not

Documentation/mm/damon/design.rst scheme's execution. · line 878

Quoted 10 lines
Documentation/mm/damon/design.rst +7 -0
+always mean the quotas are unset, if the ``temporal`` :ref:`auto-tuning
+algorithm <damon_design_damos_quotas_auto_tuning>` is used, the effective size
+quota is set to zero once the goal is [over-]achieved.  Since a set quota of
+zero effective size is always considered full, ``qt_exceeds`` keeps being
+increased once per quota reset interval in that case, until the goal is
+under-achieved again.
+
 "A scheme is tried to be applied to a region" means DAMOS core logic determined
 the region is eligible to apply the scheme's :ref:`action
 <damon_design_damos_action>`.  The :ref:`access pattern

I think the clarification is better to be added to the 'temporal' quota tuner, since this happens only when it is used. Maybe the clarification could also be shorter. For example,

'''

Documentation/mm/damon/design.rst +3 -1
@@ -775,7 +775,9 @@ There are two such tuning algorithms that users can select as they need.
   fast as possible, using maximum allowed quota, but only for a temporal short
   time.  When the quota is under-achieved, this algorithm keeps tuning quota to
   a maximum allowed one.  Once the quota is [over]-achieved, this sets the
-  quota zero.  Useful for deterministic control required environments.
+  quota zero.  Useful for deterministic control required environments.  Note
+  that the zero quota is a valid quota, and therefore ``qt_exceeds`` :ref:`stat
+  <damon_design_damos_stat>` will keep increasing in the case.
 
 The goal can be specified with five parameters, namely ``target_metric``,
 ``target_value``, ``current_value``, ``nid`` and ``path``.  The auto-tuning

'''

What do you think, Liew?

Thanks,
SJ

[...]

#4 lore raw
Quoted 37 lines · On Tue, 08 Sep 2026 17:38:00 -0700 SJ Park <[email protected]> wrote:

Hi Liew,

Quoted 6 lines · On Wed, 9 Sep 2026 01:50:23 +0800 Liew Rui Yan <[email protected]>…

qt_exceeds counts how many times the quota of a scheme has exceeded.

The value can confuse users when the effective size quota is zero, because a zero effective size quota does not always mean the quotas are unset.

Quoted 8 lines

If the quotas are unset, that is, both ms and bytes are zero and no quota goal is set, qt_exceeds never increases. But if the user uses the temporal auto-tuning algorithm, the effective size quota becomes zero once the goal is [over-]achieved. In that case the quotas are still set, so qt_exceeds keeps increasing once per quota reset interval while the goal stays achieved.

Clarify this on the design document.

Thank you for keep working on this with patience.

Quoted 16 lines

---

By the way, I found a thing in the design document that confused me.

temporal: More straightforward algorithm. Tries to achieve the goal as fast as possible, using maximum allowed quota, but only for a temporal short time. ---> When the quota is under-achieved, this algorithm keeps tuning quota to a maximum allowed one. Once the quota is [over]-achieved <---, this sets the quota zero. Useful for deterministic control required environments.

I'm not sure if "goal" was accidentally written as "quota" here. Would this be better?

Quoted 6 lines
Quoted 2 lines

When the goal is under-achieved, this algorithm keeps tuning quota to a maximum allowed one. Once the goal is [over-]achieved, [...]

Good eyes! Yes, seems it was only mistakenly written in the way. Please feel free to send a separate patch or include it into the next version of this patch, whatever better for you.

I will send a separate patch.

Quoted 48 lines
Quoted 17 lines

---
 Documentation/mm/damon/design.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/mm/damon/design.rst +3 -0
index d036340dae8a..e083b74d618b 100644
@@ -863,6 +863,16 @@ scheme's execution.
   completely tried to be applied.
 - ``max_nr_snapshots``: Upper limit of ``nr_snapshots``.
 
+``qt_exceeds`` is increased for schemes with set quotas when the quota is found
+full at a quota reset interval boundary.  While the quotas are unset,
+``qt_exceeds`` never increased.  However, a zero effective size quota does not

Documentation/mm/damon/design.rst scheme's execution. · line 878

Quoted 10 lines
Documentation/mm/damon/design.rst +7 -0
+always mean the quotas are unset, if the ``temporal`` :ref:`auto-tuning
+algorithm <damon_design_damos_quotas_auto_tuning>` is used, the effective size
+quota is set to zero once the goal is [over-]achieved.  Since a set quota of
+zero effective size is always considered full, ``qt_exceeds`` keeps being
+increased once per quota reset interval in that case, until the goal is
+under-achieved again.
+
 "A scheme is tried to be applied to a region" means DAMOS core logic determined
 the region is eligible to apply the scheme's :ref:`action
 <damon_design_damos_action>`.  The :ref:`access pattern

I think the clarification is better to be added to the 'temporal' quota tuner, since this happens only when it is used. Maybe the clarification could also be shorter. For example,

'''

Documentation/mm/damon/design.rst +3 -1
@@ -775,7 +775,9 @@ There are two such tuning algorithms that users can select as they need.
   fast as possible, using maximum allowed quota, but only for a temporal short
   time.  When the quota is under-achieved, this algorithm keeps tuning quota to
   a maximum allowed one.  Once the quota is [over]-achieved, this sets the
-  quota zero.  Useful for deterministic control required environments.
+  quota zero.  Useful for deterministic control required environments.  Note
+  that the zero quota is a valid quota, and therefore ``qt_exceeds`` :ref:`stat
+  <damon_design_damos_stat>` will keep increasing in the case.
 
 The goal can be specified with five parameters, namely ``target_metric``,
 ``target_value``, ``current_value``, ``nid`` and ``path``.  The auto-tuning

'''

Quoted 1 line

What do you think, Liew?

I agree that would be better. Although users might look up the definition of qt_exceeds first, they are also likely to navigate directly to the temporal section.

I will clarify at the temporal section in the next revision.

Best regards,
Rui Yan

maintainer
#5 lore raw
Quoted 5 lines · On Wed, 9 Sep 2026 18:07:33 +0800 Liew Rui Yan <[email protected]>…
Quoted 3 lines · On Tue, 08 Sep 2026 17:38:00 -0700 SJ Park <[email protected]> wrote:

Hi Liew,

On Wed, 9 Sep 2026 01:50:23 +0800 Liew Rui Yan <[email protected]> wrote:

[...]

Quoted 12 lines
Quoted 12 lines
Quoted 12 lines

By the way, I found a thing in the design document that confused me.

temporal: More straightforward algorithm. Tries to achieve the goal as fast as possible, using maximum allowed quota, but only for a temporal short time. ---> When the quota is under-achieved, this algorithm keeps tuning quota to a maximum allowed one. Once the quota is [over]-achieved <---, this sets the quota zero. Useful for deterministic control required environments.

I'm not sure if "goal" was accidentally written as "quota" here. Would this be better?

Quoted 8 lines
Quoted 6 lines
Quoted 2 lines

When the goal is under-achieved, this algorithm keeps tuning quota to a maximum allowed one. Once the goal is [over-]achieved, [...]

Good eyes! Yes, seems it was only mistakenly written in the way. Please feel free to send a separate patch or include it into the next version of this patch, whatever better for you.

I will send a separate patch.

Makes sense to me.

[...]

Quoted 3 lines
Quoted 3 lines

I think the clarification is better to be added to the 'temporal' quota tuner, since this happens only when it is used. Maybe the clarification could also be shorter. For example,

[...]

Quoted 5 lines

I agree that would be better. Although users might look up the definition of qt_exceeds first, they are also likely to navigate directly to the temporal section.

I will clarify at the temporal section in the next revision.

Thank you. Looking forward to patches.

Thanks,
SJ

[...]