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