| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
======================= |
| 4 |
DAMON-based Reclamation |
| 5 |
======================= |
| 6 |
|
| 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. |
| 11 |
|
| 12 |
Where Proactive Reclamation is Required? |
| 13 |
======================================== |
| 14 |
|
| 15 |
On general memory over-committed systems, proactively reclaiming cold pages |
| 16 |
helps saving memory and reducing latency spikes that incurred by the direct |
| 17 |
reclaim of the process or CPU consumption of kswapd, while incurring only |
| 18 |
minimal performance degradation [1]_ [2]_ . |
| 19 |
|
| 20 |
Free Pages Reporting [3]_ based memory over-commit virtualization systems are |
| 21 |
good example of the cases. In such systems, the guest VMs reports their free |
| 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 |
| 28 |
guests could mitigate this problem. |
| 29 |
|
| 30 |
How It Works? |
| 31 |
============= |
| 32 |
|
| 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 |
| 35 |
operation, a speed limit can be configured. Under the speed limit, it pages |
| 36 |
out memory regions that didn't accessed longer time first. System |
| 37 |
administrators can also configure under what situation this scheme should |
| 38 |
automatically activated and deactivated with three memory pressure watermarks. |
| 39 |
|
| 40 |
Interface: Module Parameters |
| 41 |
============================ |
| 42 |
|
| 43 |
To use this feature, you should first ensure your system is running on a kernel |
| 44 |
that is built with ``CONFIG_DAMON_RECLAIM=y``. |
| 45 |
|
| 46 |
To let sysadmins enable or disable it and tune for the given system, |
| 47 |
DAMON_RECLAIM utilizes module parameters. That is, you can put |
| 48 |
``damon_reclaim.<parameter>=<value>`` on the kernel boot command line or write |
| 49 |
proper values to ``/sys/module/damon_reclaim/parameters/<parameter>`` files. |
| 50 |
|
| 51 |
Below are the description of each parameter. |
| 52 |
|
| 53 |
enabled |
| 54 |
------- |
| 55 |
|
| 56 |
Enable or disable DAMON_RECLAIM. |
| 57 |
|
| 58 |
You can enable DAMON_RCLAIM by setting the value of this parameter as ``Y``. |
| 59 |
Setting it as ``N`` disables DAMON_RECLAIM. Note that DAMON_RECLAIM could do |
| 60 |
no real monitoring and reclamation due to the watermarks-based activation |
| 61 |
condition. Refer to below descriptions for the watermarks parameter for this. |
| 62 |
|
| 63 |
commit_inputs |
| 64 |
------------- |
| 65 |
|
| 66 |
Make DAMON_RECLAIM reads the input parameters again, except ``enabled``. |
| 67 |
|
| 68 |
Input parameters that updated while DAMON_RECLAIM is running are not applied |
| 69 |
by default. Once this parameter is set as ``Y``, DAMON_RECLAIM reads values |
| 70 |
of parametrs except ``enabled`` again. Once the re-reading is done, this |
| 71 |
parameter is set as ``N``. If invalid parameters are found while the |
| 72 |
re-reading, DAMON_RECLAIM will be disabled. |
| 73 |
|
| 74 |
Once ``Y`` is written to this parameter, the user must not write to any |
| 75 |
parameters until reading ``commit_inputs`` again returns ``N``. If users |
| 76 |
violate this rule, the kernel may exhibit undefined behavior. |
| 77 |
|
| 78 |
min_age |
| 79 |
------- |
| 80 |
|
| 81 |
Time threshold for cold memory regions identification in microseconds. |
| 82 |
|
| 83 |
If a memory region is not accessed for this or longer time, DAMON_RECLAIM |
| 84 |
identifies the region as cold, and reclaims it. |
| 85 |
|
| 86 |
120 seconds by default. |
| 87 |
|
| 88 |
quota_ms |
| 89 |
-------- |
| 90 |
|
| 91 |
Limit of time for the reclamation in milliseconds. |
| 92 |
|
| 93 |
DAMON_RECLAIM tries to use only up to this time within a time window |
| 94 |
(quota_reset_interval_ms) for trying reclamation of cold pages. This can be |
| 95 |
used for limiting CPU consumption of DAMON_RECLAIM. If the value is zero, the |
| 96 |
limit is disabled. |
| 97 |
|
| 98 |
10 ms by default. |
| 99 |
|
| 100 |
quota_sz |
| 101 |
-------- |
| 102 |
|
| 103 |
Limit of size of memory for the reclamation in bytes. |
| 104 |
|
| 105 |
DAMON_RECLAIM charges amount of memory which it tried to reclaim within a time |
| 106 |
window (quota_reset_interval_ms) and makes no more than this limit is tried. |
| 107 |
This can be used for limiting consumption of CPU and IO. If this value is |
| 108 |
zero, the limit is disabled. |
| 109 |
|
| 110 |
128 MiB by default. |
| 111 |
|
| 112 |
quota_reset_interval_ms |
| 113 |
----------------------- |
| 114 |
|
| 115 |
The time/size quota charge reset interval in milliseconds. |
| 116 |
|
| 117 |
The charget reset interval for the quota of time (quota_ms) and size |
| 118 |
(quota_sz). That is, DAMON_RECLAIM does not try reclamation for more than |
| 119 |
quota_ms milliseconds or quota_sz bytes within quota_reset_interval_ms |
| 120 |
milliseconds. |
| 121 |
|
| 122 |
1 second by default. |
| 123 |
|
| 124 |
quota_mem_pressure_us |
| 125 |
--------------------- |
| 126 |
|
| 127 |
Desired level of memory pressure-stall time in microseconds. |
| 128 |
|
| 129 |
While keeping the caps that set by other quotas, DAMON_RECLAIM automatically |
| 130 |
increases and decreases the effective level of the quota aiming this level of |
| 131 |
memory pressure is incurred. System-wide ``some`` memory PSI in microseconds |
| 132 |
per quota reset interval (``quota_reset_interval_ms``) is collected and |
| 133 |
compared to this value to see if the aim is satisfied. Value zero means |
| 134 |
disabling this auto-tuning feature. |
| 135 |
|
| 136 |
Disabled by default. |
| 137 |
|
| 138 |
quota_autotune_feedback |
| 139 |
----------------------- |
| 140 |
|
| 141 |
User-specifiable feedback for auto-tuning of the effective quota. |
| 142 |
|
| 143 |
While keeping the caps that set by other quotas, DAMON_RECLAIM automatically |
| 144 |
increases and decreases the effective level of the quota aiming receiving this |
| 145 |
feedback of value ``10,000`` from the user. DAMON_RECLAIM assumes the feedback |
| 146 |
value and the quota are positively proportional. Value zero means disabling |
| 147 |
this auto-tuning feature. |
| 148 |
|
| 149 |
Disabled by default. |
| 150 |
|
| 151 |
wmarks_interval |
| 152 |
--------------- |
| 153 |
|
| 154 |
Minimal time to wait before checking the watermarks, when DAMON_RECLAIM is |
| 155 |
enabled but inactive due to its watermarks rule. |
| 156 |
|
| 157 |
wmarks_high |
| 158 |
----------- |
| 159 |
|
| 160 |
Free memory rate (per thousand) for the high watermark. |
| 161 |
|
| 162 |
If free memory of the system in bytes per thousand bytes is higher than this, |
| 163 |
DAMON_RECLAIM becomes inactive, so it does nothing but only periodically checks |
| 164 |
the watermarks. |
| 165 |
|
| 166 |
wmarks_mid |
| 167 |
---------- |
| 168 |
|
| 169 |
Free memory rate (per thousand) for the middle watermark. |
| 170 |
|
| 171 |
If free memory of the system in bytes per thousand bytes is between this and |
| 172 |
the low watermark, DAMON_RECLAIM becomes active, so starts the monitoring and |
| 173 |
the reclaiming. |
| 174 |
|
| 175 |
wmarks_low |
| 176 |
---------- |
| 177 |
|
| 178 |
Free memory rate (per thousand) for the low watermark. |
| 179 |
|
| 180 |
If free memory of the system in bytes per thousand bytes is lower than this, |
| 181 |
DAMON_RECLAIM becomes inactive, so it does nothing but periodically checks the |
| 182 |
watermarks. In the case, the system falls back to the LRU-list based page |
| 183 |
granularity reclamation logic. |
| 184 |
|
| 185 |
sample_interval |
| 186 |
--------------- |
| 187 |
|
| 188 |
Sampling interval for the monitoring in microseconds. |
| 189 |
|
| 190 |
The sampling interval of DAMON for the cold memory monitoring. Please refer to |
| 191 |
the DAMON documentation (:doc:`usage`) for more detail. |
| 192 |
|
| 193 |
aggr_interval |
| 194 |
------------- |
| 195 |
|
| 196 |
Aggregation interval for the monitoring in microseconds. |
| 197 |
|
| 198 |
The aggregation interval of DAMON for the cold memory monitoring. Please |
| 199 |
refer to the DAMON documentation (:doc:`usage`) for more detail. |
| 200 |
|
| 201 |
min_nr_regions |
| 202 |
-------------- |
| 203 |
|
| 204 |
Minimum number of monitoring regions. |
| 205 |
|
| 206 |
The minimal number of monitoring regions of DAMON for the cold memory |
| 207 |
monitoring. This can be used to set lower-bound of the monitoring quality. |
| 208 |
But, setting this too high could result in increased monitoring overhead. |
| 209 |
Please refer to the DAMON documentation (:doc:`usage`) for more detail. |
| 210 |
|
| 211 |
max_nr_regions |
| 212 |
-------------- |
| 213 |
|
| 214 |
Maximum number of monitoring regions. |
| 215 |
|
| 216 |
The maximum number of monitoring regions of DAMON for the cold memory |
| 217 |
monitoring. This can be used to set upper-bound of the monitoring overhead. |
| 218 |
However, setting this too low could result in bad monitoring quality. Please |
| 219 |
refer to the DAMON documentation (:doc:`usage`) for more detail. |
| 220 |
|
| 221 |
monitor_region_start |
| 222 |
-------------------- |
| 223 |
|
| 224 |
Start of target memory region in physical address. |
| 225 |
|
| 226 |
The start physical address of memory region that DAMON_RECLAIM will do work |
| 227 |
against. That is, DAMON_RECLAIM will find cold memory regions in this region |
| 228 |
and reclaims. By default, biggest System RAM is used as the region. |
| 229 |
|
| 230 |
monitor_region_end |
| 231 |
------------------ |
| 232 |
|
| 233 |
End of target memory region in physical address. |
| 234 |
|
| 235 |
The end physical address of memory region that DAMON_RECLAIM will do work |
| 236 |
against. That is, DAMON_RECLAIM will find cold memory regions in this region |
| 237 |
and reclaims. By default, biggest System RAM is used as the region. |
| 238 |
|
| 239 |
addr_unit |
| 240 |
--------- |
| 241 |
|
| 242 |
A scale factor for memory addresses and bytes. |
| 243 |
|
| 244 |
This parameter is for setting and getting the :ref:`address unit |
| 245 |
<damon_design_addr_unit>` parameter of the DAMON instance for DAMON_RECLAIM. |
| 246 |
|
| 247 |
``monitor_region_start`` and ``monitor_region_end`` should be provided in this |
| 248 |
unit. For example, let's suppose ``addr_unit``, ``monitor_region_start`` and |
| 249 |
``monitor_region_end`` are set as ``1024``, ``0`` and ``10``, respectively. |
| 250 |
Then DAMON_RECLAIM will work for 10 KiB length of physical address range that |
| 251 |
starts from address zero (``[0 * 1024, 10 * 1024)`` in bytes). |
| 252 |
|
| 253 |
``bytes_reclaim_tried_regions`` and ``bytes_reclaimed_regions`` are also in |
| 254 |
this unit. For example, let's suppose values of ``addr_unit``, |
| 255 |
``bytes_reclaim_tried_regions`` and ``bytes_reclaimed_regions`` are ``1024``, |
| 256 |
``42``, and ``32``, respectively. Then it means DAMON_RECLAIM tried to reclaim |
| 257 |
42 KiB memory and successfully reclaimed 32 KiB memory in total. |
| 258 |
|
| 259 |
If unsure, use only the default value (``1``) and forget about this. |
| 260 |
|
| 261 |
skip_anon |
| 262 |
--------- |
| 263 |
|
| 264 |
Skip anonymous pages reclamation. |
| 265 |
|
| 266 |
If this parameter is set as ``Y``, DAMON_RECLAIM does not reclaim anonymous |
| 267 |
pages. By default, ``N``. |
| 268 |
|
| 269 |
|
| 270 |
kdamond_pid |
| 271 |
----------- |
| 272 |
|
| 273 |
PID of the DAMON thread. |
| 274 |
|
| 275 |
If DAMON_RECLAIM is enabled, this becomes the PID of the worker thread. Else, |
| 276 |
-1. |
| 277 |
|
| 278 |
nr_reclaim_tried_regions |
| 279 |
------------------------ |
| 280 |
|
| 281 |
Number of memory regions that tried to be reclaimed by DAMON_RECLAIM. |
| 282 |
|
| 283 |
bytes_reclaim_tried_regions |
| 284 |
--------------------------- |
| 285 |
|
| 286 |
Total bytes of memory regions that tried to be reclaimed by DAMON_RECLAIM. |
| 287 |
|
| 288 |
nr_reclaimed_regions |
| 289 |
-------------------- |
| 290 |
|
| 291 |
Number of memory regions that successfully be reclaimed by DAMON_RECLAIM. |
| 292 |
|
| 293 |
bytes_reclaimed_regions |
| 294 |
----------------------- |
| 295 |
|
| 296 |
Total bytes of memory regions that successfully be reclaimed by DAMON_RECLAIM. |
| 297 |
|
| 298 |
nr_quota_exceeds |
| 299 |
---------------- |
| 300 |
|
| 301 |
Number of times that the time/space quota limits have exceeded. |
| 302 |
|
| 303 |
Example |
| 304 |
======= |
| 305 |
|
| 306 |
Below runtime example commands make DAMON_RECLAIM to find memory regions that |
| 307 |
not accessed for 30 seconds or more and pages out. The reclamation is limited |
| 308 |
to be done only up to 1 GiB per second to avoid DAMON_RECLAIM consuming too |
| 309 |
much CPU time for the paging out operation. It also asks DAMON_RECLAIM to do |
| 310 |
nothing if the system's free memory rate is more than 50%, but start the real |
| 311 |
works if it becomes lower than 40%. If DAMON_RECLAIM doesn't make progress and |
| 312 |
therefore the free memory rate becomes lower than 20%, it asks DAMON_RECLAIM to |
| 313 |
do nothing again, so that we can fall back to the LRU-list based page |
| 314 |
granularity reclamation. :: |
| 315 |
|
| 316 |
# cd /sys/module/damon_reclaim/parameters |
| 317 |
# echo 30000000 > min_age |
| 318 |
# echo $((1 * 1024 * 1024 * 1024)) > quota_sz |
| 319 |
# echo 1000 > quota_reset_interval_ms |
| 320 |
# echo 500 > wmarks_high |
| 321 |
# echo 400 > wmarks_mid |
| 322 |
# echo 200 > wmarks_low |
| 323 |
# echo Y > enabled |
| 324 |
|
| 325 |
.. [1] https://research.google/pubs/pub48551/ |
| 326 |
.. [2] https://lwn.net/Articles/787611/ |
| 327 |
.. [3] https://www.kernel.org/doc/html/latest/mm/free_page_reporting.html |