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 three commands make every memory region of size >=4K that doesn't
123accessed for >=60 seconds in your workload to be swapped out. ::
124
125    $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme
126    $ echo "4K        max      0       0       60s     max     pageout" >> test_scheme
127    $ damo schemes -c test_scheme <pid of your workload>
128