diff --git a/Documentation/admin-guide/mm/damon/api.rst b/Documentation/admin-guide/mm/damon/api.rst
new file mode 100644
index 000000000000..2249d2116b39
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/api.rst
@@ -0,0 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+API Reference
+=============
+
+.. kernel-doc:: include/linux/damon.h
+
+.. kernel-doc:: mm/damon.c
diff --git a/Documentation/admin-guide/mm/damon/damon_heatmap.png b/Documentation/admin-guide/mm/damon/damon_heatmap.png
new file mode 100644
index 0000000000000000000000000000000000000000..ff485f9f59ca2717f5221b2824eaaed616b22c0e
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/damon_wss_change.png b/Documentation/admin-guide/mm/damon/damon_wss_change.png
new file mode 100644
index 0000000000000000000000000000000000000000..36699547c342cd05c9f416c78bc3fc86b9dc415e
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/damon_wss_dist.png b/Documentation/admin-guide/mm/damon/damon_wss_dist.png
new file mode 100644
index 0000000000000000000000000000000000000000..3c390f5115af9bcf7bd76ccdf9414de8ace9799b
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/faq.rst b/Documentation/admin-guide/mm/damon/faq.rst
new file mode 100644
index 000000000000..7ea52d1078a0
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/faq.rst
@@ -0,0 +1,39 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+Frequently Asked Questions
+==========================
+
+Why a new module, instead of extending perf or other user space tools?
+======================================================================
+
+First, because it needs to be lightweight as much as possible so that it can be
+used online, any unnecessary overhead such as kernel - user space context
+switching cost should be avoided.  Second, DAMON aims to be used by other
+programs including the kernel.  Therefore, having a dependency on specific
+tools like perf is not desirable.  These are the two biggest reasons why DAMON
+is implemented in the kernel space.
+
+
+Can 'idle pages tracking' or 'perf mem' substitute DAMON?
+=========================================================
+
+Idle page tracking is a low level primitive for access check of each physical
+page frame.  'perf mem' is similar, though it can use sampling to minimize the
+overhead.  DAMON is a higher-level framework for access patterns of data objects
+that focused on memory management optimization and providing sophisticated
+features for that including the overhead handling.  Therefore, 'idle pages
+tracking' and 'perf mem' could provide a subset of DAMON's output, but cannot
+substitute DAMON.  Rather than that, DAMON could use those as it's low-level
+primitives.
+
+
+Does DAMON support virtual memory only?
+========================================
+
+For now, yes.  But, DAMON will be able to support various address spaces
+including physical memory in near future.  An RFC patchset [1]_ for this
+extension is already available.  Please refer :doc:`plans` for detailed plan
+for this.
+
+.. [1] https://lore.kernel.org/linux-mm/20200409094232.29680-1-sjpark@amazon.com/
diff --git a/Documentation/admin-guide/mm/damon/freqmine_heatmap.png b/Documentation/admin-guide/mm/damon/freqmine_heatmap.png
new file mode 100644
index 0000000000000000000000000000000000000000..9641bade4e2e52cfaf77ac2ef50607239ab90899
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/freqmine_wss_sz.png b/Documentation/admin-guide/mm/damon/freqmine_wss_sz.png
new file mode 100644
index 0000000000000000000000000000000000000000..28049dec5fabfca0ca33896ee6b667dc116aacbf
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/freqmine_wss_time.png b/Documentation/admin-guide/mm/damon/freqmine_wss_time.png
new file mode 100644
index 0000000000000000000000000000000000000000..3ca9df7ee11a9cf650fc75497f653345eba28eea
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/guide.rst b/Documentation/admin-guide/mm/damon/guide.rst
new file mode 100644
index 000000000000..4a840d1b02d4
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/guide.rst
@@ -0,0 +1,196 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+The Beginner's Guide
+====================
+
+This document is to help you estimating the amount of benefit that you could
+get from DAMON, and to let you know how you could maximize the improvement.
+You are assumed to already read :doc:`start`.
+
+
+Check The Signs
+===============
+
+DAMON cannot provide the same amount of benefit to every workload.  Therefore
+you should first guess how much improvements you could get using DAMON.  If
+some of the below conditions match your situation, you could consider the use
+of DAMON.
+
+
+- *Low IPC and High Cache Miss Ratios.*  Low IPC means most of the CPU time is
+  spent waiting for the completion of time-consuming operations such as memory
+  access, while high cache miss ratios mean the caches don't help it well.
+  DAMON is not for cache level optimization, but DRAM level.  However,
+  improving DRAM management will also help this case by reducing the memory
+  operation latency.
+- *Memory Over-commitment and Unknown Users.*  If you are doing memory
+  overcommitment and you cannot control every user of your system, a memory
+  bank run could happen at any time.  You can estimate when it will happen
+  based on DAMON's monitoring results and act earlier to avoid or deal better
+  with the crisis.
+- *Frequent Memory Pressure.*  Frequent memory pressure means the wrong
+  configuration or existence of memory hogs.  DAMON will help you find the
+  right configuration and/or the criminals.
+- *Heterogeneous Memory System.*  If your system is utilizing memory devices
+  that placed between DRAM and traditional hard disks, such as non-volatile
+  memory or fast SSDs, DAMON could help you utilizing the devices more
+  efficiently.
+
+
+Profile
+=======
+
+If you found some positive signals, you could start by profiling your workloads
+using DAMON.  Find major workloads on your systems and analyze their data
+access pattern to find something wrong or can be improved.  The DAMON user
+space tool (``damo``) will be enough for this.
+
+We recommend you to start from working set size distribution check using ``damo
+report wss``.  If the distribution is ununiform or quite different from what
+you estimated, you could consider `Memory Configuration`_ optimization.
+
+Then, review the overall access pattern in heatmap form using ``damo report
+heats``.  If it shows a simple pattern consists of a small number of memory
+regions having high contrast of access temperature, you could consider `Manual
+Program Optimization`_.
+
+You don't need to take only one approach among the above plans, but you could
+use multiple of the above approaches to maximize the benefit.  If you still
+want to absorb more benefits, you should develop `Personalized DAMON
+Application`_ for your special case.
+
+
+Optimize
+========
+
+If the profiling result also says it's worth trying some optimization, you
+could consider the below approaches.  Note that some of the below approaches
+assume that your systems are configured with swap devices or other types of
+auxiliary memory so that you don't need to accommodate the whole working set in
+the main memory.  Most of the detailed optimization should be made on your
+concrete understanding of your swap and/or your auxiliary memory performance.
+
+
+Memory Configuration
+--------------------
+
+DRAM is highly performance critical but expensive and heavily consumes the
+power.  However, knowing the real important working set size is hard and thus
+people usually equips unnecessarily large or too small DRAM.  So many problems
+come from such wrong configurations.
+
+Using the working set size distribution report provided by ``damo report wss``,
+you can know the real needs and make reasonable tradeoffs.  For example,
+roughly speaking, if you worry about only 95 percentile latency, you don't need
+to equip DRAM of a size larger than 95 percentile working set size.  If you
+were suffered from frequent memory pressure, you will also easily know how much
+DRAM you should buy.
+
+Let's see a real example.  Below are the heatmap and the working set size
+distributions/changes of ``freqmine`` workload in PARSEC3 benchmark suite.  The
+working set size spikes up to 700 MiB, but keeps smaller than 100 MiB for more
+than 95% of the time.  Even though you give only 100 MiB of memory space to the
+workload, it will work well for 95% of the time.  Meanwhile, you can save the
+600 MiB of memory space.
+
+.. list-table::
+
+   * - .. kernel-figure::  freqmine_heatmap.png
+          :alt:   the access pattern in heatmap format
+          :align: center
+
+          The access pattern in heatmap format.
+
+     - .. kernel-figure::  freqmine_wss_sz.png
+          :alt:    the distribution of working set size
+          :align: center
+
+          The distribution of working set size.
+
+     - .. kernel-figure::  freqmine_wss_time.png
+          :alt:    the chronological changes of working set size
+          :align: center
+
+          The chronological changes of working set size.
+
+
+Program Modification
+--------------------
+
+If the data access pattern heatmap plotted using ``damo report heats`` is quite
+simple and clear, you could be able to know how the thing is going in the
+workload, and how you could make optimize memory management.
+
+For example, suppose that the workload has two big memory object but only one
+object is frequently accessed while the other is only occasionally scanned.
+Then, you could modify the program source code to invoke ``mlock()`` or
+``madvise()`` with ``WILLNEED`` system call for the hot object.  Or, you could
+use ``madvise()`` with ``MADV_COLD`` or ``MADV_PAGEOUT`` for the cold objects.
+Using both together would be also worth trying.
+
+A previous work [1]_ using the ``mlock()`` achieved up to 2.55x performance
+speedup.
+
+Let's see another realistic example access pattern for this kind of
+optimizations.  Below are the visualized access patterns of streamcluster
+workload in PARSEC3 benchmark suite.  We can easily see a 100 MiB sized memory
+object is the hot object.
+
+.. list-table::
+
+   * - .. kernel-figure::  streamcluster_heatmap.png
+          :alt:   the access pattern in heatmap format
+          :align: center
+
+          The access pattern in heatmap format.
+
+     - .. kernel-figure::  streamcluster_wss_sz.png
+          :alt:    the distribution of working set size
+          :align: center
+
+          The distribution of working set size.
+
+     - .. kernel-figure::  streamcluster_wss_time.png
+          :alt:    the chronological changes of working set size
+          :align: center
+
+          The chronological changes of working set size.
+
+
+Personalized DAMON Application
+------------------------------
+
+Below approaches will work well for many cases, but would not be able to
+squeeze the last benefit in some special cases because only very simple
+optimizations are available.
+
+If this is the case, it might be the time to forget the comfortable use of the
+user space tool and dive into the debugfs interface (refer to :doc:`usage` for
+the detail) of DAMON.  Using the interface, you can control the DAMON more
+flexibly.  Therefore, you can write your personalized DAMON application that
+controls the monitoring via the debugfs interface, analyzes the result, and
+apply complex optimizations itself.  Using this, you will be able to make more
+creative and wise optimizations.
+
+If you are kernel space programmer, writing kernel space DAMON applications
+using the API (refer to :doc:`api` for more detail) would be also an option.
+
+
+Reference Practices
+===================
+
+Referencing previously done successful practices could help you getting the
+sense for this kind of optimizations.  There is an academic paper [1]_
+previously reported the visualized access pattern and `Manual Program
+Optimization`_ results for a number of realistic workloads.  You can also get
+the visualized access pattern [4]_, [5]_, [6]_ and `Automated DAMON-based
+Memory Operations`_ results for other realistic workloads that collected with
+latest version of DAMON [2]_, [3]_.
+
+.. [1] https://dl.acm.org/doi/10.1145/3366626.3368125
+.. [2] https://damonitor.github.io/test/result/perf/latest/html/
+.. [3] https://lore.kernel.org/linux-mm/20200512115343.27699-1-sjpark@amazon.com/
+.. [4] https://damonitor.github.io/test/result/visual/latest/heatmap.1.html
+.. [5] https://damonitor.github.io/test/result/visual/latest/wss_sz.html
+.. [6] https://damonitor.github.io/test/result/visual/latest/wss_time.html
diff --git a/Documentation/admin-guide/mm/damon/index.rst b/Documentation/admin-guide/mm/damon/index.rst
new file mode 100644
index 000000000000..7833b607618c
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/index.rst
@@ -0,0 +1,50 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+DAMON: Data Access MONitor
+==========================
+
+The memory management is supposed to provide optimal placement of data objects
+under accurate predictions of future data accesses.  The predictions should be
+made on fine information about current accesses, but most of those are relying
+on only coarse ones, to keep the instrumentation overhead minimal.  As a
+consequence, a number of finer access information based memory management
+optimization works consistently pointed out the predictions are far from
+optimal.  That said, most of such optimization works have failed being merged
+into the mainline Linux kernel mainly due to the high overhead of their data
+access pattern instrumentation.
+
+From here, we can list up below three requirements for the data access
+information instrumentation that must be fulfilled to be adopted in a wide
+range of production environments.
+
+- *accuracy*.  The instrumented information should be useful for DRAM level
+  memory management.  Cache-level accuracy would not highly required, though.
+- *light-weight overhead*.  The instrumentation overhead should be low enough
+  to be applied online while making no impact on the performance of the main
+  workloads.
+- *scalability*.  Environmental changes such as the size of instrumentation
+  target workloads should not be able to make the instrumentation overhead
+  arbitrarily increase.
+
+DAMON is a data access monitoring framework subsystem for the Linux kernel.
+The core mechanisms of DAMON called 'region based sampling' and adaptive
+regions adjustment' (refer to :doc:`mechanisms` for the detail) make it fulfill
+the requirements.  Using this framework, therefore, the kernel's core memory
+management mechanisms including reclamation and THP can be optimized for better
+memory management.  The above-mentioned memory management optimization works
+that have not merged into the mainline will be able to have another try.  In
+user space, meanwhile, users who have some special workloads will be able to
+write personalized tools or applications for more understanding and specialized
+optimizations of their systems using the DAMON as a framework.
+
+.. toctree::
+   :maxdepth: 2
+
+   start
+   guide
+   usage
+   api
+   faq
+   mechanisms
+   plans
diff --git a/Documentation/admin-guide/mm/damon/mechanisms.rst b/Documentation/admin-guide/mm/damon/mechanisms.rst
new file mode 100644
index 000000000000..f0bc52c698a6
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/mechanisms.rst
@@ -0,0 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========
+Mechanisms
+==========
+
+This document describes the core mechanisms of DAMON and the five knobs for
+tuning, that is, ``sampling interval``, ``aggregation interval``, ``regions
+update interval``, ``minimum number of regions``, and ``maximum number of
+regions``.
+
+
+Basic Access Check
+==================
+
+The output of DAMON says what pages are how frequently accessed for a given
+duration.  The resolution of the access frequency is controlled by setting
+``sampling interval`` and ``aggregation interval``.  In detail,
+DAMON checks access to each page per ``sampling interval``, aggregates the
+results.  In other words, counts the number of the accesses to each page.
+After each ``aggregation interval`` passes, DAMON signals users to read and
+save the aggregated access frequency if they want and then clears those.  For
+the access check of each page, DAMON uses the Accessed bits of PTEs.  This can
+be described in below simple pseudo-code::
+
+    while monitoring_on:
+        for page in monitoring_target:
+            if accessed(page):
+                nr_accesses[page] += 1
+        if time() % aggregation_interval == 0:
+            for page in monitoring_target:
+                nr_accesses[page] = 0
+        sleep(sampling interval)
+
+The monitoring overhead of this mechanism will arbitrarily increase as the
+size of the target workload grows.
+
+
+Region Based Sampling
+=====================
+
+To avoid the unbounded increase of the overhead, DAMON groups adjacent pages
+that assumed to have the same access frequencies into a region.  As long as the
+assumption (pages in a region have the same access frequencies) is kept, only
+one page in the region is required to be checked.  Thus, for each ``sampling
+interval``, DAMON randomly picks one page in each region, waits for one
+``sampling interval``, checks whether the page is accessed meanwhile, and
+increases the access frequency of the region if so.  Therefore, the monitoring
+overhead is controllable by setting the number of regions.  DAMON allows users
+to set the minimum and the maximum number of regions for the trade-off.
+
+This scheme, however, cannot preserve the quality of the output if the
+assumption is not guaranteed.
+
+
+Adaptive Regions Adjustment
+===========================
+
+At the beginning of the monitoring, DAMON constructs the initial regions by
+evenly splitting the monitoring target memory region into the user-specified
+minimum number of regions.  In this initial state, the assumption is normally
+not kept and therefore the quality would be low.  To keep the assumption as
+much as possible, DAMON adaptively merges and splits each region based on their
+access frequency.
+
+For each ``aggregation interval``, it compares the access frequencies of
+adjacent regions and merges those if the frequency difference is small.  Then,
+after it reports and clears the aggregated access frequency of each region, it
+splits each region into two or three regions if the total number of regions
+will not exceed the user-specified maximum number of regions after the split.
+
+In this way, DAMON provides its best-effort quality and minimal overhead while
+keeping the bounds users set for their trade-off.
+
+
+Handling Virtual Memory Mappings
+================================
+
+This is for monitoring of virtual memory address space only.  It is the only
+one address space that supported by DAMON as of now, but other address spaces
+will be supported in the future.
+
+Only small parts in the super-huge virtual address space of the processes are
+mapped to physical memory and accessed.  Thus, tracking the unmapped address
+regions is just wasteful.  However, because DAMON can deal with some level of
+noise using the adaptive regions adjustment mechanism, tracking every mapping
+is not strictly required but could even incur a high overhead in some cases.
+That said, too huge unmapped areas inside the monitoring target should be
+removed to not take the time for the adaptive mechanism.
+
+For the reason, DAMON converts the complex mappings to three distinct regions
+that cover every mapped area of the address space.  Also, the two gaps between
+the three regions are the two biggest unmapped areas in the given address
+space.  The two biggest unmapped areas might be the gap between the heap and
+the uppermost mmap()-ed region, and the gap between the lowermost mmap()-ed
+region and the stack will be two biggest unmapped regions.  Because these gaps
+are exceptionally huge areas in usual address space, excluding these two
+biggest unmapped regions will be sufficient to make a trade-off.  Below shows
+this in detail::
+
+    <heap>
+    <BIG UNMAPPED REGION 1>
+    <uppermost mmap()-ed region>
+    (small mmap()-ed regions and munmap()-ed regions)
+    <lowermost mmap()-ed region>
+    <BIG UNMAPPED REGION 2>
+    <stack>
+
+To further minimize dynamic mapping changes applying overhead, DAMON checks the
+dynamic memory mapping changes and applies it to the abstracted target area
+only for each of a user-specified time interval (``regions update interval``).
diff --git a/Documentation/admin-guide/mm/damon/plans.rst b/Documentation/admin-guide/mm/damon/plans.rst
new file mode 100644
index 000000000000..96251752b3f0
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/plans.rst
@@ -0,0 +1,49 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+Future Plans
+============
+
+DAMON is still on its first stage.  Below plans are still under development.
+
+
+Automate Data Access Monitoring-based Memory Operation Schemes Execution
+========================================================================
+
+The ultimate goal of DAMON is being used as a building block of the data access
+pattern aware kernel memory management subsystem optimization.  However, as
+always, some users having very special workloads will want to do their
+optimization.  DAMON will automate most of the tasks for such manual
+optimizations soon.  Users will be required to only describe what kind of data
+access pattern-based operation schemes they want in a simple form.
+
+By applying a very simple scheme for THP promotion/demotion with a prototype
+implementation, DAMON reduced 60% of THP memory footprint overhead while
+preserving 50% of the THP performance benefit.  The detailed results can be
+seen on an external web page [1]_.
+
+Several RFC patchsets for this plan are available [2]_.
+
+
+Support Various Address Spaces
+==============================
+
+Currently, DAMON supports only virtual memory address spaces because it
+utilizes PTE Accessed bits as its low-level access check primitive and ``struct
+vma`` as a way to address the monitoring target regions.  However, the core
+idea of DAMON is in a separate higher layer.  Therefore, DAMON can support
+other various address spaces by changing the two low primitives to others for
+the address spaces.
+
+In the future, DAMON will make the lower level primitives configurable so that
+it can support various address spaces including physical memory.  The
+configuration will be highly flexible so that users can even implement the
+primitives by themselves for their special use cases.  Monitoring of
+clean/dirty/entire page cache, NUMA nodes, specific files, or block devices
+would be examples of such use cases.
+
+An RFC patchset for this plan is available [3]_.
+
+.. [1] https://damonitor.github.io/test/result/perf/latest/html/
+.. [2] https://lore.kernel.org/linux-mm/20200429124540.32232-1-sjpark@amazon.com/
+.. [3] https://lore.kernel.org/linux-mm/20200409094232.29680-1-sjpark@amazon.com/
diff --git a/Documentation/admin-guide/mm/damon/start.rst b/Documentation/admin-guide/mm/damon/start.rst
new file mode 100644
index 000000000000..0f1a366ac245
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/start.rst
@@ -0,0 +1,119 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Getting Started
+===============
+
+This document briefly describes how you can use DAMON by demonstrating the user
+space tool.  Please note that this document describes only a part of the
+features for brevity.  Please refer to :doc:`usage` for more details.
+
+
+TL; DR
+======
+
+Simply follow below 5 commands.  Don't forget replacing ``<your workload>``
+with your *real* workload, though. ::
+
+    $ git clone https://github.com/sjp38/linux -b damon/master
+    /* build the kernel with CONFIG_DAMON=y, install, reboot */
+    $ cd linux/tools/damon
+    $ ./damo record $(pidof <your workload>)
+    $ ./damo report heats --heatmap access_pattern.pdf
+    $ ./damo report wss --range 0 101 1 --plot wss_dist.pdf
+
+
+Prerequisites
+=============
+
+Kernel
+------
+
+You should first ensure your system is running on a kernel built with
+``CONFIG_DAMON``.  If the value is set as ``m``, you should load the module
+first::
+
+    # modprobe damon
+
+
+User Space Tool
+---------------
+
+For the demonstration, we will use a user space tool for the convenient use of
+DAMON, called DAMON Operator (DAMO).  It is located at ``tools/damon/damo`` of
+the kernel source tree.  We assume that you set ``$PATH`` to point it.  The
+``$PATH`` setting is not mandatory but we make the assumption here for the
+brevity of the below examples.
+
+Because DAMO is using the debugfs interface (refer to :doc:`usage` for the
+detail) of DAMON, you should also ensure debugfs is mounted.  Mount it manually
+as below::
+
+    # mount -t debugfs none /sys/kernel/debug/
+
+or append below line to your ``/etc/fstab`` file so that your system can
+automatically mount debugfs from next booting::
+
+    debugfs /sys/kernel/debug debugfs defaults 0 0
+
+
+Recording Data Access Patterns
+==============================
+
+Below commands record memory access pattern of a program, ``masim``, and save
+it in a file, ``damon.data``.  The program will access two 100 MiB memory
+regions one by one. ::
+
+    $ git clone https://github.com/sjp38/masim
+    $ cd masim; make; ./masim ./configs/zigzag.cfg &
+    $ sudo damo record -o damon.data $(pidof masim)
+
+The first two lines of commands start the monitoring target process in the
+background.  You can substitute this with your real workload.  The last line
+asks ``damo record`` to record the access pattern.
+
+
+Visualizing Recorded Patterns
+=============================
+
+Below three commands visualize the recorded access patterns into three
+image files, ``access_pattern_heatmap.png``, ``wss_dist.png``, and
+``wss_chron_change.png``. ::
+
+    $ damo report heats --heatmap -i damon.data access_pattern_heatmap.png
+    $ damo report wss --range 0 101 1 --plot wss_dist.png
+    $ damo report wss --range 0 101 1 --sortby time --plot wss_chron_change.png
+
+- ``access_pattern_heatmap.png`` will show the data access pattern in a
+  heatmap, which shows when (x-axis) what memory region (y-axis) is how
+  frequently accessed (color).
+- ``wss_dist.png`` will show the distribution of the working set size.
+- ``wss_chron_change.png`` will show how the working set size has
+  chronologically changed.
+
+Below are the three images.  You can show those made with other realistic
+workloads at external web pages [1]_ [2]_ [3]_.
+
+.. list-table::
+
+   * - .. kernel-figure::  damon_heatmap.png
+          :alt:   the access pattern in heatmap format
+          :align: center
+
+          The access pattern in heatmap format.
+
+     - .. kernel-figure::  damon_wss_dist.png
+          :alt:    the distribution of working set size
+          :align: center
+
+          The distribution of working set size.
+
+     - .. kernel-figure::  damon_wss_change.png
+          :alt:    the chronological changes of working set size
+          :align: center
+
+          The chronological changes of working set size.
+
+.. [1] https://damonitor.github.io/test/result/visual/latest/heatmap.1.html
+.. [2] https://damonitor.github.io/test/result/visual/latest/wss_sz.html
+.. [3] https://damonitor.github.io/test/result/visual/latest/wss_time.html
diff --git a/Documentation/admin-guide/mm/damon/streamcluster_heatmap.png b/Documentation/admin-guide/mm/damon/streamcluster_heatmap.png
new file mode 100644
index 0000000000000000000000000000000000000000..c9186f63bca4292a3f2e7602b2095c46914b9ae0
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/streamcluster_wss_sz.png b/Documentation/admin-guide/mm/damon/streamcluster_wss_sz.png
new file mode 100644
index 0000000000000000000000000000000000000000..8ea84a454233d3ab5f754d8cbdef78a15b134f70
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/streamcluster_wss_time.png b/Documentation/admin-guide/mm/damon/streamcluster_wss_time.png
new file mode 100644
index 0000000000000000000000000000000000000000..b4f19cce225e43e7b0c23563245c19ebe5ed3f0c
GIT binary patch
diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
new file mode 100644
index 000000000000..1aa4f66e4320
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/usage.rst
@@ -0,0 +1,305 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+Detailed Usages
+===============
+
+DAMON provides below three interfaces for various use cases.
+
+- *DAMON user space tool.*
+  This is for privileged people such as system administrators who want a
+  just-working human-friendly interface.  This interface is a reference
+  implementation of the DAMON debugfs wrapper user space tool.  Using this
+  tool, you can easily use the DAMON’s major features in a human-friendly way,
+  though it may not be highly tuned for your specific use-cases.
+- *debugfs interface.*
+  This is for user space programmers who want optimized use of DAMON. Using
+  this interface, you can use DAMON’s major features by reading from and
+  writing to specific debugfs files.  Of course, you can write and use your
+  personalized DAMON debugfs wrapper user space tool that reads/writes the
+  debugfs files instead of you and provides a more human-friendly interface.
+- *Kernel Space Programming Interface.*
+  This is for kernel space programmers.  Using this, you can utilize every
+  feature of DAMON most flexibly and efficiently by writing kernel space
+  DAMON application programs for you.
+
+We recommend you to start with the DAMON user space tool and move to debugfs
+interface only if the real requirement is found, and prohibit the use of the
+kernel space programming interface unless you need it, for the following
+reasons.  First of all, there will be no big difference between the overheads
+of these three interfaces, unless the use case is so special.  Also, all these
+three interfaces support all major features of DAMON.
+
+This document, therefore, does not describe the kernel space programming
+interface in detail.  For the programming interface, please refer to :doc:`api`
+or ``include/linux/damon.h`` file in the kernel source tree.
+
+
+
+User Space Tool for DAMON
+=========================
+
+A reference implementation of the DAMON user space tool which provides a
+convenient user interface is located at ``tools/damon/damo`` in the kernel
+source tree.  Please note that this is initially aimed to be used for minimal
+reference of the DAMON's debugfs interfaces and for tests of the DAMON itself.
+Based on the debugfs interface, you can create another cool and more convenient
+user space tools.
+
+The interface of the tool is basically subcommand based.  You can almost always
+use ``-h`` option to get the help of the use of each subcommand.  Currently, it
+supports two subcommands, ``record`` and ``report``.
+
+Below example commands assume you set ``$PATH`` to points ``tools/damon/`` for
+brevity.  It is not mandatory for use of ``damo``, though.
+
+
+Recording Data Access Pattern
+-----------------------------
+
+The ``record`` subcommand records the data access pattern of target processes
+in a file (``./damon.data`` by default).  You can specify the target as either
+pid of running target or a command for execution of the process.  Below example
+shows a command target usage::
+
+    # cd <kernel>/tools/damon/
+    # damo record "sleep 5"
+
+The tool will execute ``sleep 5`` by itself and record the data access patterns
+of the process.  Below example shows a pid target usage::
+
+    # sleep 5 &
+    # damo record `pidof sleep`
+
+You can tune this by setting the monitoring attributes and path to the record
+file using optional arguments to the subcommand.  To know about the monitoring
+attributes in detail, please refer to :doc:`mechanisms`.
+
+
+Analyzing Data Access Pattern
+-----------------------------
+
+The ``report`` subcommand reads a data access pattern record file (if not
+explicitly specified, reads ``./damon.data`` file by default) and generates
+human-readable reports of various types.  You can specify what type of report
+you want using a sub-subcommand to ``report`` subcommand.  ``raw``, ``heats``,
+and ``wss`` report types are supported for now.
+
+
+raw
+~~~
+
+``raw`` sub-subcommand simply transforms the binary record into human-readable
+text.  For example::
+
+    $ damo report raw
+    start_time:  193485829398
+    rel time:                0
+    nr_tasks:  1
+    pid:  1348
+    nr_regions:  4
+    560189609000-56018abce000(  22827008):  0
+    7fbdff59a000-7fbdffaf1a00(   5601792):  0
+    7fbdffaf1a00-7fbdffbb5000(    800256):  1
+    7ffea0dc0000-7ffea0dfd000(    249856):  0
+
+    rel time:        100000731
+    nr_tasks:  1
+    pid:  1348
+    nr_regions:  6
+    560189609000-56018abce000(  22827008):  0
+    7fbdff59a000-7fbdff8ce933(   3361075):  0
+    7fbdff8ce933-7fbdffaf1a00(   2240717):  1
+    7fbdffaf1a00-7fbdffb66d99(    480153):  0
+    7fbdffb66d99-7fbdffbb5000(    320103):  1
+    7ffea0dc0000-7ffea0dfd000(    249856):  0
+
+The first line shows the recording started timestamp (nanosecond).  Records of
+data access patterns are following this.  Each record is separated by a blank
+line.  Each record first specifies the recorded time (``rel time``), the number
+of monitored tasks in this record (``nr_tasks``).  A numbers of records of data
+access patterns for each task follow.  Each data access pattern for each task
+shows it's pid (``pid``) and a number of monitored virtual address regions in
+this access pattern (``nr_regions``) first.  After that, each line shows the
+start/end address, size, and the number of monitored accesses to the region for
+each of the regions.
+
+
+heats
+~~~~~
+
+The ``raw`` output is very detailed but hard to manually read and analyze.
+``heats`` sub-subcommand plots the data in 3-dimensional form, which represents
+the time in x-axis, virtual address in y-axis, and the access frequency in
+z-axis.  Users can set the resolution of the map (``--tres`` and ``--ares``)
+and start/end point of each axis (``--tmin``, ``--tmax``, ``--amin``, and
+``--amax``) via optional arguments.  For example::
+
+    $ damo report heats --tres 3 --ares 3
+    0               0               0.0
+    0               7609002         0.0
+    0               15218004        0.0
+    66112620851     0               0.0
+    66112620851     7609002         0.0
+    66112620851     15218004        0.0
+    132225241702    0               0.0
+    132225241702    7609002         0.0
+    132225241702    15218004        0.0
+
+This command shows a recorded access pattern in heatmap of 3x3 resolution.
+Therefore it shows 9 data points in total.  Each line shows each of the data
+points.  The three numbers in each line represent time in nanosecond, virtual
+address in bytes, and the observed access frequency.
+
+Users can easily convert this text output into a heatmap image (represent z-axis
+values with colors) or other 3D representations using various tools such as
+'gnuplot'.  ``heats`` sub-subcommand also provides 'gnuplot' based heatmap
+image creation.  For this, you can use ``--heatmap`` option.  Also, note that
+because it uses 'gnuplot' internally, it will fail if 'gnuplot' is not
+installed on your system.  For example::
+
+    $ ./damo report heats --heatmap heatmap.png
+
+Creates ``heatmap.png`` file containing the heatmap image.  It supports
+``pdf``, ``png``, ``jpeg``, and ``svg``.
+
+If the target address space is virtual memory address space and you plot the
+entire address space, the huge unmapped regions will make the picture looks
+only black.  Therefore you should do proper zoom in / zoom out using the axis
+boundary-setting optional arguments.  To make this effort minimal, you can use
+``--guide`` option.  For example::
+
+    $ ./damo report heats --guide
+    pid:1348
+    time: 193485829398-198337863555 (4852034157)
+    region   0: 00000094564599762944-00000094564622589952 (22827008)
+    region   1: 00000140454009610240-00000140454016012288 (6402048)
+    region   2: 00000140731597193216-00000140731597443072 (249856)
+
+The output shows unions of monitored regions (start and end addresses in byte)
+and union of monitored time duration (start and end time in nanoseconds) of
+each target task.  Therefore, it would be wise to plot the data points in each
+union.  If no axis boundary option is given, it will automatically find the
+biggest union in ``--guide`` output and plot for it.
+
+
+wss
+~~~
+
+The ``wss`` type extracts the distribution and chronological working set size
+changes from the records.  For example::
+
+    $ ./damo report wss
+    # <percentile> <wss>
+    # pid   1348
+    # avr:  66228
+    0       0
+    25      0
+    50      0
+    75      0
+    100     1920615
+
+Without any option, it shows the distribution of the working set sizes as
+above.  It shows 0th, 25th, 50th, 75th, and 100th percentile and the average of
+the measured working set sizes in the access pattern records.  In this case,
+the working set size was zero for 75th percentile but 1,920,615 bytes in max
+and 66,228 bytes on average.
+
+By setting the sort key of the percentile using '--sortby', you can show how
+the working set size has chronologically changed.  For example::
+
+    $ ./damo report wss --sortby time
+    # <percentile> <wss>
+    # pid   1348
+    # avr:  66228
+    0       0
+    25      0
+    50      0
+    75      0
+    100     0
+
+The average is still 66,228.  And, because the access was spiked in very short
+duration but we use only 4 data points, we cannot show when the access spikes
+made.  Users can specify the resolution of the distribution (``--range``).  By
+giving more fine resolution, users will be able to see the short duration
+spikes.
+
+Similar to that of ``heats --heatmap``, it also supports 'gnuplot' based simple
+visualization of the distribution via ``--plot`` option.
+
+
+debugfs Interface
+=================
+
+DAMON exports four files, ``attrs``, ``pids``, ``record``, and ``monitor_on``
+under its debugfs directory, ``<debugfs>/damon/``.
+
+
+Attributes
+----------
+
+Users can get and set the ``sampling interval``, ``aggregation interval``,
+``regions update interval``, and min/max number of monitoring target regions by
+reading from and writing to the ``attrs`` file.  To know about the monitoring
+attributes in detail, please refer to :doc:`mechanisms`.  For example, below
+commands set those values to 5 ms, 100 ms, 1,000 ms, 10 and 1000, and then
+check it again::
+
+    # cd <debugfs>/damon
+    # echo 5000 100000 1000000 10 1000 > attrs
+    # cat attrs
+    5000 100000 1000000 10 1000
+
+
+Target PIDs
+-----------
+
+Users can get and set the pids of monitoring target processes by reading from
+and writing to the ``pids`` file.  For example, below commands set processes
+having pids 42 and 4242 as the processes to be monitored and check it again::
+
+    # cd <debugfs>/damon
+    # echo 42 4242 > pids
+    # cat pids
+    42 4242
+
+Note that setting the pids doesn't start the monitoring.
+
+
+Record
+------
+
+This debugfs file allows you to record monitored access patterns in a regular
+binary file.  The recorded results are first written to an in-memory buffer and
+flushed to a file in batch.  Users can get and set the size of the buffer and
+the path to the result file by reading from and writing to the ``record`` file.
+For example, below commands set the buffer to be 4 KiB and the result to be
+saved in ``/damon.data``. ::
+
+    # cd <debugfs>/damon
+    # echo "4096 /damon.data" > record
+    # cat record
+    4096 /damon.data
+
+
+Turning On/Off
+--------------
+
+Setting the attributes as described above doesn't incur effect unless you
+explicitly start the monitoring.  You can start, stop, and check the current
+status of the monitoring by writing to and reading from the ``monitor_on``
+file.  Writing ``on`` to the file make DAMON start monitoring of the target
+processes with the attributes.  Recording will also start if requested before.
+Writing ``off`` to the file stops those.  DAMON also stops if every target
+process is terminated.  Below example commands turn on, off, and check the
+status of DAMON::
+
+    # cd <debugfs>/damon
+    # echo on > monitor_on
+    # echo off > monitor_on
+    # cat monitor_on
+    off
+
+Please note that you cannot write to the above-mentioned debugfs files while
+the monitoring is turned on.  If you write to the files while DAMON is running,
+an error code such as ``-EBUSY`` will be returned.
diff --git a/Documentation/admin-guide/mm/index.rst b/Documentation/admin-guide/mm/index.rst
index 11db46448354..d3d0ba373eb6 100644
--- a/Documentation/admin-guide/mm/index.rst
+++ b/Documentation/admin-guide/mm/index.rst
@@ -27,6 +27,7 @@ the Linux memory management.
 
    concepts
    cma_debugfs
