xref: /linux/Documentation/admin-guide/mm/damon/start.rst (revision f3956ebb3bf06ab2266ad5ee2214aed46405810c) 
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 :doc:`usage` for more details.
10
11
12TL; DR
13======
14
15Follow the commands below to monitor and visualize the memory access pattern of
16your workload. ::
17
18    # # build the kernel with CONFIG_DAMON_*=y, install it, and reboot
19    # mount -t debugfs none /sys/kernel/debug/
20    # git clone https://github.com/awslabs/damo
21    # ./damo/damo record $(pidof <your workload>)
22    # ./damo/damo report heat --plot_ascii
23
24The final command draws the access heatmap of ``<your workload>``.  The heatmap
25shows which memory region (x-axis) is accessed when (y-axis) and how frequently
26(number; the higher the more accesses have been observed). ::
27
28    111111111111111111111111111111111111111111111111111111110000
29    111121111111111111111111111111211111111111111111111111110000
30    000000000000000000000000000000000000000000000000001555552000
31    000000000000000000000000000000000000000000000222223555552000
32    000000000000000000000000000000000000000011111677775000000000
33    000000000000000000000000000000000000000488888000000000000000
34    000000000000000000000000000000000177888400000000000000000000
35    000000000000000000000000000046666522222100000000000000000000
36    000000000000000000000014444344444300000000000000000000000000
37    000000000000000002222245555510000000000000000000000000000000
38    # access_frequency:  0  1  2  3  4  5  6  7  8  9
39    # x-axis: space (140286319947776-140286426374096: 101.496 MiB)
40    # y-axis: time (605442256436361-605479951866441: 37.695430s)
41    # resolution: 60x10 (1.692 MiB and 3.770s for each character)
42
43
44Prerequisites
45=============
46
47Kernel
48------
49
50You should first ensure your system is running on a kernel built with
51``CONFIG_DAMON_*=y``.
52
53
54User Space Tool
55---------------
56
57For the demonstration, we will use the default user space tool for DAMON,
58called DAMON Operator (DAMO).  It is available at
59https://github.com/awslabs/damo.  The examples below assume that ``damo`` is on
60your ``$PATH``.  It's not mandatory, though.
61
62Because DAMO is using the debugfs interface (refer to :doc:`usage` for the
63detail) of DAMON, you should ensure debugfs is mounted.  Mount it manually as
64below::
65
66    # mount -t debugfs none /sys/kernel/debug/
67
68or append the following line to your ``/etc/fstab`` file so that your system
69can automatically mount debugfs upon booting::
70
71    debugfs /sys/kernel/debug debugfs defaults 0 0
72
73
74Recording Data Access Patterns
75==============================
76
77The commands below record the memory access patterns of a program and save the
78monitoring results to a file. ::
79
80    $ git clone https://github.com/sjp38/masim
81    $ cd masim; make; ./masim ./configs/zigzag.cfg &
82    $ sudo damo record -o damon.data $(pidof masim)
83
84The first two lines of the commands download an artificial memory access
85generator program and run it in the background.  The generator will repeatedly
86access two 100 MiB sized memory regions one by one.  You can substitute this
87with your real workload.  The last line asks ``damo`` to record the access
88pattern in the ``damon.data`` file.
89
90
91Visualizing Recorded Patterns
92=============================
93
94The following three commands visualize the recorded access patterns and save
95the results as separate image files. ::
96
97    $ damo report heats --heatmap access_pattern_heatmap.png
98    $ damo report wss --range 0 101 1 --plot wss_dist.png
99    $ damo report wss --range 0 101 1 --sortby time --plot wss_chron_change.png
100
101- ``access_pattern_heatmap.png`` will visualize the data access pattern in a
102  heatmap, showing which memory region (y-axis) got accessed when (x-axis)
103  and how frequently (color).
104- ``wss_dist.png`` will show the distribution of the working set size.
105- ``wss_chron_change.png`` will show how the working set size has
106  chronologically changed.
107
108You can view the visualizations of this example workload at [1]_.
109Visualizations of other realistic workloads are available at [2]_ [3]_ [4]_.
110
111.. [1] https://damonitor.github.io/doc/html/v17/admin-guide/mm/damon/start.html#visualizing-recorded-patterns
112.. [2] https://damonitor.github.io/test/result/visual/latest/rec.heatmap.1.png.html
113.. [3] https://damonitor.github.io/test/result/visual/latest/rec.wss_sz.png.html
114.. [4] https://damonitor.github.io/test/result/visual/latest/rec.wss_time.png.html
115