Documentation/admin-guide/mm/damon/lru_sort.rst

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