1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4Detailed Usages 5=============== 6 7DAMON 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 both virtual and physical address spaces 14 monitoring. 15- *debugfs interface.* 16 This is for privileged user space programmers who want more optimized use of 17 DAMON. Using this, users can use DAMON’s major features by reading 18 from and writing to special debugfs files. Therefore, you can write and use 19 your personalized DAMON debugfs wrapper programs that reads/writes the 20 debugfs files instead of you. The DAMON user space tool is also a reference 21 implementation of such programs. It supports both virtual and physical 22 address spaces monitoring. 23- *Kernel Space Programming Interface.* 24 This is for kernel space programmers. Using this, users can utilize every 25 feature of DAMON most flexibly and efficiently by writing kernel space 26 DAMON application programs for you. You can even extend DAMON for various 27 address spaces. 28 29Nevertheless, you could write your own user space tool using the debugfs 30interface. A reference implementation is available at 31https://github.com/awslabs/damo. If you are a kernel programmer, you could 32refer to :doc:`/vm/damon/api` for the kernel space programming interface. For 33the reason, this document describes only the debugfs interface 34 35debugfs Interface 36================= 37 38DAMON exports five files, ``attrs``, ``target_ids``, ``init_regions``, 39``schemes`` and ``monitor_on`` under its debugfs directory, 40``<debugfs>/damon/``. 41 42 43Attributes 44---------- 45 46Users can get and set the ``sampling interval``, ``aggregation interval``, 47``regions update interval``, and min/max number of monitoring target regions by 48reading from and writing to the ``attrs`` file. To know about the monitoring 49attributes in detail, please refer to the :doc:`/vm/damon/design`. For 50example, below commands set those values to 5 ms, 100 ms, 1,000 ms, 10 and 511000, and then check it again:: 52 53 # cd <debugfs>/damon 54 # echo 5000 100000 1000000 10 1000 > attrs 55 # cat attrs 56 5000 100000 1000000 10 1000 57 58 59Target IDs 60---------- 61 62Some types of address spaces supports multiple monitoring target. For example, 63the virtual memory address spaces monitoring can have multiple processes as the 64monitoring targets. Users can set the targets by writing relevant id values of 65the targets to, and get the ids of the current targets by reading from the 66``target_ids`` file. In case of the virtual address spaces monitoring, the 67values should be pids of the monitoring target processes. For example, below 68commands set processes having pids 42 and 4242 as the monitoring targets and 69check it again:: 70 71 # cd <debugfs>/damon 72 # echo 42 4242 > target_ids 73 # cat target_ids 74 42 4242 75 76Users can also monitor the physical memory address space of the system by 77writing a special keyword, "``paddr\n``" to the file. Because physical address 78space monitoring doesn't support multiple targets, reading the file will show a 79fake value, ``42``, as below:: 80 81 # cd <debugfs>/damon 82 # echo paddr > target_ids 83 # cat target_ids 84 42 85 86Note that setting the target ids doesn't start the monitoring. 87 88 89Initial Monitoring Target Regions 90--------------------------------- 91 92In case of the virtual address space monitoring, DAMON automatically sets and 93updates the monitoring target regions so that entire memory mappings of target 94processes can be covered. However, users can want to limit the monitoring 95region to specific address ranges, such as the heap, the stack, or specific 96file-mapped area. Or, some users can know the initial access pattern of their 97workloads and therefore want to set optimal initial regions for the 'adaptive 98regions adjustment'. 99 100In contrast, DAMON do not automatically sets and updates the monitoring target 101regions in case of physical memory monitoring. Therefore, users should set the 102monitoring target regions by themselves. 103 104In such cases, users can explicitly set the initial monitoring target regions 105as they want, by writing proper values to the ``init_regions`` file. Each line 106of the input should represent one region in below form.:: 107 108 <target id> <start address> <end address> 109 110The ``target id`` should already in ``target_ids`` file, and the regions should 111be passed in address order. For example, below commands will set a couple of 112address ranges, ``1-100`` and ``100-200`` as the initial monitoring target 113region of process 42, and another couple of address ranges, ``20-40`` and 114``50-100`` as that of process 4242.:: 115 116 # cd <debugfs>/damon 117 # echo "42 1 100 118 42 100 200 119 4242 20 40 120 4242 50 100" > init_regions 121 122Note that this sets the initial monitoring target regions only. In case of 123virtual memory monitoring, DAMON will automatically updates the boundary of the 124regions after one ``regions update interval``. Therefore, users should set the 125``regions update interval`` large enough in this case, if they don't want the 126update. 127 128 129Schemes 130------- 131 132For usual DAMON-based data access aware memory management optimizations, users 133would simply want the system to apply a memory management action to a memory 134region of a specific size having a specific access frequency for a specific 135time. DAMON receives such formalized operation schemes from the user and 136applies those to the target processes. It also counts the total number and 137size of regions that each scheme is applied. This statistics can be used for 138online analysis or tuning of the schemes. 139 140Users can get and set the schemes by reading from and writing to ``schemes`` 141debugfs file. Reading the file also shows the statistics of each scheme. To 142the file, each of the schemes should be represented in each line in below form: 143 144 min-size max-size min-acc max-acc min-age max-age action 145 146Note that the ranges are closed interval. Bytes for the size of regions 147(``min-size`` and ``max-size``), number of monitored accesses per aggregate 148interval for access frequency (``min-acc`` and ``max-acc``), number of 149aggregate intervals for the age of regions (``min-age`` and ``max-age``), and a 150predefined integer for memory management actions should be used. The supported 151numbers and their meanings are as below. 152 153 - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED`` 154 - 1: Call ``madvise()`` for the region with ``MADV_COLD`` 155 - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT`` 156 - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE`` 157 - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE`` 158 - 5: Do nothing but count the statistics 159 160You can disable schemes by simply writing an empty string to the file. For 161example, below commands applies a scheme saying "If a memory region of size in 162[4KiB, 8KiB] is showing accesses per aggregate interval in [0, 5] for aggregate 163interval in [10, 20], page out the region", check the entered scheme again, and 164finally remove the scheme. :: 165 166 # cd <debugfs>/damon 167 # echo "4096 8192 0 5 10 20 2" > schemes 168 # cat schemes 169 4096 8192 0 5 10 20 2 0 0 170 # echo > schemes 171 172The last two integers in the 4th line of above example is the total number and 173the total size of the regions that the scheme is applied. 174 175 176Turning On/Off 177-------------- 178 179Setting the files as described above doesn't incur effect unless you explicitly 180start the monitoring. You can start, stop, and check the current status of the 181monitoring by writing to and reading from the ``monitor_on`` file. Writing 182``on`` to the file starts the monitoring of the targets with the attributes. 183Writing ``off`` to the file stops those. DAMON also stops if every target 184process is terminated. Below example commands turn on, off, and check the 185status of DAMON:: 186 187 # cd <debugfs>/damon 188 # echo on > monitor_on 189 # echo off > monitor_on 190 # cat monitor_on 191 off 192 193Please note that you cannot write to the above-mentioned debugfs files while 194the monitoring is turned on. If you write to the files while DAMON is running, 195an error code such as ``-EBUSY`` will be returned. 196 197 198Tracepoint for Monitoring Results 199================================= 200 201DAMON provides the monitoring results via a tracepoint, 202``damon:damon_aggregated``. While the monitoring is turned on, you could 203record the tracepoint events and show results using tracepoint supporting tools 204like ``perf``. For example:: 205 206 # echo on > monitor_on 207 # perf record -e damon:damon_aggregated & 208 # sleep 5 209 # kill 9 $(pidof perf) 210 # echo off > monitor_on 211 # perf script 212