mm/damon/reclaim.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 DAMON-based Reclamation
7 DAMON-based Reclamation (DAMON_RECLAIM) is a static kernel module that aimed to
8 be used for proactive and lightweight reclamation under light memory pressure.
9 It doesn't aim to replace the LRU-list based page_granularity reclamation, but
10 to be selectively used for different level of memory pressure and requirements.
15 On general memory over-committed systems, proactively reclaiming cold pages
16 helps saving memory and reducing latency spikes that incurred by the direct
20 Free Pages Reporting [3]_ based memory over-commit virtualization systems are
22 memory to host, and the host reallocates the reported memory to other guests.
23 As a result, the memory of the systems are fully utilized.  However, the
24 guests could be not so memory-frugal, mainly because some kernel subsystems and
25 user-space applications are designed to use as much memory as available.  Then,
26 guests could report only small amount of memory as free to host, results in
27 memory utilization drop of the systems.  Running the proactive reclamation in
33 DAMON_RECLAIM finds memory regions that didn't accessed for specific time
34 duration and page out.  To avoid it consuming too much CPU for the paging out
36 out memory regions that didn't accessed longer time first.  System
38 automatically activated and deactivated with three memory pressure watermarks.
43 To use this feature, you should first ensure your system is running on a kernel
46 To let sysadmins enable or disable it and tune for the given system,
49 proper values to ``/sys/module/damon_reclaim/parameters/<parameter>`` files.
54 -------
60 no real monitoring and reclamation due to the watermarks-based activation
61 condition.  Refer to below descriptions for the watermarks parameter for this.
64 -------------
70 of parametrs except ``enabled`` again.  Once the re-reading is done, this
72 re-reading, DAMON_RECLAIM will be disabled.
75 -------
77 Time threshold for cold memory regions identification in microseconds.
79 If a memory region is not accessed for this or longer time, DAMON_RECLAIM
85 --------
89 DAMON_RECLAIM tries to use only up to this time within a time window
97 --------
99 Limit of size of memory for the reclamation in bytes.
101 DAMON_RECLAIM charges amount of memory which it tried to reclaim within a time
109 -----------------------
121 ---------------
123 Minimal time to wait before checking the watermarks, when DAMON_RECLAIM is
124 enabled but inactive due to its watermarks rule.
127 -----------
129 Free memory rate (per thousand) for the high watermark.
131 If free memory of the system in bytes per thousand bytes is higher than this,
136 ----------
138 Free memory rate (per thousand) for the middle watermark.
140 If free memory of the system in bytes per thousand bytes is between this and
145 ----------
147 Free memory rate (per thousand) for the low watermark.
149 If free memory of the system in bytes per thousand bytes is lower than this,
151 watermarks.  In the case, the system falls back to the LRU-list based page
155 ---------------
159 The sampling interval of DAMON for the cold memory monitoring.  Please refer to
163 -------------
167 The aggregation interval of DAMON for the cold memory monitoring.  Please
168 refer to the DAMON documentation (:doc:`usage`) for more detail.
171 --------------
175 The minimal number of monitoring regions of DAMON for the cold memory
176 monitoring.  This can be used to set lower-bound of the monitoring quality.
178 Please refer to the DAMON documentation (:doc:`usage`) for more detail.
181 --------------
185 The maximum number of monitoring regions of DAMON for the cold memory
186 monitoring.  This can be used to set upper-bound of the monitoring overhead.
188 refer to the DAMON documentation (:doc:`usage`) for more detail.
191 --------------------
193 Start of target memory region in physical address.
195 The start physical address of memory region that DAMON_RECLAIM will do work
196 against.  That is, DAMON_RECLAIM will find cold memory regions in this region
200 ------------------
202 End of target memory region in physical address.
204 The end physical address of memory region that DAMON_RECLAIM will do work
205 against.  That is, DAMON_RECLAIM will find cold memory regions in this region
209 ---------
218 -----------
223 -1.
226 ------------------------
228 Number of memory regions that tried to be reclaimed by DAMON_RECLAIM.
231 ---------------------------
233 Total bytes of memory regions that tried to be reclaimed by DAMON_RECLAIM.
236 --------------------
238 Number of memory regions that successfully be reclaimed by DAMON_RECLAIM.
241 -----------------------
243 Total bytes of memory regions that successfully be reclaimed by DAMON_RECLAIM.
246 ----------------
253 Below runtime example commands make DAMON_RECLAIM to find memory regions that
255 to be done only up to 1 GiB per second to avoid DAMON_RECLAIM consuming too
256 much CPU time for the paging out operation.  It also asks DAMON_RECLAIM to do
257 nothing if the system's free memory rate is more than 50%, but start the real
259 therefore the free memory rate becomes lower than 20%, it asks DAMON_RECLAIM to
260 do nothing again, so that we can fall back to the LRU-list based page