xref: /openbmc/linux/Documentation/ABI/testing/sysfs-kernel-mm-damon (revision c900529f3d9161bfde5cca0754f83b4d3c3e0220)
1 what:		/sys/kernel/mm/damon/
2 Date:		Mar 2022
3 Contact:	SeongJae Park <sj@kernel.org>
4 Description:	Interface for Data Access MONitoring (DAMON).  Contains files
5 		for controlling DAMON.  For more details on DAMON itself,
6 		please refer to Documentation/admin-guide/mm/damon/index.rst.
7 
8 What:		/sys/kernel/mm/damon/admin/
9 Date:		Mar 2022
10 Contact:	SeongJae Park <sj@kernel.org>
11 Description:	Interface for privileged users of DAMON.  Contains files for
12 		controlling DAMON that aimed to be used by privileged users.
13 
14 What:		/sys/kernel/mm/damon/admin/kdamonds/nr_kdamonds
15 Date:		Mar 2022
16 Contact:	SeongJae Park <sj@kernel.org>
17 Description:	Writing a number 'N' to this file creates the number of
18 		directories for controlling each DAMON worker thread (kdamond)
19 		named '0' to 'N-1' under the kdamonds/ directory.
20 
21 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/state
22 Date:		Mar 2022
23 Contact:	SeongJae Park <sj@kernel.org>
24 Description:	Writing 'on' or 'off' to this file makes the kdamond starts or
25 		stops, respectively.  Reading the file returns the keywords
26 		based on the current status.  Writing 'commit' to this file
27 		makes the kdamond reads the user inputs in the sysfs files
28 		except 'state' again.  Writing 'update_schemes_stats' to the
29 		file updates contents of schemes stats files of the kdamond.
30 		Writing 'update_schemes_tried_regions' to the file updates
31 		contents of 'tried_regions' directory of every scheme directory
32 		of this kdamond.  Writing 'update_schemes_tried_bytes' to the
33 		file updates only '.../tried_regions/total_bytes' files of this
34 		kdamond.  Writing 'clear_schemes_tried_regions' to the file
35 		removes contents of the 'tried_regions' directory.
36 
37 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/pid
38 Date:		Mar 2022
39 Contact:	SeongJae Park <sj@kernel.org>
40 Description:	Reading this file returns the pid of the kdamond if it is
41 		running.
42 
43 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/nr_contexts
44 Date:		Mar 2022
45 Contact:	SeongJae Park <sj@kernel.org>
46 Description:	Writing a number 'N' to this file creates the number of
47 		directories for controlling each DAMON context named '0' to
48 		'N-1' under the contexts/ directory.
49 
50 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/avail_operations
51 Date:		Apr 2022
52 Contact:	SeongJae Park <sj@kernel.org>
53 Description:	Reading this file returns the available monitoring operations
54 		sets on the currently running kernel.
55 
56 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/operations
57 Date:		Mar 2022
58 Contact:	SeongJae Park <sj@kernel.org>
59 Description:	Writing a keyword for a monitoring operations set ('vaddr' for
60 		virtual address spaces monitoring, 'fvaddr' for fixed virtual
61 		address ranges monitoring, and 'paddr' for the physical address
62 		space monitoring) to this file makes the context to use the
63 		operations set.  Reading the file returns the keyword for the
64 		operations set the context is set to use.
65 
66 		Note that only the operations sets that listed in
67 		'avail_operations' file are valid inputs.
68 
69 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/sample_us
70 Date:		Mar 2022
71 Contact:	SeongJae Park <sj@kernel.org>
72 Description:	Writing a value to this file sets the sampling interval of the
73 		DAMON context in microseconds as the value.  Reading this file
74 		returns the value.
75 
76 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/aggr_us
77 Date:		Mar 2022
78 Contact:	SeongJae Park <sj@kernel.org>
79 Description:	Writing a value to this file sets the aggregation interval of
80 		the DAMON context in microseconds as the value.  Reading this
81 		file returns the value.
82 
83 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/update_us
84 Date:		Mar 2022
85 Contact:	SeongJae Park <sj@kernel.org>
86 Description:	Writing a value to this file sets the update interval of the
87 		DAMON context in microseconds as the value.  Reading this file
88 		returns the value.
89 
90 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/min
91 
92 WDate:		Mar 2022
93 Contact:	SeongJae Park <sj@kernel.org>
94 Description:	Writing a value to this file sets the minimum number of
95 		monitoring regions of the DAMON context as the value.  Reading
96 		this file returns the value.
97 
98 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/max
99 Date:		Mar 2022
100 Contact:	SeongJae Park <sj@kernel.org>
101 Description:	Writing a value to this file sets the maximum number of
102 		monitoring regions of the DAMON context as the value.  Reading
103 		this file returns the value.
104 
105 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/nr_targets
106 Date:		Mar 2022
107 Contact:	SeongJae Park <sj@kernel.org>
108 Description:	Writing a number 'N' to this file creates the number of
109 		directories for controlling each DAMON target of the context
110 		named '0' to 'N-1' under the contexts/ directory.
111 
112 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/pid_target
113 Date:		Mar 2022
114 Contact:	SeongJae Park <sj@kernel.org>
115 Description:	Writing to and reading from this file sets and gets the pid of
116 		the target process if the context is for virtual address spaces
117 		monitoring, respectively.
118 
119 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/nr_regions
120 Date:		Mar 2022
121 Contact:	SeongJae Park <sj@kernel.org>
122 Description:	Writing a number 'N' to this file creates the number of
123 		directories for setting each DAMON target memory region of the
124 		context named '0' to 'N-1' under the regions/ directory.  In
125 		case of the virtual address space monitoring, DAMON
126 		automatically sets the target memory region based on the target
127 		processes' mappings.
128 
129 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/start
130 Date:		Mar 2022
131 Contact:	SeongJae Park <sj@kernel.org>
132 Description:	Writing to and reading from this file sets and gets the start
133 		address of the monitoring region.
134 
135 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/end
136 Date:		Mar 2022
137 Contact:	SeongJae Park <sj@kernel.org>
138 Description:	Writing to and reading from this file sets and gets the end
139 		address of the monitoring region.
140 
141 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/nr_schemes
142 Date:		Mar 2022
143 Contact:	SeongJae Park <sj@kernel.org>
144 Description:	Writing a number 'N' to this file creates the number of
145 		directories for controlling each DAMON-based operation scheme
146 		of the context named '0' to 'N-1' under the schemes/ directory.
147 
148 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/action
149 Date:		Mar 2022
150 Contact:	SeongJae Park <sj@kernel.org>
151 Description:	Writing to and reading from this file sets and gets the action
152 		of the scheme.
153 
154 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/min
155 Date:		Mar 2022
156 Contact:	SeongJae Park <sj@kernel.org>
157 Description:	Writing to and reading from this file sets and gets the minimum
158 		size of the scheme's target regions in bytes.
159 
160 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/max
161 Date:		Mar 2022
162 Contact:	SeongJae Park <sj@kernel.org>
163 Description:	Writing to and reading from this file sets and gets the maximum
164 		size of the scheme's target regions in bytes.
165 
166 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/min
167 Date:		Mar 2022
168 Contact:	SeongJae Park <sj@kernel.org>
169 Description:	Writing to and reading from this file sets and gets the manimum
170 		'nr_accesses' of the scheme's target regions.
171 
172 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/max
173 Date:		Mar 2022
174 Contact:	SeongJae Park <sj@kernel.org>
175 Description:	Writing to and reading from this file sets and gets the maximum
176 		'nr_accesses' of the scheme's target regions.
177 
178 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/min
179 Date:		Mar 2022
180 Contact:	SeongJae Park <sj@kernel.org>
181 Description:	Writing to and reading from this file sets and gets the minimum
182 		'age' of the scheme's target regions.
183 
184 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/max
185 Date:		Mar 2022
186 Contact:	SeongJae Park <sj@kernel.org>
187 Description:	Writing to and reading from this file sets and gets the maximum
188 		'age' of the scheme's target regions.
189 
190 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/ms
191 Date:		Mar 2022
192 Contact:	SeongJae Park <sj@kernel.org>
193 Description:	Writing to and reading from this file sets and gets the time
194 		quota of the scheme in milliseconds.
195 
196 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/bytes
197 Date:		Mar 2022
198 Contact:	SeongJae Park <sj@kernel.org>
199 Description:	Writing to and reading from this file sets and gets the size
200 		quota of the scheme in bytes.
201 
202 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/reset_interval_ms
203 Date:		Mar 2022
204 Contact:	SeongJae Park <sj@kernel.org>
205 Description:	Writing to and reading from this file sets and gets the quotas
206 		charge reset interval of the scheme in milliseconds.
207 
208 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/sz_permil
209 Date:		Mar 2022
210 Contact:	SeongJae Park <sj@kernel.org>
211 Description:	Writing to and reading from this file sets and gets the
212 		under-quota limit regions prioritization weight for 'size' in
213 		permil.
214 
215 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/nr_accesses_permil
216 Date:		Mar 2022
217 Contact:	SeongJae Park <sj@kernel.org>
218 Description:	Writing to and reading from this file sets and gets the
219 		under-quota limit regions prioritization weight for
220 		'nr_accesses' in permil.
221 
222 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/age_permil
223 Date:		Mar 2022
224 Contact:	SeongJae Park <sj@kernel.org>
225 Description:	Writing to and reading from this file sets and gets the
226 		under-quota limit regions prioritization weight for 'age' in
227 		permil.
228 
229 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/metric
230 Date:		Mar 2022
231 Contact:	SeongJae Park <sj@kernel.org>
232 Description:	Writing to and reading from this file sets and gets the metric
233 		of the watermarks for the scheme.  The writable/readable
234 		keywords for this file are 'none' for disabling the watermarks
235 		feature, or 'free_mem_rate' for the system's global free memory
236 		rate in permil.
237 
238 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/interval_us
239 Date:		Mar 2022
240 Contact:	SeongJae Park <sj@kernel.org>
241 Description:	Writing to and reading from this file sets and gets the metric
242 		check interval of the watermarks for the scheme in
243 		microseconds.
244 
245 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/high
246 Date:		Mar 2022
247 Contact:	SeongJae Park <sj@kernel.org>
248 Description:	Writing to and reading from this file sets and gets the high
249 		watermark of the scheme in permil.
250 
251 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/mid
252 Date:		Mar 2022
253 Contact:	SeongJae Park <sj@kernel.org>
254 Description:	Writing to and reading from this file sets and gets the mid
255 		watermark of the scheme in permil.
256 
257 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/low
258 Date:		Mar 2022
259 Contact:	SeongJae Park <sj@kernel.org>
260 Description:	Writing to and reading from this file sets and gets the low
261 		watermark of the scheme in permil.
262 
263 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/nr_filters
264 Date:		Dec 2022
265 Contact:	SeongJae Park <sj@kernel.org>
266 Description:	Writing a number 'N' to this file creates the number of
267 		directories for setting filters of the scheme named '0' to
268 		'N-1' under the filters/ directory.
269 
270 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/type
271 Date:		Dec 2022
272 Contact:	SeongJae Park <sj@kernel.org>
273 Description:	Writing to and reading from this file sets and gets the type of
274 		the memory of the interest.  'anon' for anonymous pages,
275 		'memcg' for specific memory cgroup, 'addr' for address range
276 		(an open-ended interval), or 'target' for DAMON monitoring
277 		target can be written and read.
278 
279 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/memcg_path
280 Date:		Dec 2022
281 Contact:	SeongJae Park <sj@kernel.org>
282 Description:	If 'memcg' is written to the 'type' file, writing to and
283 		reading from this file sets and gets the path to the memory
284 		cgroup of the interest.
285 
286 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_start
287 Date:		Jul 2023
288 Contact:	SeongJae Park <sj@kernel.org>
289 Description:	If 'addr' is written to the 'type' file, writing to or reading
290 		from this file sets or gets the start address of the address
291 		range for the filter.
292 
293 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_end
294 Date:		Jul 2023
295 Contact:	SeongJae Park <sj@kernel.org>
296 Description:	If 'addr' is written to the 'type' file, writing to or reading
297 		from this file sets or gets the end address of the address
298 		range for the filter.
299 
300 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/target_idx
301 Date:		Dec 2022
302 Contact:	SeongJae Park <sj@kernel.org>
303 Description:	If 'target' is written to the 'type' file, writing to or
304 		reading from this file sets or gets the index of the DAMON
305 		monitoring target of the interest.
306 
307 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/matching
308 Date:		Dec 2022
309 Contact:	SeongJae Park <sj@kernel.org>
310 Description:	Writing 'Y' or 'N' to this file sets whether to filter out
311 		pages that do or do not match to the 'type' and 'memcg_path',
312 		respectively.  Filter out means the action of the scheme will
313 		not be applied to.
314 
315 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_tried
316 Date:		Mar 2022
317 Contact:	SeongJae Park <sj@kernel.org>
318 Description:	Reading this file returns the number of regions that the action
319 		of the scheme has tried to be applied.
320 
321 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_tried
322 Date:		Mar 2022
323 Contact:	SeongJae Park <sj@kernel.org>
324 Description:	Reading this file returns the total size of regions that the
325 		action of the scheme has tried to be applied in bytes.
326 
327 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_applied
328 Date:		Mar 2022
329 Contact:	SeongJae Park <sj@kernel.org>
330 Description:	Reading this file returns the number of regions that the action
331 		of the scheme has successfully applied.
332 
333 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_applied
334 Date:		Mar 2022
335 Contact:	SeongJae Park <sj@kernel.org>
336 Description:	Reading this file returns the total size of regions that the
337 		action of the scheme has successfully applied in bytes.
338 
339 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/qt_exceeds
340 Date:		Mar 2022
341 Contact:	SeongJae Park <sj@kernel.org>
342 Description:	Reading this file returns the number of the exceed events of
343 		the scheme's quotas.
344 
345 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/total_bytes
346 Date:		Jul 2023
347 Contact:	SeongJae Park <sj@kernel.org>
348 Description:	Reading this file returns the total amount of memory that
349 		corresponding DAMON-based Operation Scheme's action has tried
350 		to be applied.
351 
352 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/start
353 Date:		Oct 2022
354 Contact:	SeongJae Park <sj@kernel.org>
355 Description:	Reading this file returns the start address of a memory region
356 		that corresponding DAMON-based Operation Scheme's action has
357 		tried to be applied.
358 
359 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/end
360 Date:		Oct 2022
361 Contact:	SeongJae Park <sj@kernel.org>
362 Description:	Reading this file returns the end address of a memory region
363 		that corresponding DAMON-based Operation Scheme's action has
364 		tried to be applied.
365 
366 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/nr_accesses
367 Date:		Oct 2022
368 Contact:	SeongJae Park <sj@kernel.org>
369 Description:	Reading this file returns the 'nr_accesses' of a memory region
370 		that corresponding DAMON-based Operation Scheme's action has
371 		tried to be applied.
372 
373 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/age
374 Date:		Oct 2022
375 Contact:	SeongJae Park <sj@kernel.org>
376 Description:	Reading this file returns the 'age' of a memory region that
377 		corresponding DAMON-based Operation Scheme's action has tried
378 		to be applied.
379