<!DOCTYPE html>
<html lang="en" data-content_root="../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Design — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../_static/alabaster.css?v=3918102e" />
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../_static/doctools.js?v=9bcbadda"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="DAMON Moniting Interval Parameters Tuning Example" href="monitoring_intervals_tuning_example.html" />
<link rel="prev" title="Frequently Asked Questions" href="faq.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../index.html">
<img class="logo" src="../../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2 current"><a class="reference internal" href="../../subsystem-apis.html#core-subsystems">Core subsystems</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../../core-api/index.html">Core API Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../driver-api/index.html">Driver implementer’s API guide</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="../index.html">Memory Management Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../power/index.html">Power Management</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../scheduler/index.html">Scheduler</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../timers/index.html">Timers</a></li>
<li class="toctree-l3"><a class="reference internal" href="../../locking/index.html">Locking</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#human-interfaces">Human interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../subsystem-apis.html#other-subsystems">Other subsystems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/mm/damon/design.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="language-selection">
English
<ul>
<li><a href="../../translations/zh_CN/mm/damon/design.html">Chinese (Simplified)</a></li>
</ul>
</div>
<section id="design">
<h1>Design<a class="headerlink" href="#design" title="Link to this heading">¶</a></h1>
<section id="execution-model-and-data-structures">
<span id="damon-design-execution-model-and-data-structures"></span><h2>Execution Model and Data Structures<a class="headerlink" href="#execution-model-and-data-structures" title="Link to this heading">¶</a></h2>
<p>The monitoring-related information including the monitoring request
specification and DAMON-based operation schemes are stored in a data structure
called DAMON <code class="docutils literal notranslate"><span class="pre">context</span></code>. DAMON executes each context with a kernel thread
called <code class="docutils literal notranslate"><span class="pre">kdamond</span></code>. Multiple kdamonds could run in parallel, for different
types of monitoring.</p>
<p>To know how user-space can do the configurations and start/stop DAMON, refer to
<a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a> documentation.</p>
</section>
<section id="overall-architecture">
<h2>Overall Architecture<a class="headerlink" href="#overall-architecture" title="Link to this heading">¶</a></h2>
<p>DAMON subsystem is configured with three layers including</p>
<ul class="simple">
<li><p><a class="reference internal" href="#damon-operations-set"><span class="std std-ref">Operations Set</span></a>: Implements fundamental
operations for DAMON that depends on the given monitoring target
address-space and available set of software/hardware primitives,</p></li>
<li><p><a class="reference internal" href="#damon-core-logic"><span class="std std-ref">Core</span></a>: Implements core logics including monitoring
overhead/accuracy control and access-aware system operations on top of the
operations set layer, and</p></li>
<li><p><a class="reference internal" href="#damon-modules"><span class="std std-ref">Modules</span></a>: Implements kernel modules for various
purposes that provides interfaces for the user space, on top of the core
layer.</p></li>
</ul>
</section>
<section id="operations-set-layer">
<span id="damon-operations-set"></span><h2>Operations Set Layer<a class="headerlink" href="#operations-set-layer" title="Link to this heading">¶</a></h2>
<p id="damon-design-configurable-operations-set">For data access monitoring and additional low level work, DAMON needs a set of
implementations for specific operations that are dependent on and optimized for
the given target address space. For example, below two operations for access
monitoring are address-space dependent.</p>
<ol class="arabic simple">
<li><p>Identification of the monitoring target address range for the address space.</p></li>
<li><p>Access check of specific address range in the target space.</p></li>
</ol>
<p>DAMON consolidates these implementations in a layer called DAMON Operations
Set, and defines the interface between it and the upper layer. The upper layer
is dedicated for DAMON’s core logics including the mechanism for control of the
monitoring accuracy and the overhead.</p>
<p>Hence, DAMON can easily be extended for any address space and/or available
hardware features by configuring the core logic to use the appropriate
operations set. If there is no available operations set for a given purpose, a
new operations set can be implemented following the interface between the
layers.</p>
<p>For example, physical memory, virtual memory, swap space, those for specific
processes, NUMA nodes, files, and backing memory devices would be supportable.
Also, if some architectures or devices support special optimized access check
features, those will be easily configurable.</p>
<p>DAMON currently provides below three operation sets. Below three subsections
describe how those work.</p>
<blockquote>
<div><ul class="simple">
<li><p>vaddr: Monitor virtual address spaces of specific processes</p></li>
<li><p>fvaddr: Monitor fixed virtual address ranges</p></li>
<li><p>paddr: Monitor the physical address space of the system</p></li>
</ul>
</div></blockquote>
<p>To know how user-space can do the configuration via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-context"><span class="std std-ref">operations</span></a> file part of the
documentation.</p>
<blockquote>
<div></div></blockquote>
<section id="vma-based-target-address-range-construction">
<span id="damon-design-vaddr-target-regions-construction"></span><h3>VMA-based Target Address Range Construction<a class="headerlink" href="#vma-based-target-address-range-construction" title="Link to this heading">¶</a></h3>
<p>A mechanism of <code class="docutils literal notranslate"><span class="pre">vaddr</span></code> DAMON operations set that automatically initializes
and updates the monitoring target address regions so that entire memory
mappings of the target processes can be covered.</p>
<p>This mechanism is only for the <code class="docutils literal notranslate"><span class="pre">vaddr</span></code> operations set. In cases of
<code class="docutils literal notranslate"><span class="pre">fvaddr</span></code> and <code class="docutils literal notranslate"><span class="pre">paddr</span></code> operation sets, users are asked to manually set the
monitoring target address ranges.</p>
<p>Only small parts in the super-huge virtual address space of the processes are
mapped to the 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.</p>
<p>For the reason, this implementation converts the complex mappings to three
distinct regions that cover every mapped area of the address space. The two
gaps between the three regions are the two biggest unmapped areas in the given
address space. The two biggest unmapped areas would be the gap between the
heap and the uppermost mmap()-ed region, and the gap between the lowermost
mmap()-ed region and the stack in most of the cases. Because these gaps are
exceptionally huge in usual address spaces, excluding these will be sufficient
to make a reasonable trade-off. Below shows this in detail:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><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>
</pre></div>
</div>
</section>
<section id="pte-accessed-bit-based-access-check">
<h3>PTE Accessed-bit Based Access Check<a class="headerlink" href="#pte-accessed-bit-based-access-check" title="Link to this heading">¶</a></h3>
<p>Both of the implementations for physical and virtual address spaces use PTE
Accessed-bit for basic access checks. Only one difference is the way of
finding the relevant PTE Accessed bit(s) from the address. While the
implementation for the virtual address walks the page table for the target task
of the address, the implementation for the physical address walks every page
table having a mapping to the address. In this way, the implementations find
and clear the bit(s) for next sampling target address and checks whether the
bit(s) set again after one sampling period. This could disturb other kernel
subsystems using the Accessed bits, namely Idle page tracking and the reclaim
logic. DAMON does nothing to avoid disturbing Idle page tracking, so handling
the interference is the responsibility of sysadmins. However, it solves the
conflict with the reclaim logic using <code class="docutils literal notranslate"><span class="pre">PG_idle</span></code> and <code class="docutils literal notranslate"><span class="pre">PG_young</span></code> page flags,
as Idle page tracking does.</p>
</section>
<section id="address-unit">
<span id="damon-design-addr-unit"></span><h3>Address Unit<a class="headerlink" href="#address-unit" title="Link to this heading">¶</a></h3>
<p>DAMON core layer uses <code class="docutils literal notranslate"><span class="pre">unsinged</span> <span class="pre">long</span></code> type for monitoring target address
ranges. In some cases, the address space for a given operations set could be
too large to be handled with the type. ARM (32-bit) with large physical
address extension is an example. For such cases, a per-operations set
parameter called <code class="docutils literal notranslate"><span class="pre">address</span> <span class="pre">unit</span></code> is provided. It represents the scale factor
that need to be multiplied to the core layer’s address for calculating real
address on the given address space. Support of <code class="docutils literal notranslate"><span class="pre">address</span> <span class="pre">unit</span></code> parameter is
up to each operations set implementation. <code class="docutils literal notranslate"><span class="pre">paddr</span></code> is the only operations set
implementation that supports the parameter.</p>
</section>
</section>
<section id="core-logics">
<span id="damon-core-logic"></span><h2>Core Logics<a class="headerlink" href="#core-logics" title="Link to this heading">¶</a></h2>
<section id="monitoring">
<span id="damon-design-monitoring"></span><h3>Monitoring<a class="headerlink" href="#monitoring" title="Link to this heading">¶</a></h3>
<p>Below four sections describe each of the DAMON core mechanisms and the five
monitoring attributes, <code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code>, <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code>,
<code class="docutils literal notranslate"><span class="pre">update</span> <span class="pre">interval</span></code>, <code class="docutils literal notranslate"><span class="pre">minimum</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">regions</span></code>, and <code class="docutils literal notranslate"><span class="pre">maximum</span> <span class="pre">number</span> <span class="pre">of</span>
<span class="pre">regions</span></code>.</p>
<p>To know how user-space can set the attributes via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-monitoring-attrs"><span class="std std-ref">monitoring_attrs</span></a>
part of the documentation.</p>
<section id="access-frequency-monitoring">
<h4>Access Frequency Monitoring<a class="headerlink" href="#access-frequency-monitoring" title="Link to this heading">¶</a></h4>
<p>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
<code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code> and <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code>. In detail, DAMON checks
access to each page per <code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code> and aggregates the results. In
other words, counts the number of the accesses to each page. After each
<code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code> passes, DAMON calls callback functions that previously
registered by users so that users can read the aggregated results and then
clears the results. This can be described in below simple pseudo-code:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>while monitoring_on:
for page in monitoring_target:
if accessed(page):
nr_accesses[page] += 1
if time() % aggregation_interval == 0:
for callback in user_registered_callbacks:
callback(monitoring_target, nr_accesses)
for page in monitoring_target:
nr_accesses[page] = 0
sleep(sampling interval)
</pre></div>
</div>
<p>The monitoring overhead of this mechanism will arbitrarily increase as the
size of the target workload grows.</p>
</section>
<section id="region-based-sampling">
<span id="damon-design-region-based-sampling"></span><h4>Region Based Sampling<a class="headerlink" href="#region-based-sampling" title="Link to this heading">¶</a></h4>
<p>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 <code class="docutils literal notranslate"><span class="pre">sampling</span>
<span class="pre">interval</span></code>, DAMON randomly picks one page in each region, waits for one
<code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code>, checks whether the page is accessed meanwhile, and
increases the access frequency counter of the region if so. The counter is
called <code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code> of the region. 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.</p>
<p>This scheme, however, cannot preserve the quality of the output if the
assumption is not guaranteed.</p>
</section>
<section id="adaptive-regions-adjustment">
<span id="damon-design-adaptive-regions-adjustment"></span><h4>Adaptive Regions Adjustment<a class="headerlink" href="#adaptive-regions-adjustment" title="Link to this heading">¶</a></h4>
<p>Even somehow the initial monitoring target regions are well constructed to
fulfill the assumption (pages in same region have similar access frequencies),
the data access pattern can be dynamically changed. This will result in low
monitoring quality. To keep the assumption as much as possible, DAMON
adaptively merges and splits each region based on their access frequency.</p>
<p>For each <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code>, it compares the access frequencies
(<code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code>) of adjacent regions. If the difference is small, and if the
sum of the two regions’ sizes is smaller than the size of total regions divided
by the <code class="docutils literal notranslate"><span class="pre">minimum</span> <span class="pre">number</span> <span class="pre">of</span> <span class="pre">regions</span></code>, DAMON merges the two regions. If the
resulting number of total regions is still higher than <code class="docutils literal notranslate"><span class="pre">maximum</span> <span class="pre">number</span> <span class="pre">of</span>
<span class="pre">regions</span></code>, it repeats the merging with increasing access frequenceis difference
threshold until the upper-limit of the number of regions is met, or the
threshold becomes higher than possible maximum value (<code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code>
divided by <code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code>). 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.</p>
<p>In this way, DAMON provides its best-effort quality and minimal overhead while
keeping the bounds users set for their trade-off.</p>
</section>
<section id="age-tracking">
<span id="damon-design-age-tracking"></span><h4>Age Tracking<a class="headerlink" href="#age-tracking" title="Link to this heading">¶</a></h4>
<p>By analyzing the monitoring results, users can also find how long the current
access pattern of a region has maintained. That could be used for good
understanding of the access pattern. For example, page placement algorithm
utilizing both the frequency and the recency could be implemented using that.
To make such access pattern maintained period analysis easier, DAMON maintains
yet another counter called <code class="docutils literal notranslate"><span class="pre">age</span></code> in each region. For each <code class="docutils literal notranslate"><span class="pre">aggregation</span>
<span class="pre">interval</span></code>, DAMON checks if the region’s size and access frequency
(<code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code>) has significantly changed. If so, the counter is reset to
zero. Otherwise, the counter is increased.</p>
</section>
<section id="dynamic-target-space-updates-handling">
<h4>Dynamic Target Space Updates Handling<a class="headerlink" href="#dynamic-target-space-updates-handling" title="Link to this heading">¶</a></h4>
<p>The monitoring target address range could dynamically changed. For example,
virtual memory could be dynamically mapped and unmapped. Physical memory could
be hot-plugged.</p>
<p>As the changes could be quite frequent in some cases, DAMON allows the
monitoring operations to check dynamic changes including memory mapping changes
and applies it to monitoring operations-related data structures such as the
abstracted monitoring target memory area only for each of a user-specified time
interval (<code class="docutils literal notranslate"><span class="pre">update</span> <span class="pre">interval</span></code>).</p>
<p>User-space can get the monitoring results via DAMON sysfs interface and/or
tracepoints. For more details, please refer to the documentations for
<a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-schemes-tried-regions"><span class="std std-ref">DAMOS tried regions</span></a> and <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#tracepoint"><span class="std std-ref">Tracepoints for Monitoring Results</span></a>,
respectively.</p>
</section>
<section id="monitoring-parameters-tuning-guide">
<span id="damon-design-monitoring-params-tuning-guide"></span><h4>Monitoring Parameters Tuning Guide<a class="headerlink" href="#monitoring-parameters-tuning-guide" title="Link to this heading">¶</a></h4>
<p>In short, set <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code> to capture meaningful amount of accesses
for the purpose. The amount of accesses can be measured using <code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code>
and <code class="docutils literal notranslate"><span class="pre">age</span></code> of regions in the aggregated monitoring results snapshot. The
default value of the interval, <code class="docutils literal notranslate"><span class="pre">100ms</span></code>, turns out to be too short in many
cases. Set <code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code> proportional to <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code>. By
default, <code class="docutils literal notranslate"><span class="pre">1/20</span></code> is recommended as the ratio.</p>
<p><code class="docutils literal notranslate"><span class="pre">Aggregation</span> <span class="pre">interval</span></code> should be set as the time interval that the workload
can make an amount of accesses for the monitoring purpose, within the interval.
If the interval is too short, only small number of accesses are captured. As a
result, the monitoring results look everything is samely accessed only rarely.
For many purposes, that would be useless. If it is too long, however, the time
to converge regions with the <a class="reference internal" href="#damon-design-adaptive-regions-adjustment"><span class="std std-ref">regions adjustment mechanism</span></a> can be too long, depending on the
time scale of the given purpose. This could happen if the workload is actually
making only rare accesses but the user thinks the amount of accesses for the
monitoring purpose too high. For such cases, the target amount of access to
capture per <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code> should carefully reconsidered. Also, note
that the captured amount of accesses is represented with not only
<code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code>, but also <code class="docutils literal notranslate"><span class="pre">age</span></code>. For example, even if every region on the
monitoring results show zero <code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code>, regions could still be
distinguished using <code class="docutils literal notranslate"><span class="pre">age</span></code> values as the recency information.</p>
<p>Hence the optimum value of <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code> depends on the access
intensiveness of the workload. The user should tune the interval based on the
amount of access that captured on each aggregated snapshot of the monitoring
results.</p>
<p>Note that the default value of the interval is 100 milliseconds, which is too
short in many cases, especially on large systems.</p>
<p><code class="docutils literal notranslate"><span class="pre">Sampling</span> <span class="pre">interval</span></code> defines the resolution of each aggregation. If it is set
too large, monitoring results will look like every region was samely rarely
accessed, or samely frequently accessed. That is, regions become
undistinguishable based on access pattern, and therefore the results will be
useless in many use cases. If <code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code> is too small, it will not
degrade the resolution, but will increase the monitoring overhead. If it is
appropriate enough to provide a resolution of the monitoring results that
sufficient for the given purpose, it shouldn’t be unnecessarily further
lowered. It is recommended to be set proportional to <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code>.
By default, the ratio is set as <code class="docutils literal notranslate"><span class="pre">1/20</span></code>, and it is still recommended.</p>
<p>Based on the manual tuning guide, DAMON provides more intuitive knob-based
intervals auto tuning mechanism. Please refer to <a class="reference internal" href="#damon-design-monitoring-intervals-autotuning"><span class="std std-ref">the design document of
the feature</span></a> for detail.</p>
<p>Refer to below documents for an example tuning based on the above guide.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="monitoring_intervals_tuning_example.html">DAMON Moniting Interval Parameters Tuning Example</a></li>
</ul>
</div>
</section>
<section id="monitoring-intervals-auto-tuning">
<span id="damon-design-monitoring-intervals-autotuning"></span><h4>Monitoring Intervals Auto-tuning<a class="headerlink" href="#monitoring-intervals-auto-tuning" title="Link to this heading">¶</a></h4>
<p>DAMON provides automatic tuning of the <code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code> and <code class="docutils literal notranslate"><span class="pre">aggregation</span>
<span class="pre">interval</span></code> based on the <a class="reference internal" href="#damon-design-monitoring-params-tuning-guide"><span class="std std-ref">the tuning guide idea</span></a>. The tuning mechanism allows
users to set the aimed amount of access events to observe via DAMON within
given time interval. The target can be specified by the user as a ratio of
DAMON-observed access events to the theoretical maximum amount of the events
(<code class="docutils literal notranslate"><span class="pre">access_bp</span></code>) that measured within a given number of aggregations
(<code class="docutils literal notranslate"><span class="pre">aggrs</span></code>).</p>
<p>The DAMON-observed access events are calculated in byte granularity based on
DAMON <a class="reference internal" href="#damon-design-region-based-sampling"><span class="std std-ref">region assumption</span></a>. For
example, if a region of size <code class="docutils literal notranslate"><span class="pre">X</span></code> bytes of <code class="docutils literal notranslate"><span class="pre">Y</span></code> <code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code> is found, it
means <code class="docutils literal notranslate"><span class="pre">X</span> <span class="pre">*</span> <span class="pre">Y</span></code> access events are observed by DAMON. Theoretical maximum
access events for the region is calculated in same way, but replacing <code class="docutils literal notranslate"><span class="pre">Y</span></code>
with theoretical maximum <code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code>, which can be calculated as
<code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span> <span class="pre">/</span> <span class="pre">sampling</span> <span class="pre">interval</span></code>.</p>
<p>The mechanism calculates the ratio of access events for <code class="docutils literal notranslate"><span class="pre">aggrs</span></code> aggregations,
and increases or decrease the <code class="docutils literal notranslate"><span class="pre">sampleing</span> <span class="pre">interval</span></code> and <code class="docutils literal notranslate"><span class="pre">aggregation</span>
<span class="pre">interval</span></code> in same ratio, if the observed access ratio is lower or higher than
the target, respectively. The ratio of the intervals change is decided in
proportion to the distance between current samples ratio and the target ratio.</p>
<p>The user can further set the minimum and maximum <code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code> that can
be set by the tuning mechanism using two parameters (<code class="docutils literal notranslate"><span class="pre">min_sample_us</span></code> and
<code class="docutils literal notranslate"><span class="pre">max_sample_us</span></code>). Because the tuning mechanism changes <code class="docutils literal notranslate"><span class="pre">sampling</span> <span class="pre">interval</span></code>
and <code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code> in same ratio always, the minimum and maximum
<code class="docutils literal notranslate"><span class="pre">aggregation</span> <span class="pre">interval</span></code> after each of the tuning changes can automatically set
together.</p>
<p>The tuning is turned off by default, and need to be set explicitly by the user.
As a rule of thumbs and the Parreto principle, 4% access samples ratio target
is recommended. Note that Parreto principle (80/20 rule) has applied twice.
That is, assumes 4% (20% of 20%) DAMON-observed access events ratio (source)
to capture 64% (80% multipled by 80%) real access events (outcomes).</p>
<p>To know how user-space can use this feature via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-scheme"><span class="std std-ref">intervals_goal</span></a> part of
the documentation.</p>
</section>
</section>
<section id="operation-schemes">
<span id="damon-design-damos"></span><h3>Operation Schemes<a class="headerlink" href="#operation-schemes" title="Link to this heading">¶</a></h3>
<p>One common purpose of data access monitoring is access-aware system efficiency
optimizations. For example,</p>
<blockquote>
<div><p>paging out memory regions that are not accessed for more than two minutes</p>
</div></blockquote>
<p>or</p>
<blockquote>
<div><p>using THP for memory regions that are larger than 2 MiB and showing a high
access frequency for more than one minute.</p>
</div></blockquote>
<p>One straightforward approach for such schemes would be profile-guided
optimizations. That is, getting data access monitoring results of the
workloads or the system using DAMON, finding memory regions of special
characteristics by profiling the monitoring results, and making system
operation changes for the regions. The changes could be made by modifying or
providing advice to the software (the application and/or the kernel), or
reconfiguring the hardware. Both offline and online approaches could be
available.</p>
<p>Among those, providing advice to the kernel at runtime would be flexible and
effective, and therefore widely be used. However, implementing such schemes
could impose unnecessary redundancy and inefficiency. The profiling could be
redundant if the type of interest is common. Exchanging the information
including monitoring results and operation advice between kernel and user
spaces could be inefficient.</p>
<p>To allow users to reduce such redundancy and inefficiencies by offloading the
works, DAMON provides a feature called Data Access Monitoring-based Operation
Schemes (DAMOS). It lets users specify their desired schemes at a high
level. For such specifications, DAMON starts monitoring, finds regions having
the access pattern of interest, and applies the user-desired operation actions
to the regions, for every user-specified time interval called
<code class="docutils literal notranslate"><span class="pre">apply_interval</span></code>.</p>
<p>To know how user-space can set <code class="docutils literal notranslate"><span class="pre">apply_interval</span></code> via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs
interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-scheme"><span class="std std-ref">apply_interval_us</span></a>
part of the documentation.</p>
<section id="operation-action">
<span id="damon-design-damos-action"></span><h4>Operation Action<a class="headerlink" href="#operation-action" title="Link to this heading">¶</a></h4>
<p>The management action that the users desire to apply to the regions of their
interest. For example, paging out, prioritizing for next reclamation victim
selection, advising <code class="docutils literal notranslate"><span class="pre">khugepaged</span></code> to collapse or split, or doing nothing but
collecting statistics of the regions.</p>
<p>The list of supported actions is defined in DAMOS, but the implementation of
each action is in the DAMON operations set layer because the implementation
normally depends on the monitoring target address space. For example, the code
for paging specific virtual address ranges out would be different from that for
physical address ranges. And the monitoring operations implementation sets are
not mandated to support all actions of the list. Hence, the availability of
specific DAMOS action depends on what operations set is selected to be used
together.</p>
<p>The list of the supported actions, their meaning, and DAMON operations sets
that supports each action are as below.</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">willneed</span></code>: Call <code class="docutils literal notranslate"><span class="pre">madvise()</span></code> for the region with <code class="docutils literal notranslate"><span class="pre">MADV_WILLNEED</span></code>.
Supported by <code class="docutils literal notranslate"><span class="pre">vaddr</span></code> and <code class="docutils literal notranslate"><span class="pre">fvaddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cold</span></code>: Call <code class="docutils literal notranslate"><span class="pre">madvise()</span></code> for the region with <code class="docutils literal notranslate"><span class="pre">MADV_COLD</span></code>.
Supported by <code class="docutils literal notranslate"><span class="pre">vaddr</span></code> and <code class="docutils literal notranslate"><span class="pre">fvaddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pageout</span></code>: Reclaim the region.
Supported by <code class="docutils literal notranslate"><span class="pre">vaddr</span></code>, <code class="docutils literal notranslate"><span class="pre">fvaddr</span></code> and <code class="docutils literal notranslate"><span class="pre">paddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">hugepage</span></code>: Call <code class="docutils literal notranslate"><span class="pre">madvise()</span></code> for the region with <code class="docutils literal notranslate"><span class="pre">MADV_HUGEPAGE</span></code>.
Supported by <code class="docutils literal notranslate"><span class="pre">vaddr</span></code> and <code class="docutils literal notranslate"><span class="pre">fvaddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">nohugepage</span></code>: Call <code class="docutils literal notranslate"><span class="pre">madvise()</span></code> for the region with <code class="docutils literal notranslate"><span class="pre">MADV_NOHUGEPAGE</span></code>.
Supported by <code class="docutils literal notranslate"><span class="pre">vaddr</span></code> and <code class="docutils literal notranslate"><span class="pre">fvaddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">lru_prio</span></code>: Prioritize the region on its LRU lists.
Supported by <code class="docutils literal notranslate"><span class="pre">paddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">lru_deprio</span></code>: Deprioritize the region on its LRU lists.
Supported by <code class="docutils literal notranslate"><span class="pre">paddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">migrate_hot</span></code>: Migrate the regions prioritizing warmer regions.
Supported by <code class="docutils literal notranslate"><span class="pre">vaddr</span></code>, <code class="docutils literal notranslate"><span class="pre">fvaddr</span></code> and <code class="docutils literal notranslate"><span class="pre">paddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">migrate_cold</span></code>: Migrate the regions prioritizing colder regions.
Supported by <code class="docutils literal notranslate"><span class="pre">vaddr</span></code>, <code class="docutils literal notranslate"><span class="pre">fvaddr</span></code> and <code class="docutils literal notranslate"><span class="pre">paddr</span></code> operations set.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">stat</span></code>: Do nothing but count the statistics.
Supported by all operations sets.</p></li>
</ul>
</div></blockquote>
<p>Applying the actions except <code class="docutils literal notranslate"><span class="pre">stat</span></code> to a region is considered as changing the
region’s characteristics. Hence, DAMOS resets the age of regions when any such
actions are applied to those.</p>
<p>To know how user-space can set the action via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-scheme"><span class="std std-ref">action</span></a> part of the
documentation.</p>
</section>
<section id="target-access-pattern">
<span id="damon-design-damos-access-pattern"></span><h4>Target Access Pattern<a class="headerlink" href="#target-access-pattern" title="Link to this heading">¶</a></h4>
<p>The access pattern of the schemes’ interest. The patterns are constructed with
the properties that DAMON’s monitoring results provide, specifically the size,
the access frequency, and the age. Users can describe their access pattern of
interest by setting minimum and maximum values of the three properties. If a
region’s three properties are in the ranges, DAMOS classifies it as one of the
regions that the scheme is having an interest in.</p>
<p>To know how user-space can set the access pattern via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs
interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-access-pattern"><span class="std std-ref">access_pattern</span></a> part of the documentation.</p>
</section>
<section id="quotas">
<span id="damon-design-damos-quotas"></span><h4>Quotas<a class="headerlink" href="#quotas" title="Link to this heading">¶</a></h4>
<p>DAMOS upper-bound overhead control feature. DAMOS could incur high overhead if
the target access pattern is not properly tuned. For example, if a huge memory
region having the access pattern of interest is found, applying the scheme’s
action to all pages of the huge region could consume unacceptably large system
resources. Preventing such issues by tuning the access pattern could be
challenging, especially if the access patterns of the workloads are highly
dynamic.</p>
<p>To mitigate that situation, DAMOS provides an upper-bound overhead control
feature called quotas. It lets users specify an upper limit of time that DAMOS
can use for applying the action, and/or a maximum bytes of memory regions that
the action can be applied within a user-specified time duration.</p>
<p>To know how user-space can set the basic quotas via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-quotas"><span class="std std-ref">quotas</span></a> part of the
documentation.</p>
<section id="prioritization">
<span id="damon-design-damos-quotas-prioritization"></span><h5>Prioritization<a class="headerlink" href="#prioritization" title="Link to this heading">¶</a></h5>
<p>A mechanism for making a good decision under the quotas. When the action
cannot be applied to all regions of interest due to the quotas, DAMOS
prioritizes regions and applies the action to only regions having high enough
priorities so that it will not exceed the quotas.</p>
<p>The prioritization mechanism should be different for each action. For example,
rarely accessed (colder) memory regions would be prioritized for page-out
scheme action. In contrast, the colder regions would be deprioritized for huge
page collapse scheme action. Hence, the prioritization mechanisms for each
action are implemented in each DAMON operations set, together with the actions.</p>
<p>Though the implementation is up to the DAMON operations set, it would be common
to calculate the priority using the access pattern properties of the regions.
Some users would want the mechanisms to be personalized for their specific
case. For example, some users would want the mechanism to weigh the recency
(<code class="docutils literal notranslate"><span class="pre">age</span></code>) more than the access frequency (<code class="docutils literal notranslate"><span class="pre">nr_accesses</span></code>). DAMOS allows users
to specify the weight of each access pattern property and passes the
information to the underlying mechanism. Nevertheless, how and even whether
the weight will be respected are up to the underlying prioritization mechanism
implementation.</p>
<p>To know how user-space can set the prioritization weights via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs
interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-quotas"><span class="std std-ref">weights</span></a> part of
the documentation.</p>
</section>
<section id="aim-oriented-feedback-driven-auto-tuning">
<span id="damon-design-damos-quotas-auto-tuning"></span><h5>Aim-oriented Feedback-driven Auto-tuning<a class="headerlink" href="#aim-oriented-feedback-driven-auto-tuning" title="Link to this heading">¶</a></h5>
<p>Automatic feedback-driven quota tuning. Instead of setting the absolute quota
value, users can specify the metric of their interest, and what target value
they want the metric value to be. DAMOS then automatically tunes the
aggressiveness (the quota) of the corresponding scheme. For example, if DAMOS
is under achieving the goal, DAMOS automatically increases the quota. If DAMOS
is over achieving the goal, it decreases the quota.</p>
<p>The goal can be specified with four parameters, namely <code class="docutils literal notranslate"><span class="pre">target_metric</span></code>,
<code class="docutils literal notranslate"><span class="pre">target_value</span></code>, <code class="docutils literal notranslate"><span class="pre">current_value</span></code> and <code class="docutils literal notranslate"><span class="pre">nid</span></code>. The auto-tuning mechanism
tries to make <code class="docutils literal notranslate"><span class="pre">current_value</span></code> of <code class="docutils literal notranslate"><span class="pre">target_metric</span></code> be same to
<code class="docutils literal notranslate"><span class="pre">target_value</span></code>.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">user_input</span></code>: User-provided value. Users could use any metric that they
has interest in for the value. Use space main workload’s latency or
throughput, system metrics like free memory ratio or memory pressure stall
time (PSI) could be examples. Note that users should explicitly set
<code class="docutils literal notranslate"><span class="pre">current_value</span></code> on their own in this case. In other words, users should
repeatedly provide the feedback.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">some_mem_psi_us</span></code>: System-wide <code class="docutils literal notranslate"><span class="pre">some</span></code> memory pressure stall information
in microseconds that measured from last quota reset to next quota reset.
DAMOS does the measurement on its own, so only <code class="docutils literal notranslate"><span class="pre">target_value</span></code> need to be
set by users at the initial time. In other words, DAMOS does self-feedback.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">node_mem_used_bp</span></code>: Specific NUMA node’s used memory ratio in bp (1/10,000).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">node_mem_free_bp</span></code>: Specific NUMA node’s free memory ratio in bp (1/10,000).</p></li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">nid</span></code> is optionally required for only <code class="docutils literal notranslate"><span class="pre">node_mem_used_bp</span></code> and
<code class="docutils literal notranslate"><span class="pre">node_mem_free_bp</span></code> to point the specific NUMA node.</p>
<p>To know how user-space can set the tuning goal metric, the target value, and/or
the current value via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to
<a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-schemes-quota-goals"><span class="std std-ref">quota goals</span></a> part of the documentation.</p>
</section>
</section>
<section id="watermarks">
<span id="damon-design-damos-watermarks"></span><h4>Watermarks<a class="headerlink" href="#watermarks" title="Link to this heading">¶</a></h4>
<p>Conditional DAMOS (de)activation automation. Users might want DAMOS to run
only under certain situations. For example, when a sufficient amount of free
memory is guaranteed, running a scheme for proactive reclamation would only
consume unnecessary system resources. To avoid such consumption, the user would
need to manually monitor some metrics such as free memory ratio, and turn
DAMON/DAMOS on or off.</p>
<p>DAMOS allows users to offload such works using three watermarks. It allows the
users to configure the metric of their interest, and three watermark values,
namely high, middle, and low. If the value of the metric becomes above the
high watermark or below the low watermark, the scheme is deactivated. If the
metric becomes below the mid watermark but above the low watermark, the scheme
is activated. If all schemes are deactivated by the watermarks, the monitoring
is also deactivated. In this case, the DAMON worker thread only periodically
checks the watermarks and therefore incurs nearly zero overhead.</p>
<p>To know how user-space can set the watermarks via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-watermarks"><span class="std std-ref">watermarks</span></a> part of the
documentation.</p>
</section>
<section id="filters">
<span id="damon-design-damos-filters"></span><h4>Filters<a class="headerlink" href="#filters" title="Link to this heading">¶</a></h4>
<p>Non-access pattern-based target memory regions filtering. If users run
self-written programs or have good profiling tools, they could know something
more than the kernel, such as future access patterns or some special
requirements for specific types of memory. For example, some users may know
only anonymous pages can impact their program’s performance. They can also
have a list of latency-critical processes.</p>
<p>To let users optimize DAMOS schemes with such special knowledge, DAMOS provides
a feature called DAMOS filters. The feature allows users to set an arbitrary
number of filters for each scheme. Each filter specifies</p>
<ul class="simple">
<li><p>a type of memory (<code class="docutils literal notranslate"><span class="pre">type</span></code>),</p></li>
<li><p>whether it is for the memory of the type or all except the type
(<code class="docutils literal notranslate"><span class="pre">matching</span></code>), and</p></li>
<li><p>whether it is to allow (include) or reject (exclude) applying
the scheme’s action to the memory (<code class="docutils literal notranslate"><span class="pre">allow</span></code>).</p></li>
</ul>
<p>For efficient handling of filters, some types of filters are handled by the
core layer, while others are handled by operations set. In the latter case,
hence, support of the filter types depends on the DAMON operations set. In
case of the core layer-handled filters, the memory regions that excluded by the
filter are not counted as the scheme has tried to the region. In contrast, if
a memory regions is filtered by an operations set layer-handled filter, it is
counted as the scheme has tried. This difference affects the statistics.</p>
<p>When multiple filters are installed, the group of filters that handled by the
core layer are evaluated first. After that, the group of filters that handled
by the operations layer are evaluated. Filters in each of the groups are
evaluated in the installed order. If a part of memory is matched to one of the
filter, next filters are ignored. If the part passes through the filters
evaluation stage because it is not matched to any of the filters, applying the
scheme’s action to it depends on the last filter’s allowance type. If the last
filter was for allowing, the part of memory will be rejected, and vice versa.</p>
<p>For example, let’s assume 1) a filter for allowing anonymous pages and 2)
another filter for rejecting young pages are installed in the order. If a page
of a region that eligible to apply the scheme’s action is an anonymous page,
the scheme’s action will be applied to the page regardless of whether it is
young or not, since it matches with the first allow-filter. If the page is
not anonymous but young, the scheme’s action will not be applied, since the
second reject-filter blocks it. If the page is neither anonymous nor young,
the page will pass through the filters evaluation stage since there is no
matching filter, and the action will be applied to the page.</p>
<p>Below <code class="docutils literal notranslate"><span class="pre">type</span></code> of filters are currently supported.</p>
<ul class="simple">
<li><dl class="simple">
<dt>Core layer handled</dt><dd><ul>
<li><dl class="simple">
<dt>addr</dt><dd><ul>
<li><p>Applied to pages that belonging to a given address range.</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>target</dt><dd><ul>
<li><p>Applied to pages that belonging to a given DAMON monitoring target.</p></li>
</ul>
</dd>
</dl>
</li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Operations layer handled, supported by only <code class="docutils literal notranslate"><span class="pre">paddr</span></code> operations set.</dt><dd><ul>
<li><dl class="simple">
<dt>anon</dt><dd><ul>
<li><p>Applied to pages that containing data that not stored in files.</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>active</dt><dd><ul>
<li><p>Applied to active pages.</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>memcg</dt><dd><ul>
<li><p>Applied to pages that belonging to a given cgroup.</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>young</dt><dd><ul>
<li><p>Applied to pages that are accessed after the last access check from the
scheme.</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>hugepage_size</dt><dd><ul>
<li><p>Applied to pages that managed in a given size range.</p></li>
</ul>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>unmapped</dt><dd><ul>
<li><p>Applied to pages that unmapped.</p></li>
</ul>
</dd>
</dl>
</li>
</ul>
</dd>
</dl>
</li>
</ul>
<p>To know how user-space can set the filters via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-filters"><span class="std std-ref">filters</span></a> part of the
documentation.</p>
</section>
<section id="statistics">
<span id="damon-design-damos-stat"></span><h4>Statistics<a class="headerlink" href="#statistics" title="Link to this heading">¶</a></h4>
<p>The statistics of DAMOS behaviors that designed to help monitoring, tuning and
debugging of DAMOS.</p>
<p>DAMOS accounts below statistics for each scheme, from the beginning of the
scheme’s execution.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">nr_tried</span></code>: Total number of regions that the scheme is tried to be applied.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sz_tried</span></code>: Total size of regions that the scheme is tried to be applied.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sz_ops_filter_passed</span></code>: Total bytes that passed operations set
layer-handled DAMOS filters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">nr_applied</span></code>: Total number of regions that the scheme is applied.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sz_applied</span></code>: Total size of regions that the scheme is applied.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">qt_exceeds</span></code>: Total number of times the quota of the scheme has exceeded.</p></li>
</ul>
<p>“A scheme is tried to be applied to a region” means DAMOS core logic determined
the region is eligible to apply the scheme’s <a class="reference internal" href="#damon-design-damos-action"><span class="std std-ref">action</span></a>. The <a class="reference internal" href="#damon-design-damos-access-pattern"><span class="std std-ref">access pattern</span></a>, <a class="reference internal" href="#damon-design-damos-quotas"><span class="std std-ref">quotas</span></a>, <a class="reference internal" href="#damon-design-damos-watermarks"><span class="std std-ref">watermarks</span></a>, and <a class="reference internal" href="#damon-design-damos-filters"><span class="std std-ref">filters</span></a> that handled on core logic could affect this.
The core logic will only ask the underlying <a class="reference internal" href="#damon-operations-set"><span class="std std-ref">operation set</span></a> to do apply the action to the region, so whether the
action is really applied or not is unclear. That’s why it is called “tried”.</p>
<p>“A scheme is applied to a region” means the <a class="reference internal" href="#damon-operations-set"><span class="std std-ref">operation set</span></a> has applied the action to at least a part of the
region. The <a class="reference internal" href="#damon-design-damos-filters"><span class="std std-ref">filters</span></a> that handled by the
operation set, and the types of the <a class="reference internal" href="#damon-design-damos-action"><span class="std std-ref">action</span></a>
and the pages of the region can affect this. For example, if a filter is set
to exclude anonymous pages and the region has only anonymous pages, or if the
action is <code class="docutils literal notranslate"><span class="pre">pageout</span></code> while all pages of the region are unreclaimable, applying
the action to the region will fail.</p>
<p>To know how user-space can read the stats via <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a>, refer to :ref:s`stats <sysfs_stats>` part of the
documentation.</p>
</section>
<section id="regions-walking">
<h4>Regions Walking<a class="headerlink" href="#regions-walking" title="Link to this heading">¶</a></h4>
<p>DAMOS feature allowing users access each region that a DAMOS action has just
applied. Using this feature, DAMON <a class="reference internal" href="#damon-design-api"><span class="std std-ref">API</span></a> allows users
access full properties of the regions including the access monitoring results
and amount of the region’s internal memory that passed the DAMOS filters.
<a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">DAMON sysfs interface</span></a> also allows users read the data
via special <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-schemes-tried-regions"><span class="std std-ref">files</span></a>.</p>
</section>
</section>
<section id="application-programming-interface">
<span id="damon-design-api"></span><h3>Application Programming Interface<a class="headerlink" href="#application-programming-interface" title="Link to this heading">¶</a></h3>
<p>The programming interface for kernel space data access-aware applications.
DAMON is a framework, so it does nothing by itself. Instead, it only helps
other kernel components such as subsystems and modules building their data
access-aware applications using DAMON’s core features. For this, DAMON exposes
its all features to other kernel components via its application programming
interface, namely <code class="docutils literal notranslate"><span class="pre">include/linux/damon.h</span></code>. Please refer to the API
<a class="reference internal" href="api.html"><span class="doc">document</span></a> for details of the interface.</p>
</section>
</section>
<section id="modules">
<span id="damon-modules"></span><h2>Modules<a class="headerlink" href="#modules" title="Link to this heading">¶</a></h2>
<p>Because the core of DAMON is a framework for kernel components, it doesn’t
provide any direct interface for the user space. Such interfaces should be
implemented by each DAMON API user kernel components, instead. DAMON subsystem
itself implements such DAMON API user modules, which are supposed to be used
for general purpose DAMON control and special purpose data access-aware system
operations, and provides stable application binary interfaces (ABI) for the
user space. The user space can build their efficient data access-aware
applications using the interfaces.</p>
<section id="general-purpose-user-interface-modules">
<h3>General Purpose User Interface Modules<a class="headerlink" href="#general-purpose-user-interface-modules" title="Link to this heading">¶</a></h3>
<p>DAMON modules that provide user space ABIs for general purpose DAMON usage in
runtime.</p>
<p>Like many other ABIs, the modules create files on pseudo file systems like
‘sysfs’, allow users to specify their requests to and get the answers from
DAMON by writing to and reading from the files. As a response to such I/O,
DAMON user interface modules control DAMON and retrieve the results as user
requested via the DAMON API, and return the results to the user-space.</p>
<p>The ABIs are designed to be used for user space applications development,
rather than human beings’ fingers. Human users are recommended to use such
user space tools. One such Python-written user space tool is available at
Github (<a class="reference external" href="https://github.com/damonitor/damo">https://github.com/damonitor/damo</a>), Pypi
(<a class="reference external" href="https://pypistats.org/packages/damo">https://pypistats.org/packages/damo</a>), and Fedora
(<a class="reference external" href="https://packages.fedoraproject.org/pkgs/python-damo/damo/">https://packages.fedoraproject.org/pkgs/python-damo/damo/</a>).</p>
<p>Currently, one module for this type, namely ‘DAMON sysfs interface’ is
available. Please refer to the ABI <a class="reference internal" href="../../admin-guide/mm/damon/usage.html#sysfs-interface"><span class="std std-ref">doc</span></a> for details of
the interfaces.</p>
</section>
<section id="special-purpose-access-aware-kernel-modules">
<h3>Special-Purpose Access-aware Kernel Modules<a class="headerlink" href="#special-purpose-access-aware-kernel-modules" title="Link to this heading">¶</a></h3>
<p>DAMON modules that provide user space ABI for specific purpose DAMON usage.</p>
<p>DAMON user interface modules are for full control of all DAMON features in
runtime. For each special-purpose system-wide data access-aware system
operations such as proactive reclamation or LRU lists balancing, the interfaces
could be simplified by removing unnecessary knobs for the specific purpose, and
extended for boot-time and even compile time control. Default values of DAMON
control parameters for the usage would also need to be optimized for the
purpose.</p>
<p>To support such cases, yet more DAMON API user kernel modules that provide more
simple and optimized user space interfaces are available. Currently, two
modules for proactive reclamation and LRU lists manipulation are provided. For
more detail, please read the usage documents for those
(<a class="reference internal" href="../../admin-guide/mm/damon/reclaim.html"><span class="doc">DAMON-based Reclamation</span></a> and
<a class="reference internal" href="../../admin-guide/mm/damon/lru_sort.html"><span class="doc">DAMON-based LRU-lists Sorting</span></a>).</p>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../../_sources/mm/damon/design.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>