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 three files, ``attrs``, ``target_ids``, and ``monitor_on`` under
  38 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 Turning On/Off
  78 --------------
  79
  80 Setting the files as described above doesn't incur effect unless you explicitly
  81 start the monitoring.  You can start, stop, and check the current status of the
  82 monitoring by writing to and reading from the ``monitor_on`` file.  Writing
  83 ``on`` to the file starts the monitoring of the targets with the attributes.
  84 Writing ``off`` to the file stops those.  DAMON also stops if every target
  85 process is terminated.  Below example commands turn on, off, and check the
  86 status of DAMON::
  87
  88     # cd <debugfs>/damon
  89     # echo on > monitor_on
  90     # echo off > monitor_on
  91     # cat monitor_on
  92     off
  93
  94 Please note that you cannot write to the above-mentioned debugfs files while
  95 the monitoring is turned on.  If you write to the files while DAMON is running,
  96 an error code such as ``-EBUSY`` will be returned.
  97
  98
  99 Tracepoint for Monitoring Results
 100 =================================
 101
 102 DAMON provides the monitoring results via a tracepoint,
 103 ``damon:damon_aggregated``.  While the monitoring is turned on, you could
 104 record the tracepoint events and show results using tracepoint supporting tools
 105 like ``perf``.  For example::
 106
 107     # echo on > monitor_on
 108     # perf record -e damon:damon_aggregated &
 109     # sleep 5
 110     # kill 9 $(pidof perf)
 111     # echo off > monitor_on
 112     # perf script