@@ -7,37 +7,40 @@ Detailed Usages
- *DAMON user space tool.*
is for privileged people such as system administrators who want a
Using this, users can use the DAMON’
It may not be highly tuned for
virtual and physical address spaces
monitoring.
` This <https://github.com/awslabs/damo> `_ is for privileged people such as
system administrators who want a just-working human-friendly interface.
Using this, users can use the DAMON’ major features in a human-friendly way.
It may not be highly tuned for special cases, though. It supports both
virtual and physical address spaces monitoring. For more detail, please
- *debugfs interface.*
This is for privileged user space programmers who want more optimized use of
’ features by reading
you can write and use
reads/writes the
is also a reference
implementation of such programs. It supports both virtual and physical
:ref: `This <debugfs_interface>`
want more optimized use of DAMON. Using this, users can use DAMON’
features by reading from and writing to special debugfs files. Therefore,
you can write and use your personalized DAMON debugfs wrapper programs that
reads/writes the debugfs files instead of you. The ` DAMON user space tool
<https://github.com/awslabs/damo>`_ is one example of such programs. It
supports both virtual and physical address spaces monitoring. Note that this
:ref: `statistics <damos_stats>` for the
:ref: `tracepoint <tracepoint>` .
- *Kernel Space Programming Interface.*
This is for kernel space programmers. Using this, users can utilize every
writing kernel space
DAMON for various
address spaces.
:doc: `This </vm/damon/api>`
users can utilize every feature of DAMON most flexibly and efficiently by
writing kernel space DAMON application programs for you. You can even extend
DAMON for various address spaces. For detail, please refer to the interface
:doc: `document </vm/damon/api>` .
Nevertheless, you could write your own user space tool using the debugfs
interface. A reference implementation is available at
:doc: `/vm/damon/api` for the kernel space programming interface. For
.. _debugfs_interface:
debugfs Interface
=================
five files, `` attrs `` , `` target_ids `` , `` init_regions `` ,
`` schemes `` and `` monitor_on `` under its debugfs directory,
`` <debugfs>/damon/ `` .
eight files, `` attrs `` , `` target_ids `` , `` init_regions `` ,
`` schemes `` , `` monitor_on `` , `` kdamond_pid `` , `` mk_contexts `` and
`` rm_contexts `` under its debugfs directory, `` `` .
Attributes
@@ -131,24 +134,38 @@ Schemes
size having a specific access frequency for a specific
time. DAMON receives such formalized operation schemes from the user and
access pattern. DAMON receives such formalized operation
schemes from the user and applies those to the target processes.
`` schemes ``
form:
::
min-size max-size min-acc max-acc min-age max-age action
<target access pattern> <action> <quota> <watermarks>
(`` min-size `` and `` max-size `` ), number of monitored accesses per aggregate
interval for access frequency (`` min-acc `` and `` max-acc `` ), number of
`` min-age `` and `` max-age `` ), and a
numbers and their meanings are as below.
Target Access Pattern
~~~~~~~~~~~~~~~~~~~~~
The `` <target access pattern> `` is constructed with three ranges in below
::
min-size max-size min-acc max-acc min-age max-age
`` min-size `` and `` max-size `` ),
`` min-acc `` and `` max-acc `` ), number of aggregate intervals for the age of
`` min-age `` and `` max-age `` ) are specified. Note that the ranges are
Action
~~~~~~
`` <action> `` is a predefined integer for memory management actions, which
- 0: Call `` madvise() `` for the region with `` MADV_WILLNEED ``
- 1: Call `` madvise() `` for the region with `` MADV_COLD ``
@@ -157,20 +174,82 @@ numbers and their meanings are as below.
- 4: Call `` madvise() `` for the region with `` MADV_NOHUGEPAGE ``
- 5: Do nothing but count the statistics
You can disable schemes by simply writing an empty string to the file. For
interval in [10, 20], page out the region", check the entered scheme again, and
finally remove the scheme. ::
Quota
~~~~~
Optimal `` target access pattern `` for each `` action `` is workload dependent, so
not easy to find. Worse yet, setting a scheme of some action too aggressive
`` <quota> `` in below form::
<ms> <sz> <reset interval> <priority weights>
`` <ms> `` milliseconds for applying
`` target access pattern `` within the
`` <reset interval> `` milliseconds, and to apply the action to only up to
`` <sz> `` bytes of memory regions within the `` <reset interval> `` . Setting both
`` <ms> `` and `` <sz> `` zero disables the quota limits.
`` target access pattern `` based on their size, access frequency,
`` <priority weights> `` in below form::
<size weight> <access frequency weight> <age weight>
Watermarks
~~~~~~~~~~
::
<metric> <check interval> <high mark> <middle mark> <low mark>
`` <metric> `` is a predefined integer for the metric to be checked. The
- 0: Ignore the watermarks
- 1: System's free memory rate (per thousand)
`` <check interval> `` microseconds.
`` <high mark> `` or lower than `` <low mark> `` , the
`` <mid mark> `` , the scheme
.. _damos_stats:
Statistics
~~~~~~~~~~
`` schemes `` file. Reading the file
Example
~~~~~~~
::
# cd <debugfs>/damon
# e cho "4096 8192 0 5 10 20 2" > schemes
# cat schemes
4096 8192 0 5 10 20 2 0 0
# e cho > scheme s
# s cheme= "4096 8192 0 5 10 20 2" # target access pattern and action
# scheme+=" 10 $((1024*1024*1024)) 1000" # quota s
# scheme+=" 0 0 100" # prioritization weights
# s cheme+=" 1 5000000 600 500 300" # watermark s
# echo "$scheme" > schemes
Turning On/Off
@@ -195,6 +274,54 @@ the monitoring is turned on. If you write to the files while DAMON is running,
`` -EBUSY `` will be returned.
Monitoring Thread PID
---------------------
`` kdamond `` . You
`` kdamond_pid `` file. When the
`` none `` . ::
# cd <debugfs>/damon
# cat monitor_on
off
# cat kdamond_pid
none
# echo on > monitor_on
# cat kdamond_pid
18594
Using Multiple Monitoring Threads
---------------------------------
`` kdamond `` thread is created for each monitoring context. You can create
`` kdamond `` required use case using
`` mk_contexts `` and `` rm_contexts `` files.
`` mk_contexts `` file creates a
::
# cd <debugfs>/damon
# ls foo
# ls: cannot access 'foo': No such file or directory
# echo foo > mk_contexts
# ls foo
# attrs init_regions kdamond_pid schemes target_ids
`` rm_contexts `` file. ::
# echo foo > rm_contexts
# ls foo
# ls: cannot access 'foo': No such file or directory
`` mk_contexts `` , `` rm_contexts `` , and `` monitor_on `` files are in the
.. _tracepoint:
Tracepoint for Monitoring Results
=================================
Linus Torvalds