1c4ba6014SSeongJae Park.. SPDX-License-Identifier: GPL-2.0 2c4ba6014SSeongJae Park 3c4ba6014SSeongJae Park=============== 4c4ba6014SSeongJae ParkGetting Started 5c4ba6014SSeongJae Park=============== 6c4ba6014SSeongJae Park 7c4ba6014SSeongJae ParkThis document briefly describes how you can use DAMON by demonstrating its 8c4ba6014SSeongJae Parkdefault user space tool. Please note that this document describes only a part 949ce7deeSSeongJae Parkof its features for brevity. Please refer to the usage `doc 1049ce7deeSSeongJae Park<https://github.com/awslabs/damo/blob/next/USAGE.md>`_ of the tool for more 1149ce7deeSSeongJae Parkdetails. 12c4ba6014SSeongJae Park 13c4ba6014SSeongJae Park 14c4ba6014SSeongJae ParkPrerequisites 15c4ba6014SSeongJae Park============= 16c4ba6014SSeongJae Park 17c4ba6014SSeongJae ParkKernel 18c4ba6014SSeongJae Park------ 19c4ba6014SSeongJae Park 20c4ba6014SSeongJae ParkYou should first ensure your system is running on a kernel built with 21c4ba6014SSeongJae Park``CONFIG_DAMON_*=y``. 22c4ba6014SSeongJae Park 23c4ba6014SSeongJae Park 24c4ba6014SSeongJae ParkUser Space Tool 25c4ba6014SSeongJae Park--------------- 26c4ba6014SSeongJae Park 27c4ba6014SSeongJae ParkFor the demonstration, we will use the default user space tool for DAMON, 28c4ba6014SSeongJae Parkcalled DAMON Operator (DAMO). It is available at 29c4ba6014SSeongJae Parkhttps://github.com/awslabs/damo. The examples below assume that ``damo`` is on 30c4ba6014SSeongJae Parkyour ``$PATH``. It's not mandatory, though. 31c4ba6014SSeongJae Park 3204cc7e4bSSeongJae ParkBecause DAMO is using the sysfs interface (refer to :doc:`usage` for the 3304cc7e4bSSeongJae Parkdetail) of DAMON, you should ensure :doc:`sysfs </filesystems/sysfs>` is 3404cc7e4bSSeongJae Parkmounted. 35c4ba6014SSeongJae Park 36c4ba6014SSeongJae Park 37c4ba6014SSeongJae ParkRecording Data Access Patterns 38c4ba6014SSeongJae Park============================== 39c4ba6014SSeongJae Park 40c4ba6014SSeongJae ParkThe commands below record the memory access patterns of a program and save the 41c4ba6014SSeongJae Parkmonitoring results to a file. :: 42c4ba6014SSeongJae Park 43c4ba6014SSeongJae Park $ git clone https://github.com/sjp38/masim 44c4ba6014SSeongJae Park $ cd masim; make; ./masim ./configs/zigzag.cfg & 45c4ba6014SSeongJae Park $ sudo damo record -o damon.data $(pidof masim) 46c4ba6014SSeongJae Park 47c4ba6014SSeongJae ParkThe first two lines of the commands download an artificial memory access 48c4ba6014SSeongJae Parkgenerator program and run it in the background. The generator will repeatedly 49c4ba6014SSeongJae Parkaccess two 100 MiB sized memory regions one by one. You can substitute this 50c4ba6014SSeongJae Parkwith your real workload. The last line asks ``damo`` to record the access 51c4ba6014SSeongJae Parkpattern in the ``damon.data`` file. 52c4ba6014SSeongJae Park 53c4ba6014SSeongJae Park 54c4ba6014SSeongJae ParkVisualizing Recorded Patterns 55c4ba6014SSeongJae Park============================= 56c4ba6014SSeongJae Park 57b1eee3c5SSeongJae ParkYou can visualize the pattern in a heatmap, showing which memory region 58b1eee3c5SSeongJae Park(x-axis) got accessed when (y-axis) and how frequently (number).:: 59c4ba6014SSeongJae Park 60b1eee3c5SSeongJae Park $ sudo damo report heats --heatmap stdout 61b1eee3c5SSeongJae Park 22222222222222222222222222222222222222211111111111111111111111111111111111111100 62b1eee3c5SSeongJae Park 44444444444444444444444444444444444444434444444444444444444444444444444444443200 63b1eee3c5SSeongJae Park 44444444444444444444444444444444444444433444444444444444444444444444444444444200 64b1eee3c5SSeongJae Park 33333333333333333333333333333333333333344555555555555555555555555555555555555200 65b1eee3c5SSeongJae Park 33333333333333333333333333333333333344444444444444444444444444444444444444444200 66b1eee3c5SSeongJae Park 22222222222222222222222222222222222223355555555555555555555555555555555555555200 67b1eee3c5SSeongJae Park 00000000000000000000000000000000000000288888888888888888888888888888888888888400 68b1eee3c5SSeongJae Park 00000000000000000000000000000000000000288888888888888888888888888888888888888400 69b1eee3c5SSeongJae Park 33333333333333333333333333333333333333355555555555555555555555555555555555555200 70b1eee3c5SSeongJae Park 88888888888888888888888888888888888888600000000000000000000000000000000000000000 71b1eee3c5SSeongJae Park 88888888888888888888888888888888888888600000000000000000000000000000000000000000 72b1eee3c5SSeongJae Park 33333333333333333333333333333333333333444444444444444444444444444444444444443200 73b1eee3c5SSeongJae Park 00000000000000000000000000000000000000288888888888888888888888888888888888888400 74b1eee3c5SSeongJae Park [...] 75b1eee3c5SSeongJae Park # access_frequency: 0 1 2 3 4 5 6 7 8 9 76b1eee3c5SSeongJae Park # x-axis: space (139728247021568-139728453431248: 196.848 MiB) 77b1eee3c5SSeongJae Park # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s) 78b1eee3c5SSeongJae Park # resolution: 80x40 (2.461 MiB and 1.758 s for each character) 79c4ba6014SSeongJae Park 80b1eee3c5SSeongJae ParkYou can also visualize the distribution of the working set size, sorted by the 81b1eee3c5SSeongJae Parksize.:: 82c4ba6014SSeongJae Park 83b1eee3c5SSeongJae Park $ sudo damo report wss --range 0 101 10 84b1eee3c5SSeongJae Park # <percentile> <wss> 85b1eee3c5SSeongJae Park # target_id 18446632103789443072 86b1eee3c5SSeongJae Park # avr: 107.708 MiB 87b1eee3c5SSeongJae Park 0 0 B | | 88b1eee3c5SSeongJae Park 10 95.328 MiB |**************************** | 89b1eee3c5SSeongJae Park 20 95.332 MiB |**************************** | 90b1eee3c5SSeongJae Park 30 95.340 MiB |**************************** | 91b1eee3c5SSeongJae Park 40 95.387 MiB |**************************** | 92b1eee3c5SSeongJae Park 50 95.387 MiB |**************************** | 93b1eee3c5SSeongJae Park 60 95.398 MiB |**************************** | 94b1eee3c5SSeongJae Park 70 95.398 MiB |**************************** | 95b1eee3c5SSeongJae Park 80 95.504 MiB |**************************** | 96b1eee3c5SSeongJae Park 90 190.703 MiB |********************************************************* | 97b1eee3c5SSeongJae Park 100 196.875 MiB |***********************************************************| 98b1eee3c5SSeongJae Park 99b1eee3c5SSeongJae ParkUsing ``--sortby`` option with the above command, you can show how the working 100b1eee3c5SSeongJae Parkset size has chronologically changed.:: 101b1eee3c5SSeongJae Park 102b1eee3c5SSeongJae Park $ sudo damo report wss --range 0 101 10 --sortby time 103b1eee3c5SSeongJae Park # <percentile> <wss> 104b1eee3c5SSeongJae Park # target_id 18446632103789443072 105b1eee3c5SSeongJae Park # avr: 107.708 MiB 106b1eee3c5SSeongJae Park 0 3.051 MiB | | 107b1eee3c5SSeongJae Park 10 190.703 MiB |***********************************************************| 108b1eee3c5SSeongJae Park 20 95.336 MiB |***************************** | 109b1eee3c5SSeongJae Park 30 95.328 MiB |***************************** | 110b1eee3c5SSeongJae Park 40 95.387 MiB |***************************** | 111b1eee3c5SSeongJae Park 50 95.332 MiB |***************************** | 112b1eee3c5SSeongJae Park 60 95.320 MiB |***************************** | 113b1eee3c5SSeongJae Park 70 95.398 MiB |***************************** | 114b1eee3c5SSeongJae Park 80 95.398 MiB |***************************** | 115b1eee3c5SSeongJae Park 90 95.340 MiB |***************************** | 116b1eee3c5SSeongJae Park 100 95.398 MiB |***************************** | 117c4ba6014SSeongJae Park 11868536f8eSSeongJae Park 11968536f8eSSeongJae ParkData Access Pattern Aware Memory Management 12068536f8eSSeongJae Park=========================================== 12168536f8eSSeongJae Park 122*60eb644bSSeongJae ParkBelow command makes every memory region of size >=4K that has not accessed for 123*60eb644bSSeongJae Park>=60 seconds in your workload to be swapped out. :: 12468536f8eSSeongJae Park 125*60eb644bSSeongJae Park $ sudo damo schemes --damos_access_rate 0 0 --damos_sz_region 4K max \ 126*60eb644bSSeongJae Park --damos_age 60s max --damos_action pageout \ 127*60eb644bSSeongJae Park <pid of your workload> 128