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/modules/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
214kdamond_pid
215-----------
216
217PID of the DAMON thread.
218
219If DAMON_LRU_SORT is enabled, this becomes the PID of the worker thread.  Else,
220-1.
221
222nr_lru_sort_tried_hot_regions
223-----------------------------
224
225Number of hot memory regions that tried to be LRU-sorted.
226
227bytes_lru_sort_tried_hot_regions
228--------------------------------
229
230Total bytes of hot memory regions that tried to be LRU-sorted.
231
232nr_lru_sorted_hot_regions
233-------------------------
234
235Number of hot memory regions that successfully be LRU-sorted.
236
237bytes_lru_sorted_hot_regions
238----------------------------
239
240Total bytes of hot memory regions that successfully be LRU-sorted.
241
242nr_hot_quota_exceeds
243--------------------
244
245Number of times that the time quota limit for hot regions have exceeded.
246
247nr_lru_sort_tried_cold_regions
248------------------------------
249
250Number of cold memory regions that tried to be LRU-sorted.
251
252bytes_lru_sort_tried_cold_regions
253---------------------------------
254
255Total bytes of cold memory regions that tried to be LRU-sorted.
256
257nr_lru_sorted_cold_regions
258--------------------------
259
260Number of cold memory regions that successfully be LRU-sorted.
261
262bytes_lru_sorted_cold_regions
263-----------------------------
264
265Total bytes of cold memory regions that successfully be LRU-sorted.
266
267nr_cold_quota_exceeds
268---------------------
269
270Number of times that the time quota limit for cold regions have exceeded.
271
272Example
273=======
274
275Below runtime example commands make DAMON_LRU_SORT to find memory regions
276having >=50% access frequency and LRU-prioritize while LRU-deprioritizing
277memory regions that not accessed for 120 seconds.  The prioritization and
278deprioritization is limited to be done using only up to 1% CPU time to avoid
279DAMON_LRU_SORT consuming too much CPU time for the (de)prioritization.  It also
280asks DAMON_LRU_SORT to do nothing if the system's free memory rate is more than
28150%, but start the real works if it becomes lower than 40%.  If DAMON_RECLAIM
282doesn't make progress and therefore the free memory rate becomes lower than
28320%, it asks DAMON_LRU_SORT to do nothing again, so that we can fall back to
284the LRU-list based page granularity reclamation. ::
285
286    # cd /sys/modules/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
295