Documentation/admin-guide/mm/damon/start.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===============
   4 Getting Started
   5 ===============
   6
   7 This document briefly describes how you can use DAMON by demonstrating its
   8 default user space tool.  Please note that this document describes only a part
   9 of its features for brevity.  Please refer to the usage `doc
  10 <https://github.com/awslabs/damo/blob/next/USAGE.md>`_ of the tool for more
  11 details.
  12
  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 Prerequisites
  47 =============
  48
  49 Kernel
  50 ------
  51
  52 You should first ensure your system is running on a kernel built with
  53 ``CONFIG_DAMON_*=y``.
  54
  55
  56 User Space Tool
  57 ---------------
  58
  59 For the demonstration, we will use the default user space tool for DAMON,
  60 called DAMON Operator (DAMO).  It is available at
  61 https://github.com/awslabs/damo.  The examples below assume that ``damo`` is on
  62 your ``$PATH``.  It's not mandatory, though.
  63
  64 Because DAMO is using the debugfs interface (refer to :doc:`usage` for the
  65 detail) of DAMON, you should ensure debugfs is mounted.  Mount it manually as
  66 below::
  67
  68     # mount -t debugfs none /sys/kernel/debug/
  69
  70 or append the following line to your ``/etc/fstab`` file so that your system
  71 can automatically mount debugfs upon booting::
  72
  73     debugfs /sys/kernel/debug debugfs defaults 0 0
  74
  75
  76 Recording Data Access Patterns
  77 ==============================
  78
  79 The commands below record the memory access patterns of a program and save the
  80 monitoring results to a file. ::
  81
  82     $ git clone https://github.com/sjp38/masim
  83     $ cd masim; make; ./masim ./configs/zigzag.cfg &
  84     $ sudo damo record -o damon.data $(pidof masim)
  85
  86 The first two lines of the commands download an artificial memory access
  87 generator program and run it in the background.  The generator will repeatedly
  88 access two 100 MiB sized memory regions one by one.  You can substitute this
  89 with your real workload.  The last line asks ``damo`` to record the access
  90 pattern in the ``damon.data`` file.
  91
  92
  93 Visualizing Recorded Patterns
  94 =============================
  95
  96 The following three commands visualize the recorded access patterns and save
  97 the results as separate image files. ::
  98
  99     $ sudo damo report heats --heatmap access_pattern_heatmap.png
 100     $ sudo damo report wss --range 0 101 1 --plot wss_dist.png
 101     $ sudo damo report wss --range 0 101 1 --sortby time --plot wss_chron_change.png
 102
 103 - ``access_pattern_heatmap.png`` will visualize the data access pattern in a
 104   heatmap, showing which memory region (y-axis) got accessed when (x-axis)
 105   and how frequently (color).
 106 - ``wss_dist.png`` will show the distribution of the working set size.
 107 - ``wss_chron_change.png`` will show how the working set size has
 108   chronologically changed.
 109
 110 You can view the visualizations of this example workload at [1]_.
 111 Visualizations of other realistic workloads are available at [2]_ [3]_ [4]_.
 112
 113
 114 Data Access Pattern Aware Memory Management
 115 ===========================================
 116
 117 Below three commands make every memory region of size >=4K that doesn't
 118 accessed for >=60 seconds in your workload to be swapped out. ::
 119
 120     $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme
 121     $ echo "4K        max      0       0       60s     max     pageout" >> test_scheme
 122     $ damo schemes -c test_scheme <pid of your workload>
 123
 124 .. [1] https://damonitor.github.io/doc/html/v17/admin-guide/mm/damon/start.html#visualizing-recorded-patterns
 125 .. [2] https://damonitor.github.io/test/result/visual/latest/rec.heatmap.1.png.html
 126 .. [3] https://damonitor.github.io/test/result/visual/latest/rec.wss_sz.png.html
 127 .. [4] https://damonitor.github.io/test/result/visual/latest/rec.wss_time.png.html