1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4Getting Started 5=============== 6 7This document briefly describes how you can use DAMON by demonstrating its 8default user space tool. Please note that this document describes only a part 9of its features for brevity. Please refer to the usage `doc 10<https://github.com/awslabs/damo/blob/next/USAGE.md>`_ of the tool for more 11details. 12 13 14Prerequisites 15============= 16 17Kernel 18------ 19 20You should first ensure your system is running on a kernel built with 21``CONFIG_DAMON_*=y``. 22 23 24User Space Tool 25--------------- 26 27For the demonstration, we will use the default user space tool for DAMON, 28called DAMON Operator (DAMO). It is available at 29https://github.com/awslabs/damo. The examples below assume that ``damo`` is on 30your ``$PATH``. It's not mandatory, though. 31 32Because DAMO is using the sysfs interface (refer to :doc:`usage` for the 33detail) of DAMON, you should ensure :doc:`sysfs </filesystems/sysfs>` is 34mounted. 35 36 37Snapshot Data Access Patterns 38============================= 39 40The commands below show the memory access pattern of a program at the moment of 41the execution. :: 42 43 $ git clone https://github.com/sjp38/masim; cd masim; make 44 $ sudo damo start "./masim ./configs/stairs.cfg --quiet" 45 $ sudo ./damo show 46 0 addr [85.541 TiB , 85.541 TiB ) (57.707 MiB ) access 0 % age 10.400 s 47 1 addr [85.541 TiB , 85.542 TiB ) (413.285 MiB) access 0 % age 11.400 s 48 2 addr [127.649 TiB , 127.649 TiB) (57.500 MiB ) access 0 % age 1.600 s 49 3 addr [127.649 TiB , 127.649 TiB) (32.500 MiB ) access 0 % age 500 ms 50 4 addr [127.649 TiB , 127.649 TiB) (9.535 MiB ) access 100 % age 300 ms 51 5 addr [127.649 TiB , 127.649 TiB) (8.000 KiB ) access 60 % age 0 ns 52 6 addr [127.649 TiB , 127.649 TiB) (6.926 MiB ) access 0 % age 1 s 53 7 addr [127.998 TiB , 127.998 TiB) (120.000 KiB) access 0 % age 11.100 s 54 8 addr [127.998 TiB , 127.998 TiB) (8.000 KiB ) access 40 % age 100 ms 55 9 addr [127.998 TiB , 127.998 TiB) (4.000 KiB ) access 0 % age 11 s 56 total size: 577.590 MiB 57 $ sudo ./damo stop 58 59The first command of the above example downloads and builds an artificial 60memory access generator program called ``masim``. The second command asks DAMO 61to execute the artificial generator process start via the given command and 62make DAMON monitors the generator process. The third command retrieves the 63current snapshot of the monitored access pattern of the process from DAMON and 64shows the pattern in a human readable format. 65 66Each line of the output shows which virtual address range (``addr [XX, XX)``) 67of the process is how frequently (``access XX %``) accessed for how long time 68(``age XX``). For example, the fifth region of ~9 MiB size is being most 69frequently accessed for last 300 milliseconds. Finally, the fourth command 70stops DAMON. 71 72Note that DAMON can monitor not only virtual address spaces but multiple types 73of address spaces including the physical address space. 74 75 76Recording Data Access Patterns 77============================== 78 79The commands below record the memory access patterns of a program and save the 80monitoring results to a file. :: 81 82 $ ./masim ./configs/zigzag.cfg & 83 $ sudo damo record -o damon.data $(pidof masim) 84 85The line of the commands run the artificial memory access 86generator program again. The generator will repeatedly 87access two 100 MiB sized memory regions one by one. You can substitute this 88with your real workload. The last line asks ``damo`` to record the access 89pattern in the ``damon.data`` file. 90 91 92Visualizing Recorded Patterns 93============================= 94 95You can visualize the pattern in a heatmap, showing which memory region 96(x-axis) got accessed when (y-axis) and how frequently (number).:: 97 98 $ sudo damo report heats --heatmap stdout 99 22222222222222222222222222222222222222211111111111111111111111111111111111111100 100 44444444444444444444444444444444444444434444444444444444444444444444444444443200 101 44444444444444444444444444444444444444433444444444444444444444444444444444444200 102 33333333333333333333333333333333333333344555555555555555555555555555555555555200 103 33333333333333333333333333333333333344444444444444444444444444444444444444444200 104 22222222222222222222222222222222222223355555555555555555555555555555555555555200 105 00000000000000000000000000000000000000288888888888888888888888888888888888888400 106 00000000000000000000000000000000000000288888888888888888888888888888888888888400 107 33333333333333333333333333333333333333355555555555555555555555555555555555555200 108 88888888888888888888888888888888888888600000000000000000000000000000000000000000 109 88888888888888888888888888888888888888600000000000000000000000000000000000000000 110 33333333333333333333333333333333333333444444444444444444444444444444444444443200 111 00000000000000000000000000000000000000288888888888888888888888888888888888888400 112 [...] 113 # access_frequency: 0 1 2 3 4 5 6 7 8 9 114 # x-axis: space (139728247021568-139728453431248: 196.848 MiB) 115 # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s) 116 # resolution: 80x40 (2.461 MiB and 1.758 s for each character) 117 118You can also visualize the distribution of the working set size, sorted by the 119size.:: 120 121 $ sudo damo report wss --range 0 101 10 122 # <percentile> <wss> 123 # target_id 18446632103789443072 124 # avr: 107.708 MiB 125 0 0 B | | 126 10 95.328 MiB |**************************** | 127 20 95.332 MiB |**************************** | 128 30 95.340 MiB |**************************** | 129 40 95.387 MiB |**************************** | 130 50 95.387 MiB |**************************** | 131 60 95.398 MiB |**************************** | 132 70 95.398 MiB |**************************** | 133 80 95.504 MiB |**************************** | 134 90 190.703 MiB |********************************************************* | 135 100 196.875 MiB |***********************************************************| 136 137Using ``--sortby`` option with the above command, you can show how the working 138set size has chronologically changed.:: 139 140 $ sudo damo report wss --range 0 101 10 --sortby time 141 # <percentile> <wss> 142 # target_id 18446632103789443072 143 # avr: 107.708 MiB 144 0 3.051 MiB | | 145 10 190.703 MiB |***********************************************************| 146 20 95.336 MiB |***************************** | 147 30 95.328 MiB |***************************** | 148 40 95.387 MiB |***************************** | 149 50 95.332 MiB |***************************** | 150 60 95.320 MiB |***************************** | 151 70 95.398 MiB |***************************** | 152 80 95.398 MiB |***************************** | 153 90 95.340 MiB |***************************** | 154 100 95.398 MiB |***************************** | 155 156 157Data Access Pattern Aware Memory Management 158=========================================== 159 160Below command makes every memory region of size >=4K that has not accessed for 161>=60 seconds in your workload to be swapped out. :: 162 163 $ sudo damo schemes --damos_access_rate 0 0 --damos_sz_region 4K max \ 164 --damos_age 60s max --damos_action pageout \ 165 <pid of your workload> 166