include/linux/damon.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * DAMON api
   4  *
   5  * Author: SeongJae Park <sjpark@amazon.de>
   6  */
   7
   8 #ifndef _DAMON_H_
   9 #define _DAMON_H_
  10
  11 #include <linux/mutex.h>
  12 #include <linux/time64.h>
  13 #include <linux/types.h>
  14
  15 struct damon_ctx;
  16
  17 /**
  18  * struct damon_primitive       Monitoring primitives for given use cases.
  19  *
  20  * @init:                       Initialize primitive-internal data structures.
  21  * @update:                     Update primitive-internal data structures.
  22  * @prepare_access_checks:      Prepare next access check of target regions.
  23  * @check_accesses:             Check the accesses to target regions.
  24  * @reset_aggregated:           Reset aggregated accesses monitoring results.
  25  * @target_valid:               Determine if the target is valid.
  26  * @cleanup:                    Clean up the context.
  27  *
  28  * DAMON can be extended for various address spaces and usages.  For this,
  29  * users should register the low level primitives for their target address
  30  * space and usecase via the &damon_ctx.primitive.  Then, the monitoring thread
  31  * (&damon_ctx.kdamond) calls @init and @prepare_access_checks before starting
  32  * the monitoring, @update after each &damon_ctx.primitive_update_interval, and
  33  * @check_accesses, @target_valid and @prepare_access_checks after each
  34  * &damon_ctx.sample_interval.  Finally, @reset_aggregated is called after each
  35  * &damon_ctx.aggr_interval.
  36  *
  37  * @init should initialize primitive-internal data structures.  For example,
  38  * this could be used to construct proper monitoring target regions and link
  39  * those to @damon_ctx.target.
  40  * @update should update the primitive-internal data structures.  For example,
  41  * this could be used to update monitoring target regions for current status.
  42  * @prepare_access_checks should manipulate the monitoring regions to be
  43  * prepared for the next access check.
  44  * @check_accesses should check the accesses to each region that made after the
  45  * last preparation and update the number of observed accesses of each region.
  46  * @reset_aggregated should reset the access monitoring results that aggregated
  47  * by @check_accesses.
  48  * @target_valid should check whether the target is still valid for the
  49  * monitoring.
  50  * @cleanup is called from @kdamond just before its termination.
  51  */
  52 struct damon_primitive {
  53         void (*init)(struct damon_ctx *context);
  54         void (*update)(struct damon_ctx *context);
  55         void (*prepare_access_checks)(struct damon_ctx *context);
  56         void (*check_accesses)(struct damon_ctx *context);
  57         void (*reset_aggregated)(struct damon_ctx *context);
  58         bool (*target_valid)(void *target);
  59         void (*cleanup)(struct damon_ctx *context);
  60 };
  61
  62 /*
  63  * struct damon_callback        Monitoring events notification callbacks.
  64  *
  65  * @before_start:       Called before starting the monitoring.
  66  * @after_sampling:     Called after each sampling.
  67  * @after_aggregation:  Called after each aggregation.
  68  * @before_terminate:   Called before terminating the monitoring.
  69  * @private:            User private data.
  70  *
  71  * The monitoring thread (&damon_ctx.kdamond) calls @before_start and
  72  * @before_terminate just before starting and finishing the monitoring,
  73  * respectively.  Therefore, those are good places for installing and cleaning
  74  * @private.
  75  *
  76  * The monitoring thread calls @after_sampling and @after_aggregation for each
  77  * of the sampling intervals and aggregation intervals, respectively.
  78  * Therefore, users can safely access the monitoring results without additional
  79  * protection.  For the reason, users are recommended to use these callback for
  80  * the accesses to the results.
  81  *
  82  * If any callback returns non-zero, monitoring stops.
  83  */
  84 struct damon_callback {
  85         void *private;
  86
  87         int (*before_start)(struct damon_ctx *context);
  88         int (*after_sampling)(struct damon_ctx *context);
  89         int (*after_aggregation)(struct damon_ctx *context);
  90         int (*before_terminate)(struct damon_ctx *context);
  91 };
  92
  93 /**
  94  * struct damon_ctx - Represents a context for each monitoring.  This is the
  95  * main interface that allows users to set the attributes and get the results
  96  * of the monitoring.
  97  *
  98  * @sample_interval:            The time between access samplings.
  99  * @aggr_interval:              The time between monitor results aggregations.
 100  * @primitive_update_interval:  The time between monitoring primitive updates.
 101  *
 102  * For each @sample_interval, DAMON checks whether each region is accessed or
 103  * not.  It aggregates and keeps the access information (number of accesses to
 104  * each region) for @aggr_interval time.  DAMON also checks whether the target
 105  * memory regions need update (e.g., by ``mmap()`` calls from the application,
 106  * in case of virtual memory monitoring) and applies the changes for each
 107  * @primitive_update_interval.  All time intervals are in micro-seconds.
 108  * Please refer to &struct damon_primitive and &struct damon_callback for more
 109  * detail.
 110  *
 111  * @kdamond:            Kernel thread who does the monitoring.
 112  * @kdamond_stop:       Notifies whether kdamond should stop.
 113  * @kdamond_lock:       Mutex for the synchronizations with @kdamond.
 114  *
 115  * For each monitoring context, one kernel thread for the monitoring is
 116  * created.  The pointer to the thread is stored in @kdamond.
 117  *
 118  * Once started, the monitoring thread runs until explicitly required to be
 119  * terminated or every monitoring target is invalid.  The validity of the
 120  * targets is checked via the &damon_primitive.target_valid of @primitive.  The
 121  * termination can also be explicitly requested by writing non-zero to
 122  * @kdamond_stop.  The thread sets @kdamond to NULL when it terminates.
 123  * Therefore, users can know whether the monitoring is ongoing or terminated by
 124  * reading @kdamond.  Reads and writes to @kdamond and @kdamond_stop from
 125  * outside of the monitoring thread must be protected by @kdamond_lock.
 126  *
 127  * Note that the monitoring thread protects only @kdamond and @kdamond_stop via
 128  * @kdamond_lock.  Accesses to other fields must be protected by themselves.
 129  *
 130  * @primitive:  Set of monitoring primitives for given use cases.
 131  * @callback:   Set of callbacks for monitoring events notifications.
 132  *
 133  * @target:     Pointer to the user-defined monitoring target.
 134  */
 135 struct damon_ctx {
 136         unsigned long sample_interval;
 137         unsigned long aggr_interval;
 138         unsigned long primitive_update_interval;
 139
 140 /* private: internal use only */
 141         struct timespec64 last_aggregation;
 142         struct timespec64 last_primitive_update;
 143
 144 /* public: */
 145         struct task_struct *kdamond;
 146         bool kdamond_stop;
 147         struct mutex kdamond_lock;
 148
 149         struct damon_primitive primitive;
 150         struct damon_callback callback;
 151
 152         void *target;
 153 };
 154
 155 #ifdef CONFIG_DAMON
 156
 157 struct damon_ctx *damon_new_ctx(void);
 158 void damon_destroy_ctx(struct damon_ctx *ctx);
 159 int damon_set_attrs(struct damon_ctx *ctx, unsigned long sample_int,
 160                 unsigned long aggr_int, unsigned long primitive_upd_int);
 161
 162 int damon_start(struct damon_ctx **ctxs, int nr_ctxs);
 163 int damon_stop(struct damon_ctx **ctxs, int nr_ctxs);
 164
 165 #endif  /* CONFIG_DAMON */
 166
 167 #endif  /* _DAMON_H */