Series comparison

-[PATCH 0/8] mm/damon: auto-tune aggregation interval
+[RFC PATCH 0/8] mm/damon: auto-tune aggregation interval
 ...
 repeatable tries, it can be a good job for machines.
 Based on the guideline's theory, we design an automation of aggregation
 interval tuning, in a way similar to that of camera auto-exposure
 feature.  It defines the amount of interesting information as the ratio
-of DAMON-observed access events that DAMON actually observed to
+of captured access events to total capturing attempts of single snapshot,
-theoretical maximum amount of it within each snapshot.  Events are
+or more technically speaking, the ratio of positive access check samples
-accounted in byte and sampling attempts granularity.  For example, let's
+to total samples within the aggregation interval.  It allows the users
-say there is a region of 'X' bytes size.  DAMON tried access check
+to set the target value of the ratio.  Once the target is set, the
-smapling for the region 'Y' times in total for a given aggregation.
+automation periodically measures the current value of the ratio and
-Among the 'Y' attempts, 'Z' times it shown positive results.  Then, the
+increase or decrease the aggregation interval if the ratio value is
-theoritical maximum number of access events for the region is 'X * Y'.
+lower or higher than the target.  The amount of the change is proportion
-And the number of access events that DAMON has observed for the region
+to the distance between current value and the target value.
 is 'X * Z'.  The abount of the interesting information is
 '(X * Z / X * Y)'.  Note that each snapshot would have multiple regions.
-Users can set an arbitrary value of the ratio as their target.  Once the
+To avoid auto-tuning goes too long way, let users set minimum and
-target is set, the automation periodically measures the current value of
+maximum aggregation interval time.  Changing only aggregation interval
-the ratio and increase or decrease the aggregation interval if the ratio
+while sampling interval is kept make the maximum level of access
-value is lower or higher than the target.  The amount of the change is
+frequency in each snapshot, or discernment of regions inconsistent.
-proportion to the distance between the current adn the target values.
+Also, unnecessarily short sampling interval causes meaningless
+monitoring overhed.  The automation therefore adjusts the sampling
-To avoid auto-tuning goes too long way, let users set the minimum and
+interval together with aggregation interval, while keeping the ratio
-the maximum aggregation interval times.  Changing only aggregation
+between the two intervals.  Users can set the ratio, or the discernment.
 interval while sampling interval is kept makes the maximum level of
 access frequency in each snapshot, or discernment of regions
 inconsistent.  Also, unnecessarily short sampling interval causes
 meaningless monitoring overhed.  The automation therefore adjusts the
 sampling interval together with aggregation interval, while keeping the
 ratio between the two intervals.  Users can set the ratio, or the
 discernment.
 Discussion
 ==========
-The modified question (aimed amount of access events, or lights, in each
+The modified question (aimed amount of heats in each snapshot) is easy
-snapshot) is easy to answer by both the users and the kernel.  If users
+to answer by both the users and the kernel.  If users are interested in
-are interested in finding more cold regions, the value should be lower,
+finding more cold regions, the value should be lower, and vice versa.
-and vice versa.  If users have no idea, kernel can suggest a fair
+If users have no idea, kernel can suggest about 20% positive access
-default value based on some theories and experiments.  For example,
+samples ratio as a fair default value based on the Pareto principle.
 based on the Pareto principle (80/20 rule), we could expect 20% target
 ratio will capture 80% of real access events.  Since 80% might be too
 high, applying the rule once again, 4% (20% * 20%) may capture about 56%
 (80% * 80%) of real access events.
 Sampling to aggregation intervals ratio and min/max aggregation
 intervals are also arguably easy to answer.  What users want is
 discernment of regions for efficient system operation, for examples, X
 amount of colder regions or Y amount of warmer regions, not exactly how
 many times each cache line is accessed in nanoseconds degree.  The
 appropriate min/max aggregation interval can relatively naively set, and
 may better to set for aimed monitoring overhead.  Since sampling
-interval is directly deciding the overhead, setting it based on the
+interval is directly related with the overhead, setting it based on the
 sampling interval can be easy.  With my experiences, I'd argue the
 intervals ratio 0.05, and 5 milliseconds to 20 seconds sampling interval
 range (100 milliseconds to 400 seconds aggregation interval) can be a
-good default suggestion.
+good default suggestions.
 Evaluation
 ==========
-On a machine running a real world server workload, I ran DAMON to
+We confirmed the tuning works as expected with only a few simple
-monitor its physical address space for about 23 hours, with this feature
+workloads including kernel builds, and that's why this is an RFC.  We
-turned on.  We set it to tune sampling interval in a range from 5
+will conduct more evaluations with more massive and realistic workloads
-milliseconds to 10 seconds, aiming 4 % DAMON-observed access ratio per
+and share the results by the time that we drop the RFC tag.
 three aggregation intervals.  The exact command I used is as below.
     damo start --monitoring_intervals_goal 4% 3 5ms 10s --damos_action stat
 During the test run, DAMON continuously updated sampling and aggregation
 intervals as designed, within the given range.  For all the time, DAMON
 was able to find the intervals that meets the target access events ratio
 in the given intervals range (sampling interval between 5 milliseconds
 and 10 seconds).
 For most of the time, tuned sampling interval was converged in 300-400
 milliseconds.  It made only small amount of changes within the range.
 The average of the tuned sampling interval during the test was about 380
 milliseconds.
 The workload periodically gets less load and decreases its CPU usage.
 Presumably this also caused it making less memory access events.
 Reactively to such event,s DAMON also increased the intervals as
 expected.  It was still able to find the optimum interval that
 satisfying the target access ratio within the given intervals range.
 Usually it was converged to about 5 seconds.  Once the workload gets
 normal amount of load again, DAMON reactively reduced the intervals to
 the normal range.
 I collected and visualized DAMON's monitoring results on the server a
 few times.  Every time the visualized access pattern looked not biased
 to only cold or hot pages but diverse and balanced.  Let me show some of
 the snapshots that I collected at the nearly end of the test (after
 about 23 hours have passed since starting DAMON on the server).
 The recency histogram looks as below.  Please note that this
 visualization shows only a very coarse grained information.  For more
 details about the visualization format, please refer to DAMON user-space
 tool documentation[1].
     # ./damo report access --style recency-sz-hist --tried_regions_of 0 0 0 --access_rate 0 0
     <last accessed time (us)> <total size>
     [-19 h 7 m 45.514 s, -17 h 12 m 58.963 s)  6.198 GiB  |****                |
     [-17 h 12 m 58.963 s, -15 h 18 m 12.412 s) 0 B        |                    |
     [-15 h 18 m 12.412 s, -13 h 23 m 25.860 s) 0 B        |                    |
     [-13 h 23 m 25.860 s, -11 h 28 m 39.309 s) 0 B        |                    |
     [-11 h 28 m 39.309 s, -9 h 33 m 52.757 s)  0 B        |                    |
     [-9 h 33 m 52.757 s, -7 h 39 m 6.206 s)    0 B        |                    |
     [-7 h 39 m 6.206 s, -5 h 44 m 19.654 s)    0 B        |                    |
     [-5 h 44 m 19.654 s, -3 h 49 m 33.103 s)   0 B        |                    |
     [-3 h 49 m 33.103 s, -1 h 54 m 46.551 s)   0 B        |                    |
     [-1 h 54 m 46.551 s, -0 ns)                16.967 GiB |*********           |
     [-0 ns, --6886551440000 ns)                38.835 GiB |********************|
     memory bw estimate: 9.425 GiB per second
     total size: 62.000 GiB
 It shows about 38 GiB of memory was accessed at least once within last
 aggregation interval (given ~300 milliseconds tuned sampling interval,
 this is about six seconds).  This is about 61 % of the total memory.  In
 other words, DAMON found warmest 61 % memory of the system.  The number
 is particularly interesting given our Pareto principle based theory for
 the tuning goal value.  We set it as 20 % of 20 % (4 %), thinking it
 would capture 80 % of 80 % (64 %) real access events.  And it foudn 61 %
 hot memory, or working set.  Nevertheless, to make the theory clearer,
 much more discussion and tests would be needed.  At the moment,
 nonetheless, we can say making the target value higher helps finding
 more hot memory regions.
 The histogram also shows an amount of cold memory.  About 17 GiB memory
 of the system has not accessed at least for last aggregation interval
 (about six seconds), and at most for about last two hours.  The real
 longest unaccessed time of the 17 GiB memory was about 19 minutes,
 though.  This is a limitation of this visualization format.
 It further found very cold 6 GiB memory.  It has not accessed at least for last
 hours and at most 19 hours.
 What about hot memory distribution?  To see this, I capture and
 visualize the snapshot in access temperature histogram.  Again, please
 refer to the DAMON user-space tool documentation[1] for the format and
 what access temperature mean.   Both the visualization and metric shows
 only very coarse grained and limited information.  The resulting
 histogram look like below.
     # ./damo report access --style temperature-sz-hist --tried_regions_of 0 0 0
     <temperature> <total size>
     [-6,840,763,776,000, -5,501,580,939,800) 6.198 GiB  |***                 |
     [-5,501,580,939,800, -4,162,398,103,600) 0 B        |                    |
     [-4,162,398,103,600, -2,823,215,267,400) 0 B        |                    |
     [-2,823,215,267,400, -1,484,032,431,200) 0 B        |                    |
     [-1,484,032,431,200, -144,849,595,000)   0 B        |                    |
     [-144,849,595,000, 1,194,333,241,200)    55.802 GiB |********************|
     [1,194,333,241,200, 2,533,516,077,400)   4.000 KiB  |*                   |
     [2,533,516,077,400, 3,872,698,913,600)   4.000 KiB  |*                   |
     [3,872,698,913,600, 5,211,881,749,800)   8.000 KiB  |*                   |
     [5,211,881,749,800, 6,551,064,586,000)   12.000 KiB |*                   |
     [6,551,064,586,000, 7,890,247,422,200)   4.000 KiB  |*                   |
     memory bw estimate: 5.178 GiB per second
     total size: 62.000 GiB
 We can see most of the memory is in similar access temperature range,
 and definitely some pages are extremely hot.
 To see the picture in more detail, let's capture and visualize the
 snapshot per DAMON-region, sorted by their access temperature.  The
 total number of the regions was about 300.  Due to the limited space,
 I'm showing only a few parts of the output here.
     # ./damo report access --style hot --tried_regions_of 0 0 0
     heatmap: 00000000888888889999999888888888888888888888888888888888888888888888888888888888
     # min/max temperatures: -6,827,258,184,000, 17,589,052,500, column size: 793.600 MiB
      |999999999999999999999999999999999999999| 4.000 KiB   access 100 % 18 h 9 m 43.918 s
      |999999999999999999999999999999999999999| 8.000 KiB   access 100 % 17 h 56 m 5.351 s
      |999999999999999999999999999999999999999| 4.000 KiB   access 100 % 15 h 24 m 19.634 s
      |999999999999999999999999999999999999999| 4.000 KiB   access 100 % 14 h 10 m 55.606 s
      |999999999999999999999999999999999999999| 4.000 KiB   access 100 % 11 h 34 m 18.993 s
     [...]
                |99999999999999999999999999999| 8.000 KiB   access 100 % 1 m 27.945 s
                |11111111111111111111111111111| 80.000 KiB  access 15 %  1 m 21.180 s
                |00000000000000000000000000000| 24.000 KiB  access 5 %   1 m 21.180 s
                |00000000000000000000000000000| 5.919 GiB   access 10 %  1 m 14.415 s
                |99999999999999999999999999999| 12.000 KiB  access 100 % 1 m 7.650 s
     [...]
                                            |0| 4.000 KiB   access 5 %   0 ns
                                            |0| 12.000 KiB  access 5 %   0 ns
                                            |0| 188.000 KiB access 0 %   0 ns
                                            |0| 24.000 KiB  access 0 %   0 ns
                                            |0| 48.000 KiB  access 0 %   0 ns
     [...]
              |0000000000000000000000000000000| 8.000 KiB   access 0 %   6 m 45.901 s
             |00000000000000000000000000000000| 36.000 KiB  access 0 %   7 m 26.491 s
             |00000000000000000000000000000000| 4.000 KiB   access 0 %   12 m 37.682 s
            |000000000000000000000000000000000| 8.000 KiB   access 0 %   18 m 9.168 s
            |000000000000000000000000000000000| 16.000 KiB  access 0 %   19 m 3.288 s
     |0000000000000000000000000000000000000000| 6.198 GiB   access 0 %   18 h 57 m 52.582 s
     memory bw estimate: 8.798 GiB per second
     total size: 62.000 GiB
 We can see DAMON found small and extremely hot regions that accessed for
 all access check sampling (once per about 300 milliseconds) for more
 than  10 hours.  The access temperature rapidly decreases.  DAMON was
 also able to find small and big regions that not accessed for up to
 about 19 minutes.  It even found an outlier cold region of 6 GiB that
 not accessed for about 19 hours.  It is unclear what the outlier region
 is, as of this writing.
 For the testing, DAMON was consuming about 0.1% of single CPU time.
 This is again expected results, since DAMON was using about 370
 milliseconds sampling interval in most case.
     # ps -p $kdamond_pid -o %cpu
     %CPU
 .1
 I also ran similar tests against kernel build workload and an in-memory
 cache workload benchmark[2].  Detialed results including tuned intervals
 and captured access pattern were of course different sicne those depend
 on the workloads.  But the auto-tuning feature was always working as
 expected like the above results for the real world workload.
 To wrap up, with intervals auto-tuning feature, DAMON was able to
 capture access pattern snapshots of a quality on a real world server
 workload.  The auto-tuning feature was able to adaptively react to the
 dynamic access patterns of the workload and reliably provide consistent
 monitoring results without manual human interventions.  Also, the
 auto-tuning made DAMON consumes only necessary amount of resource for
 the required quality.
 Changelog
 =========
 Changes from RFC v2
 (https://lore.kernel.org/20250228220328.49438-1-sj@kernel.org)
 - Add detailed evaluation results on cover letter
 Changes from RFC v1
 (https://lore.kernel.org/20250213014438.145611-1-sj@kernel.org)
 - Replace the target metric from positive samples ratio to
   DAMON-observed access samples ratio
 - Fix wrong max events accounting bug
 - Fix double-increase of next_aggregation_sis
 References
 ==========
 [1] https://github.com/damonitor/damo/blob/next/USAGE.md#access-report-styles
 [2] https://github.com/facebookresearch/DCPerf/blob/main/packages/tao_bench/README.md
 SeongJae Park (8):
   mm/damon: add data structure for monitoring intervals auto-tuning
   mm/damon/core: implement intervals auto-tuning
   mm/damon/sysfs: implement intervals tuning goal directory
 ...
   Docs/admin-guide/mm/damon/usage: add intervals_goal directory on the
     hierarchy
  .../ABI/testing/sysfs-kernel-mm-damon         |  30 +++
  Documentation/admin-guide/mm/damon/usage.rst  |  25 ++
- Documentation/mm/damon/design.rst             |  50 ++++
+ Documentation/mm/damon/design.rst             |  38 +++
  include/linux/damon.h                         |  43 ++++
- mm/damon/core.c                               |  98 ++++++++
+ mm/damon/core.c                               |  90 ++++++++
  mm/damon/sysfs.c                              | 216 ++++++++++++++++++
-files changed, 462 insertions(+)
+files changed, 442 insertions(+)
-base-commit: 2ade695ab17eb4005f006001aa9c51ad22d2f206
+base-commit: d5c35650f4945e1406871f9d9d51ab8c54ec0d03
 --
 .39.5

-[PATCH 1/8] mm/damon: add data structure for monitoring intervals auto-tuning
+[RFC PATCH 1/8] mm/damon: add data structure for monitoring intervals auto-tuning
-Add data structures for DAMON sampling and aggregation intervals
+Add data structures for using DAMON sampling and aggregation intervals
-automatic tuning that aims specific amount of DAMON-observed access
+automatic tuning aiming specific amount of access events per snapshot.
-events per snapshot.  In more detail, define the data structure for the
+Specificaslly, define a data structure to define the tuning goal, namely
-tuning goal, link it to the monitoring attributes data structure so that
+target ratio of positive access check samples, link it to monitoring
-DAMON kernel API callers can make the request, and update parameters
+attributes data structure so that DAMON kernel API users can make the
-setup DAMON function to respect the new parameter.
+request, and update parameters setup DAMON function to respect the new
 data.
 Signed-off-by: SeongJae Park <sj@kernel.org>
 ---
  include/linux/damon.h | 27 +++++++++++++++++++++++++++
  mm/damon/core.c       | 22 ++++++++++++++++++++++
 ...
  };
 +/**
 + * struct damon_intervals_goal - Monitoring intervals auto-tuning goal.
 + *
-+ * @access_bp:        Access events observation ratio to achieve in bp.
++ * @samples_bp:        Positive access check samples ratio to achieve.
-+ * @aggrs:        Number of aggregations to acheive @access_bp within.
++ * @aggrs:        Number of aggregations to acheive @samples_bp within.
 + * @min_sample_us:    Minimum resulting sampling interval in microseconds.
 + * @max_sample_us:    Maximum resulting sampling interval in microseconds.
 + *
 + * DAMON automatically tunes &damon_attrs->sample_interval and
-+ * &damon_attrs->aggr_interval aiming the ratio in bp (1/10,000) of
++ * &damon_attrs->aggr_interval aiming the ratio in bp (1/10,000) of access
-+ * DAMON-observed access events to theoretical maximum amount within @aggrs
++ * check samples that shown positive result (was accessed) to total samples
-+ * aggregations be same to @access_bp.  The logic increases
++ * within @aggrs aggregations be same to @samples_bp.  The logic increases
 + * &damon_attrs->aggr_interval and &damon_attrs->sampling_interval in same
-+ * ratio if the current access events observation ratio is lower than the
++ * ratio if the current positive access samples ratio is lower than the target
-+ * target for each @aggrs aggregations, and vice versa.
++ * for each @aggrs aggregations, and vice versa.
 + *
 + * If @aggrs is zero, the tuning is disabled and hence this struct is ignored.
 + */
 +struct damon_intervals_goal {
-+    unsigned long access_bp;
++    unsigned long samples_bp;
 +    unsigned long aggrs;
 +    unsigned long min_sample_us;
 +    unsigned long max_sample_us;
 +};
 +
 ...

-[PATCH 2/8] mm/damon/core: implement intervals auto-tuning
+[RFC PATCH 2/8] mm/damon/core: implement intervals auto-tuning
 Implement the DAMON sampling and aggregation intervals auto-tuning
-mechanism as briefly described on 'struct damon_intervals_goal'.  The
+mechanism as designed on the cover letter of this patch series.  The
-core part for deciding the direction and amount of the changes is
+mechanism reuses the feedback loop function for DAMOS quotas
-implemented reusing the feedback loop function which is being used for
+auto-tuning.  Unlike the DAMOS quotas auto-tuning use case, limit the
-DAMOS quotas auto-tuning.  Unlike the DAMOS quotas auto-tuning use case,
+maximum decreasing amount after the adjustment to 50% of the current
-limit the maximum decreasing amount after the adjustment to 50% of the
+value.  This is because the intervals have no good merits at rapidly
-current value, though.  This is because the intervals have no good
+reducing, and it is assumed the user will set the range of tunable
-merits at rapid reductions since it could unnecessarily increase the
+values not very wide.
 monitoring overhead.
 Signed-off-by: SeongJae Park <sj@kernel.org>
 ---
- include/linux/damon.h | 16 +++++++++
+ include/linux/damon.h | 16 ++++++++++
- mm/damon/core.c       | 76 +++++++++++++++++++++++++++++++++++++++++++
+ mm/damon/core.c       | 68 +++++++++++++++++++++++++++++++++++++++++++
-files changed, 92 insertions(+)
+files changed, 84 insertions(+)
 diff --git a/include/linux/damon.h b/include/linux/damon.h
 index XXXXXXX..XXXXXXX 100644
 --- a/include/linux/damon.h
 +++ b/include/linux/damon.h
 ...
      ctx->next_ops_update_sis = ctx->passed_sample_intervals +
 @@ -XXX,XX +XXX,XX @@ static void kdamond_reset_aggregated(struct damon_ctx *c)
      }
  }