+   data_access_monitor
    hugetlbpage
    idle_page_tracking
    ksm
diff --git a/Documentation/index.rst b/Documentation/index.rst
index e99d0bd2589d..92e70f544634 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -6,15 +6,10 @@
 
 .. _linux_doc:
 
-The Linux Kernel documentation
-==============================
+The DAMON documentation
+=======================
 
-This is the top level of the kernel's documentation tree.  Kernel
-documentation, like the kernel itself, is very much a work in progress;
-that is especially true as we work to integrate our many scattered
-documents into a coherent whole.  Please note that improvements to the
-documentation are welcome; join the linux-doc list at vger.kernel.org if
-you want to help out.
+This is the Linux kernel's documentation modified for DAMON only.
 
 Licensing documentation
 -----------------------
@@ -25,168 +20,13 @@ tree, as well as links to the full license text.
 
 * :ref:`kernel_licensing`
 
-User-oriented documentation
----------------------------
+DAMON: Data Access Monitor
+--------------------------
 
-The following manuals are written for *users* of the kernel — those who are
+The following manual is for *users* of DAMON — those who are
 trying to get it to work optimally on a given system.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
-   admin-guide/index
-   kbuild/index
-
-Firmware-related documentation
-------------------------------
-The following holds information on the kernel's expectations regarding the
-platform firmwares.
-
-.. toctree::
-   :maxdepth: 2
-
-   firmware-guide/index
-
-Application-developer documentation
------------------------------------
-
-The user-space API manual gathers together documents describing aspects of
-the kernel interface as seen by application developers.
-
-.. toctree::
-   :maxdepth: 2
-
-   userspace-api/index
-
-
-Introduction to kernel development
-----------------------------------
-
-These manuals contain overall information about how to develop the kernel.
-The kernel community is quite large, with thousands of developers
-contributing over the course of a year.  As with any large community,
-knowing how things are done will make the process of getting your changes
-merged much easier.
-
-.. toctree::
-   :maxdepth: 2
-
-   process/index
-   dev-tools/index
-   doc-guide/index
-   kernel-hacking/index
-   trace/index
-   maintainer/index
-   fault-injection/index
-   livepatch/index
-
-
-Kernel API documentation
-------------------------
-
-These books get into the details of how specific kernel subsystems work
-from the point of view of a kernel developer.  Much of the information here
-is taken directly from the kernel source, with supplemental material added
-as needed (or at least as we managed to add it — probably *not* all that is
-needed).
-
-.. toctree::
-   :maxdepth: 2
-
-   driver-api/index
-   core-api/index
-   locking/index
-   accounting/index
-   block/index
-   cdrom/index
-   ide/index
-   fb/index
-   fpga/index
-   hid/index
-   i2c/index
-   iio/index
-   isdn/index
-   infiniband/index
-   leds/index
-   media/index
-   netlabel/index
-   networking/index
-   pcmcia/index
-   power/index
-   target/index
-   timers/index
-   spi/index
-   w1/index
-   watchdog/index
-   virt/index
-   input/index
-   hwmon/index
-   gpu/index
-   security/index
-   sound/index
-   crypto/index
-   filesystems/index
-   vm/index
-   bpf/index
-   usb/index
-   PCI/index
-   misc-devices/index
-   mic/index
-   scheduler/index
-
-Architecture-agnostic documentation
------------------------------------
-
-.. toctree::
-   :maxdepth: 2
-
-   asm-annotations
-
-Architecture-specific documentation
------------------------------------
-
-These books provide programming details about architecture-specific
-implementation.
-
-.. toctree::
-   :maxdepth: 2
-
-   arm/index
-   arm64/index
-   ia64/index
-   m68k/index
-   mips/index
-   nios2/nios2
-   openrisc/index
-   parisc/index
-   powerpc/index
-   riscv/index
-   s390/index
-   sh/index
-   sparc/index
-   x86/index
-   xtensa/index
-
-Filesystem Documentation
-------------------------
-
-The documentation in this section are provided by specific filesystem
-subprojects.
-
-.. toctree::
-   :maxdepth: 2
-
-   filesystems/ext4/index
-
-Translations
-------------
-
-.. toctree::
-   :maxdepth: 2
-
-   translations/index
-
-Indices and tables
-==================
-
-* :ref:`genindex`
+   admin-guide/mm/damon/index
