Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

Docs/admin-guide/mm/damon/start: simplify the content

Information in 'TL; DR' section of 'Getting Started' is duplicated in
other parts of the doc. It is also asking readers to visit the access
pattern visualizations gallery web site to show the results of example
visualization commands, while the users of the commands can use terminal
output.

To make the doc simple, this removes the duplicated 'TL; DR' section and
replaces the visualization example commands with versions using terminal
outputs.

Link: https://lkml.kernel.org/r/20211022090311.3856-4-sj@kernel.org
Signed-off-by: SeongJae Park <sj@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Peter Xu <peterx@redhat.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

authored by

SeongJae Park and committed by
Linus Torvalds
b1eee3c5 49ce7dee

+57 -50
+57 -50
Documentation/admin-guide/mm/damon/start.rst
··· 11 11 details. 12 12 13 13 14 - TL; DR 15 - ====== 16 - 17 - Follow the commands below to monitor and visualize the memory access pattern of 18 - your workload. :: 19 - 20 - # # build the kernel with CONFIG_DAMON_*=y, install it, and reboot 21 - # mount -t debugfs none /sys/kernel/debug/ 22 - # git clone https://github.com/awslabs/damo 23 - # ./damo/damo record $(pidof <your workload>) 24 - # ./damo/damo report heats --heatmap stdout 25 - 26 - The final command draws the access heatmap of ``<your workload>``. The heatmap 27 - shows which memory region (x-axis) is accessed when (y-axis) and how frequently 28 - (number; the higher the more accesses have been observed). :: 29 - 30 - 111111111111111111111111111111111111111111111111111111110000 31 - 111121111111111111111111111111211111111111111111111111110000 32 - 000000000000000000000000000000000000000000000000001555552000 33 - 000000000000000000000000000000000000000000000222223555552000 34 - 000000000000000000000000000000000000000011111677775000000000 35 - 000000000000000000000000000000000000000488888000000000000000 36 - 000000000000000000000000000000000177888400000000000000000000 37 - 000000000000000000000000000046666522222100000000000000000000 38 - 000000000000000000000014444344444300000000000000000000000000 39 - 000000000000000002222245555510000000000000000000000000000000 40 - # access_frequency: 0 1 2 3 4 5 6 7 8 9 41 - # x-axis: space (140286319947776-140286426374096: 101.496 MiB) 42 - # y-axis: time (605442256436361-605479951866441: 37.695430s) 43 - # resolution: 60x10 (1.692 MiB and 3.770s for each character) 44 - 45 - 46 14 Prerequisites 47 15 ============= 48 16 ··· 61 93 Visualizing Recorded Patterns 62 94 ============================= 63 95 64 - The following three commands visualize the recorded access patterns and save 65 - the results as separate image files. :: 96 + You can visualize the pattern in a heatmap, showing which memory region 97 + (x-axis) got accessed when (y-axis) and how frequently (number).:: 66 98 67 - $ sudo damo report heats --heatmap access_pattern_heatmap.png 68 - $ sudo damo report wss --range 0 101 1 --plot wss_dist.png 69 - $ sudo damo report wss --range 0 101 1 --sortby time --plot wss_chron_change.png 99 + $ sudo damo report heats --heatmap stdout 100 + 22222222222222222222222222222222222222211111111111111111111111111111111111111100 101 + 44444444444444444444444444444444444444434444444444444444444444444444444444443200 102 + 44444444444444444444444444444444444444433444444444444444444444444444444444444200 103 + 33333333333333333333333333333333333333344555555555555555555555555555555555555200 104 + 33333333333333333333333333333333333344444444444444444444444444444444444444444200 105 + 22222222222222222222222222222222222223355555555555555555555555555555555555555200 106 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 107 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 108 + 33333333333333333333333333333333333333355555555555555555555555555555555555555200 109 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 110 + 88888888888888888888888888888888888888600000000000000000000000000000000000000000 111 + 33333333333333333333333333333333333333444444444444444444444444444444444444443200 112 + 00000000000000000000000000000000000000288888888888888888888888888888888888888400 113 + [...] 114 + # access_frequency: 0 1 2 3 4 5 6 7 8 9 115 + # x-axis: space (139728247021568-139728453431248: 196.848 MiB) 116 + # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s) 117 + # resolution: 80x40 (2.461 MiB and 1.758 s for each character) 70 118 71 - - ``access_pattern_heatmap.png`` will visualize the data access pattern in a 72 - heatmap, showing which memory region (y-axis) got accessed when (x-axis) 73 - and how frequently (color). 74 - - ``wss_dist.png`` will show the distribution of the working set size. 75 - - ``wss_chron_change.png`` will show how the working set size has 76 - chronologically changed. 119 + You can also visualize the distribution of the working set size, sorted by the 120 + size.:: 77 121 78 - You can view the visualizations of this example workload at [1]_. 79 - Visualizations of other realistic workloads are available at [2]_ [3]_ [4]_. 122 + $ sudo damo report wss --range 0 101 10 123 + # <percentile> <wss> 124 + # target_id 18446632103789443072 125 + # avr: 107.708 MiB 126 + 0 0 B | | 127 + 10 95.328 MiB |**************************** | 128 + 20 95.332 MiB |**************************** | 129 + 30 95.340 MiB |**************************** | 130 + 40 95.387 MiB |**************************** | 131 + 50 95.387 MiB |**************************** | 132 + 60 95.398 MiB |**************************** | 133 + 70 95.398 MiB |**************************** | 134 + 80 95.504 MiB |**************************** | 135 + 90 190.703 MiB |********************************************************* | 136 + 100 196.875 MiB |***********************************************************| 137 + 138 + Using ``--sortby`` option with the above command, you can show how the working 139 + set size has chronologically changed.:: 140 + 141 + $ sudo damo report wss --range 0 101 10 --sortby time 142 + # <percentile> <wss> 143 + # target_id 18446632103789443072 144 + # avr: 107.708 MiB 145 + 0 3.051 MiB | | 146 + 10 190.703 MiB |***********************************************************| 147 + 20 95.336 MiB |***************************** | 148 + 30 95.328 MiB |***************************** | 149 + 40 95.387 MiB |***************************** | 150 + 50 95.332 MiB |***************************** | 151 + 60 95.320 MiB |***************************** | 152 + 70 95.398 MiB |***************************** | 153 + 80 95.398 MiB |***************************** | 154 + 90 95.340 MiB |***************************** | 155 + 100 95.398 MiB |***************************** | 80 156 81 157 82 158 Data Access Pattern Aware Memory Management ··· 132 120 $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme 133 121 $ echo "4K max 0 0 60s max pageout" >> test_scheme 134 122 $ damo schemes -c test_scheme <pid of your workload> 135 - 136 - .. [1] https://damonitor.github.io/doc/html/v17/admin-guide/mm/damon/start.html#visualizing-recorded-patterns 137 - .. [2] https://damonitor.github.io/test/result/visual/latest/rec.heatmap.1.png.html 138 - .. [3] https://damonitor.github.io/test/result/visual/latest/rec.wss_sz.png.html 139 - .. [4] https://damonitor.github.io/test/result/visual/latest/rec.wss_time.png.html