1.. SPDX-License-Identifier: GPL-2.0 2 3============================= 4DAMON-based LRU-lists Sorting 5============================= 6 7DAMON-based LRU-lists Sorting (DAMON_LRU_SORT) is a static kernel module that 8aimed to be used for proactive and lightweight data access pattern based 9(de)prioritization of pages on their LRU-lists for making LRU-lists a more 10trusworthy data access pattern source. 11 12Where Proactive LRU-lists Sorting is Required? 13============================================== 14 15As page-granularity access checking overhead could be significant on huge 16systems, LRU lists are normally not proactively sorted but partially and 17reactively sorted for special events including specific user requests, system 18calls and memory pressure. As a result, LRU lists are sometimes not so 19perfectly prepared to be used as a trustworthy access pattern source for some 20situations including reclamation target pages selection under sudden memory 21pressure. 22 23Because DAMON can identify access patterns of best-effort accuracy while 24inducing only user-specified range of overhead, proactively running 25DAMON_LRU_SORT could be helpful for making LRU lists more trustworthy access 26pattern source with low and controlled overhead. 27 28How It Works? 29============= 30 31DAMON_LRU_SORT finds hot pages (pages of memory regions that showing access 32rates that higher than a user-specified threshold) and cold pages (pages of 33memory regions that showing no access for a time that longer than a 34user-specified threshold) using DAMON, and prioritizes hot pages while 35deprioritizing cold pages on their LRU-lists. To avoid it consuming too much 36CPU for the prioritizations, a CPU time usage limit can be configured. Under 37the limit, it prioritizes and deprioritizes more hot and cold pages first, 38respectively. System administrators can also configure under what situation 39this scheme should automatically activated and deactivated with three memory 40pressure watermarks. 41 42Its default parameters for hotness/coldness thresholds and CPU quota limit are 43conservatively chosen. That is, the module under its default parameters could 44be widely used without harm for common situations while providing a level of 45benefits for systems having clear hot/cold access patterns under memory 46pressure while consuming only a limited small portion of CPU time. 47 48Interface: Module Parameters 49============================ 50 51To use this feature, you should first ensure your system is running on a kernel 52that is built with ``CONFIG_DAMON_LRU_SORT=y``. 53 54To let sysadmins enable or disable it and tune for the given system, 55DAMON_LRU_SORT utilizes module parameters. That is, you can put 56``damon_lru_sort.<parameter>=<value>`` on the kernel boot command line or write 57proper values to ``/sys/module/damon_lru_sort/parameters/<parameter>`` files. 58 59Below are the description of each parameter. 60 61enabled 62------- 63 64Enable or disable DAMON_LRU_SORT. 65 66You can enable DAMON_LRU_SORT by setting the value of this parameter as ``Y``. 67Setting it as ``N`` disables DAMON_LRU_SORT. Note that DAMON_LRU_SORT could do 68no real monitoring and LRU-lists sorting due to the watermarks-based activation 69condition. Refer to below descriptions for the watermarks parameter for this. 70 71commit_inputs 72------------- 73 74Make DAMON_LRU_SORT reads the input parameters again, except ``enabled``. 75 76Input parameters that updated while DAMON_LRU_SORT is running are not applied 77by default. Once this parameter is set as ``Y``, DAMON_LRU_SORT reads values 78of parametrs except ``enabled`` again. Once the re-reading is done, this 79parameter is set as ``N``. If invalid parameters are found while the 80re-reading, DAMON_LRU_SORT will be disabled. 81 82hot_thres_access_freq 83--------------------- 84 85Access frequency threshold for hot memory regions identification in permil. 86 87If a memory region is accessed in frequency of this or higher, DAMON_LRU_SORT 88identifies the region as hot, and mark it as accessed on the LRU list, so that 89it could not be reclaimed under memory pressure. 50% by default. 90 91cold_min_age 92------------ 93 94Time threshold for cold memory regions identification in microseconds. 95 96If a memory region is not accessed for this or longer time, DAMON_LRU_SORT 97identifies the region as cold, and mark it as unaccessed on the LRU list, so 98that it could be reclaimed first under memory pressure. 120 seconds by 99default. 100 101quota_ms 102-------- 103 104Limit of time for trying the LRU lists sorting in milliseconds. 105 106DAMON_LRU_SORT tries to use only up to this time within a time window 107(quota_reset_interval_ms) for trying LRU lists sorting. This can be used 108for limiting CPU consumption of DAMON_LRU_SORT. If the value is zero, the 109limit is disabled. 110 11110 ms by default. 112 113quota_reset_interval_ms 114----------------------- 115 116The time quota charge reset interval in milliseconds. 117 118The charge reset interval for the quota of time (quota_ms). That is, 119DAMON_LRU_SORT does not try LRU-lists sorting for more than quota_ms 120milliseconds or quota_sz bytes within quota_reset_interval_ms milliseconds. 121 1221 second by default. 123 124wmarks_interval 125--------------- 126 127The watermarks check time interval in microseconds. 128 129Minimal time to wait before checking the watermarks, when DAMON_LRU_SORT is 130enabled but inactive due to its watermarks rule. 5 seconds by default. 131 132wmarks_high 133----------- 134 135Free memory rate (per thousand) for the high watermark. 136 137If free memory of the system in bytes per thousand bytes is higher than this, 138DAMON_LRU_SORT becomes inactive, so it does nothing but periodically checks the 139watermarks. 200 (20%) by default. 140 141wmarks_mid 142---------- 143 144Free memory rate (per thousand) for the middle watermark. 145 146If free memory of the system in bytes per thousand bytes is between this and 147the low watermark, DAMON_LRU_SORT becomes active, so starts the monitoring and 148the LRU-lists sorting. 150 (15%) by default. 149 150wmarks_low 151---------- 152 153Free memory rate (per thousand) for the low watermark. 154 155If free memory of the system in bytes per thousand bytes is lower than this, 156DAMON_LRU_SORT becomes inactive, so it does nothing but periodically checks the 157watermarks. 50 (5%) by default. 158 159sample_interval 160--------------- 161 162Sampling interval for the monitoring in microseconds. 163 164The sampling interval of DAMON for the cold memory monitoring. Please refer to 165the DAMON documentation (:doc:`usage`) for more detail. 5ms by default. 166 167aggr_interval 168------------- 169 170Aggregation interval for the monitoring in microseconds. 171 172The aggregation interval of DAMON for the cold memory monitoring. Please 173refer to the DAMON documentation (:doc:`usage`) for more detail. 100ms by 174default. 175 176min_nr_regions 177-------------- 178 179Minimum number of monitoring regions. 180 181The minimal number of monitoring regions of DAMON for the cold memory 182monitoring. This can be used to set lower-bound of the monitoring quality. 183But, setting this too high could result in increased monitoring overhead. 184Please refer to the DAMON documentation (:doc:`usage`) for more detail. 10 by 185default. 186 187max_nr_regions 188-------------- 189 190Maximum number of monitoring regions. 191 192The maximum number of monitoring regions of DAMON for the cold memory 193monitoring. This can be used to set upper-bound of the monitoring overhead. 194However, setting this too low could result in bad monitoring quality. Please 195refer to the DAMON documentation (:doc:`usage`) for more detail. 1000 by 196defaults. 197 198monitor_region_start 199-------------------- 200 201Start of target memory region in physical address. 202 203The start physical address of memory region that DAMON_LRU_SORT will do work 204against. By default, biggest System RAM is used as the region. 205 206monitor_region_end 207------------------ 208 209End of target memory region in physical address. 210 211The end physical address of memory region that DAMON_LRU_SORT will do work 212against. By default, biggest System RAM is used as the region. 213 214addr_unit 215--------- 216 217A scale factor for memory addresses and bytes. 218 219This parameter is for setting and getting the :ref:`address unit 220<damon_design_addr_unit>` parameter of the DAMON instance for DAMON_RECLAIM. 221 222``monitor_region_start`` and ``monitor_region_end`` should be provided in this 223unit. For example, let's suppose ``addr_unit``, ``monitor_region_start`` and 224``monitor_region_end`` are set as ``1024``, ``0`` and ``10``, respectively. 225Then DAMON_LRU_SORT will work for 10 KiB length of physical address range that 226starts from address zero (``[0 * 1024, 10 * 1024)`` in bytes). 227 228Stat parameters having ``bytes_`` prefix are also in this unit. For example, 229let's suppose values of ``addr_unit``, ``bytes_lru_sort_tried_hot_regions`` and 230``bytes_lru_sorted_hot_regions`` are ``1024``, ``42``, and ``32``, 231respectively. Then it means DAMON_LRU_SORT tried to LRU-sort 42 KiB of hot 232memory and successfully LRU-sorted 32 KiB of the memory in total. 233 234If unsure, use only the default value (``1``) and forget about this. 235 236kdamond_pid 237----------- 238 239PID of the DAMON thread. 240 241If DAMON_LRU_SORT is enabled, this becomes the PID of the worker thread. Else, 242-1. 243 244nr_lru_sort_tried_hot_regions 245----------------------------- 246 247Number of hot memory regions that tried to be LRU-sorted. 248 249bytes_lru_sort_tried_hot_regions 250-------------------------------- 251 252Total bytes of hot memory regions that tried to be LRU-sorted. 253 254nr_lru_sorted_hot_regions 255------------------------- 256 257Number of hot memory regions that successfully be LRU-sorted. 258 259bytes_lru_sorted_hot_regions 260---------------------------- 261 262Total bytes of hot memory regions that successfully be LRU-sorted. 263 264nr_hot_quota_exceeds 265-------------------- 266 267Number of times that the time quota limit for hot regions have exceeded. 268 269nr_lru_sort_tried_cold_regions 270------------------------------ 271 272Number of cold memory regions that tried to be LRU-sorted. 273 274bytes_lru_sort_tried_cold_regions 275--------------------------------- 276 277Total bytes of cold memory regions that tried to be LRU-sorted. 278 279nr_lru_sorted_cold_regions 280-------------------------- 281 282Number of cold memory regions that successfully be LRU-sorted. 283 284bytes_lru_sorted_cold_regions 285----------------------------- 286 287Total bytes of cold memory regions that successfully be LRU-sorted. 288 289nr_cold_quota_exceeds 290--------------------- 291 292Number of times that the time quota limit for cold regions have exceeded. 293 294Example 295======= 296 297Below runtime example commands make DAMON_LRU_SORT to find memory regions 298having >=50% access frequency and LRU-prioritize while LRU-deprioritizing 299memory regions that not accessed for 120 seconds. The prioritization and 300deprioritization is limited to be done using only up to 1% CPU time to avoid 301DAMON_LRU_SORT consuming too much CPU time for the (de)prioritization. It also 302asks DAMON_LRU_SORT to do nothing if the system's free memory rate is more than 30350%, but start the real works if it becomes lower than 40%. If DAMON_RECLAIM 304doesn't make progress and therefore the free memory rate becomes lower than 30520%, it asks DAMON_LRU_SORT to do nothing again, so that we can fall back to 306the LRU-list based page granularity reclamation. :: 307 308 # cd /sys/module/damon_lru_sort/parameters 309 # echo 500 > hot_thres_access_freq 310 # echo 120000000 > cold_min_age 311 # echo 10 > quota_ms 312 # echo 1000 > quota_reset_interval_ms 313 # echo 500 > wmarks_high 314 # echo 400 > wmarks_mid 315 # echo 200 > wmarks_low 316 # echo Y > enabled 317