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