0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===============
0004 Getting Started
0005 ===============
0006
0007 This document briefly describes how you can use DAMON by demonstrating its
0008 default user space tool. Please note that this document describes only a part
0009 of its features for brevity. Please refer to the usage `doc
0010 <https://github.com/awslabs/damo/blob/next/USAGE.md>`_ of the tool for more
0011 details.
0012
0013
0014 Prerequisites
0015 =============
0016
0017 Kernel
0018 ------
0019
0020 You should first ensure your system is running on a kernel built with
0021 ``CONFIG_DAMON_*=y``.
0022
0023
0024 User Space Tool
0025 ---------------
0026
0027 For the demonstration, we will use the default user space tool for DAMON,
0028 called DAMON Operator (DAMO). It is available at
0029 https://github.com/awslabs/damo. The examples below assume that ``damo`` is on
0030 your ``$PATH``. It's not mandatory, though.
0031
0032 Because DAMO is using the debugfs interface (refer to :doc:`usage` for the
0033 detail) of DAMON, you should ensure debugfs is mounted. Mount it manually as
0034 below::
0035
0036 # mount -t debugfs none /sys/kernel/debug/
0037
0038 or append the following line to your ``/etc/fstab`` file so that your system
0039 can automatically mount debugfs upon booting::
0040
0041 debugfs /sys/kernel/debug debugfs defaults 0 0
0042
0043
0044 Recording Data Access Patterns
0045 ==============================
0046
0047 The commands below record the memory access patterns of a program and save the
0048 monitoring results to a file. ::
0049
0050 $ git clone https://github.com/sjp38/masim
0051 $ cd masim; make; ./masim ./configs/zigzag.cfg &
0052 $ sudo damo record -o damon.data $(pidof masim)
0053
0054 The first two lines of the commands download an artificial memory access
0055 generator program and run it in the background. The generator will repeatedly
0056 access two 100 MiB sized memory regions one by one. You can substitute this
0057 with your real workload. The last line asks ``damo`` to record the access
0058 pattern in the ``damon.data`` file.
0059
0060
0061 Visualizing Recorded Patterns
0062 =============================
0063
0064 You can visualize the pattern in a heatmap, showing which memory region
0065 (x-axis) got accessed when (y-axis) and how frequently (number).::
0066
0067 $ sudo damo report heats --heatmap stdout
0068 22222222222222222222222222222222222222211111111111111111111111111111111111111100
0069 44444444444444444444444444444444444444434444444444444444444444444444444444443200
0070 44444444444444444444444444444444444444433444444444444444444444444444444444444200
0071 33333333333333333333333333333333333333344555555555555555555555555555555555555200
0072 33333333333333333333333333333333333344444444444444444444444444444444444444444200
0073 22222222222222222222222222222222222223355555555555555555555555555555555555555200
0074 00000000000000000000000000000000000000288888888888888888888888888888888888888400
0075 00000000000000000000000000000000000000288888888888888888888888888888888888888400
0076 33333333333333333333333333333333333333355555555555555555555555555555555555555200
0077 88888888888888888888888888888888888888600000000000000000000000000000000000000000
0078 88888888888888888888888888888888888888600000000000000000000000000000000000000000
0079 33333333333333333333333333333333333333444444444444444444444444444444444444443200
0080 00000000000000000000000000000000000000288888888888888888888888888888888888888400
0081 [...]
0082 # access_frequency: 0 1 2 3 4 5 6 7 8 9
0083 # x-axis: space (139728247021568-139728453431248: 196.848 MiB)
0084 # y-axis: time (15256597248362-15326899978162: 1 m 10.303 s)
0085 # resolution: 80x40 (2.461 MiB and 1.758 s for each character)
0086
0087 You can also visualize the distribution of the working set size, sorted by the
0088 size.::
0089
0090 $ sudo damo report wss --range 0 101 10
0091 # <percentile> <wss>
0092 # target_id 18446632103789443072
0093 # avr: 107.708 MiB
0094 0 0 B | |
0095 10 95.328 MiB |**************************** |
0096 20 95.332 MiB |**************************** |
0097 30 95.340 MiB |**************************** |
0098 40 95.387 MiB |**************************** |
0099 50 95.387 MiB |**************************** |
0100 60 95.398 MiB |**************************** |
0101 70 95.398 MiB |**************************** |
0102 80 95.504 MiB |**************************** |
0103 90 190.703 MiB |********************************************************* |
0104 100 196.875 MiB |***********************************************************|
0105
0106 Using ``--sortby`` option with the above command, you can show how the working
0107 set size has chronologically changed.::
0108
0109 $ sudo damo report wss --range 0 101 10 --sortby time
0110 # <percentile> <wss>
0111 # target_id 18446632103789443072
0112 # avr: 107.708 MiB
0113 0 3.051 MiB | |
0114 10 190.703 MiB |***********************************************************|
0115 20 95.336 MiB |***************************** |
0116 30 95.328 MiB |***************************** |
0117 40 95.387 MiB |***************************** |
0118 50 95.332 MiB |***************************** |
0119 60 95.320 MiB |***************************** |
0120 70 95.398 MiB |***************************** |
0121 80 95.398 MiB |***************************** |
0122 90 95.340 MiB |***************************** |
0123 100 95.398 MiB |***************************** |
0124
0125
0126 Data Access Pattern Aware Memory Management
0127 ===========================================
0128
0129 Below three commands make every memory region of size >=4K that doesn't
0130 accessed for >=60 seconds in your workload to be swapped out. ::
0131
0132 $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme
0133 $ echo "4K max 0 0 60s max pageout" >> test_scheme
0134 $ damo schemes -c test_scheme <pid of your workload>
