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

[Liew Rui Yan <aethernet65535@gmail.com>]

On Tue, 08 Sep 2026 17:38:00 -0700 SJ Park <sj@kernel.org> wrote:

> Hi Liew,
> 
> On Wed,  9 Sep 2026 01:50:23 +0800 Liew Rui Yan <aethernet65535@gmail.com> wrote:
> 
> > 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.
> 
> Thank you for keep working on this with patience.
> 
> > 
> > Signed-off-by: Liew Rui Yan <aethernet65535@gmail.com>
> > ---
> > 
> > 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, [...]
> 
> 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.

> 
> > 
> > ---
> >  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
> 
> 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,
> 
> '''
> --- a/Documentation/mm/damon/design.rst
> +++ b/Documentation/mm/damon/design.rst
> @@ -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?

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