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