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

[Liew Rui Yan]

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.

Signed-off-by: Liew Rui Yan <aethernet65535@xxxxxxxxx>
---

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

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index d036340dae8a..e083b74d618b 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -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
-- 
2.55.0