1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 =============== 3 ===============
4 Getting Started 4 Getting Started
5 =============== 5 ===============
6 6
7 This document briefly describes how you can us 7 This document briefly describes how you can use DAMON by demonstrating its
8 default user space tool. Please note that thi 8 default user space tool. Please note that this document describes only a part
9 of its features for brevity. Please refer to 9 of its features for brevity. Please refer to the usage `doc
10 <https://github.com/damonitor/damo/blob/next/U 10 <https://github.com/damonitor/damo/blob/next/USAGE.md>`_ of the tool for more
11 details. 11 details.
12 12
13 13
14 Prerequisites 14 Prerequisites
15 ============= 15 =============
16 16
17 Kernel 17 Kernel
18 ------ 18 ------
19 19
20 You should first ensure your system is running 20 You should first ensure your system is running on a kernel built with
21 ``CONFIG_DAMON_*=y``. 21 ``CONFIG_DAMON_*=y``.
22 22
23 23
24 User Space Tool 24 User Space Tool
25 --------------- 25 ---------------
26 26
27 For the demonstration, we will use the default 27 For the demonstration, we will use the default user space tool for DAMON,
28 called DAMON Operator (DAMO). It is available 28 called DAMON Operator (DAMO). It is available at
29 https://github.com/damonitor/damo. The exampl 29 https://github.com/damonitor/damo. The examples below assume that ``damo`` is on
30 your ``$PATH``. It's not mandatory, though. 30 your ``$PATH``. It's not mandatory, though.
31 31
32 Because DAMO is using the sysfs interface (ref 32 Because DAMO is using the sysfs interface (refer to :doc:`usage` for the
33 detail) of DAMON, you should ensure :doc:`sysf 33 detail) of DAMON, you should ensure :doc:`sysfs </filesystems/sysfs>` is
34 mounted. 34 mounted.
35 35
36 36
37 Snapshot Data Access Patterns 37 Snapshot Data Access Patterns
38 ============================= 38 =============================
39 39
40 The commands below show the memory access patt 40 The commands below show the memory access pattern of a program at the moment of
41 the execution. :: 41 the execution. ::
42 42
43 $ git clone https://github.com/sjp38/masim 43 $ git clone https://github.com/sjp38/masim; cd masim; make
44 $ sudo damo start "./masim ./configs/stair 44 $ sudo damo start "./masim ./configs/stairs.cfg --quiet"
45 $ sudo ./damo show 45 $ sudo ./damo show
46 0 addr [85.541 TiB , 85.541 TiB ) (57.7 46 0 addr [85.541 TiB , 85.541 TiB ) (57.707 MiB ) access 0 % age 10.400 s
47 1 addr [85.541 TiB , 85.542 TiB ) (413. 47 1 addr [85.541 TiB , 85.542 TiB ) (413.285 MiB) access 0 % age 11.400 s
48 2 addr [127.649 TiB , 127.649 TiB) (57.5 48 2 addr [127.649 TiB , 127.649 TiB) (57.500 MiB ) access 0 % age 1.600 s
49 3 addr [127.649 TiB , 127.649 TiB) (32.5 49 3 addr [127.649 TiB , 127.649 TiB) (32.500 MiB ) access 0 % age 500 ms
50 4 addr [127.649 TiB , 127.649 TiB) (9.53 50 4 addr [127.649 TiB , 127.649 TiB) (9.535 MiB ) access 100 % age 300 ms
51 5 addr [127.649 TiB , 127.649 TiB) (8.00 51 5 addr [127.649 TiB , 127.649 TiB) (8.000 KiB ) access 60 % age 0 ns
52 6 addr [127.649 TiB , 127.649 TiB) (6.92 52 6 addr [127.649 TiB , 127.649 TiB) (6.926 MiB ) access 0 % age 1 s
53 7 addr [127.998 TiB , 127.998 TiB) (120. 53 7 addr [127.998 TiB , 127.998 TiB) (120.000 KiB) access 0 % age 11.100 s
54 8 addr [127.998 TiB , 127.998 TiB) (8.00 54 8 addr [127.998 TiB , 127.998 TiB) (8.000 KiB ) access 40 % age 100 ms
55 9 addr [127.998 TiB , 127.998 TiB) (4.00 55 9 addr [127.998 TiB , 127.998 TiB) (4.000 KiB ) access 0 % age 11 s
56 total size: 577.590 MiB 56 total size: 577.590 MiB
57 $ sudo ./damo stop 57 $ sudo ./damo stop
58 58
59 The first command of the above example downloa 59 The first command of the above example downloads and builds an artificial
60 memory access generator program called ``masim 60 memory access generator program called ``masim``. The second command asks DAMO
61 to execute the artificial generator process st 61 to execute the artificial generator process start via the given command and
62 make DAMON monitors the generator process. Th 62 make DAMON monitors the generator process. The third command retrieves the
63 current snapshot of the monitored access patte 63 current snapshot of the monitored access pattern of the process from DAMON and
64 shows the pattern in a human readable format. 64 shows the pattern in a human readable format.
65 65
66 Each line of the output shows which virtual ad 66 Each line of the output shows which virtual address range (``addr [XX, XX)``)
67 of the process is how frequently (``access XX 67 of the process is how frequently (``access XX %``) accessed for how long time
68 (``age XX``). For example, the fifth region o 68 (``age XX``). For example, the fifth region of ~9 MiB size is being most
69 frequently accessed for last 300 milliseconds. 69 frequently accessed for last 300 milliseconds. Finally, the fourth command
70 stops DAMON. 70 stops DAMON.
71 71
72 Note that DAMON can monitor not only virtual a 72 Note that DAMON can monitor not only virtual address spaces but multiple types
73 of address spaces including the physical addre 73 of address spaces including the physical address space.
74 74
75 75
76 Recording Data Access Patterns 76 Recording Data Access Patterns
77 ============================== 77 ==============================
78 78
79 The commands below record the memory access pa 79 The commands below record the memory access patterns of a program and save the
80 monitoring results to a file. :: 80 monitoring results to a file. ::
81 81
82 $ ./masim ./configs/zigzag.cfg & 82 $ ./masim ./configs/zigzag.cfg &
83 $ sudo damo record -o damon.data $(pidof m 83 $ sudo damo record -o damon.data $(pidof masim)
84 84
85 The line of the commands run the artificial me 85 The line of the commands run the artificial memory access
86 generator program again. The generator will r 86 generator program again. The generator will repeatedly
87 access two 100 MiB sized memory regions one by 87 access two 100 MiB sized memory regions one by one. You can substitute this
88 with your real workload. The last line asks ` 88 with your real workload. The last line asks ``damo`` to record the access
89 pattern in the ``damon.data`` file. 89 pattern in the ``damon.data`` file.
90 90
91 91
92 Visualizing Recorded Patterns 92 Visualizing Recorded Patterns
93 ============================= 93 =============================
94 94
95 You can visualize the pattern in a heatmap, sh 95 You can visualize the pattern in a heatmap, showing which memory region
96 (x-axis) got accessed when (y-axis) and how fr 96 (x-axis) got accessed when (y-axis) and how frequently (number).::
97 97
98 $ sudo damo report heats --heatmap stdout 98 $ sudo damo report heats --heatmap stdout
99 222222222222222222222222222222222222222111 99 22222222222222222222222222222222222222211111111111111111111111111111111111111100
100 444444444444444444444444444444444444444344 100 44444444444444444444444444444444444444434444444444444444444444444444444444443200
101 444444444444444444444444444444444444444334 101 44444444444444444444444444444444444444433444444444444444444444444444444444444200
102 333333333333333333333333333333333333333445 102 33333333333333333333333333333333333333344555555555555555555555555555555555555200
103 333333333333333333333333333333333333444444 103 33333333333333333333333333333333333344444444444444444444444444444444444444444200
104 222222222222222222222222222222222222233555 104 22222222222222222222222222222222222223355555555555555555555555555555555555555200
105 000000000000000000000000000000000000002888 105 00000000000000000000000000000000000000288888888888888888888888888888888888888400
106 000000000000000000000000000000000000002888 106 00000000000000000000000000000000000000288888888888888888888888888888888888888400
107 333333333333333333333333333333333333333555 107 33333333333333333333333333333333333333355555555555555555555555555555555555555200
108 888888888888888888888888888888888888886000 108 88888888888888888888888888888888888888600000000000000000000000000000000000000000
109 888888888888888888888888888888888888886000 109 88888888888888888888888888888888888888600000000000000000000000000000000000000000
110 333333333333333333333333333333333333334444 110 33333333333333333333333333333333333333444444444444444444444444444444444444443200
111 000000000000000000000000000000000000002888 111 00000000000000000000000000000000000000288888888888888888888888888888888888888400
112 [...] 112 [...]
113 # access_frequency: 0 1 2 3 4 5 6 113 # access_frequency: 0 1 2 3 4 5 6 7 8 9
114 # x-axis: space (139728247021568-139728453 114 # x-axis: space (139728247021568-139728453431248: 196.848 MiB)
115 # y-axis: time (15256597248362-15326899978 115 # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s)
116 # resolution: 80x40 (2.461 MiB and 1.758 s 116 # resolution: 80x40 (2.461 MiB and 1.758 s for each character)
117 117
118 You can also visualize the distribution of the 118 You can also visualize the distribution of the working set size, sorted by the
119 size.:: 119 size.::
120 120
121 $ sudo damo report wss --range 0 101 10 121 $ sudo damo report wss --range 0 101 10
122 # <percentile> <wss> 122 # <percentile> <wss>
123 # target_id 18446632103789443072 123 # target_id 18446632103789443072
124 # avr: 107.708 MiB 124 # avr: 107.708 MiB
125 0 0 B | 125 0 0 B | |
126 10 95.328 MiB |********************* 126 10 95.328 MiB |**************************** |
127 20 95.332 MiB |********************* 127 20 95.332 MiB |**************************** |
128 30 95.340 MiB |********************* 128 30 95.340 MiB |**************************** |
129 40 95.387 MiB |********************* 129 40 95.387 MiB |**************************** |
130 50 95.387 MiB |********************* 130 50 95.387 MiB |**************************** |
131 60 95.398 MiB |********************* 131 60 95.398 MiB |**************************** |
132 70 95.398 MiB |********************* 132 70 95.398 MiB |**************************** |
133 80 95.504 MiB |********************* 133 80 95.504 MiB |**************************** |
134 90 190.703 MiB |********************* 134 90 190.703 MiB |********************************************************* |
135 100 196.875 MiB |********************* 135 100 196.875 MiB |***********************************************************|
136 136
137 Using ``--sortby`` option with the above comma 137 Using ``--sortby`` option with the above command, you can show how the working
138 set size has chronologically changed.:: 138 set size has chronologically changed.::
139 139
140 $ sudo damo report wss --range 0 101 10 -- 140 $ sudo damo report wss --range 0 101 10 --sortby time
141 # <percentile> <wss> 141 # <percentile> <wss>
142 # target_id 18446632103789443072 142 # target_id 18446632103789443072
143 # avr: 107.708 MiB 143 # avr: 107.708 MiB
144 0 3.051 MiB | 144 0 3.051 MiB | |
145 10 190.703 MiB |********************* 145 10 190.703 MiB |***********************************************************|
146 20 95.336 MiB |********************* 146 20 95.336 MiB |***************************** |
147 30 95.328 MiB |********************* 147 30 95.328 MiB |***************************** |
148 40 95.387 MiB |********************* 148 40 95.387 MiB |***************************** |
149 50 95.332 MiB |********************* 149 50 95.332 MiB |***************************** |
150 60 95.320 MiB |********************* 150 60 95.320 MiB |***************************** |
151 70 95.398 MiB |********************* 151 70 95.398 MiB |***************************** |
152 80 95.398 MiB |********************* 152 80 95.398 MiB |***************************** |
153 90 95.340 MiB |********************* 153 90 95.340 MiB |***************************** |
154 100 95.398 MiB |********************* 154 100 95.398 MiB |***************************** |
155 155
156 156
157 Data Access Pattern Aware Memory Management 157 Data Access Pattern Aware Memory Management
158 =========================================== 158 ===========================================
159 159
160 Below command makes every memory region of siz 160 Below command makes every memory region of size >=4K that has not accessed for
161 >=60 seconds in your workload to be swapped ou 161 >=60 seconds in your workload to be swapped out. ::
162 162
163 $ sudo damo schemes --damos_access_rate 0 163 $ sudo damo schemes --damos_access_rate 0 0 --damos_sz_region 4K max \
164 --damos_age 60s max -- 164 --damos_age 60s max --damos_action pageout \
165 <pid of your workload> 165 <pid of your workload>
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.