-+static unsigned long damon_get_intervals_score(struct damon_ctx *c)
-+{
-+    struct damon_target *t;
-+    struct damon_region *r;
-+    unsigned long sz_region, max_access_events = 0, access_events = 0;
-+    unsigned long target_access_events;
-+    unsigned long goal_bp = c->attrs.intervals_goal.access_bp;
-+
-+    damon_for_each_target(t, c) {
-+        damon_for_each_region(r, t) {
-+            sz_region = damon_sz_region(r);
-+            max_access_events += sz_region * c->attrs.aggr_samples;
-+            access_events += sz_region * r->nr_accesses;
-+        }
-+    }
-+    target_access_events = max_access_events * goal_bp / 10000;
-+    return access_events * 10000 / target_access_events;
-+}
-+
 +static unsigned long damon_feed_loop_next_input(unsigned long last_input,
 +        unsigned long score);
 +
 +static unsigned long damon_get_intervals_adaptation_bp(struct damon_ctx *c)
 +{
-+    unsigned long score_bp, adaptation_bp;
++    struct damon_target *t;
 +    struct damon_region *r;
 +    unsigned long nr_regions = 0, access_samples = 0;
 +    struct damon_intervals_goal *goal = &c->attrs.intervals_goal;
 +    unsigned long max_samples, target_samples, score_bp;
 +    unsigned long adaptation_bp;
 +
-+    score_bp = damon_get_intervals_score(c);
++    damon_for_each_target(t, c) {
 +        nr_regions = damon_nr_regions(t);
 +        damon_for_each_region(r, t)
 +            access_samples += r->nr_accesses;
 +    }
 +    max_samples = nr_regions * c->attrs.aggr_samples;
 +    target_samples = max_samples * goal->samples_bp / 10000;
 +    score_bp = access_samples * 10000 / target_samples;
 +    adaptation_bp = damon_feed_loop_next_input(100000000, score_bp) /
 +        10000;
 +    /*
 +     * adaptaion_bp ranges from 1 to 20,000.  Avoid too rapid reduction of
 +     * the intervals by rescaling [1,10,000] to [5000, 10,000].
 +     */
 +    if (adaptation_bp <= 10000)
 +        adaptation_bp = 5000 + adaptation_bp / 2;
++
 +    return adaptation_bp;
 +}
 +
 +static void kdamond_tune_intervals(struct damon_ctx *c)
 +{
 ...
 +    if (adaptation_bp == 10000)
 +        return;
 +
 +    new_attrs = c->attrs;
 +    goal = &c->attrs.intervals_goal;
-+    new_attrs.sample_interval = min(goal->max_sample_us,
++    new_attrs.sample_interval = min(
-+            c->attrs.sample_interval * adaptation_bp / 10000);
++            c->attrs.sample_interval * adaptation_bp / 10000,
-+    new_attrs.sample_interval = max(goal->min_sample_us,
++            goal->max_sample_us);
-+            new_attrs.sample_interval);
++    new_attrs.sample_interval = max(new_attrs.sample_interval,
 +            goal->min_sample_us);
 +    new_attrs.aggr_interval = new_attrs.sample_interval *
 +        c->attrs.aggr_samples;
 +    damon_set_attrs(c, &new_attrs);
 +}
 +
 ...
 +        ctx->attrs.intervals_goal.aggrs;
      damon_for_each_scheme(scheme, ctx) {
          apply_interval = scheme->apply_interval_us ?
 @@ -XXX,XX +XXX,XX @@ static int kdamond_fn(void *data)
-         sample_interval = ctx->attrs.sample_interval ?
-             ctx->attrs.sample_interval : 1;
          if (ctx->passed_sample_intervals >= next_aggregation_sis) {
+             ctx->next_aggregation_sis = next_aggregation_sis +
+                 ctx->attrs.aggr_interval / sample_interval;
 +            if (ctx->attrs.intervals_goal.aggrs &&
 +                    ctx->passed_sample_intervals >=
 +                    ctx->next_intervals_tune_sis) {
 +                ctx->next_intervals_tune_sis +=
 +                    ctx->attrs.aggr_samples *
 +                    ctx->attrs.intervals_goal.aggrs;
 +                kdamond_tune_intervals(ctx);
-+                sample_interval = ctx->attrs.sample_interval ?
-+                    ctx->attrs.sample_interval : 1;
-+
 +            }
-             ctx->next_aggregation_sis = next_aggregation_sis +
-                 ctx->attrs.aggr_interval / sample_interval;
+             kdamond_reset_aggregated(ctx);
+             kdamond_split_regions(ctx);
 --
 .39.5

-[PATCH 3/8] mm/damon/sysfs: implement intervals tuning goal directory
+[RFC PATCH 3/8] mm/damon/sysfs: implement intervals tuning goal directory
 Implement DAMON sysfs interface directory and its files for setting
-DAMON sampling and aggregation intervals auto-tuning goal.
+DAMON sampling and aggregation intervals auto-tuning goal.  Nearly all
 kernel API data structures that newly introduced for this new feature
 are directly exposed.
 Signed-off-by: SeongJae Park <sj@kernel.org>
 ---
  mm/damon/sysfs.c | 189 +++++++++++++++++++++++++++++++++++++++++++++++
 file changed, 189 insertions(+)
 ...
 + * intervals goal directory
 + */
 +
 +struct damon_sysfs_intervals_goal {
 +    struct kobject kobj;
-+    unsigned long access_bp;
++    unsigned long samples_bp;
 +    unsigned long aggrs;
 +    unsigned long min_sample_us;
 +    unsigned long max_sample_us;
 +};
 +
 +static struct damon_sysfs_intervals_goal *damon_sysfs_intervals_goal_alloc(
-+        unsigned long access_bp, unsigned long aggrs,
++        unsigned long samples_bp, unsigned long aggrs,
 +        unsigned long min_sample_us, unsigned long max_sample_us)
 +{
 +    struct damon_sysfs_intervals_goal *goal = kmalloc(sizeof(*goal),
 +            GFP_KERNEL);
 +
 +    if (!goal)
 +        return NULL;
 +
 +    goal->kobj = (struct kobject){};
-+    goal->access_bp = access_bp;
++    goal->samples_bp = samples_bp;
 +    goal->aggrs = aggrs;
 +    goal->min_sample_us = min_sample_us;
 +    goal->max_sample_us = max_sample_us;
 +    return goal;
 +}
 +
-+static ssize_t access_bp_show(struct kobject *kobj,
++static ssize_t samples_bp_show(struct kobject *kobj,
 +        struct kobj_attribute *attr, char *buf)
 +{
 +    struct damon_sysfs_intervals_goal *goal = container_of(kobj,
 +            struct damon_sysfs_intervals_goal, kobj);
 +
-+    return sysfs_emit(buf, "%lu\n", goal->access_bp);
++    return sysfs_emit(buf, "%lu\n", goal->samples_bp);
 +}
 +
-+static ssize_t access_bp_store(struct kobject *kobj,
++static ssize_t samples_bp_store(struct kobject *kobj,
 +        struct kobj_attribute *attr, const char *buf, size_t count)
 +{
 +    struct damon_sysfs_intervals_goal *goal = container_of(kobj,
 +            struct damon_sysfs_intervals_goal, kobj);
 +    unsigned long nr;
 +    int err = kstrtoul(buf, 0, &nr);
 +
 +    if (err)
 +        return err;
 +
-+    goal->access_bp = nr;
++    goal->samples_bp = nr;
 +    return count;
 +}
 +
 +static ssize_t aggrs_show(struct kobject *kobj,
 +        struct kobj_attribute *attr, char *buf)
 ...
 +static void damon_sysfs_intervals_goal_release(struct kobject *kobj)
 +{
 +    kfree(container_of(kobj, struct damon_sysfs_intervals_goal, kobj));
 +}
 +
-+static struct kobj_attribute damon_sysfs_intervals_goal_access_bp_attr =
++static struct kobj_attribute damon_sysfs_intervals_goal_samples_bp_attr =
-+        __ATTR_RW_MODE(access_bp, 0600);
++        __ATTR_RW_MODE(samples_bp, 0600);
 +
 +static struct kobj_attribute damon_sysfs_intervals_goal_aggrs_attr =
 +        __ATTR_RW_MODE(aggrs, 0600);
 +
 +static struct kobj_attribute damon_sysfs_intervals_goal_min_sample_us_attr =
 +        __ATTR_RW_MODE(min_sample_us, 0600);
 +
 +static struct kobj_attribute damon_sysfs_intervals_goal_max_sample_us_attr =
 +        __ATTR_RW_MODE(max_sample_us, 0600);
 +
 +static struct attribute *damon_sysfs_intervals_goal_attrs[] = {
-+    &damon_sysfs_intervals_goal_access_bp_attr.attr,
++    &damon_sysfs_intervals_goal_samples_bp_attr.attr,
 +    &damon_sysfs_intervals_goal_aggrs_attr.attr,
 +    &damon_sysfs_intervals_goal_min_sample_us_attr.attr,
 +    &damon_sysfs_intervals_goal_max_sample_us_attr.attr,
 +    NULL,
 +};
 ...

-[PATCH 4/8] mm/damon/sysfs: commit intervals tuning goal
+[RFC PATCH 4/8] mm/damon/sysfs: commit intervals tuning goal
 ...
          sys_attrs->nr_regions_range;
      struct damon_attrs attrs = {
          .sample_interval = sys_intervals->sample_us,
          .aggr_interval = sys_intervals->aggr_us,
 +        .intervals_goal = {
-+            .access_bp = sys_goal->access_bp,
++            .samples_bp = sys_goal->samples_bp,
 +            .aggrs = sys_goal->aggrs,
 +            .min_sample_us = sys_goal->min_sample_us,
 +            .max_sample_us = sys_goal->max_sample_us},
          .ops_update_interval = sys_intervals->update_us,
          .min_nr_regions = sys_nr_regions->min,
          .max_nr_regions = sys_nr_regions->max,
 --
 .39.5

-[PATCH 5/8] mm/damon/sysfs: implement a command to update auto-tuned monitoring intervals
+[RFC PATCH 5/8] mm/damon/sysfs: implement a command to update auto-tuned monitoring intervals
 DAMON kernel API callers can show auto-tuned sampling and aggregation
 intervals from the monmitoring attributes data structure.  That can be
 useful for debugging or tuning of the feature.  DAMON user-space ABI
 users has no way to see that, though.  Implement a new DAMON sysfs
-interface command, namely 'update_tuned_intervals', for the purpose.
+interface kdamond state command, namely 'update_tuned_intervals', for
-If the command is written to the kdamond state file, the tuned sampling
+the purpose.  Once the command is written to the kdamond state file, the
-and aggregation intervals will be updated to the corresponding sysfs
+tuned sampling and aggregation intervals will be updated to the
-interface files.
+corresponding sysfs interface.
 Signed-off-by: SeongJae Park <sj@kernel.org>
 ---
  mm/damon/sysfs.c | 20 ++++++++++++++++++++
 file changed, 20 insertions(+)
 ...

-[PATCH 6/8] Docs/mm/damon/design: document for intervals auto-tuning
+[RFC PATCH 6/8] Docs/mm/damon/design: document for intervals auto-tuning
-Document the design of DAMON sampling and aggregation intervals
+Document DAMON sampling and aggregation intervals auto-tuning design.
 auto-tuning.
 Signed-off-by: SeongJae Park <sj@kernel.org>
 ---
- Documentation/mm/damon/design.rst | 46 +++++++++++++++++++++++++++++++
+ Documentation/mm/damon/design.rst | 34 +++++++++++++++++++++++++++++++
-file changed, 46 insertions(+)
+file changed, 34 insertions(+)
 diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
 index XXXXXXX..XXXXXXX 100644
 --- a/Documentation/mm/damon/design.rst
 +++ b/Documentation/mm/damon/design.rst
 ...
 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 +
 +DAMON provides automatic tuning of the ``sampling interval`` and ``aggregation
 +interval`` based on the :ref:`the tuning guide idea
 +<damon_design_monitoring_params_tuning_guide>`.  The tuning mechanism allows
-+users to set the aimed amount of access events to observe via DAMON within
++users to set the aimed amount of heats to observe with DAMON within given time
-+given time interval.  The target can be specified by the user as a ratio of
++interval.  The target can be specified by the user as a ratio of access check
-+DAMON-observed access events to the theoretical maximum amount of the events
++samples that gave positive result to the total samples (``samples_bp``) that
-+(``access_bp``) that measured within a given number of aggregations
++measured within a given number of aggregations (``aggrs``).  The mechanism
-+(``aggrs``).
++calculates the ratio of access check samples for ``aggrs`` aggregations, and
-+
++increases or decrease the ``sampleing interval`` and ``aggregation interval``
-+The DAMON-observed access events are calculated in byte granularity based on
++in same ratio, if the samples ratio is lower or higher than the target,
-+DAMON :ref:`region assumption <damon_design_region_based_sample>`.  For
++respectively.  The ratio of the intervals change is decided in proportion to
-+example, if a region of size ``X`` bytes of ``Y`` ``nr_accesses`` is found, it
++the distance between current samples ratio and the target ratio.
 +means ``X * Y`` access events are observed by DAMON.  Theoretical maximum
 +access events for the region is calculated in same way, but replacing ``Y``
 +with theoretical maximum ``nr_accesses``, which can be calculated as
 +``aggregation interval / sampling interval``.
 +
 +The mechanism calculates the ratio of access events for ``aggrs`` aggregations,
 +and increases or decrease the ``sampleing interval`` and ``aggregation
 +interval`` in same ratio, if the observed access ratio is lower or higher than
 +the target, respectively.  The ratio of the intervals change is decided in
 +proportion to the distance between current samples ratio and the target ratio.
 +
 +The user can further set the minimum and maximum ``sampling interval`` that can
 +be set by the tuning mechanism using two parameters (``min_sample_us`` and
 +``max_sample_us``).  Because the tuning mechanism changes ``sampling interval``
 +and ``aggregation interval`` in same ratio always, the minimum and maximum
 +``aggregation interval`` after each of the tuning changes can automatically set
 +together.
 +
 +The tuning is turned off by default, and need to be set explicitly by the user.
-+As a rule of thumbs and the Parreto principle, 4% access samples ratio target
++As a rule of thumbs and the Parreto principle, 20% access samples ratio target
-+is recommended.  Note that Parreto principle (80/20 rule) has applied twice.
++is recommended.
 +That is, assumes 4% (20% of 20%) DAMON-observed access events ratio (source)
 +to capture 64% (80% multipled by 80%) real access events (outcomes).
 +
 +
  .. _damon_design_damos:
  Operation Schemes
 --
 .39.5

-[PATCH 7/8] Docs/ABI/damon: document intervals auto-tuning ABI
+[RFC PATCH 7/8] Docs/ABI/damon: document intervals auto-tuning ABI
 ...
 +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon
 @@ -XXX,XX +XXX,XX @@ Description:    Writing a value to this file sets the update interval of the
          DAMON context in microseconds as the value.  Reading this file
          returns the value.
-+What:        /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/access_bp
++What:        /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/samples_bp
 +Date:        Feb 2025
 +Contact:    SeongJae Park <sj@kernel.org>
 +Description:    Writing a value to this file sets the monitoring intervals
-+        auto-tuning target DAMON-observed access events ratio within
++        auto-tuning target positive access check samples ratio within
 +        the given time interval (aggrs in same directory), in bp
 +        (1/10,000).  Reading this file returns the value.
 +
 +What:        /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/aggrs
 +Date:        Feb 2025
 +Contact:    SeongJae Park <sj@kernel.org>
 +Description:    Writing a value to this file sets the time interval to achieve
-+        the monitoring intervals auto-tuning target DAMON-observed
++        the monitoring intervals auto-tuning target positive access
-+        access events ratio (access_bp in same directory) within.
++        check samples ratio (samples_bp in same directory) within.
 +        Reading this file returns the value.
 +
 +What:        /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/min_sample_us
 +Date:        Feb 2025
 +Contact:    SeongJae Park <sj@kernel.org>
 ...

-[PATCH 8/8] Docs/admin-guide/mm/damon/usage: add intervals_goal directory on the hierarchy
+[RFC PATCH 8/8] Docs/admin-guide/mm/damon/usage: add intervals_goal directory on the hierarchy
 ...
 +++ b/Documentation/admin-guide/mm/damon/usage.rst
 @@ -XXX,XX +XXX,XX @@ comma (",").
      │ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations
      │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/
      │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
-+    │ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us
++    │ │ │ │ │ │ │ intervals_goal/samples_bp,aggrs,min_sample_us,max_sample_us
      │ │ │ │ │ │ nr_regions/min,max
      │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
      │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target
 @@ -XXX,XX +XXX,XX @@ Users can write below commands for the kdamond to the ``state`` file.
  - ``off``: Stop running.
 ...
 +-------------------------------------------------------
 +
 +Under the ``intervals`` directory, one directory for automated tuning of
 +``sample_us`` and ``aggr_us``, namely ``intervals_goal`` directory also exists.
 +Under the directory, four files for the auto-tuning control, namely
-+``access_bp``, ``aggrs``, ``min_sample_us`` and ``max_sample_us`` exist.
++``samples_bp``, ``aggrs``, ``min_sample_us`` and ``max_sample_us`` exist.
 +Please refer to  the :ref:`design document of the feature
 +<damon_design_monitoring_intervals_autotuning>` for the internal of the tuning
 +mechanism.  Reading and writing the four files under ``intervals_goal``
 +directory shows and updates the tuning parameters that described in the
 +:ref:design doc <damon_design_monitoring_intervals_autotuning>` with the same
 ...
  contexts/<N>/targets/
 diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
 index XXXXXXX..XXXXXXX 100644
 --- a/Documentation/mm/damon/design.rst
 +++ b/Documentation/mm/damon/design.rst
-@@ -XXX,XX +XXX,XX @@ is recommended.  Note that Parreto principle (80/20 rule) has applied twice.
+@@ -XXX,XX +XXX,XX @@ The tuning is turned off by default, and need to be set explicitly by the user.
- That is, assumes 4% (20% of 20%) DAMON-observed access events ratio (source)
+ As a rule of thumbs and the Parreto principle, 20% access samples ratio target
- to capture 64% (80% multipled by 80%) real access events (outcomes).
+ is recommended.
 +To know how user-space can use this feature via :ref:`DAMON sysfs interface
 +<sysfs_interface>`, refer to :ref:`intervals_goal <sysfs_scheme>` part of
 +the documentation.
 +
  .. _damon_design_damos:
 --
 .39.5

DAMON requires time-consuming and repetitive aggregation interval
tuning.  Introduce a feature for automating it using a feedback loop
that aims an amount of observed access events, like auto-exposing
cameras.

Background: Access Frequency Monitoring and Aggregation Interval
================================================================

DAMON checks if each memory element (damon_region) is accessed or not
for every user-specified time interval called 'sampling interval'.  It
aggregates the check intervals on per-element counter called
'nr_accesses'.  DAMON users can read the counters to get the access
temperature of a given element.  The counters are reset for every
another user-specified time interval called 'aggregation interval'.

This can be illustrated as DAMON continuously capturing a snapshot of
access events that happen and captured within the last aggregation
interval.  This implies the aggregation interval plays a key role for
the quality of the snapshots, like the camera exposure time.  If it is
too short, the amount of access events that happened and captured for
each snapshot is small, so each snapshot will show no many interesting
things but just a cold and dark world with hopefuly one pale blue dot or
two.  If it is too long, too many events are aggregated in a single
shot, so each snapshot will look like world of flames, or Muspellheim.
It will be difficult to find practical insights in both cases.

Problem: Time Consuming and Repetitive Tuning
=============================================

The appropriate length of the aggregation interval depends on how
frequently the system and workloads are making access events that DAMON
can observe.  Hence, users have to tune the interval with excessive
amount of tests with the target system and workloads.  If the system and
workloads are changed, the tuning should be done again.  If the
characteristic of the workloads is dynamic, it becomes more challenging.
It is therefore time-consuming and repetitive.

The tuning challenge mainly stems from the wrong question.  It is not
asking users what quality of monitoring results they want, but how DAMON
should operate for their hidden goal.  To make the right answer, users
need to fully understand DAMON's mechanisms and the characteristics of
their workloads.  Users shouldn't be asked to understand the underlying
mechanism.  Understanding the characteristics of the workloads shouldn't
be the role of users but DAMON.

Aim-oriented Feedback-driven Auto-Tuning
=========================================

Fortunately, the appropriate length of the aggregation interval can be
inferred using a feedback loop.  If the current snapshots are showing no
much intresting information, in other words, if it shows only rare
access events, increasing the aggregation interval helps, and vice
versa.  We tested this theory on a few real-world workloads, and
documented one of the experience with an official DAMON monitoring
intervals tuning guideline.  Since it is a simple theory that requires
repeatable tries, it can be a good job for machines.

Based on the guideline's theory, we design an automation of aggregation
interval tuning, in a way similar to that of camera auto-exposure
feature.  It defines the amount of interesting information as the ratio
of DAMON-observed access events that DAMON actually observed to
theoretical maximum amount of it within each snapshot.  Events are
accounted in byte and sampling attempts granularity.  For example, let's
say there is a region of 'X' bytes size.  DAMON tried access check
smapling for the region 'Y' times in total for a given aggregation.
Among the 'Y' attempts, 'Z' times it shown positive results.  Then, the
theoritical maximum number of access events for the region is 'X * Y'.
And the number of access events that DAMON has observed for the region
is 'X * Z'.  The abount of the interesting information is
'(X * Z / X * Y)'.  Note that each snapshot would have multiple regions.

Users can set an arbitrary value of the ratio as their target.  Once the
target is set, the automation periodically measures the current value of
the ratio and increase or decrease the aggregation interval if the ratio
value is lower or higher than the target.  The amount of the change is
proportion to the distance between the current adn the target values.

To avoid auto-tuning goes too long way, let users set the minimum and
the maximum aggregation interval times.  Changing only aggregation
interval while sampling interval is kept makes the maximum level of
access frequency in each snapshot, or discernment of regions
inconsistent.  Also, unnecessarily short sampling interval causes
meaningless monitoring overhed.  The automation therefore adjusts the
sampling interval together with aggregation interval, while keeping the
ratio between the two intervals.  Users can set the ratio, or the
discernment.

Discussion
==========

The modified question (aimed amount of access events, or lights, in each
snapshot) is easy to answer by both the users and the kernel.  If users
are interested in finding more cold regions, the value should be lower,
and vice versa.  If users have no idea, kernel can suggest a fair
default value based on some theories and experiments.  For example,
based on the Pareto principle (80/20 rule), we could expect 20% target
ratio will capture 80% of real access events.  Since 80% might be too
high, applying the rule once again, 4% (20% * 20%) may capture about 56%
(80% * 80%) of real access events.

Sampling to aggregation intervals ratio and min/max aggregation
intervals are also arguably easy to answer.  What users want is
discernment of regions for efficient system operation, for examples, X
amount of colder regions or Y amount of warmer regions, not exactly how
many times each cache line is accessed in nanoseconds degree.  The
appropriate min/max aggregation interval can relatively naively set, and
may better to set for aimed monitoring overhead.  Since sampling
interval is directly deciding the overhead, setting it based on the
sampling interval can be easy.  With my experiences, I'd argue the
intervals ratio 0.05, and 5 milliseconds to 20 seconds sampling interval
range (100 milliseconds to 400 seconds aggregation interval) can be a
good default suggestion.

Evaluation
==========

On a machine running a real world server workload, I ran DAMON to
monitor its physical address space for about 23 hours, with this feature
turned on.  We set it to tune sampling interval in a range from 5
milliseconds to 10 seconds, aiming 4 % DAMON-observed access ratio per
three aggregation intervals.  The exact command I used is as below.

damo start --monitoring_intervals_goal 4% 3 5ms 10s --damos_action stat

During the test run, DAMON continuously updated sampling and aggregation
intervals as designed, within the given range.  For all the time, DAMON
was able to find the intervals that meets the target access events ratio
in the given intervals range (sampling interval between 5 milliseconds
and 10 seconds).

For most of the time, tuned sampling interval was converged in 300-400
milliseconds.  It made only small amount of changes within the range.
The average of the tuned sampling interval during the test was about 380
milliseconds.

The workload periodically gets less load and decreases its CPU usage.
Presumably this also caused it making less memory access events.
Reactively to such event,s DAMON also increased the intervals as
expected.  It was still able to find the optimum interval that
satisfying the target access ratio within the given intervals range.
Usually it was converged to about 5 seconds.  Once the workload gets
normal amount of load again, DAMON reactively reduced the intervals to
the normal range.

I collected and visualized DAMON's monitoring results on the server a
few times.  Every time the visualized access pattern looked not biased
to only cold or hot pages but diverse and balanced.  Let me show some of
the snapshots that I collected at the nearly end of the test (after
about 23 hours have passed since starting DAMON on the server).

The recency histogram looks as below.  Please note that this
visualization shows only a very coarse grained information.  For more
details about the visualization format, please refer to DAMON user-space
tool documentation[1].

# ./damo report access --style recency-sz-hist --tried_regions_of 0 0 0 --access_rate 0 0
    <last accessed time (us)> <total size>
    [-19 h 7 m 45.514 s, -17 h 12 m 58.963 s)  6.198 GiB  |****                |
    [-17 h 12 m 58.963 s, -15 h 18 m 12.412 s) 0 B        |                    |
    [-15 h 18 m 12.412 s, -13 h 23 m 25.860 s) 0 B        |                    |
    [-13 h 23 m 25.860 s, -11 h 28 m 39.309 s) 0 B        |                    |
    [-11 h 28 m 39.309 s, -9 h 33 m 52.757 s)  0 B        |                    |
    [-9 h 33 m 52.757 s, -7 h 39 m 6.206 s)    0 B        |                    |
    [-7 h 39 m 6.206 s, -5 h 44 m 19.654 s)    0 B        |                    |
    [-5 h 44 m 19.654 s, -3 h 49 m 33.103 s)   0 B        |                    |
    [-3 h 49 m 33.103 s, -1 h 54 m 46.551 s)   0 B        |                    |
    [-1 h 54 m 46.551 s, -0 ns)                16.967 GiB |*********           |
    [-0 ns, --6886551440000 ns)                38.835 GiB |********************|
    memory bw estimate: 9.425 GiB per second
    total size: 62.000 GiB

It shows about 38 GiB of memory was accessed at least once within last
aggregation interval (given ~300 milliseconds tuned sampling interval,
this is about six seconds).  This is about 61 % of the total memory.  In
other words, DAMON found warmest 61 % memory of the system.  The number
is particularly interesting given our Pareto principle based theory for
the tuning goal value.  We set it as 20 % of 20 % (4 %), thinking it
would capture 80 % of 80 % (64 %) real access events.  And it foudn 61 %
hot memory, or working set.  Nevertheless, to make the theory clearer,
much more discussion and tests would be needed.  At the moment,
nonetheless, we can say making the target value higher helps finding
more hot memory regions.

The histogram also shows an amount of cold memory.  About 17 GiB memory
of the system has not accessed at least for last aggregation interval
(about six seconds), and at most for about last two hours.  The real
longest unaccessed time of the 17 GiB memory was about 19 minutes,
though.  This is a limitation of this visualization format.

It further found very cold 6 GiB memory.  It has not accessed at least for last
17 hours and at most 19 hours.

What about hot memory distribution?  To see this, I capture and
visualize the snapshot in access temperature histogram.  Again, please
refer to the DAMON user-space tool documentation[1] for the format and
what access temperature mean.   Both the visualization and metric shows
only very coarse grained and limited information.  The resulting
histogram look like below.

# ./damo report access --style temperature-sz-hist --tried_regions_of 0 0 0
    <temperature> <total size>
    [-6,840,763,776,000, -5,501,580,939,800) 6.198 GiB  |***                 |
    [-5,501,580,939,800, -4,162,398,103,600) 0 B        |                    |
    [-4,162,398,103,600, -2,823,215,267,400) 0 B        |                    |
    [-2,823,215,267,400, -1,484,032,431,200) 0 B        |                    |
    [-1,484,032,431,200, -144,849,595,000)   0 B        |                    |
    [-144,849,595,000, 1,194,333,241,200)    55.802 GiB |********************|
    [1,194,333,241,200, 2,533,516,077,400)   4.000 KiB  |*                   |
    [2,533,516,077,400, 3,872,698,913,600)   4.000 KiB  |*                   |
    [3,872,698,913,600, 5,211,881,749,800)   8.000 KiB  |*                   |
    [5,211,881,749,800, 6,551,064,586,000)   12.000 KiB |*                   |
    [6,551,064,586,000, 7,890,247,422,200)   4.000 KiB  |*                   |
    memory bw estimate: 5.178 GiB per second
    total size: 62.000 GiB

We can see most of the memory is in similar access temperature range,
and definitely some pages are extremely hot.

To see the picture in more detail, let's capture and visualize the
snapshot per DAMON-region, sorted by their access temperature.  The
total number of the regions was about 300.  Due to the limited space,
I'm showing only a few parts of the output here.

# ./damo report access --style hot --tried_regions_of 0 0 0
    heatmap: 00000000888888889999999888888888888888888888888888888888888888888888888888888888
    # min/max temperatures: -6,827,258,184,000, 17,589,052,500, column size: 793.600 MiB
     |999999999999999999999999999999999999999| 4.000 KiB   access 100 % 18 h 9 m 43.918 s
     |999999999999999999999999999999999999999| 8.000 KiB   access 100 % 17 h 56 m 5.351 s
     |999999999999999999999999999999999999999| 4.000 KiB   access 100 % 15 h 24 m 19.634 s
     |999999999999999999999999999999999999999| 4.000 KiB   access 100 % 14 h 10 m 55.606 s
     |999999999999999999999999999999999999999| 4.000 KiB   access 100 % 11 h 34 m 18.993 s
    [...]
               |99999999999999999999999999999| 8.000 KiB   access 100 % 1 m 27.945 s
               |11111111111111111111111111111| 80.000 KiB  access 15 %  1 m 21.180 s
               |00000000000000000000000000000| 24.000 KiB  access 5 %   1 m 21.180 s
               |00000000000000000000000000000| 5.919 GiB   access 10 %  1 m 14.415 s
               |99999999999999999999999999999| 12.000 KiB  access 100 % 1 m 7.650 s
    [...]
                                           |0| 4.000 KiB   access 5 %   0 ns
                                           |0| 12.000 KiB  access 5 %   0 ns
                                           |0| 188.000 KiB access 0 %   0 ns
                                           |0| 24.000 KiB  access 0 %   0 ns
                                           |0| 48.000 KiB  access 0 %   0 ns
    [...]
             |0000000000000000000000000000000| 8.000 KiB   access 0 %   6 m 45.901 s
            |00000000000000000000000000000000| 36.000 KiB  access 0 %   7 m 26.491 s
            |00000000000000000000000000000000| 4.000 KiB   access 0 %   12 m 37.682 s
           |000000000000000000000000000000000| 8.000 KiB   access 0 %   18 m 9.168 s
           |000000000000000000000000000000000| 16.000 KiB  access 0 %   19 m 3.288 s
    |0000000000000000000000000000000000000000| 6.198 GiB   access 0 %   18 h 57 m 52.582 s
    memory bw estimate: 8.798 GiB per second
    total size: 62.000 GiB

We can see DAMON found small and extremely hot regions that accessed for
all access check sampling (once per about 300 milliseconds) for more
than  10 hours.  The access temperature rapidly decreases.  DAMON was
also able to find small and big regions that not accessed for up to
about 19 minutes.  It even found an outlier cold region of 6 GiB that
not accessed for about 19 hours.  It is unclear what the outlier region
is, as of this writing.

For the testing, DAMON was consuming about 0.1% of single CPU time.
This is again expected results, since DAMON was using about 370
milliseconds sampling interval in most case.

# ps -p $kdamond_pid -o %cpu
    %CPU
     0.1

I also ran similar tests against kernel build workload and an in-memory
cache workload benchmark[2].  Detialed results including tuned intervals
and captured access pattern were of course different sicne those depend
on the workloads.  But the auto-tuning feature was always working as
expected like the above results for the real world workload.

To wrap up, with intervals auto-tuning feature, DAMON was able to
capture access pattern snapshots of a quality on a real world server
workload.  The auto-tuning feature was able to adaptively react to the
dynamic access patterns of the workload and reliably provide consistent
monitoring results without manual human interventions.  Also, the
auto-tuning made DAMON consumes only necessary amount of resource for
the required quality.

Changelog
=========

Changes from RFC v2
(https://lore.kernel.org/20250228220328.49438-1-sj@kernel.org)
- Add detailed evaluation results on cover letter

Changes from RFC v1
(https://lore.kernel.org/20250213014438.145611-1-sj@kernel.org)
- Replace the target metric from positive samples ratio to
  DAMON-observed access samples ratio
- Fix wrong max events accounting bug
- Fix double-increase of next_aggregation_sis

References
==========

[1] https://github.com/damonitor/damo/blob/next/USAGE.md#access-report-styles
[2] https://github.com/facebookresearch/DCPerf/blob/main/packages/tao_bench/README.md

SeongJae Park (8):
  mm/damon: add data structure for monitoring intervals auto-tuning
  mm/damon/core: implement intervals auto-tuning
  mm/damon/sysfs: implement intervals tuning goal directory
  mm/damon/sysfs: commit intervals tuning goal
  mm/damon/sysfs: implement a command to update auto-tuned monitoring
    intervals
  Docs/mm/damon/design: document for intervals auto-tuning
  Docs/ABI/damon: document intervals auto-tuning ABI
  Docs/admin-guide/mm/damon/usage: add intervals_goal directory on the
    hierarchy

base-commit: 2ade695ab17eb4005f006001aa9c51ad22d2f206
-- 
2.39.5

Add data structures for DAMON sampling and aggregation intervals
automatic tuning that aims specific amount of DAMON-observed access
events per snapshot.  In more detail, define the data structure for the
tuning goal, link it to the monitoring attributes data structure so that
DAMON kernel API callers can make the request, and update parameters
setup DAMON function to respect the new parameter.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 include/linux/damon.h | 27 +++++++++++++++++++++++++++
 mm/damon/core.c       | 22 ++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/include/linux/damon.h b/include/linux/damon.h
index XXXXXXX..XXXXXXX 100644
--- a/include/linux/damon.h
+++ b/include/linux/damon.h
@@ -XXX,XX +XXX,XX @@ struct damon_call_control {
 	bool canceled;
 };
 
+/**
+ * struct damon_intervals_goal - Monitoring intervals auto-tuning goal.
+ *
+ * @access_bp:		Access events observation ratio to achieve in bp.
+ * @aggrs:		Number of aggregations to acheive @access_bp within.
+ * @min_sample_us:	Minimum resulting sampling interval in microseconds.
+ * @max_sample_us:	Maximum resulting sampling interval in microseconds.
+ *
+ * DAMON automatically tunes &damon_attrs->sample_interval and
+ * &damon_attrs->aggr_interval aiming the ratio in bp (1/10,000) of
+ * DAMON-observed access events to theoretical maximum amount within @aggrs
+ * aggregations be same to @access_bp.  The logic increases
+ * &damon_attrs->aggr_interval and &damon_attrs->sampling_interval in same
+ * ratio if the current access events observation ratio is lower than the
+ * target for each @aggrs aggregations, and vice versa.
+ *
+ * If @aggrs is zero, the tuning is disabled and hence this struct is ignored.
+ */
+struct damon_intervals_goal {
+	unsigned long access_bp;
+	unsigned long aggrs;
+	unsigned long min_sample_us;
+	unsigned long max_sample_us;
+};
+
 /**
  * struct damon_attrs - Monitoring attributes for accuracy/overhead control.
  *
  * @sample_interval:		The time between access samplings.
  * @aggr_interval:		The time between monitor results aggregations.
  * @ops_update_interval:	The time between monitoring operations updates.
+ * @intervals_goal:		Intervals auto-tuning goal.
  * @min_nr_regions:		The minimum number of adaptive monitoring
  *				regions.
  * @max_nr_regions:		The maximum number of adaptive monitoring
@@ -XXX,XX +XXX,XX @@ struct damon_attrs {
 	unsigned long sample_interval;
 	unsigned long aggr_interval;
 	unsigned long ops_update_interval;
+	struct damon_intervals_goal intervals_goal;
 	unsigned long min_nr_regions;
 	unsigned long max_nr_regions;
 };
diff --git a/mm/damon/core.c b/mm/damon/core.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/core.c
+++ b/mm/damon/core.c
@@ -XXX,XX +XXX,XX @@ static void damon_update_monitoring_results(struct damon_ctx *ctx,
 					r, old_attrs, new_attrs);
 }
 
+/*
+ * damon_valid_intervals_goal() - return if the intervals goal of @attrs is
+ * valid.
+ */
+static bool damon_valid_intervals_goal(struct damon_attrs *attrs)
+{
+	struct damon_intervals_goal *goal = &attrs->intervals_goal;
+
+	/* tuning is disabled */
+	if (!goal->aggrs)
+		return true;
+	if (goal->min_sample_us > goal->max_sample_us)
+		return false;
+	if (attrs->sample_interval < goal->min_sample_us ||
+			goal->max_sample_us < attrs->sample_interval)
+		return false;
+	return true;
+}
+
 /**
  * damon_set_attrs() - Set attributes for the monitoring.
  * @ctx:		monitoring context
@@ -XXX,XX +XXX,XX @@ int damon_set_attrs(struct damon_ctx *ctx, struct damon_attrs *attrs)
 		attrs->sample_interval : 1;
 	struct damos *s;
 
+	if (!damon_valid_intervals_goal(attrs))
+		return -EINVAL;
+
 	if (attrs->min_nr_regions < 3)
 		return -EINVAL;
 	if (attrs->min_nr_regions > attrs->max_nr_regions)
-- 
2.39.5

Implement the DAMON sampling and aggregation intervals auto-tuning
mechanism as briefly described on 'struct damon_intervals_goal'.  The
core part for deciding the direction and amount of the changes is
implemented reusing the feedback loop function which is being used for
DAMOS quotas auto-tuning.  Unlike the DAMOS quotas auto-tuning use case,
limit the maximum decreasing amount after the adjustment to 50% of the
current value, though.  This is because the intervals have no good
merits at rapid reductions since it could unnecessarily increase the
monitoring overhead.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 include/linux/damon.h | 16 +++++++++
 mm/damon/core.c       | 76 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)

diff --git a/include/linux/damon.h b/include/linux/damon.h
index XXXXXXX..XXXXXXX 100644
--- a/include/linux/damon.h
+++ b/include/linux/damon.h
@@ -XXX,XX +XXX,XX @@ struct damon_attrs {
 	struct damon_intervals_goal intervals_goal;
 	unsigned long min_nr_regions;
 	unsigned long max_nr_regions;
+/* private: internal use only */
+	/*
+	 * @aggr_interval to @sample_interval ratio.
+	 * Core-external components call damon_set_attrs() with &damon_attrs
+	 * that this field is unset.  In the case, damon_set_attrs() sets this
+	 * field of resulting &damon_attrs.  Core-internal components such as
+	 * kdamond_tune_intervals() calls damon_set_attrs() with &damon_attrs
+	 * that this field is set.  In the case, damon_set_attrs() just keep
+	 * it.
+	 */
+	unsigned long aggr_samples;
 };
 
 /**
@@ -XXX,XX +XXX,XX @@ struct damon_ctx {
 	 * update
 	 */
 	unsigned long next_ops_update_sis;
+	/*
+	 * number of sample intervals that should be passed before next
+	 * intervals tuning
+	 */
+	unsigned long next_intervals_tune_sis;
 	/* for waiting until the execution of the kdamond_fn is started */
 	struct completion kdamond_started;
 	/* for scheme quotas prioritization */
diff --git a/mm/damon/core.c b/mm/damon/core.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/core.c
+++ b/mm/damon/core.c
@@ -XXX,XX +XXX,XX @@ int damon_set_attrs(struct damon_ctx *ctx, struct damon_attrs *attrs)
 	if (attrs->sample_interval > attrs->aggr_interval)
 		return -EINVAL;
 
+	/* calls from core-external doesn't set this. */
+	if (!attrs->aggr_samples)
+		attrs->aggr_samples = attrs->aggr_interval / sample_interval;
+
 	ctx->next_aggregation_sis = ctx->passed_sample_intervals +
 		attrs->aggr_interval / sample_interval;
 	ctx->next_ops_update_sis = ctx->passed_sample_intervals +
@@ -XXX,XX +XXX,XX @@ static void kdamond_reset_aggregated(struct damon_ctx *c)
 	}
 }
 
+static unsigned long damon_get_intervals_score(struct damon_ctx *c)
+{
+	struct damon_target *t;
+	struct damon_region *r;
+	unsigned long sz_region, max_access_events = 0, access_events = 0;
+	unsigned long target_access_events;
+	unsigned long goal_bp = c->attrs.intervals_goal.access_bp;
+
+	damon_for_each_target(t, c) {
+		damon_for_each_region(r, t) {
+			sz_region = damon_sz_region(r);
+			max_access_events += sz_region * c->attrs.aggr_samples;
+			access_events += sz_region * r->nr_accesses;
+		}
+	}
+	target_access_events = max_access_events * goal_bp / 10000;
+	return access_events * 10000 / target_access_events;
+}
+
+static unsigned long damon_feed_loop_next_input(unsigned long last_input,
+		unsigned long score);
+
+static unsigned long damon_get_intervals_adaptation_bp(struct damon_ctx *c)
+{
+	unsigned long score_bp, adaptation_bp;
+
+	score_bp = damon_get_intervals_score(c);
+	adaptation_bp = damon_feed_loop_next_input(100000000, score_bp) /
+		10000;
+	/*
+	 * adaptaion_bp ranges from 1 to 20,000.  Avoid too rapid reduction of
+	 * the intervals by rescaling [1,10,000] to [5000, 10,000].
+	 */
+	if (adaptation_bp <= 10000)
+		adaptation_bp = 5000 + adaptation_bp / 2;
+	return adaptation_bp;
+}
+
+static void kdamond_tune_intervals(struct damon_ctx *c)
+{
+	unsigned long adaptation_bp;
+	struct damon_attrs new_attrs;
+	struct damon_intervals_goal *goal;
+
+	adaptation_bp = damon_get_intervals_adaptation_bp(c);
+	if (adaptation_bp == 10000)
+		return;
+
+	new_attrs = c->attrs;
+	goal = &c->attrs.intervals_goal;
+	new_attrs.sample_interval = min(goal->max_sample_us,
+			c->attrs.sample_interval * adaptation_bp / 10000);
+	new_attrs.sample_interval = max(goal->min_sample_us,
+			new_attrs.sample_interval);
+	new_attrs.aggr_interval = new_attrs.sample_interval *
+		c->attrs.aggr_samples;
+	damon_set_attrs(c, &new_attrs);
+}
+
 static void damon_split_region_at(struct damon_target *t,
 				  struct damon_region *r, unsigned long sz_r);
 
@@ -XXX,XX +XXX,XX @@ static void kdamond_init_intervals_sis(struct damon_ctx *ctx)
 	ctx->next_aggregation_sis = ctx->attrs.aggr_interval / sample_interval;
 	ctx->next_ops_update_sis = ctx->attrs.ops_update_interval /
 		sample_interval;
+	ctx->next_intervals_tune_sis = ctx->next_aggregation_sis *
+		ctx->attrs.intervals_goal.aggrs;
 
 	damon_for_each_scheme(scheme, ctx) {
 		apply_interval = scheme->apply_interval_us ?
@@ -XXX,XX +XXX,XX @@ static int kdamond_fn(void *data)
 		sample_interval = ctx->attrs.sample_interval ?
 			ctx->attrs.sample_interval : 1;
 		if (ctx->passed_sample_intervals >= next_aggregation_sis) {
+			if (ctx->attrs.intervals_goal.aggrs &&
+					ctx->passed_sample_intervals >=
+					ctx->next_intervals_tune_sis) {
+				ctx->next_intervals_tune_sis +=
+					ctx->attrs.aggr_samples *
+					ctx->attrs.intervals_goal.aggrs;
+				kdamond_tune_intervals(ctx);
+				sample_interval = ctx->attrs.sample_interval ?
+					ctx->attrs.sample_interval : 1;
+
+			}
 			ctx->next_aggregation_sis = next_aggregation_sis +
 				ctx->attrs.aggr_interval / sample_interval;
 
-- 
2.39.5

Implement DAMON sysfs interface directory and its files for setting
DAMON sampling and aggregation intervals auto-tuning goal.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 mm/damon/sysfs.c | 189 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 189 insertions(+)

diff --git a/mm/damon/sysfs.c b/mm/damon/sysfs.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/sysfs.c
+++ b/mm/damon/sysfs.c
@@ -XXX,XX +XXX,XX @@ static const struct kobj_type damon_sysfs_targets_ktype = {
 	.default_groups = damon_sysfs_targets_groups,
 };
 
+/*
+ * intervals goal directory
+ */
+
+struct damon_sysfs_intervals_goal {
+	struct kobject kobj;
+	unsigned long access_bp;
+	unsigned long aggrs;
+	unsigned long min_sample_us;
+	unsigned long max_sample_us;
+};
+
+static struct damon_sysfs_intervals_goal *damon_sysfs_intervals_goal_alloc(
+		unsigned long access_bp, unsigned long aggrs,
+		unsigned long min_sample_us, unsigned long max_sample_us)
+{
+	struct damon_sysfs_intervals_goal *goal = kmalloc(sizeof(*goal),
+			GFP_KERNEL);
+
+	if (!goal)
+		return NULL;
+
+	goal->kobj = (struct kobject){};
+	goal->access_bp = access_bp;
+	goal->aggrs = aggrs;
+	goal->min_sample_us = min_sample_us;
+	goal->max_sample_us = max_sample_us;
+	return goal;
+}
+
+static ssize_t access_bp_show(struct kobject *kobj,
+		struct kobj_attribute *attr, char *buf)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+
+	return sysfs_emit(buf, "%lu\n", goal->access_bp);
+}
+
+static ssize_t access_bp_store(struct kobject *kobj,
+		struct kobj_attribute *attr, const char *buf, size_t count)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+	unsigned long nr;
+	int err = kstrtoul(buf, 0, &nr);
+
+	if (err)
+		return err;
+
+	goal->access_bp = nr;
+	return count;
+}
+
+static ssize_t aggrs_show(struct kobject *kobj,
+		struct kobj_attribute *attr, char *buf)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+
+	return sysfs_emit(buf, "%lu\n", goal->aggrs);
+}
+
+static ssize_t aggrs_store(struct kobject *kobj,
+		struct kobj_attribute *attr, const char *buf, size_t count)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+	unsigned long nr;
+	int err = kstrtoul(buf, 0, &nr);
+
+	if (err)
+		return err;
+
+	goal->aggrs = nr;
+	return count;
+}
+
+static ssize_t min_sample_us_show(struct kobject *kobj,
+		struct kobj_attribute *attr, char *buf)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+
+	return sysfs_emit(buf, "%lu\n", goal->min_sample_us);
+}
+
+static ssize_t min_sample_us_store(struct kobject *kobj,
+		struct kobj_attribute *attr, const char *buf, size_t count)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+	unsigned long nr;
+	int err = kstrtoul(buf, 0, &nr);
+
+	if (err)
+		return err;
+
+	goal->min_sample_us = nr;
+	return count;
+}
+
+static ssize_t max_sample_us_show(struct kobject *kobj,
+		struct kobj_attribute *attr, char *buf)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+
+	return sysfs_emit(buf, "%lu\n", goal->max_sample_us);
+}
+
+static ssize_t max_sample_us_store(struct kobject *kobj,
+		struct kobj_attribute *attr, const char *buf, size_t count)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+	unsigned long nr;
+	int err = kstrtoul(buf, 0, &nr);
+
+	if (err)
+		return err;
+
+	goal->max_sample_us = nr;
+	return count;
+}
+
+static void damon_sysfs_intervals_goal_release(struct kobject *kobj)
+{
+	kfree(container_of(kobj, struct damon_sysfs_intervals_goal, kobj));
+}
+
+static struct kobj_attribute damon_sysfs_intervals_goal_access_bp_attr =
+		__ATTR_RW_MODE(access_bp, 0600);
+
+static struct kobj_attribute damon_sysfs_intervals_goal_aggrs_attr =
+		__ATTR_RW_MODE(aggrs, 0600);
+
+static struct kobj_attribute damon_sysfs_intervals_goal_min_sample_us_attr =
+		__ATTR_RW_MODE(min_sample_us, 0600);
+
+static struct kobj_attribute damon_sysfs_intervals_goal_max_sample_us_attr =
+		__ATTR_RW_MODE(max_sample_us, 0600);
+
+static struct attribute *damon_sysfs_intervals_goal_attrs[] = {
+	&damon_sysfs_intervals_goal_access_bp_attr.attr,
+	&damon_sysfs_intervals_goal_aggrs_attr.attr,
+	&damon_sysfs_intervals_goal_min_sample_us_attr.attr,
+	&damon_sysfs_intervals_goal_max_sample_us_attr.attr,
+	NULL,
+};
+ATTRIBUTE_GROUPS(damon_sysfs_intervals_goal);
+
+static const struct kobj_type damon_sysfs_intervals_goal_ktype = {
+	.release = damon_sysfs_intervals_goal_release,
+	.sysfs_ops = &kobj_sysfs_ops,
+	.default_groups = damon_sysfs_intervals_goal_groups,
+};
+
 /*
  * intervals directory
  */
@@ -XXX,XX +XXX,XX @@ struct damon_sysfs_intervals {
 	unsigned long sample_us;
 	unsigned long aggr_us;
 	unsigned long update_us;
+	struct damon_sysfs_intervals_goal *intervals_goal;
 };
 
 static struct damon_sysfs_intervals *damon_sysfs_intervals_alloc(
@@ -XXX,XX +XXX,XX @@ static struct damon_sysfs_intervals *damon_sysfs_intervals_alloc(
 	return intervals;
 }
 
+static int damon_sysfs_intervals_add_dirs(struct damon_sysfs_intervals *intervals)
+{
+	struct damon_sysfs_intervals_goal *goal;
+	int err;
+
+	goal = damon_sysfs_intervals_goal_alloc(0, 0, 0, 0);
+	if (!goal)
+		return -ENOMEM;
+
+	err = kobject_init_and_add(&goal->kobj,
+			&damon_sysfs_intervals_goal_ktype, &intervals->kobj,
+			"intervals_goal");
+	if (err) {
+		kobject_put(&goal->kobj);
+		intervals->intervals_goal = NULL;
+		return err;
+	}
+	intervals->intervals_goal = goal;
+	return 0;
+}
+
+static void damon_sysfs_intervals_rm_dirs(struct damon_sysfs_intervals *intervals)
+{
+	kobject_put(&intervals->intervals_goal->kobj);
+}
+
 static ssize_t sample_us_show(struct kobject *kobj,
 		struct kobj_attribute *attr, char *buf)
 {
@@ -XXX,XX +XXX,XX @@ static int damon_sysfs_attrs_add_dirs(struct damon_sysfs_attrs *attrs)
 	err = kobject_init_and_add(&intervals->kobj,
 			&damon_sysfs_intervals_ktype, &attrs->kobj,
 			"intervals");
+	if (err)
+		goto put_intervals_out;
+	err = damon_sysfs_intervals_add_dirs(intervals);
 	if (err)
 		goto put_intervals_out;
 	attrs->intervals = intervals;
@@ -XXX,XX +XXX,XX @@ static int damon_sysfs_attrs_add_dirs(struct damon_sysfs_attrs *attrs)
 static void damon_sysfs_attrs_rm_dirs(struct damon_sysfs_attrs *attrs)
 {
 	kobject_put(&attrs->nr_regions_range->kobj);
+	damon_sysfs_intervals_rm_dirs(attrs->intervals);
 	kobject_put(&attrs->intervals->kobj);
 }
 
-- 
2.39.5

Connect DAMON sysfs interface for sampling and aggregation intervals
auto-tuning with DAMON core API, so that users can really use the
feature using the sysfs files.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 mm/damon/sysfs.c | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/mm/damon/sysfs.c b/mm/damon/sysfs.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/sysfs.c
+++ b/mm/damon/sysfs.c
@@ -XXX,XX +XXX,XX @@ static int damon_sysfs_set_attrs(struct damon_ctx *ctx,
 		struct damon_sysfs_attrs *sys_attrs)
 {
 	struct damon_sysfs_intervals *sys_intervals = sys_attrs->intervals;
+	struct damon_sysfs_intervals_goal *sys_goal =
+		sys_intervals->intervals_goal;
 	struct damon_sysfs_ul_range *sys_nr_regions =
 		sys_attrs->nr_regions_range;
 	struct damon_attrs attrs = {
 		.sample_interval = sys_intervals->sample_us,
 		.aggr_interval = sys_intervals->aggr_us,
+		.intervals_goal = {
+			.access_bp = sys_goal->access_bp,
+			.aggrs = sys_goal->aggrs,
+			.min_sample_us = sys_goal->min_sample_us,
+			.max_sample_us = sys_goal->max_sample_us},
 		.ops_update_interval = sys_intervals->update_us,
 		.min_nr_regions = sys_nr_regions->min,
 		.max_nr_regions = sys_nr_regions->max,
-- 
2.39.5

DAMON kernel API callers can show auto-tuned sampling and aggregation
intervals from the monmitoring attributes data structure.  That can be
useful for debugging or tuning of the feature.  DAMON user-space ABI
users has no way to see that, though.  Implement a new DAMON sysfs
interface command, namely 'update_tuned_intervals', for the purpose.
If the command is written to the kdamond state file, the tuned sampling
and aggregation intervals will be updated to the corresponding sysfs
interface files.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 mm/damon/sysfs.c | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/mm/damon/sysfs.c b/mm/damon/sysfs.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/sysfs.c
+++ b/mm/damon/sysfs.c
@@ -XXX,XX +XXX,XX @@ enum damon_sysfs_cmd {
 	 * effective size quota of the scheme in bytes.
 	 */
 	DAMON_SYSFS_CMD_UPDATE_SCHEMES_EFFECTIVE_QUOTAS,
+	/*
+	 * @DAMON_SYSFS_CMD_UPDATE_TUNED_INTERVALS: Update the tuned monitoring
+	 * intevals.
+	 */
+	DAMON_SYSFS_CMD_UPDATE_TUNED_INTERVALS,
 	/*
 	 * @NR_DAMON_SYSFS_CMDS: Total number of DAMON sysfs commands.
 	 */
@@ -XXX,XX +XXX,XX @@ static const char * const damon_sysfs_cmd_strs[] = {
 	"update_schemes_tried_regions",
 	"clear_schemes_tried_regions",
 	"update_schemes_effective_quotas",
+	"update_tuned_intervals",
 };
 
 /*
@@ -XXX,XX +XXX,XX @@ static int damon_sysfs_upd_schemes_effective_quotas(void *data)
 	return 0;
 }
 
+static int damon_sysfs_upd_tuned_intervals(void *data)
+{
+	struct damon_sysfs_kdamond *kdamond = data;
+	struct damon_ctx *ctx = kdamond->damon_ctx;
+
+	kdamond->contexts->contexts_arr[0]->attrs->intervals->sample_us =
+		ctx->attrs.sample_interval;
+	kdamond->contexts->contexts_arr[0]->attrs->intervals->aggr_us =
+		ctx->attrs.aggr_interval;
+	return 0;
+}
 
 /*
  * damon_sysfs_cmd_request_callback() - DAMON callback for handling requests.
@@ -XXX,XX +XXX,XX @@ static int damon_sysfs_handle_cmd(enum damon_sysfs_cmd cmd,
 		return damon_sysfs_damon_call(
 				damon_sysfs_upd_schemes_effective_quotas,
 				kdamond);
+	case DAMON_SYSFS_CMD_UPDATE_TUNED_INTERVALS:
+		return damon_sysfs_damon_call(
+				damon_sysfs_upd_tuned_intervals, kdamond);
 	default:
 		break;
 	}
-- 
2.39.5

Document the design of DAMON sampling and aggregation intervals
auto-tuning.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/mm/damon/design.rst | 46 +++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index XXXXXXX..XXXXXXX 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -XXX,XX +XXX,XX @@ sufficient for the given purpose, it shouldn't be unnecessarily further
 lowered.  It is recommended to be set proportional to ``aggregation interval``.
 By default, the ratio is set as ``1/20``, and it is still recommended.
 
+Based on the manual tuning guide, DAMON provides more intuitive knob-based
+intervals auto tuning mechanism.  Please refer to :ref:`the design document of
+the feature <damon_design_monitoring_intervals_autotuning>` for detail.
+
 Refer to below documents for an example tuning based on the above guide.
 
 .. toctree::
@@ -XXX,XX +XXX,XX @@ Refer to below documents for an example tuning based on the above guide.
    monitoring_intervals_tuning_example
 
 
+.. _damon_design_monitoring_intervals_autotuning:
+
+Monitoring Intervals Auto-tuning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DAMON provides automatic tuning of the ``sampling interval`` and ``aggregation
+interval`` based on the :ref:`the tuning guide idea
+<damon_design_monitoring_params_tuning_guide>`.  The tuning mechanism allows
+users to set the aimed amount of access events to observe via DAMON within
+given time interval.  The target can be specified by the user as a ratio of
+DAMON-observed access events to the theoretical maximum amount of the events
+(``access_bp``) that measured within a given number of aggregations
+(``aggrs``).
+
+The DAMON-observed access events are calculated in byte granularity based on
+DAMON :ref:`region assumption <damon_design_region_based_sample>`.  For
+example, if a region of size ``X`` bytes of ``Y`` ``nr_accesses`` is found, it
+means ``X * Y`` access events are observed by DAMON.  Theoretical maximum
+access events for the region is calculated in same way, but replacing ``Y``
+with theoretical maximum ``nr_accesses``, which can be calculated as
+``aggregation interval / sampling interval``.
+
+The mechanism calculates the ratio of access events for ``aggrs`` aggregations,
+and increases or decrease the ``sampleing interval`` and ``aggregation
+interval`` in same ratio, if the observed access ratio is lower or higher than
+the target, respectively.  The ratio of the intervals change is decided in
+proportion to the distance between current samples ratio and the target ratio.
+
+The user can further set the minimum and maximum ``sampling interval`` that can
+be set by the tuning mechanism using two parameters (``min_sample_us`` and
+``max_sample_us``).  Because the tuning mechanism changes ``sampling interval``
+and ``aggregation interval`` in same ratio always, the minimum and maximum
+``aggregation interval`` after each of the tuning changes can automatically set
+together.
+
+The tuning is turned off by default, and need to be set explicitly by the user.
+As a rule of thumbs and the Parreto principle, 4% access samples ratio target
+is recommended.  Note that Parreto principle (80/20 rule) has applied twice.
+That is, assumes 4% (20% of 20%) DAMON-observed access events ratio (source)
+to capture 64% (80% multipled by 80%) real access events (outcomes).
+
+
 .. _damon_design_damos:
 
 Operation Schemes
-- 
2.39.5

Document the DAMON user-space ABI for DAMON sampling and aggregation
intervals auto-tuning.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 .../ABI/testing/sysfs-kernel-mm-damon         | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon
index XXXXXXX..XXXXXXX 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-damon
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon
@@ -XXX,XX +XXX,XX @@ Description:	Writing a value to this file sets the update interval of the
 		DAMON context in microseconds as the value.  Reading this file
 		returns the value.
 
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/access_bp
+Date:		Feb 2025
+Contact:	SeongJae Park <sj@kernel.org>
+Description:	Writing a value to this file sets the monitoring intervals
+		auto-tuning target DAMON-observed access events ratio within
+		the given time interval (aggrs in same directory), in bp
+		(1/10,000).  Reading this file returns the value.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/aggrs
+Date:		Feb 2025
+Contact:	SeongJae Park <sj@kernel.org>
+Description:	Writing a value to this file sets the time interval to achieve
+		the monitoring intervals auto-tuning target DAMON-observed
+		access events ratio (access_bp in same directory) within.
+		Reading this file returns the value.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/min_sample_us
+Date:		Feb 2025
+Contact:	SeongJae Park <sj@kernel.org>
+Description:	Writing a value to this file sets the minimum value of
+		auto-tuned sampling interval in microseconds.  Reading this
+		file returns the value.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/max_sample_us
+Date:		Feb 2025
+Contact:	SeongJae Park <sj@kernel.org>
+Description:	Writing a value to this file sets the maximum value of
+		auto-tuned sampling interval in microseconds.  Reading this
+		file returns the value.
+
 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/min
 
 WDate:		Mar 2022
-- 
2.39.5

Document DAMON sysfs interface usage for DAMON sampling and aggregation
intervals auto-tuning.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/admin-guide/mm/damon/usage.rst | 25 ++++++++++++++++++++
 Documentation/mm/damon/design.rst            |  4 ++++
 2 files changed, 29 insertions(+)

diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
index XXXXXXX..XXXXXXX 100644
--- a/Documentation/admin-guide/mm/damon/usage.rst
+++ b/Documentation/admin-guide/mm/damon/usage.rst
@@ -XXX,XX +XXX,XX @@ comma (",").
     │ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations
     │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/
     │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
+    │ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us
     │ │ │ │ │ │ nr_regions/min,max
     │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
     │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target
@@ -XXX,XX +XXX,XX @@ Users can write below commands for the kdamond to the ``state`` file.
 - ``off``: Stop running.
 - ``commit``: Read the user inputs in the sysfs files except ``state`` file
   again.
+- ``update_tuned_intervals``: Update the contents of ``sample_us`` and
+  ``aggr_us`` files of the kdamond with the auto-tuning applied ``sampling
+  interval`` and ``aggregation interval`` for the files.  Please refer to
+  :ref:`intervals_goal section <damon_usage_sysfs_monitoring_intervals_goal>`
+  for more details.
 - ``commit_schemes_quota_goals``: Read the DAMON-based operation schemes'
   :ref:`quota goals <sysfs_schemes_quota_goals>`.
 - ``update_schemes_stats``: Update the contents of stats files for each
@@ -XXX,XX +XXX,XX @@ writing to and rading from the files.
 For more details about the intervals and monitoring regions range, please refer
 to the Design document (:doc:`/mm/damon/design`).
 
+.. _damon_usage_sysfs_monitoring_intervals_goal:
+
+contexts/<N>/monitoring_attrs/intervals/intervals_goal/
+-------------------------------------------------------
+
+Under the ``intervals`` directory, one directory for automated tuning of
+``sample_us`` and ``aggr_us``, namely ``intervals_goal`` directory also exists.
+Under the directory, four files for the auto-tuning control, namely
+``access_bp``, ``aggrs``, ``min_sample_us`` and ``max_sample_us`` exist.
+Please refer to  the :ref:`design document of the feature
+<damon_design_monitoring_intervals_autotuning>` for the internal of the tuning
+mechanism.  Reading and writing the four files under ``intervals_goal``
+directory shows and updates the tuning parameters that described in the
+:ref:design doc <damon_design_monitoring_intervals_autotuning>` with the same
+names.  The tuning starts with the user-set ``sample_us`` and ``aggr_us``.  The
+tuning-applied current values of the two intervals can be read from the
+``sample_us`` and ``aggr_us`` files after writing ``update_tuned_intervals`` to
+the ``state`` file.
+
 .. _sysfs_targets:
 
 contexts/<N>/targets/
diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index XXXXXXX..XXXXXXX 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -XXX,XX +XXX,XX @@ is recommended.  Note that Parreto principle (80/20 rule) has applied twice.
 That is, assumes 4% (20% of 20%) DAMON-observed access events ratio (source)
 to capture 64% (80% multipled by 80%) real access events (outcomes).
 
+To know how user-space can use this feature via :ref:`DAMON sysfs interface
+<sysfs_interface>`, refer to :ref:`intervals_goal <sysfs_scheme>` part of
+the documentation.
+
 
 .. _damon_design_damos:
 
-- 
2.39.5

Background: Access Frequency Monitoring and Aggregation Interval
================================================================

Problem: Time Consuming and Repetitive Tuning
=============================================

Aim-oriented Feedback-driven Auto-Tuning
=========================================

Based on the guideline's theory, we design an automation of aggregation
interval tuning, in a way similar to that of camera auto-exposure
feature.  It defines the amount of interesting information as the ratio
of captured access events to total capturing attempts of single snapshot,
or more technically speaking, the ratio of positive access check samples
to total samples within the aggregation interval.  It allows the users
to set the target value of the ratio.  Once the target is set, the
automation periodically measures the current value of the ratio and
increase or decrease the aggregation interval if the ratio value is
lower or higher than the target.  The amount of the change is proportion
to the distance between current value and the target value.

To avoid auto-tuning goes too long way, let users set minimum and
maximum aggregation interval time.  Changing only aggregation interval
while sampling interval is kept make the maximum level of access
frequency in each snapshot, or discernment of regions inconsistent.
Also, unnecessarily short sampling interval causes meaningless
monitoring overhed.  The automation therefore adjusts the sampling
interval together with aggregation interval, while keeping the ratio
between the two intervals.  Users can set the ratio, or the discernment.

Discussion
==========

The modified question (aimed amount of heats in each snapshot) is easy
to answer by both the users and the kernel.  If users are interested in
finding more cold regions, the value should be lower, and vice versa.
If users have no idea, kernel can suggest about 20% positive access
samples ratio as a fair default value based on the Pareto principle.

Sampling to aggregation intervals ratio and min/max aggregation
intervals are also arguably easy to answer.  What users want is
discernment of regions for efficient system operation, for examples, X
amount of colder regions or Y amount of warmer regions, not exactly how
many times each cache line is accessed in nanoseconds degree.  The
appropriate min/max aggregation interval can relatively naively set, and
may better to set for aimed monitoring overhead.  Since sampling
interval is directly related with the overhead, setting it based on the
sampling interval can be easy.  With my experiences, I'd argue the
intervals ratio 0.05, and 5 milliseconds to 20 seconds sampling interval
range (100 milliseconds to 400 seconds aggregation interval) can be a
good default suggestions.

Evaluation
==========

We confirmed the tuning works as expected with only a few simple
workloads including kernel builds, and that's why this is an RFC.  We
will conduct more evaluations with more massive and realistic workloads
and share the results by the time that we drop the RFC tag.

base-commit: d5c35650f4945e1406871f9d9d51ab8c54ec0d03
-- 
2.39.5

Add data structures for using DAMON sampling and aggregation intervals
automatic tuning aiming specific amount of access events per snapshot.
Specificaslly, define a data structure to define the tuning goal, namely
target ratio of positive access check samples, link it to monitoring
attributes data structure so that DAMON kernel API users can make the
request, and update parameters setup DAMON function to respect the new
data.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 include/linux/damon.h | 27 +++++++++++++++++++++++++++
 mm/damon/core.c       | 22 ++++++++++++++++++++++
 2 files changed, 49 insertions(+)

diff --git a/include/linux/damon.h b/include/linux/damon.h
index XXXXXXX..XXXXXXX 100644
--- a/include/linux/damon.h
+++ b/include/linux/damon.h
@@ -XXX,XX +XXX,XX @@ struct damon_call_control {
 	bool canceled;
 };
 
+/**
+ * struct damon_intervals_goal - Monitoring intervals auto-tuning goal.
+ *
+ * @samples_bp:		Positive access check samples ratio to achieve.
+ * @aggrs:		Number of aggregations to acheive @samples_bp within.
+ * @min_sample_us:	Minimum resulting sampling interval in microseconds.
+ * @max_sample_us:	Maximum resulting sampling interval in microseconds.
+ *
+ * DAMON automatically tunes &damon_attrs->sample_interval and
+ * &damon_attrs->aggr_interval aiming the ratio in bp (1/10,000) of access
+ * check samples that shown positive result (was accessed) to total samples
+ * within @aggrs aggregations be same to @samples_bp.  The logic increases
+ * &damon_attrs->aggr_interval and &damon_attrs->sampling_interval in same
+ * ratio if the current positive access samples ratio is lower than the target
+ * for each @aggrs aggregations, and vice versa.
+ *
+ * If @aggrs is zero, the tuning is disabled and hence this struct is ignored.
+ */
+struct damon_intervals_goal {
+	unsigned long samples_bp;
+	unsigned long aggrs;
+	unsigned long min_sample_us;
+	unsigned long max_sample_us;
+};
+
 /**
  * struct damon_attrs - Monitoring attributes for accuracy/overhead control.
  *
  * @sample_interval:		The time between access samplings.
  * @aggr_interval:		The time between monitor results aggregations.
  * @ops_update_interval:	The time between monitoring operations updates.
+ * @intervals_goal:		Intervals auto-tuning goal.
  * @min_nr_regions:		The minimum number of adaptive monitoring
  *				regions.
  * @max_nr_regions:		The maximum number of adaptive monitoring
@@ -XXX,XX +XXX,XX @@ struct damon_attrs {
 	unsigned long sample_interval;
 	unsigned long aggr_interval;
 	unsigned long ops_update_interval;
+	struct damon_intervals_goal intervals_goal;
 	unsigned long min_nr_regions;
 	unsigned long max_nr_regions;
 };
diff --git a/mm/damon/core.c b/mm/damon/core.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/core.c
+++ b/mm/damon/core.c
@@ -XXX,XX +XXX,XX @@ static void damon_update_monitoring_results(struct damon_ctx *ctx,
 					r, old_attrs, new_attrs);
 }
 
+/*
+ * damon_valid_intervals_goal() - return if the intervals goal of @attrs is
+ * valid.
+ */
+static bool damon_valid_intervals_goal(struct damon_attrs *attrs)
+{
+	struct damon_intervals_goal *goal = &attrs->intervals_goal;
+
+	/* tuning is disabled */
+	if (!goal->aggrs)
+		return true;
+	if (goal->min_sample_us > goal->max_sample_us)
+		return false;
+	if (attrs->sample_interval < goal->min_sample_us ||
+			goal->max_sample_us < attrs->sample_interval)
+		return false;
+	return true;
+}
+
 /**
  * damon_set_attrs() - Set attributes for the monitoring.
  * @ctx:		monitoring context
@@ -XXX,XX +XXX,XX @@ int damon_set_attrs(struct damon_ctx *ctx, struct damon_attrs *attrs)
 		attrs->sample_interval : 1;
 	struct damos *s;
 
+	if (!damon_valid_intervals_goal(attrs))
+		return -EINVAL;
+
 	if (attrs->min_nr_regions < 3)
 		return -EINVAL;
 	if (attrs->min_nr_regions > attrs->max_nr_regions)
-- 
2.39.5

Implement the DAMON sampling and aggregation intervals auto-tuning
mechanism as designed on the cover letter of this patch series.  The
mechanism reuses the feedback loop function for DAMOS quotas
auto-tuning.  Unlike the DAMOS quotas auto-tuning use case, limit the
maximum decreasing amount after the adjustment to 50% of the current
value.  This is because the intervals have no good merits at rapidly
reducing, and it is assumed the user will set the range of tunable
values not very wide.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 include/linux/damon.h | 16 ++++++++++
 mm/damon/core.c       | 68 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)

diff --git a/include/linux/damon.h b/include/linux/damon.h
index XXXXXXX..XXXXXXX 100644
--- a/include/linux/damon.h
+++ b/include/linux/damon.h
@@ -XXX,XX +XXX,XX @@ struct damon_attrs {
 	struct damon_intervals_goal intervals_goal;
 	unsigned long min_nr_regions;
 	unsigned long max_nr_regions;
+/* private: internal use only */
+	/*
+	 * @aggr_interval to @sample_interval ratio.
+	 * Core-external components call damon_set_attrs() with &damon_attrs
+	 * that this field is unset.  In the case, damon_set_attrs() sets this
+	 * field of resulting &damon_attrs.  Core-internal components such as
+	 * kdamond_tune_intervals() calls damon_set_attrs() with &damon_attrs
+	 * that this field is set.  In the case, damon_set_attrs() just keep
+	 * it.
+	 */
+	unsigned long aggr_samples;
 };
 
 /**
@@ -XXX,XX +XXX,XX @@ struct damon_ctx {
 	 * update
 	 */
 	unsigned long next_ops_update_sis;
+	/*
+	 * number of sample intervals that should be passed before next
+	 * intervals tuning
+	 */
+	unsigned long next_intervals_tune_sis;
 	/* for waiting until the execution of the kdamond_fn is started */
 	struct completion kdamond_started;
 	/* for scheme quotas prioritization */
diff --git a/mm/damon/core.c b/mm/damon/core.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/core.c
+++ b/mm/damon/core.c
@@ -XXX,XX +XXX,XX @@ int damon_set_attrs(struct damon_ctx *ctx, struct damon_attrs *attrs)
 	if (attrs->sample_interval > attrs->aggr_interval)
 		return -EINVAL;
 
+	/* calls from core-external doesn't set this. */
+	if (!attrs->aggr_samples)
+		attrs->aggr_samples = attrs->aggr_interval / sample_interval;
+
 	ctx->next_aggregation_sis = ctx->passed_sample_intervals +
 		attrs->aggr_interval / sample_interval;
 	ctx->next_ops_update_sis = ctx->passed_sample_intervals +
@@ -XXX,XX +XXX,XX @@ static void kdamond_reset_aggregated(struct damon_ctx *c)
 	}
 }
 
+static unsigned long damon_feed_loop_next_input(unsigned long last_input,
+		unsigned long score);
+
+static unsigned long damon_get_intervals_adaptation_bp(struct damon_ctx *c)
+{
+	struct damon_target *t;
+	struct damon_region *r;
+	unsigned long nr_regions = 0, access_samples = 0;
+	struct damon_intervals_goal *goal = &c->attrs.intervals_goal;
+	unsigned long max_samples, target_samples, score_bp;
+	unsigned long adaptation_bp;
+
+	damon_for_each_target(t, c) {
+		nr_regions = damon_nr_regions(t);
+		damon_for_each_region(r, t)
+			access_samples += r->nr_accesses;
+	}
+	max_samples = nr_regions * c->attrs.aggr_samples;
+	target_samples = max_samples * goal->samples_bp / 10000;
+	score_bp = access_samples * 10000 / target_samples;
+	adaptation_bp = damon_feed_loop_next_input(100000000, score_bp) /
+		10000;
+	/*
+	 * adaptaion_bp ranges from 1 to 20,000.  Avoid too rapid reduction of
+	 * the intervals by rescaling [1,10,000] to [5000, 10,000].
+	 */
+	if (adaptation_bp <= 10000)
+		adaptation_bp = 5000 + adaptation_bp / 2;
+
+	return adaptation_bp;
+}
+
+static void kdamond_tune_intervals(struct damon_ctx *c)
+{
+	unsigned long adaptation_bp;
+	struct damon_attrs new_attrs;
+	struct damon_intervals_goal *goal;
+
+	adaptation_bp = damon_get_intervals_adaptation_bp(c);
+	if (adaptation_bp == 10000)
+		return;
+
+	new_attrs = c->attrs;
+	goal = &c->attrs.intervals_goal;
+	new_attrs.sample_interval = min(
+			c->attrs.sample_interval * adaptation_bp / 10000,
+			goal->max_sample_us);
+	new_attrs.sample_interval = max(new_attrs.sample_interval,
+			goal->min_sample_us);
+	new_attrs.aggr_interval = new_attrs.sample_interval *
+		c->attrs.aggr_samples;
+	damon_set_attrs(c, &new_attrs);
+}
+
 static void damon_split_region_at(struct damon_target *t,
 				  struct damon_region *r, unsigned long sz_r);
 
@@ -XXX,XX +XXX,XX @@ static void kdamond_init_intervals_sis(struct damon_ctx *ctx)
 	ctx->next_aggregation_sis = ctx->attrs.aggr_interval / sample_interval;
 	ctx->next_ops_update_sis = ctx->attrs.ops_update_interval /
 		sample_interval;
+	ctx->next_intervals_tune_sis = ctx->next_aggregation_sis *
+		ctx->attrs.intervals_goal.aggrs;
 
 	damon_for_each_scheme(scheme, ctx) {
 		apply_interval = scheme->apply_interval_us ?
@@ -XXX,XX +XXX,XX @@ static int kdamond_fn(void *data)
 		if (ctx->passed_sample_intervals >= next_aggregation_sis) {
 			ctx->next_aggregation_sis = next_aggregation_sis +
 				ctx->attrs.aggr_interval / sample_interval;
+			if (ctx->attrs.intervals_goal.aggrs &&
+					ctx->passed_sample_intervals >=
+					ctx->next_intervals_tune_sis) {
+				ctx->next_intervals_tune_sis +=
+					ctx->attrs.aggr_samples *
+					ctx->attrs.intervals_goal.aggrs;
+				kdamond_tune_intervals(ctx);
+			}
 
 			kdamond_reset_aggregated(ctx);
 			kdamond_split_regions(ctx);
-- 
2.39.5

Implement DAMON sysfs interface directory and its files for setting
DAMON sampling and aggregation intervals auto-tuning goal.  Nearly all
kernel API data structures that newly introduced for this new feature
are directly exposed.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 mm/damon/sysfs.c | 189 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 189 insertions(+)

diff --git a/mm/damon/sysfs.c b/mm/damon/sysfs.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/sysfs.c
+++ b/mm/damon/sysfs.c
@@ -XXX,XX +XXX,XX @@ static const struct kobj_type damon_sysfs_targets_ktype = {
 	.default_groups = damon_sysfs_targets_groups,
 };
 
+/*
+ * intervals goal directory
+ */
+
+struct damon_sysfs_intervals_goal {
+	struct kobject kobj;
+	unsigned long samples_bp;
+	unsigned long aggrs;
+	unsigned long min_sample_us;
+	unsigned long max_sample_us;
+};
+
+static struct damon_sysfs_intervals_goal *damon_sysfs_intervals_goal_alloc(
+		unsigned long samples_bp, unsigned long aggrs,
+		unsigned long min_sample_us, unsigned long max_sample_us)
+{
+	struct damon_sysfs_intervals_goal *goal = kmalloc(sizeof(*goal),
+			GFP_KERNEL);
+
+	if (!goal)
+		return NULL;
+
+	goal->kobj = (struct kobject){};
+	goal->samples_bp = samples_bp;
+	goal->aggrs = aggrs;
+	goal->min_sample_us = min_sample_us;
+	goal->max_sample_us = max_sample_us;
+	return goal;
+}
+
+static ssize_t samples_bp_show(struct kobject *kobj,
+		struct kobj_attribute *attr, char *buf)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+
+	return sysfs_emit(buf, "%lu\n", goal->samples_bp);
+}
+
+static ssize_t samples_bp_store(struct kobject *kobj,
+		struct kobj_attribute *attr, const char *buf, size_t count)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+	unsigned long nr;
+	int err = kstrtoul(buf, 0, &nr);
+
+	if (err)
+		return err;
+
+	goal->samples_bp = nr;
+	return count;
+}
+
+static ssize_t aggrs_show(struct kobject *kobj,
+		struct kobj_attribute *attr, char *buf)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+
+	return sysfs_emit(buf, "%lu\n", goal->aggrs);
+}
+
+static ssize_t aggrs_store(struct kobject *kobj,
+		struct kobj_attribute *attr, const char *buf, size_t count)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+	unsigned long nr;
+	int err = kstrtoul(buf, 0, &nr);
+
+	if (err)
+		return err;
+
+	goal->aggrs = nr;
+	return count;
+}
+
+static ssize_t min_sample_us_show(struct kobject *kobj,
+		struct kobj_attribute *attr, char *buf)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+
+	return sysfs_emit(buf, "%lu\n", goal->min_sample_us);
+}
+
+static ssize_t min_sample_us_store(struct kobject *kobj,
+		struct kobj_attribute *attr, const char *buf, size_t count)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+	unsigned long nr;
+	int err = kstrtoul(buf, 0, &nr);
+
+	if (err)
+		return err;
+
+	goal->min_sample_us = nr;
+	return count;
+}
+
+static ssize_t max_sample_us_show(struct kobject *kobj,
+		struct kobj_attribute *attr, char *buf)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+
+	return sysfs_emit(buf, "%lu\n", goal->max_sample_us);
+}
+
+static ssize_t max_sample_us_store(struct kobject *kobj,
+		struct kobj_attribute *attr, const char *buf, size_t count)
+{
+	struct damon_sysfs_intervals_goal *goal = container_of(kobj,
+			struct damon_sysfs_intervals_goal, kobj);
+	unsigned long nr;
+	int err = kstrtoul(buf, 0, &nr);
+
+	if (err)
+		return err;
+
+	goal->max_sample_us = nr;
+	return count;
+}
+
+static void damon_sysfs_intervals_goal_release(struct kobject *kobj)
+{
+	kfree(container_of(kobj, struct damon_sysfs_intervals_goal, kobj));
+}
+
+static struct kobj_attribute damon_sysfs_intervals_goal_samples_bp_attr =
+		__ATTR_RW_MODE(samples_bp, 0600);
+
+static struct kobj_attribute damon_sysfs_intervals_goal_aggrs_attr =
+		__ATTR_RW_MODE(aggrs, 0600);
+
+static struct kobj_attribute damon_sysfs_intervals_goal_min_sample_us_attr =
+		__ATTR_RW_MODE(min_sample_us, 0600);
+
+static struct kobj_attribute damon_sysfs_intervals_goal_max_sample_us_attr =
+		__ATTR_RW_MODE(max_sample_us, 0600);
+
+static struct attribute *damon_sysfs_intervals_goal_attrs[] = {
+	&damon_sysfs_intervals_goal_samples_bp_attr.attr,
+	&damon_sysfs_intervals_goal_aggrs_attr.attr,
+	&damon_sysfs_intervals_goal_min_sample_us_attr.attr,
+	&damon_sysfs_intervals_goal_max_sample_us_attr.attr,
+	NULL,
+};
+ATTRIBUTE_GROUPS(damon_sysfs_intervals_goal);
+
+static const struct kobj_type damon_sysfs_intervals_goal_ktype = {
+	.release = damon_sysfs_intervals_goal_release,
+	.sysfs_ops = &kobj_sysfs_ops,
+	.default_groups = damon_sysfs_intervals_goal_groups,
+};
+
 /*
  * intervals directory
  */
