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.
Structures¶
-
struct
damon_addr_range
¶ Represents an address region of [start, end).
Definition
struct damon_addr_range {
unsigned long start;
unsigned long end;
};
Members
start
Start address of the region (inclusive).
end
End address of the region (exclusive).
-
struct
damon_region
¶ Represents a monitoring target region.
Definition
struct damon_region {
struct damon_addr_range ar;
unsigned long sampling_addr;
unsigned int nr_accesses;
struct list_head list;
};
Members
ar
The address range of the region.
sampling_addr
Address of the sample for the next access check.
nr_accesses
Access frequency of this region.
list
List head for siblings.
-
struct
damon_target
¶ Represents a monitoring target.
Definition
struct damon_target {
unsigned long id;
unsigned int nr_regions;
struct list_head regions_list;
struct list_head list;
};
Members
id
Unique identifier for this target.
nr_regions
Number of monitoring target regions of this target.
regions_list
Head of the monitoring target regions of this target.
list
List head for siblings.
Description
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.
Definition
struct damon_ctx {
unsigned long sample_interval;
unsigned long aggr_interval;
unsigned long primitive_update_interval;
struct task_struct *kdamond;
bool kdamond_stop;
struct mutex kdamond_lock;
struct damon_primitive primitive;
struct damon_callback callback;
unsigned long min_nr_regions;
unsigned long max_nr_regions;
struct list_head adaptive_targets;
};
Members
sample_interval
The time between access samplings.
aggr_interval
The time between monitor results aggregations.
primitive_update_interval
The time between monitoring primitive updates.
kdamond
Kernel thread who does the monitoring.
kdamond_stop
Notifies whether kdamond should stop.
kdamond_lock
Mutex for the synchronizations with kdamond.
primitive
Set of monitoring primitives for given use cases.
callback
Set of callbacks for monitoring events notifications.
min_nr_regions
The minimum number of adaptive monitoring regions.
max_nr_regions
The maximum number of adaptive monitoring regions.
adaptive_targets
Head of monitoring targets (
damon_target
) list.
Description
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
primitive_update_interval. All time intervals are in micro-seconds.
Please refer to struct damon_primitive
and struct damon_callback
for more
detail.
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 damon_primitive.target_valid
of primitive. 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.
Functions¶
-
int
damon_set_targets
(struct damon_ctx *ctx, unsigned long *ids, ssize_t nr_ids)¶ Set monitoring targets.
Parameters
struct damon_ctx *ctx
monitoring context
unsigned long *ids
array of target ids
ssize_t nr_ids
number of entries in ids
Description
This function should not be called while the kdamond is running.
Return
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 primitive_upd_int, unsigned long min_nr_reg, unsigned long max_nr_reg)¶ Set attributes for the monitoring.
Parameters
struct damon_ctx *ctx
monitoring context
unsigned long sample_int
time interval between samplings
unsigned long aggr_int
time interval between aggregations
unsigned long primitive_upd_int
time interval between monitoring primitive updates
unsigned long min_nr_reg
minimal number of regions
unsigned long max_nr_reg
maximum number of regions
Description
This function should not be called while the kdamond is running. Every time interval is in micro-seconds.
Return
0 on success, negative error code otherwise.
-
int
damon_nr_running_ctxs
(void)¶ Return number of currently running contexts.
Parameters
void
no arguments
-
int
damon_start
(struct damon_ctx **ctxs, int nr_ctxs)¶ Starts the monitorings for a given group of contexts.
Parameters
struct damon_ctx **ctxs
an array of the pointers for contexts to start monitoring
int nr_ctxs
size of ctxs
Description
This function starts a group of monitoring threads for a group of monitoring contexts. One thread per each context is created and run in parallel. 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.
Return
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.
Parameters
struct damon_ctx **ctxs
an array of the pointers for contexts to stop monitoring
int nr_ctxs
size of ctxs
Return
0 on success, negative error code otherwise.