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 37Recording Data Access Patterns 38============================== 39 40The commands below record the memory access patterns of a program and save the 41monitoring results to a file. :: 42 43 $ git clone https://github.com/sjp38/masim 44 $ cd masim; make; ./masim ./configs/zigzag.cfg & 45 $ sudo damo record -o damon.data $(pidof masim) 46 47The first two lines of the commands download an artificial memory access 48generator program and run it in the background. The generator will repeatedly 49access two 100 MiB sized memory regions one by one. You can substitute this 50with your real workload. The last line asks ``damo`` to record the access 51pattern in the ``damon.data`` file. 52 53 54Visualizing Recorded Patterns 55============================= 56 57You can visualize the pattern in a heatmap, showing which memory region 58(x-axis) got accessed when (y-axis) and how frequently (number).:: 59 60 $ sudo damo report heats --heatmap stdout 61 22222222222222222222222222222222222222211111111111111111111111111111111111111100 62 44444444444444444444444444444444444444434444444444444444444444444444444444443200 63 44444444444444444444444444444444444444433444444444444444444444444444444444444200 64 33333333333333333333333333333333333333344555555555555555555555555555555555555200 65 33333333333333333333333333333333333344444444444444444444444444444444444444444200 66 22222222222222222222222222222222222223355555555555555555555555555555555555555200 67 00000000000000000000000000000000000000288888888888888888888888888888888888888400 68 00000000000000000000000000000000000000288888888888888888888888888888888888888400 69 33333333333333333333333333333333333333355555555555555555555555555555555555555200 70 88888888888888888888888888888888888888600000000000000000000000000000000000000000 71 88888888888888888888888888888888888888600000000000000000000000000000000000000000 72 33333333333333333333333333333333333333444444444444444444444444444444444444443200 73 00000000000000000000000000000000000000288888888888888888888888888888888888888400 74 [...] 75 # access_frequency: 0 1 2 3 4 5 6 7 8 9 76 # x-axis: space (139728247021568-139728453431248: 196.848 MiB) 77 # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s) 78 # resolution: 80x40 (2.461 MiB and 1.758 s for each character) 79 80You can also visualize the distribution of the working set size, sorted by the 81size.:: 82 83 $ sudo damo report wss --range 0 101 10 84 # <percentile> <wss> 85 # target_id 18446632103789443072 86 # avr: 107.708 MiB 87 0 0 B | | 88 10 95.328 MiB |**************************** | 89 20 95.332 MiB |**************************** | 90 30 95.340 MiB |**************************** | 91 40 95.387 MiB |**************************** | 92 50 95.387 MiB |**************************** | 93 60 95.398 MiB |**************************** | 94 70 95.398 MiB |**************************** | 95 80 95.504 MiB |**************************** | 96 90 190.703 MiB |********************************************************* | 97 100 196.875 MiB |***********************************************************| 98 99Using ``--sortby`` option with the above command, you can show how the working 100set size has chronologically changed.:: 101 102 $ sudo damo report wss --range 0 101 10 --sortby time 103 # <percentile> <wss> 104 # target_id 18446632103789443072 105 # avr: 107.708 MiB 106 0 3.051 MiB | | 107 10 190.703 MiB |***********************************************************| 108 20 95.336 MiB |***************************** | 109 30 95.328 MiB |***************************** | 110 40 95.387 MiB |***************************** | 111 50 95.332 MiB |***************************** | 112 60 95.320 MiB |***************************** | 113 70 95.398 MiB |***************************** | 114 80 95.398 MiB |***************************** | 115 90 95.340 MiB |***************************** | 116 100 95.398 MiB |***************************** | 117 118 119Data Access Pattern Aware Memory Management 120=========================================== 121 122Below command makes every memory region of size >=4K that has not accessed for 123>=60 seconds in your workload to be swapped out. :: 124 125 $ sudo damo schemes --damos_access_rate 0 0 --damos_sz_region 4K max \ 126 --damos_age 60s max --damos_action pageout \ 127 <pid of your workload> 128