Documentation/admin-guide/mm/damon/usage.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===============
   4 Detailed Usages
   5 ===============
   6
   7 DAMON provides below three interfaces for different users.
   8
   9 - *DAMON user space tool.*
  10   This is for privileged people such as system administrators who want a
  11   just-working human-friendly interface.  Using this, users can use the DAMON’s
  12   major features in a human-friendly way.  It may not be highly tuned for
  13   special cases, though.  It supports only virtual address spaces monitoring.
  14 - *debugfs interface.*
  15   This is for privileged user space programmers who want more optimized use of
  16   DAMON.  Using this, users can use DAMON’s major features by reading
  17   from and writing to special debugfs files.  Therefore, you can write and use
  18   your personalized DAMON debugfs wrapper programs that reads/writes the
  19   debugfs files instead of you.  The DAMON user space tool is also a reference
  20   implementation of such programs.  It supports only virtual address spaces
  21   monitoring.
  22 - *Kernel Space Programming Interface.*
  23   This is for kernel space programmers.  Using this, users can utilize every
  24   feature of DAMON most flexibly and efficiently by writing kernel space
  25   DAMON application programs for you.  You can even extend DAMON for various
  26   address spaces.
  27
  28 Nevertheless, you could write your own user space tool using the debugfs
  29 interface.  A reference implementation is available at
  30 https://github.com/awslabs/damo.  If you are a kernel programmer, you could
  31 refer to :doc:`/vm/damon/api` for the kernel space programming interface.  For
  32 the reason, this document describes only the debugfs interface
  33
  34 debugfs Interface
  35 =================
  36
  37 DAMON exports four files, ``attrs``, ``target_ids``, ``schemes`` and
  38 ``monitor_on`` under its debugfs directory, ``<debugfs>/damon/``.
  39
  40
  41 Attributes
  42 ----------
  43
  44 Users can get and set the ``sampling interval``, ``aggregation interval``,
  45 ``regions update interval``, and min/max number of monitoring target regions by
  46 reading from and writing to the ``attrs`` file.  To know about the monitoring
  47 attributes in detail, please refer to the :doc:`/vm/damon/design`.  For
  48 example, below commands set those values to 5 ms, 100 ms, 1,000 ms, 10 and
  49 1000, and then check it again::
  50
  51     # cd <debugfs>/damon
  52     # echo 5000 100000 1000000 10 1000 > attrs
  53     # cat attrs
  54     5000 100000 1000000 10 1000
  55
  56
  57 Target IDs
  58 ----------
  59
  60 Some types of address spaces supports multiple monitoring target.  For example,
  61 the virtual memory address spaces monitoring can have multiple processes as the
  62 monitoring targets.  Users can set the targets by writing relevant id values of
  63 the targets to, and get the ids of the current targets by reading from the
  64 ``target_ids`` file.  In case of the virtual address spaces monitoring, the
  65 values should be pids of the monitoring target processes.  For example, below
  66 commands set processes having pids 42 and 4242 as the monitoring targets and
  67 check it again::
  68
  69     # cd <debugfs>/damon
  70     # echo 42 4242 > target_ids
  71     # cat target_ids
  72     42 4242
  73
  74 Note that setting the target ids doesn't start the monitoring.
  75
  76
  77 Schemes
  78 -------
  79
  80 For usual DAMON-based data access aware memory management optimizations, users
  81 would simply want the system to apply a memory management action to a memory
  82 region of a specific size having a specific access frequency for a specific
  83 time.  DAMON receives such formalized operation schemes from the user and
  84 applies those to the target processes.  It also counts the total number and
  85 size of regions that each scheme is applied.  This statistics can be used for
  86 online analysis or tuning of the schemes.
  87
  88 Users can get and set the schemes by reading from and writing to ``schemes``
  89 debugfs file.  Reading the file also shows the statistics of each scheme.  To
  90 the file, each of the schemes should be represented in each line in below form:
  91
  92     min-size max-size min-acc max-acc min-age max-age action
  93
  94 Note that the ranges are closed interval.  Bytes for the size of regions
  95 (``min-size`` and ``max-size``), number of monitored accesses per aggregate
  96 interval for access frequency (``min-acc`` and ``max-acc``), number of
  97 aggregate intervals for the age of regions (``min-age`` and ``max-age``), and a
  98 predefined integer for memory management actions should be used.  The supported
  99 numbers and their meanings are as below.
 100
 101  - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED``
 102  - 1: Call ``madvise()`` for the region with ``MADV_COLD``
 103  - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT``
 104  - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``
 105  - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``
 106  - 5: Do nothing but count the statistics
 107
 108 You can disable schemes by simply writing an empty string to the file.  For
 109 example, below commands applies a scheme saying "If a memory region of size in
 110 [4KiB, 8KiB] is showing accesses per aggregate interval in [0, 5] for aggregate
 111 interval in [10, 20], page out the region", check the entered scheme again, and
 112 finally remove the scheme. ::
 113
 114     # cd <debugfs>/damon
 115     # echo "4096 8192    0 5    10 20    2" > schemes
 116     # cat schemes
 117     4096 8192 0 5 10 20 2 0 0
 118     # echo > schemes
 119
 120 The last two integers in the 4th line of above example is the total number and
 121 the total size of the regions that the scheme is applied.
 122
 123
 124 Turning On/Off
 125 --------------
 126
 127 Setting the files as described above doesn't incur effect unless you explicitly
 128 start the monitoring.  You can start, stop, and check the current status of the
 129 monitoring by writing to and reading from the ``monitor_on`` file.  Writing
 130 ``on`` to the file starts the monitoring of the targets with the attributes.
 131 Writing ``off`` to the file stops those.  DAMON also stops if every target
 132 process is terminated.  Below example commands turn on, off, and check the
 133 status of DAMON::
 134
 135     # cd <debugfs>/damon
 136     # echo on > monitor_on
 137     # echo off > monitor_on
 138     # cat monitor_on
 139     off
 140
 141 Please note that you cannot write to the above-mentioned debugfs files while
 142 the monitoring is turned on.  If you write to the files while DAMON is running,
 143 an error code such as ``-EBUSY`` will be returned.
 144
 145
 146 Tracepoint for Monitoring Results
 147 =================================
 148
 149 DAMON provides the monitoring results via a tracepoint,
 150 ``damon:damon_aggregated``.  While the monitoring is turned on, you could
 151 record the tracepoint events and show results using tracepoint supporting tools
 152 like ``perf``.  For example::
 153
 154     # echo on > monitor_on
 155     # perf record -e damon:damon_aggregated &
 156     # sleep 5
 157     # kill 9 $(pidof perf)
 158     # echo off > monitor_on
 159     # perf script