Commit | Line | Data |
---|---|---|
c4ba6014 SP |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ====== | |
4 | Design | |
5 | ====== | |
6 | ||
45b849df | 7 | |
1f1d83ca SP |
8 | .. _damon_design_execution_model_and_data_structures: |
9 | ||
10 | Execution Model and Data Structures | |
11 | =================================== | |
12 | ||
13 | The monitoring-related information including the monitoring request | |
14 | specification and DAMON-based operation schemes are stored in a data structure | |
15 | called DAMON ``context``. DAMON executes each context with a kernel thread | |
16 | called ``kdamond``. Multiple kdamonds could run in parallel, for different | |
17 | types of monitoring. | |
18 | ||
19 | ||
45b849df SP |
20 | Overall Architecture |
21 | ==================== | |
22 | ||
23 | DAMON subsystem is configured with three layers including | |
24 | ||
25 | - Operations Set: Implements fundamental operations for DAMON that depends on | |
26 | the given monitoring target address-space and available set of | |
27 | software/hardware primitives, | |
28 | - Core: Implements core logics including monitoring overhead/accurach control | |
29 | and access-aware system operations on top of the operations set layer, and | |
30 | - Modules: Implements kernel modules for various purposes that provides | |
31 | interfaces for the user space, on top of the core layer. | |
32 | ||
33 | ||
669971b4 SP |
34 | .. _damon_design_configurable_operations_set: |
35 | ||
e168962d SP |
36 | Configurable Operations Set |
37 | --------------------------- | |
c4ba6014 | 38 | |
69e7b88c SP |
39 | For data access monitoring and additional low level work, DAMON needs a set of |
40 | implementations for specific operations that are dependent on and optimized for | |
41 | the given target address space. On the other hand, the accuracy and overhead | |
42 | tradeoff mechanism, which is the core logic of DAMON, is in the pure logic | |
43 | space. DAMON separates the two parts in different layers, namely DAMON | |
44 | Operations Set and DAMON Core Logics Layers, respectively. It further defines | |
45 | the interface between the layers to allow various operations sets to be | |
46 | configured with the core logic. | |
47 | ||
48 | Due to this design, users can extend DAMON for any address space by configuring | |
49 | the core logic to use the appropriate operations set. If any appropriate set | |
50 | is unavailable, users can implement one on their own. | |
c4ba6014 SP |
51 | |
52 | For example, physical memory, virtual memory, swap space, those for specific | |
53 | processes, NUMA nodes, files, and backing memory devices would be supportable. | |
69e7b88c SP |
54 | Also, if some architectures or devices supporting special optimized access |
55 | check primitives, those will be easily configurable. | |
c4ba6014 SP |
56 | |
57 | ||
eaabfa43 SP |
58 | Programmable Modules |
59 | -------------------- | |
60 | ||
61 | Core layer of DAMON is implemented as a framework, and exposes its application | |
62 | programming interface to all kernel space components such as subsystems and | |
63 | modules. For common use cases of DAMON, DAMON subsystem provides kernel | |
64 | modules that built on top of the core layer using the API, which can be easily | |
65 | used by the user space end users. | |
66 | ||
67 | ||
669971b4 SP |
68 | .. _damon_operations_set: |
69 | ||
e168962d SP |
70 | Operations Set Layer |
71 | ==================== | |
c4ba6014 | 72 | |
561f4fc4 | 73 | The monitoring operations are defined in two parts: |
c4ba6014 SP |
74 | |
75 | 1. Identification of the monitoring target address range for the address space. | |
76 | 2. Access check of specific address range in the target space. | |
77 | ||
669971b4 SP |
78 | DAMON currently provides below three operation sets. Below two subsections |
79 | describe how those work. | |
80 | ||
81 | - vaddr: Monitor virtual address spaces of specific processes | |
82 | - fvaddr: Monitor fixed virtual address ranges | |
83 | - paddr: Monitor the physical address space of the system | |
c4ba6014 SP |
84 | |
85 | ||
2d89957c SP |
86 | .. _damon_design_vaddr_target_regions_construction: |
87 | ||
c4ba6014 SP |
88 | VMA-based Target Address Range Construction |
89 | ------------------------------------------- | |
90 | ||
2d89957c SP |
91 | A mechanism of ``vaddr`` DAMON operations set that automatically initializes |
92 | and updates the monitoring target address regions so that entire memory | |
93 | mappings of the target processes can be covered. | |
94 | ||
95 | This mechanism is only for the ``vaddr`` operations set. In cases of | |
96 | ``fvaddr`` and ``paddr`` operation sets, users are asked to manually set the | |
97 | monitoring target address ranges. | |
c6380721 | 98 | |
c4ba6014 SP |
99 | Only small parts in the super-huge virtual address space of the processes are |
100 | mapped to the physical memory and accessed. Thus, tracking the unmapped | |
101 | address regions is just wasteful. However, because DAMON can deal with some | |
102 | level of noise using the adaptive regions adjustment mechanism, tracking every | |
103 | mapping is not strictly required but could even incur a high overhead in some | |
104 | cases. That said, too huge unmapped areas inside the monitoring target should | |
105 | be removed to not take the time for the adaptive mechanism. | |
106 | ||
107 | For the reason, this implementation converts the complex mappings to three | |
108 | distinct regions that cover every mapped area of the address space. The two | |
109 | gaps between the three regions are the two biggest unmapped areas in the given | |
110 | address space. The two biggest unmapped areas would be the gap between the | |
111 | heap and the uppermost mmap()-ed region, and the gap between the lowermost | |
112 | mmap()-ed region and the stack in most of the cases. Because these gaps are | |
113 | exceptionally huge in usual address spaces, excluding these will be sufficient | |
114 | to make a reasonable trade-off. Below shows this in detail:: | |
115 | ||
116 | <heap> | |
117 | <BIG UNMAPPED REGION 1> | |
118 | <uppermost mmap()-ed region> | |
119 | (small mmap()-ed regions and munmap()-ed regions) | |
120 | <lowermost mmap()-ed region> | |
121 | <BIG UNMAPPED REGION 2> | |
122 | <stack> | |
123 | ||
124 | ||
125 | PTE Accessed-bit Based Access Check | |
126 | ----------------------------------- | |
127 | ||
c6380721 SP |
128 | Both of the implementations for physical and virtual address spaces use PTE |
129 | Accessed-bit for basic access checks. Only one difference is the way of | |
130 | finding the relevant PTE Accessed bit(s) from the address. While the | |
131 | implementation for the virtual address walks the page table for the target task | |
132 | of the address, the implementation for the physical address walks every page | |
133 | table having a mapping to the address. In this way, the implementations find | |
134 | and clear the bit(s) for next sampling target address and checks whether the | |
135 | bit(s) set again after one sampling period. This could disturb other kernel | |
136 | subsystems using the Accessed bits, namely Idle page tracking and the reclaim | |
742cc2bf SP |
137 | logic. DAMON does nothing to avoid disturbing Idle page tracking, so handling |
138 | the interference is the responsibility of sysadmins. However, it solves the | |
139 | conflict with the reclaim logic using ``PG_idle`` and ``PG_young`` page flags, | |
140 | as Idle page tracking does. | |
c4ba6014 SP |
141 | |
142 | ||
e168962d SP |
143 | Core Logics |
144 | =========== | |
145 | ||
146 | ||
147 | Monitoring | |
148 | ---------- | |
c4ba6014 SP |
149 | |
150 | Below four sections describe each of the DAMON core mechanisms and the five | |
151 | monitoring attributes, ``sampling interval``, ``aggregation interval``, | |
4c1f287f SP |
152 | ``update interval``, ``minimum number of regions``, and ``maximum number of |
153 | regions``. | |
c4ba6014 SP |
154 | |
155 | ||
156 | Access Frequency Monitoring | |
e168962d | 157 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
c4ba6014 SP |
158 | |
159 | The output of DAMON says what pages are how frequently accessed for a given | |
160 | duration. The resolution of the access frequency is controlled by setting | |
161 | ``sampling interval`` and ``aggregation interval``. In detail, DAMON checks | |
162 | access to each page per ``sampling interval`` and aggregates the results. In | |
163 | other words, counts the number of the accesses to each page. After each | |
164 | ``aggregation interval`` passes, DAMON calls callback functions that previously | |
165 | registered by users so that users can read the aggregated results and then | |
166 | clears the results. This can be described in below simple pseudo-code:: | |
167 | ||
168 | while monitoring_on: | |
169 | for page in monitoring_target: | |
170 | if accessed(page): | |
171 | nr_accesses[page] += 1 | |
172 | if time() % aggregation_interval == 0: | |
173 | for callback in user_registered_callbacks: | |
174 | callback(monitoring_target, nr_accesses) | |
175 | for page in monitoring_target: | |
176 | nr_accesses[page] = 0 | |
177 | sleep(sampling interval) | |
178 | ||
179 | The monitoring overhead of this mechanism will arbitrarily increase as the | |
180 | size of the target workload grows. | |
181 | ||
182 | ||
4f554ca1 SP |
183 | .. _damon_design_region_based_sampling: |
184 | ||
c4ba6014 | 185 | Region Based Sampling |
e168962d | 186 | ~~~~~~~~~~~~~~~~~~~~~ |
c4ba6014 SP |
187 | |
188 | To avoid the unbounded increase of the overhead, DAMON groups adjacent pages | |
189 | that assumed to have the same access frequencies into a region. As long as the | |
190 | assumption (pages in a region have the same access frequencies) is kept, only | |
191 | one page in the region is required to be checked. Thus, for each ``sampling | |
192 | interval``, DAMON randomly picks one page in each region, waits for one | |
193 | ``sampling interval``, checks whether the page is accessed meanwhile, and | |
24df886f SP |
194 | increases the access frequency counter of the region if so. The counter is |
195 | called ``nr_regions`` of the region. Therefore, the monitoring overhead is | |
196 | controllable by setting the number of regions. DAMON allows users to set the | |
197 | minimum and the maximum number of regions for the trade-off. | |
c4ba6014 SP |
198 | |
199 | This scheme, however, cannot preserve the quality of the output if the | |
200 | assumption is not guaranteed. | |
201 | ||
202 | ||
203 | Adaptive Regions Adjustment | |
e168962d | 204 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
c4ba6014 SP |
205 | |
206 | Even somehow the initial monitoring target regions are well constructed to | |
207 | fulfill the assumption (pages in same region have similar access frequencies), | |
208 | the data access pattern can be dynamically changed. This will result in low | |
209 | monitoring quality. To keep the assumption as much as possible, DAMON | |
210 | adaptively merges and splits each region based on their access frequency. | |
211 | ||
212 | For each ``aggregation interval``, it compares the access frequencies of | |
213 | adjacent regions and merges those if the frequency difference is small. Then, | |
214 | after it reports and clears the aggregated access frequency of each region, it | |
215 | splits each region into two or three regions if the total number of regions | |
216 | will not exceed the user-specified maximum number of regions after the split. | |
217 | ||
218 | In this way, DAMON provides its best-effort quality and minimal overhead while | |
219 | keeping the bounds users set for their trade-off. | |
220 | ||
221 | ||
4f554ca1 SP |
222 | .. _damon_design_age_tracking: |
223 | ||
b16b54c9 SP |
224 | Age Tracking |
225 | ~~~~~~~~~~~~ | |
226 | ||
227 | By analyzing the monitoring results, users can also find how long the current | |
228 | access pattern of a region has maintained. That could be used for good | |
229 | understanding of the access pattern. For example, page placement algorithm | |
230 | utilizing both the frequency and the recency could be implemented using that. | |
231 | To make such access pattern maintained period analysis easier, DAMON maintains | |
232 | yet another counter called ``age`` in each region. For each ``aggregation | |
233 | interval``, DAMON checks if the region's size and access frequency | |
234 | (``nr_accesses``) has significantly changed. If so, the counter is reset to | |
235 | zero. Otherwise, the counter is increased. | |
236 | ||
237 | ||
c4ba6014 | 238 | Dynamic Target Space Updates Handling |
e168962d | 239 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
c4ba6014 SP |
240 | |
241 | The monitoring target address range could dynamically changed. For example, | |
242 | virtual memory could be dynamically mapped and unmapped. Physical memory could | |
243 | be hot-plugged. | |
244 | ||
4c1f287f SP |
245 | As the changes could be quite frequent in some cases, DAMON allows the |
246 | monitoring operations to check dynamic changes including memory mapping changes | |
247 | and applies it to monitoring operations-related data structures such as the | |
248 | abstracted monitoring target memory area only for each of a user-specified time | |
249 | interval (``update interval``). | |
2dc4e6a5 SP |
250 | |
251 | ||
01e08737 SP |
252 | .. _damon_design_damos: |
253 | ||
2dc4e6a5 SP |
254 | Operation Schemes |
255 | ----------------- | |
256 | ||
257 | One common purpose of data access monitoring is access-aware system efficiency | |
258 | optimizations. For example, | |
259 | ||
260 | paging out memory regions that are not accessed for more than two minutes | |
261 | ||
262 | or | |
263 | ||
264 | using THP for memory regions that are larger than 2 MiB and showing a high | |
265 | access frequency for more than one minute. | |
266 | ||
267 | One straightforward approach for such schemes would be profile-guided | |
268 | optimizations. That is, getting data access monitoring results of the | |
269 | workloads or the system using DAMON, finding memory regions of special | |
270 | characteristics by profiling the monitoring results, and making system | |
271 | operation changes for the regions. The changes could be made by modifying or | |
272 | providing advice to the software (the application and/or the kernel), or | |
273 | reconfiguring the hardware. Both offline and online approaches could be | |
274 | available. | |
275 | ||
276 | Among those, providing advice to the kernel at runtime would be flexible and | |
277 | effective, and therefore widely be used. However, implementing such schemes | |
278 | could impose unnecessary redundancy and inefficiency. The profiling could be | |
279 | redundant if the type of interest is common. Exchanging the information | |
280 | including monitoring results and operation advice between kernel and user | |
281 | spaces could be inefficient. | |
282 | ||
283 | To allow users to reduce such redundancy and inefficiencies by offloading the | |
284 | works, DAMON provides a feature called Data Access Monitoring-based Operation | |
285 | Schemes (DAMOS). It lets users specify their desired schemes at a high | |
286 | level. For such specifications, DAMON starts monitoring, finds regions having | |
287 | the access pattern of interest, and applies the user-desired operation actions | |
3f8723f1 SP |
288 | to the regions, for every user-specified time interval called |
289 | ``apply_interval``. | |
2dc4e6a5 SP |
290 | |
291 | ||
01e08737 SP |
292 | .. _damon_design_damos_action: |
293 | ||
2dc4e6a5 SP |
294 | Operation Action |
295 | ~~~~~~~~~~~~~~~~ | |
296 | ||
297 | The management action that the users desire to apply to the regions of their | |
298 | interest. For example, paging out, prioritizing for next reclamation victim | |
299 | selection, advising ``khugepaged`` to collapse or split, or doing nothing but | |
300 | collecting statistics of the regions. | |
301 | ||
302 | The list of supported actions is defined in DAMOS, but the implementation of | |
303 | each action is in the DAMON operations set layer because the implementation | |
304 | normally depends on the monitoring target address space. For example, the code | |
305 | for paging specific virtual address ranges out would be different from that for | |
306 | physical address ranges. And the monitoring operations implementation sets are | |
307 | not mandated to support all actions of the list. Hence, the availability of | |
308 | specific DAMOS action depends on what operations set is selected to be used | |
309 | together. | |
310 | ||
5b7708e6 SP |
311 | The list of the supported actions, their meaning, and DAMON operations sets |
312 | that supports each action are as below. | |
313 | ||
314 | - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED``. | |
315 | Supported by ``vaddr`` and ``fvaddr`` operations set. | |
316 | - ``cold``: Call ``madvise()`` for the region with ``MADV_COLD``. | |
317 | Supported by ``vaddr`` and ``fvaddr`` operations set. | |
ff0b5905 | 318 | - ``pageout``: Reclaim the region. |
5b7708e6 SP |
319 | Supported by ``vaddr``, ``fvaddr`` and ``paddr`` operations set. |
320 | - ``hugepage``: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``. | |
321 | Supported by ``vaddr`` and ``fvaddr`` operations set. | |
322 | - ``nohugepage``: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``. | |
323 | Supported by ``vaddr`` and ``fvaddr`` operations set. | |
324 | - ``lru_prio``: Prioritize the region on its LRU lists. | |
325 | Supported by ``paddr`` operations set. | |
326 | - ``lru_deprio``: Deprioritize the region on its LRU lists. | |
327 | Supported by ``paddr`` operations set. | |
328 | - ``stat``: Do nothing but count the statistics. | |
329 | Supported by all operations sets. | |
330 | ||
331 | Applying the actions except ``stat`` to a region is considered as changing the | |
332 | region's characteristics. Hence, DAMOS resets the age of regions when any such | |
333 | actions are applied to those. | |
2dc4e6a5 SP |
334 | |
335 | ||
01e08737 SP |
336 | .. _damon_design_damos_access_pattern: |
337 | ||
2dc4e6a5 SP |
338 | Target Access Pattern |
339 | ~~~~~~~~~~~~~~~~~~~~~ | |
340 | ||
341 | The access pattern of the schemes' interest. The patterns are constructed with | |
342 | the properties that DAMON's monitoring results provide, specifically the size, | |
343 | the access frequency, and the age. Users can describe their access pattern of | |
344 | interest by setting minimum and maximum values of the three properties. If a | |
345 | region's three properties are in the ranges, DAMOS classifies it as one of the | |
346 | regions that the scheme is having an interest in. | |
b1388786 SP |
347 | |
348 | ||
01e08737 SP |
349 | .. _damon_design_damos_quotas: |
350 | ||
b1388786 SP |
351 | Quotas |
352 | ~~~~~~ | |
353 | ||
354 | DAMOS upper-bound overhead control feature. DAMOS could incur high overhead if | |
355 | the target access pattern is not properly tuned. For example, if a huge memory | |
356 | region having the access pattern of interest is found, applying the scheme's | |
357 | action to all pages of the huge region could consume unacceptably large system | |
358 | resources. Preventing such issues by tuning the access pattern could be | |
359 | challenging, especially if the access patterns of the workloads are highly | |
360 | dynamic. | |
361 | ||
362 | To mitigate that situation, DAMOS provides an upper-bound overhead control | |
363 | feature called quotas. It lets users specify an upper limit of time that DAMOS | |
364 | can use for applying the action, and/or a maximum bytes of memory regions that | |
365 | the action can be applied within a user-specified time duration. | |
366 | ||
367 | ||
01e08737 SP |
368 | .. _damon_design_damos_quotas_prioritization: |
369 | ||
b1388786 SP |
370 | Prioritization |
371 | ^^^^^^^^^^^^^^ | |
372 | ||
373 | A mechanism for making a good decision under the quotas. When the action | |
374 | cannot be applied to all regions of interest due to the quotas, DAMOS | |
375 | prioritizes regions and applies the action to only regions having high enough | |
376 | priorities so that it will not exceed the quotas. | |
377 | ||
378 | The prioritization mechanism should be different for each action. For example, | |
379 | rarely accessed (colder) memory regions would be prioritized for page-out | |
380 | scheme action. In contrast, the colder regions would be deprioritized for huge | |
381 | page collapse scheme action. Hence, the prioritization mechanisms for each | |
382 | action are implemented in each DAMON operations set, together with the actions. | |
383 | ||
384 | Though the implementation is up to the DAMON operations set, it would be common | |
385 | to calculate the priority using the access pattern properties of the regions. | |
386 | Some users would want the mechanisms to be personalized for their specific | |
387 | case. For example, some users would want the mechanism to weigh the recency | |
388 | (``age``) more than the access frequency (``nr_accesses``). DAMOS allows users | |
389 | to specify the weight of each access pattern property and passes the | |
390 | information to the underlying mechanism. Nevertheless, how and even whether | |
391 | the weight will be respected are up to the underlying prioritization mechanism | |
392 | implementation. | |
393 | ||
394 | ||
6140edee SP |
395 | .. _damon_design_damos_quotas_auto_tuning: |
396 | ||
3143a7bf SP |
397 | Aim-oriented Feedback-driven Auto-tuning |
398 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
399 | ||
400 | Automatic feedback-driven quota tuning. Instead of setting the absolute quota | |
3c17174f SP |
401 | value, users can specify the metric of their interest, and what target value |
402 | they want the metric value to be. DAMOS then automatically tunes the | |
3143a7bf SP |
403 | aggressiveness (the quota) of the corresponding scheme. For example, if DAMOS |
404 | is under achieving the goal, DAMOS automatically increases the quota. If DAMOS | |
405 | is over achieving the goal, it decreases the quota. | |
406 | ||
3c17174f SP |
407 | The goal can be specified with three parameters, namely ``target_metric``, |
408 | ``target_value``, and ``current_value``. The auto-tuning mechanism tries to | |
409 | make ``current_value`` of ``target_metric`` be same to ``target_value``. | |
410 | Currently, two ``target_metric`` are provided. | |
411 | ||
412 | - ``user_input``: User-provided value. Users could use any metric that they | |
413 | has interest in for the value. Use space main workload's latency or | |
414 | throughput, system metrics like free memory ratio or memory pressure stall | |
415 | time (PSI) could be examples. Note that users should explicitly set | |
416 | ``current_value`` on their own in this case. In other words, users should | |
417 | repeatedly provide the feedback. | |
418 | - ``some_mem_psi_us``: System-wide ``some`` memory pressure stall information | |
419 | in microseconds that measured from last quota reset to next quota reset. | |
420 | DAMOS does the measurement on its own, so only ``target_value`` need to be | |
421 | set by users at the initial time. In other words, DAMOS does self-feedback. | |
422 | ||
3143a7bf | 423 | |
01e08737 SP |
424 | .. _damon_design_damos_watermarks: |
425 | ||
b1388786 SP |
426 | Watermarks |
427 | ~~~~~~~~~~ | |
428 | ||
429 | Conditional DAMOS (de)activation automation. Users might want DAMOS to run | |
430 | only under certain situations. For example, when a sufficient amount of free | |
431 | memory is guaranteed, running a scheme for proactive reclamation would only | |
432 | consume unnecessary system resources. To avoid such consumption, the user would | |
433 | need to manually monitor some metrics such as free memory ratio, and turn | |
434 | DAMON/DAMOS on or off. | |
435 | ||
436 | DAMOS allows users to offload such works using three watermarks. It allows the | |
437 | users to configure the metric of their interest, and three watermark values, | |
438 | namely high, middle, and low. If the value of the metric becomes above the | |
439 | high watermark or below the low watermark, the scheme is deactivated. If the | |
440 | metric becomes below the mid watermark but above the low watermark, the scheme | |
441 | is activated. If all schemes are deactivated by the watermarks, the monitoring | |
442 | is also deactivated. In this case, the DAMON worker thread only periodically | |
443 | checks the watermarks and therefore incurs nearly zero overhead. | |
444 | ||
445 | ||
01e08737 SP |
446 | .. _damon_design_damos_filters: |
447 | ||
b1388786 SP |
448 | Filters |
449 | ~~~~~~~ | |
450 | ||
451 | Non-access pattern-based target memory regions filtering. If users run | |
452 | self-written programs or have good profiling tools, they could know something | |
453 | more than the kernel, such as future access patterns or some special | |
454 | requirements for specific types of memory. For example, some users may know | |
455 | only anonymous pages can impact their program's performance. They can also | |
456 | have a list of latency-critical processes. | |
457 | ||
458 | To let users optimize DAMOS schemes with such special knowledge, DAMOS provides | |
459 | a feature called DAMOS filters. The feature allows users to set an arbitrary | |
460 | number of filters for each scheme. Each filter specifies the type of target | |
461 | memory, and whether it should exclude the memory of the type (filter-out), or | |
462 | all except the memory of the type (filter-in). | |
463 | ||
2f02fbba SP |
464 | For efficient handling of filters, some types of filters are handled by the |
465 | core layer, while others are handled by operations set. In the latter case, | |
466 | hence, support of the filter types depends on the DAMON operations set. In | |
467 | case of the core layer-handled filters, the memory regions that excluded by the | |
468 | filter are not counted as the scheme has tried to the region. In contrast, if | |
469 | a memory regions is filtered by an operations set layer-handled filter, it is | |
470 | counted as the scheme has tried. This difference affects the statistics. | |
471 | ||
472 | Below types of filters are currently supported. | |
473 | ||
474 | - anonymous page | |
475 | - Applied to pages that containing data that not stored in files. | |
476 | - Handled by operations set layer. Supported by only ``paddr`` set. | |
477 | - memory cgroup | |
478 | - Applied to pages that belonging to a given cgroup. | |
479 | - Handled by operations set layer. Supported by only ``paddr`` set. | |
480 | - young page | |
481 | - Applied to pages that are accessed after the last access check from the | |
482 | scheme. | |
483 | - Handled by operations set layer. Supported by only ``paddr`` set. | |
484 | - address range | |
485 | - Applied to pages that belonging to a given address range. | |
486 | - Handled by the core logic. | |
487 | - DAMON monitoring target | |
488 | - Applied to pages that belonging to a given DAMON monitoring target. | |
489 | - Handled by the core logic. | |
f508a0fb SP |
490 | |
491 | ||
492 | Application Programming Interface | |
493 | --------------------------------- | |
494 | ||
495 | The programming interface for kernel space data access-aware applications. | |
496 | DAMON is a framework, so it does nothing by itself. Instead, it only helps | |
497 | other kernel components such as subsystems and modules building their data | |
498 | access-aware applications using DAMON's core features. For this, DAMON exposes | |
499 | its all features to other kernel components via its application programming | |
500 | interface, namely ``include/linux/damon.h``. Please refer to the API | |
501 | :doc:`document </mm/damon/api>` for details of the interface. | |
da969810 SP |
502 | |
503 | ||
504 | Modules | |
505 | ======= | |
506 | ||
507 | Because the core of DAMON is a framework for kernel components, it doesn't | |
508 | provide any direct interface for the user space. Such interfaces should be | |
509 | implemented by each DAMON API user kernel components, instead. DAMON subsystem | |
510 | itself implements such DAMON API user modules, which are supposed to be used | |
511 | for general purpose DAMON control and special purpose data access-aware system | |
512 | operations, and provides stable application binary interfaces (ABI) for the | |
513 | user space. The user space can build their efficient data access-aware | |
514 | applications using the interfaces. | |
515 | ||
516 | ||
517 | General Purpose User Interface Modules | |
518 | -------------------------------------- | |
519 | ||
520 | DAMON modules that provide user space ABIs for general purpose DAMON usage in | |
521 | runtime. | |
522 | ||
523 | DAMON user interface modules, namely 'DAMON sysfs interface' and 'DAMON debugfs | |
524 | interface' are DAMON API user kernel modules that provide ABIs to the | |
525 | user-space. Please note that DAMON debugfs interface is currently deprecated. | |
526 | ||
527 | Like many other ABIs, the modules create files on sysfs and debugfs, allow | |
528 | users to specify their requests to and get the answers from DAMON by writing to | |
529 | and reading from the files. As a response to such I/O, DAMON user interface | |
530 | modules control DAMON and retrieve the results as user requested via the DAMON | |
531 | API, and return the results to the user-space. | |
532 | ||
533 | The ABIs are designed to be used for user space applications development, | |
534 | rather than human beings' fingers. Human users are recommended to use such | |
535 | user space tools. One such Python-written user space tool is available at | |
536 | Github (https://github.com/awslabs/damo), Pypi | |
537 | (https://pypistats.org/packages/damo), and Fedora | |
538 | (https://packages.fedoraproject.org/pkgs/python-damo/damo/). | |
539 | ||
540 | Please refer to the ABI :doc:`document </admin-guide/mm/damon/usage>` for | |
541 | details of the interfaces. | |
542 | ||
543 | ||
544 | Special-Purpose Access-aware Kernel Modules | |
545 | ------------------------------------------- | |
546 | ||
547 | DAMON modules that provide user space ABI for specific purpose DAMON usage. | |
548 | ||
549 | DAMON sysfs/debugfs user interfaces are for full control of all DAMON features | |
550 | in runtime. For each special-purpose system-wide data access-aware system | |
551 | operations such as proactive reclamation or LRU lists balancing, the interfaces | |
552 | could be simplified by removing unnecessary knobs for the specific purpose, and | |
553 | extended for boot-time and even compile time control. Default values of DAMON | |
554 | control parameters for the usage would also need to be optimized for the | |
555 | purpose. | |
556 | ||
557 | To support such cases, yet more DAMON API user kernel modules that provide more | |
558 | simple and optimized user space interfaces are available. Currently, two | |
559 | modules for proactive reclamation and LRU lists manipulation are provided. For | |
560 | more detail, please read the usage documents for those | |
561 | (:doc:`/admin-guide/mm/damon/reclaim` and | |
562 | :doc:`/admin-guide/mm/damon/lru_sort`). |