@@ -XXX,XX +XXX,XX @@ struct damon_sysfs_intervals {
 	unsigned long sample_us;
 	unsigned long aggr_us;
 	unsigned long update_us;
+	struct damon_sysfs_intervals_goal *intervals_goal;
 };
 
 static struct damon_sysfs_intervals *damon_sysfs_intervals_alloc(
@@ -XXX,XX +XXX,XX @@ static struct damon_sysfs_intervals *damon_sysfs_intervals_alloc(
 	return intervals;
 }
 
+static int damon_sysfs_intervals_add_dirs(struct damon_sysfs_intervals *intervals)
+{
+	struct damon_sysfs_intervals_goal *goal;
+	int err;
+
+	goal = damon_sysfs_intervals_goal_alloc(0, 0, 0, 0);
+	if (!goal)
+		return -ENOMEM;
+
+	err = kobject_init_and_add(&goal->kobj,
+			&damon_sysfs_intervals_goal_ktype, &intervals->kobj,
+			"intervals_goal");
+	if (err) {
+		kobject_put(&goal->kobj);
+		intervals->intervals_goal = NULL;
+		return err;
+	}
+	intervals->intervals_goal = goal;
+	return 0;
+}
+
+static void damon_sysfs_intervals_rm_dirs(struct damon_sysfs_intervals *intervals)
+{
+	kobject_put(&intervals->intervals_goal->kobj);
+}
+
 static ssize_t sample_us_show(struct kobject *kobj,
 		struct kobj_attribute *attr, char *buf)
 {
@@ -XXX,XX +XXX,XX @@ static int damon_sysfs_attrs_add_dirs(struct damon_sysfs_attrs *attrs)
 	err = kobject_init_and_add(&intervals->kobj,
 			&damon_sysfs_intervals_ktype, &attrs->kobj,
 			"intervals");
+	if (err)
+		goto put_intervals_out;
+	err = damon_sysfs_intervals_add_dirs(intervals);
 	if (err)
 		goto put_intervals_out;
 	attrs->intervals = intervals;
@@ -XXX,XX +XXX,XX @@ static int damon_sysfs_attrs_add_dirs(struct damon_sysfs_attrs *attrs)
 static void damon_sysfs_attrs_rm_dirs(struct damon_sysfs_attrs *attrs)
 {
 	kobject_put(&attrs->nr_regions_range->kobj);
+	damon_sysfs_intervals_rm_dirs(attrs->intervals);
 	kobject_put(&attrs->intervals->kobj);
 }
 
-- 
2.39.5

Connect DAMON sysfs interface for sampling and aggregation intervals
auto-tuning with DAMON core API, so that users can really use the
feature using the sysfs files.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 mm/damon/sysfs.c | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/mm/damon/sysfs.c b/mm/damon/sysfs.c
index XXXXXXX..XXXXXXX 100644
--- a/mm/damon/sysfs.c
+++ b/mm/damon/sysfs.c
@@ -XXX,XX +XXX,XX @@ static int damon_sysfs_set_attrs(struct damon_ctx *ctx,
 		struct damon_sysfs_attrs *sys_attrs)
 {
 	struct damon_sysfs_intervals *sys_intervals = sys_attrs->intervals;
+	struct damon_sysfs_intervals_goal *sys_goal =
+		sys_intervals->intervals_goal;
 	struct damon_sysfs_ul_range *sys_nr_regions =
 		sys_attrs->nr_regions_range;
 	struct damon_attrs attrs = {
 		.sample_interval = sys_intervals->sample_us,
 		.aggr_interval = sys_intervals->aggr_us,
+		.intervals_goal = {
+			.samples_bp = sys_goal->samples_bp,
+			.aggrs = sys_goal->aggrs,
+			.min_sample_us = sys_goal->min_sample_us,
+			.max_sample_us = sys_goal->max_sample_us},
 		.ops_update_interval = sys_intervals->update_us,
 		.min_nr_regions = sys_nr_regions->min,
 		.max_nr_regions = sys_nr_regions->max,
-- 
2.39.5

DAMON kernel API callers can show auto-tuned sampling and aggregation
intervals from the monmitoring attributes data structure.  That can be
useful for debugging or tuning of the feature.  DAMON user-space ABI
users has no way to see that, though.  Implement a new DAMON sysfs
interface kdamond state command, namely 'update_tuned_intervals', for
the purpose.  Once the command is written to the kdamond state file, the
tuned sampling and aggregation intervals will be updated to the
corresponding sysfs interface.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 mm/damon/sysfs.c | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

Document DAMON sampling and aggregation intervals auto-tuning design.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/mm/damon/design.rst | 34 +++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index XXXXXXX..XXXXXXX 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -XXX,XX +XXX,XX @@ sufficient for the given purpose, it shouldn't be unnecessarily further
 lowered.  It is recommended to be set proportional to ``aggregation interval``.
 By default, the ratio is set as ``1/20``, and it is still recommended.
 
+Based on the manual tuning guide, DAMON provides more intuitive knob-based
+intervals auto tuning mechanism.  Please refer to :ref:`the design document of
+the feature <damon_design_monitoring_intervals_autotuning>` for detail.
+
 Refer to below documents for an example tuning based on the above guide.
 
 .. toctree::
@@ -XXX,XX +XXX,XX @@ Refer to below documents for an example tuning based on the above guide.
    monitoring_intervals_tuning_example
 
 
+.. _damon_design_monitoring_intervals_autotuning:
+
+Monitoring Intervals Auto-tuning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+DAMON provides automatic tuning of the ``sampling interval`` and ``aggregation
+interval`` based on the :ref:`the tuning guide idea
+<damon_design_monitoring_params_tuning_guide>`.  The tuning mechanism allows
+users to set the aimed amount of heats to observe with DAMON within given time
+interval.  The target can be specified by the user as a ratio of access check
+samples that gave positive result to the total samples (``samples_bp``) that
+measured within a given number of aggregations (``aggrs``).  The mechanism
+calculates the ratio of access check samples for ``aggrs`` aggregations, and
+increases or decrease the ``sampleing interval`` and ``aggregation interval``
+in same ratio, if the samples ratio is lower or higher than the target,
+respectively.  The ratio of the intervals change is decided in proportion to
+the distance between current samples ratio and the target ratio.
+
+The user can further set the minimum and maximum ``sampling interval`` that can
+be set by the tuning mechanism using two parameters (``min_sample_us`` and
+``max_sample_us``).  Because the tuning mechanism changes ``sampling interval``
+and ``aggregation interval`` in same ratio always, the minimum and maximum
+``aggregation interval`` after each of the tuning changes can automatically set
+together.
+
+The tuning is turned off by default, and need to be set explicitly by the user.
+As a rule of thumbs and the Parreto principle, 20% access samples ratio target
+is recommended.
+
+
 .. _damon_design_damos:
 
 Operation Schemes
-- 
2.39.5

Document the DAMON user-space ABI for DAMON sampling and aggregation
intervals auto-tuning.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 .../ABI/testing/sysfs-kernel-mm-damon         | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon
index XXXXXXX..XXXXXXX 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-damon
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon
@@ -XXX,XX +XXX,XX @@ Description:	Writing a value to this file sets the update interval of the
 		DAMON context in microseconds as the value.  Reading this file
 		returns the value.
 
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/samples_bp
+Date:		Feb 2025
+Contact:	SeongJae Park <sj@kernel.org>
+Description:	Writing a value to this file sets the monitoring intervals
+		auto-tuning target positive access check samples ratio within
+		the given time interval (aggrs in same directory), in bp
+		(1/10,000).  Reading this file returns the value.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/aggrs
+Date:		Feb 2025
+Contact:	SeongJae Park <sj@kernel.org>
+Description:	Writing a value to this file sets the time interval to achieve
+		the monitoring intervals auto-tuning target positive access
+		check samples ratio (samples_bp in same directory) within.
+		Reading this file returns the value.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/min_sample_us
+Date:		Feb 2025
+Contact:	SeongJae Park <sj@kernel.org>
+Description:	Writing a value to this file sets the minimum value of
+		auto-tuned sampling interval in microseconds.  Reading this
+		file returns the value.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/intrvals_goal/max_sample_us
+Date:		Feb 2025
+Contact:	SeongJae Park <sj@kernel.org>
+Description:	Writing a value to this file sets the maximum value of
+		auto-tuned sampling interval in microseconds.  Reading this
+		file returns the value.
+
 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/min
 
 WDate:		Mar 2022
-- 
2.39.5

Document DAMON sysfs interface usage for DAMON sampling and aggregation
intervals auto-tuning.

diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
index XXXXXXX..XXXXXXX 100644
--- a/Documentation/admin-guide/mm/damon/usage.rst
+++ b/Documentation/admin-guide/mm/damon/usage.rst
@@ -XXX,XX +XXX,XX @@ comma (",").
     │ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations
     │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/
     │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
+    │ │ │ │ │ │ │ intervals_goal/samples_bp,aggrs,min_sample_us,max_sample_us
     │ │ │ │ │ │ nr_regions/min,max
     │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
     │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target
@@ -XXX,XX +XXX,XX @@ Users can write below commands for the kdamond to the ``state`` file.
 - ``off``: Stop running.
 - ``commit``: Read the user inputs in the sysfs files except ``state`` file
   again.
+- ``update_tuned_intervals``: Update the contents of ``sample_us`` and
+  ``aggr_us`` files of the kdamond with the auto-tuning applied ``sampling
+  interval`` and ``aggregation interval`` for the files.  Please refer to
+  :ref:`intervals_goal section <damon_usage_sysfs_monitoring_intervals_goal>`
+  for more details.
 - ``commit_schemes_quota_goals``: Read the DAMON-based operation schemes'
   :ref:`quota goals <sysfs_schemes_quota_goals>`.
 - ``update_schemes_stats``: Update the contents of stats files for each
@@ -XXX,XX +XXX,XX @@ writing to and rading from the files.
 For more details about the intervals and monitoring regions range, please refer
 to the Design document (:doc:`/mm/damon/design`).
 
+.. _damon_usage_sysfs_monitoring_intervals_goal:
+
+contexts/<N>/monitoring_attrs/intervals/intervals_goal/
+-------------------------------------------------------
+
+Under the ``intervals`` directory, one directory for automated tuning of
+``sample_us`` and ``aggr_us``, namely ``intervals_goal`` directory also exists.
+Under the directory, four files for the auto-tuning control, namely
+``samples_bp``, ``aggrs``, ``min_sample_us`` and ``max_sample_us`` exist.
+Please refer to  the :ref:`design document of the feature
+<damon_design_monitoring_intervals_autotuning>` for the internal of the tuning
+mechanism.  Reading and writing the four files under ``intervals_goal``
+directory shows and updates the tuning parameters that described in the
+:ref:design doc <damon_design_monitoring_intervals_autotuning>` with the same
+names.  The tuning starts with the user-set ``sample_us`` and ``aggr_us``.  The
+tuning-applied current values of the two intervals can be read from the
+``sample_us`` and ``aggr_us`` files after writing ``update_tuned_intervals`` to
+the ``state`` file.
+
 .. _sysfs_targets:
 
 contexts/<N>/targets/
diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index XXXXXXX..XXXXXXX 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -XXX,XX +XXX,XX @@ The tuning is turned off by default, and need to be set explicitly by the user.
 As a rule of thumbs and the Parreto principle, 20% access samples ratio target
 is recommended.
 
+To know how user-space can use this feature via :ref:`DAMON sysfs interface
+<sysfs_interface>`, refer to :ref:`intervals_goal <sysfs_scheme>` part of
+the documentation.
+
 
 .. _damon_design_damos:
 
-- 
2.39.5