API Reference

Kernel space programs can use every feature of DAMON using below APIs. All you need to do is including damon.h, which is located in include/linux/ of the source tree.


struct damon_addr_range

Represents an address region of [start, end).


struct damon_addr_range {
  unsigned long start;
  unsigned long end;



Start address of the region (inclusive).


End address of the region (exclusive).

struct damon_region

Represents a monitoring target region.


struct damon_region {
  struct damon_addr_range ar;
  unsigned long sampling_addr;
  unsigned int nr_accesses;
  struct list_head list;



The address range of the region.


Address of the sample for the next access check.


Access frequency of this region.


List head for siblings.

struct damon_target

Represents a monitoring target.


struct damon_target {
  unsigned long id;
  struct list_head regions_list;
  struct list_head list;



Unique identifier for this target.


Head of the monitoring target regions of this target.


List head for siblings.


Each monitoring context could have multiple targets. For example, a context for virtual memory address spaces could have multiple target processes. The id of each target should be unique among the targets of the context. For example, in the virtual address monitoring context, it could be a pidfd or an address of an mm_struct.

struct damon_ctx

Represents a context for each monitoring. This is the main interface that allows users to set the attributes and get the results of the monitoring.


struct damon_ctx {
  unsigned long sample_interval;
  unsigned long aggr_interval;
  unsigned long regions_update_interval;
  unsigned long min_nr_regions;
  unsigned long max_nr_regions;
  struct timespec64 last_aggregation;
  struct timespec64 last_regions_update;
  unsigned char *rbuf;
  unsigned int rbuf_len;
  unsigned int rbuf_offset;
  char *rfile_path;
  struct task_struct *kdamond;
  bool kdamond_stop;
  struct mutex kdamond_lock;
  struct list_head targets_list;
  void (*init_target_regions)(struct damon_ctx *context);
  void (*update_target_regions)(struct damon_ctx *context);
  void (*prepare_access_checks)(struct damon_ctx *context);
  unsigned int (*check_accesses)(struct damon_ctx *context);
  bool (*target_valid)(struct damon_target *target);
  void (*cleanup)(struct damon_ctx *context);
  void (*sample_cb)(struct damon_ctx *context);
  void (*aggregate_cb)(struct damon_ctx *context);



The time between access samplings.


The time between monitor results aggregations.


The time between monitor regions updates.


The minimum number of monitoring regions.


The maximum number of monitoring regions.


In-memory buffer for monitoring result recording.


The length of rbuf.


The offset for next write to rbuf.


Record file path.


Kernel thread who does the monitoring.


Notifies whether kdamond should stop.


Mutex for the synchronizations with kdamond.


Head of monitoring targets (damon_target) list.


Constructs initial monitoring target regions.


Updates monitoring target regions.


Prepares next access check of target regions.


Checks the access of target regions.


Determine if the target is valid.


Cleans up the context.


Called for each sampling interval.


Called for each aggregation interval.


For each sample_interval, DAMON checks whether each region is accessed or not. It aggregates and keeps the access information (number of accesses to each region) for aggr_interval time. DAMON also checks whether the target memory regions need update (e.g., by mmap() calls from the application, in case of virtual memory monitoring) and applies the changes for each regions_update_interval. All time intervals are in micro-seconds.

If rbuf, rbuf_len, and rfile_path are set, the monitored results are automatically stored in rfile_path file.

For each monitoring context, one kernel thread for the monitoring is created. The pointer to the thread is stored in kdamond.

Once started, the monitoring thread runs until explicitly required to be terminated or every monitoring target is invalid. The validity of the targets is checked via the target_valid callback. The termination can also be explicitly requested by writing non-zero to kdamond_stop. The thread sets kdamond to NULL when it terminates. Therefore, users can know whether the monitoring is ongoing or terminated by reading kdamond. Reads and writes to kdamond and kdamond_stop from outside of the monitoring thread must be protected by kdamond_lock.

Note that the monitoring thread protects only kdamond and kdamond_stop via kdamond_lock. Accesses to other fields must be protected by themselves.

DAMON can be extended for various address spaces by users. For this, users can register the target address space dependent low level functions for their usecases via the callback pointers of the context. The monitoring thread calls init_target_regions before starting the monitoring, update_target_regions for each regions_update_interval, and prepare_access_checks, check_accesses, and target_valid for each sample_interval.

init_target_regions should construct proper monitoring target regions and link those to the DAMON context struct. update_target_regions should update the monitoring target regions for current status. prepare_access_checks should manipulate the monitoring regions to be prepare for the next access check. check_accesses should check the accesses to each region that made after the last preparation and update the ->nr_accesses of each region. target_valid should check whether the target is still valid for the monitoring. cleanup is called from kdamond just before its termination. After this call, only kdamond_lock and kdamond will be touched.

sample_cb and aggregate_cb are called from kdamond for each of the sampling intervals and aggregation intervals, respectively. Therefore, users can safely access to the monitoring results via targets_list without additional protection of kdamond_lock. For the reason, users are recommended to use these callback for the accesses to the results.


int damon_start(struct damon_ctx * ctxs, int nr_ctxs)

Starts the monitorings for a given group of contexts.


struct damon_ctx * ctxs

an array of the contexts to start monitoring

int nr_ctxs

size of ctxs


This function starts a group of monitoring threads for a group of monitoring contexts. One thread per each context is created and run concurrently. The caller should handle synchronization between the threads by itself. If a group of threads that created by other ‘damon_start()’ call is currently running, this function does nothing but returns -EBUSY.


0 on success, negative error code otherwise.

int damon_stop(struct damon_ctx * ctxs, int nr_ctxs)

Stops the monitorings for a given group of contexts.


struct damon_ctx * ctxs

an array of the contexts to stop monitoring

int nr_ctxs

size of ctxs


0 on success, negative error code otherwise.

int damon_set_targets(struct damon_ctx * ctx, unsigned long * ids, ssize_t nr_ids)

Set monitoring targets.


struct damon_ctx * ctx

monitoring context

unsigned long * ids

array of target ids

ssize_t nr_ids

number of entries in ids


This function should not be called while the kdamond is running.


0 on success, negative error code otherwise.

int damon_set_recording(struct damon_ctx * ctx, unsigned int rbuf_len, char * rfile_path)

Set attributes for the recording.


struct damon_ctx * ctx

target kdamond context

unsigned int rbuf_len

length of the result buffer

char * rfile_path

path to the monitor result files


Setting ‘rbuf_len’ 0 disables recording.

This function should not be called while the kdamond is running.


0 on success, negative error code otherwise.

int damon_set_attrs(struct damon_ctx * ctx, unsigned long sample_int, unsigned long aggr_int, unsigned long regions_update_int, unsigned long min_nr_reg, unsigned long max_nr_reg)

Set attributes for the monitoring.


struct damon_ctx * ctx

monitoring context

unsigned long sample_int

time interval between samplings

unsigned long aggr_int

time interval between aggregations

unsigned long regions_update_int

time interval between target regions update

unsigned long min_nr_reg

minimal number of regions

unsigned long max_nr_reg

maximum number of regions


This function should not be called while the kdamond is running. Every time interval is in micro-seconds.


0 on success, negative error code otherwise.