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 82active_mem_bp 83------------- 84 85Desired active to [in]active memory ratio in bp (1/10,000). 86 87While keeping the caps that set by other quotas, DAMON_LRU_SORT automatically 88increases and decreases the effective level of the quota aiming the LRU 89[de]prioritizations of the hot and cold memory resulting in this active to 90[in]active memory ratio. Value zero means disabling this auto-tuning feature. 91 92Disabled by default. 93 94Auto-tune monitoring intervals 95------------------------------ 96 97If this parameter is set as ``Y``, DAMON_LRU_SORT automatically tunes DAMON's 98sampling and aggregation intervals. The auto-tuning aims to capture meaningful 99amount of access events in each DAMON-snapshot, while keeping the sampling 100interval 5 milliseconds in minimum, and 10 seconds in maximum. Setting this as 101``N`` disables the auto-tuning. 102 103Disabled by default. 104 105filter_young_pages 106------------------ 107 108Filter [non-]young pages accordingly for LRU [de]prioritizations. 109 110If this is set, check page level access (youngness) once again before each 111LRU [de]prioritization operation. LRU prioritization operation is skipped 112if the page has not accessed since the last check (not young). LRU 113deprioritization operation is skipped if the page has accessed since the 114last check (young). The feature is enabled or disabled if this parameter is 115set as ``Y`` or ``N``, respectively. 116 117Disabled by default. 118 119hot_thres_access_freq 120--------------------- 121 122Access frequency threshold for hot memory regions identification in permil. 123 124If a memory region is accessed in frequency of this or higher, DAMON_LRU_SORT 125identifies the region as hot, and mark it as accessed on the LRU list, so that 126it could not be reclaimed under memory pressure. 50% by default. 127 128cold_min_age 129------------ 130 131Time threshold for cold memory regions identification in microseconds. 132 133If a memory region is not accessed for this or longer time, DAMON_LRU_SORT 134identifies the region as cold, and mark it as unaccessed on the LRU list, so 135that it could be reclaimed first under memory pressure. 120 seconds by 136default. 137 138quota_ms 139-------- 140 141Limit of time for trying the LRU lists sorting in milliseconds. 142 143DAMON_LRU_SORT tries to use only up to this time within a time window 144(quota_reset_interval_ms) for trying LRU lists sorting. This can be used 145for limiting CPU consumption of DAMON_LRU_SORT. If the value is zero, the 146limit is disabled. 147 14810 ms by default. 149 150quota_reset_interval_ms 151----------------------- 152 153The time quota charge reset interval in milliseconds. 154 155The charge reset interval for the quota of time (quota_ms). That is, 156DAMON_LRU_SORT does not try LRU-lists sorting for more than quota_ms 157milliseconds or quota_sz bytes within quota_reset_interval_ms milliseconds. 158 1591 second by default. 160 161wmarks_interval 162--------------- 163 164The watermarks check time interval in microseconds. 165 166Minimal time to wait before checking the watermarks, when DAMON_LRU_SORT is 167enabled but inactive due to its watermarks rule. 5 seconds by default. 168 169wmarks_high 170----------- 171 172Free memory rate (per thousand) for the high watermark. 173 174If free memory of the system in bytes per thousand bytes is higher than this, 175DAMON_LRU_SORT becomes inactive, so it does nothing but periodically checks the 176watermarks. 200 (20%) by default. 177 178wmarks_mid 179---------- 180 181Free memory rate (per thousand) for the middle watermark. 182 183If free memory of the system in bytes per thousand bytes is between this and 184the low watermark, DAMON_LRU_SORT becomes active, so starts the monitoring and 185the LRU-lists sorting. 150 (15%) by default. 186 187wmarks_low 188---------- 189 190Free memory rate (per thousand) for the low watermark. 191 192If free memory of the system in bytes per thousand bytes is lower than this, 193DAMON_LRU_SORT becomes inactive, so it does nothing but periodically checks the 194watermarks. 50 (5%) by default. 195 196sample_interval 197--------------- 198 199Sampling interval for the monitoring in microseconds. 200 201The sampling interval of DAMON for the cold memory monitoring. Please refer to 202the DAMON documentation (:doc:`usage`) for more detail. 5ms by default. 203 204aggr_interval 205------------- 206 207Aggregation interval for the monitoring in microseconds. 208 209The aggregation interval of DAMON for the cold memory monitoring. Please 210refer to the DAMON documentation (:doc:`usage`) for more detail. 100ms by 211default. 212 213min_nr_regions 214-------------- 215 216Minimum number of monitoring regions. 217 218The minimal number of monitoring regions of DAMON for the cold memory 219monitoring. This can be used to set lower-bound of the monitoring quality. 220But, setting this too high could result in increased monitoring overhead. 221Please refer to the DAMON documentation (:doc:`usage`) for more detail. 10 by 222default. 223 224max_nr_regions 225-------------- 226 227Maximum number of monitoring regions. 228 229The maximum number of monitoring regions of DAMON for the cold memory 230monitoring. This can be used to set upper-bound of the monitoring overhead. 231However, setting this too low could result in bad monitoring quality. Please 232refer to the DAMON documentation (:doc:`usage`) for more detail. 1000 by 233defaults. 234 235monitor_region_start 236-------------------- 237 238Start of target memory region in physical address. 239 240The start physical address of memory region that DAMON_LRU_SORT will do work 241against. By default, biggest System RAM is used as the region. 242 243monitor_region_end 244------------------ 245 246End of target memory region in physical address. 247 248The end physical address of memory region that DAMON_LRU_SORT will do work 249against. By default, biggest System RAM is used as the region. 250 251addr_unit 252--------- 253 254A scale factor for memory addresses and bytes. 255 256This parameter is for setting and getting the :ref:`address unit 257<damon_design_addr_unit>` parameter of the DAMON instance for DAMON_RECLAIM. 258 259``monitor_region_start`` and ``monitor_region_end`` should be provided in this 260unit. For example, let's suppose ``addr_unit``, ``monitor_region_start`` and 261``monitor_region_end`` are set as ``1024``, ``0`` and ``10``, respectively. 262Then DAMON_LRU_SORT will work for 10 KiB length of physical address range that 263starts from address zero (``[0 * 1024, 10 * 1024)`` in bytes). 264 265Stat parameters having ``bytes_`` prefix are also in this unit. For example, 266let's suppose values of ``addr_unit``, ``bytes_lru_sort_tried_hot_regions`` and 267``bytes_lru_sorted_hot_regions`` are ``1024``, ``42``, and ``32``, 268respectively. Then it means DAMON_LRU_SORT tried to LRU-sort 42 KiB of hot 269memory and successfully LRU-sorted 32 KiB of the memory in total. 270 271If unsure, use only the default value (``1``) and forget about this. 272 273kdamond_pid 274----------- 275 276PID of the DAMON thread. 277 278If DAMON_LRU_SORT is enabled, this becomes the PID of the worker thread. Else, 279-1. 280 281nr_lru_sort_tried_hot_regions 282----------------------------- 283 284Number of hot memory regions that tried to be LRU-sorted. 285 286bytes_lru_sort_tried_hot_regions 287-------------------------------- 288 289Total bytes of hot memory regions that tried to be LRU-sorted. 290 291nr_lru_sorted_hot_regions 292------------------------- 293 294Number of hot memory regions that successfully be LRU-sorted. 295 296bytes_lru_sorted_hot_regions 297---------------------------- 298 299Total bytes of hot memory regions that successfully be LRU-sorted. 300 301nr_hot_quota_exceeds 302-------------------- 303 304Number of times that the time quota limit for hot regions have exceeded. 305 306nr_lru_sort_tried_cold_regions 307------------------------------ 308 309Number of cold memory regions that tried to be LRU-sorted. 310 311bytes_lru_sort_tried_cold_regions 312--------------------------------- 313 314Total bytes of cold memory regions that tried to be LRU-sorted. 315 316nr_lru_sorted_cold_regions 317-------------------------- 318 319Number of cold memory regions that successfully be LRU-sorted. 320 321bytes_lru_sorted_cold_regions 322----------------------------- 323 324Total bytes of cold memory regions that successfully be LRU-sorted. 325 326nr_cold_quota_exceeds 327--------------------- 328 329Number of times that the time quota limit for cold regions have exceeded. 330 331Example 332======= 333 334Below runtime example commands make DAMON_LRU_SORT to find memory regions 335having >=50% access frequency and LRU-prioritize while LRU-deprioritizing 336memory regions that not accessed for 120 seconds. The prioritization and 337deprioritization is limited to be done using only up to 1% CPU time to avoid 338DAMON_LRU_SORT consuming too much CPU time for the (de)prioritization. It also 339asks DAMON_LRU_SORT to do nothing if the system's free memory rate is more than 34050%, but start the real works if it becomes lower than 40%. If DAMON_RECLAIM 341doesn't make progress and therefore the free memory rate becomes lower than 34220%, it asks DAMON_LRU_SORT to do nothing again, so that we can fall back to 343the LRU-list based page granularity reclamation. :: 344 345 # cd /sys/module/damon_lru_sort/parameters 346 # echo 500 > hot_thres_access_freq 347 # echo 120000000 > cold_min_age 348 # echo 10 > quota_ms 349 # echo 1000 > quota_reset_interval_ms 350 # echo 500 > wmarks_high 351 # echo 400 > wmarks_mid 352 # echo 200 > wmarks_low 353 # echo Y > enabled 354