Documentation/ABI/testing/sysfs-kernel-mm-damon

   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>/apply_interval_us
 155 Date:           Sep 2023
 156 Contact:        SeongJae Park <sj@kernel.org>
 157 Description:    Writing a value to this file sets the action apply interval of
 158                 the scheme in microseconds.  Reading this file returns the
 159                 value.
 160
 161 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/min
 162 Date:           Mar 2022
 163 Contact:        SeongJae Park <sj@kernel.org>
 164 Description:    Writing to and reading from this file sets and gets the minimum
 165                 size of the scheme's target regions in bytes.
 166
 167 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/max
 168 Date:           Mar 2022
 169 Contact:        SeongJae Park <sj@kernel.org>
 170 Description:    Writing to and reading from this file sets and gets the maximum
 171                 size of the scheme's target regions in bytes.
 172
 173 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/min
 174 Date:           Mar 2022
 175 Contact:        SeongJae Park <sj@kernel.org>
 176 Description:    Writing to and reading from this file sets and gets the manimum
 177                 'nr_accesses' of the scheme's target regions.
 178
 179 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/max
 180 Date:           Mar 2022
 181 Contact:        SeongJae Park <sj@kernel.org>
 182 Description:    Writing to and reading from this file sets and gets the maximum
 183                 'nr_accesses' of the scheme's target regions.
 184
 185 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/min
 186 Date:           Mar 2022
 187 Contact:        SeongJae Park <sj@kernel.org>
 188 Description:    Writing to and reading from this file sets and gets the minimum
 189                 'age' of the scheme's target regions.
 190
 191 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/max
 192 Date:           Mar 2022
 193 Contact:        SeongJae Park <sj@kernel.org>
 194 Description:    Writing to and reading from this file sets and gets the maximum
 195                 'age' of the scheme's target regions.
 196
 197 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/ms
 198 Date:           Mar 2022
 199 Contact:        SeongJae Park <sj@kernel.org>
 200 Description:    Writing to and reading from this file sets and gets the time
 201                 quota of the scheme in milliseconds.
 202
 203 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/bytes
 204 Date:           Mar 2022
 205 Contact:        SeongJae Park <sj@kernel.org>
 206 Description:    Writing to and reading from this file sets and gets the size
 207                 quota of the scheme in bytes.
 208
 209 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/reset_interval_ms
 210 Date:           Mar 2022
 211 Contact:        SeongJae Park <sj@kernel.org>
 212 Description:    Writing to and reading from this file sets and gets the quotas
 213                 charge reset interval of the scheme in milliseconds.
 214
 215 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/sz_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 'size' in
 220                 permil.
 221
 222 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/nr_accesses_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
 227                 'nr_accesses' in permil.
 228
 229 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/age_permil
 230 Date:           Mar 2022
 231 Contact:        SeongJae Park <sj@kernel.org>
 232 Description:    Writing to and reading from this file sets and gets the
 233                 under-quota limit regions prioritization weight for 'age' in
 234                 permil.
 235
 236 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/metric
 237 Date:           Mar 2022
 238 Contact:        SeongJae Park <sj@kernel.org>
 239 Description:    Writing to and reading from this file sets and gets the metric
 240                 of the watermarks for the scheme.  The writable/readable
 241                 keywords for this file are 'none' for disabling the watermarks
 242                 feature, or 'free_mem_rate' for the system's global free memory
 243                 rate in permil.
 244
 245 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/interval_us
 246 Date:           Mar 2022
 247 Contact:        SeongJae Park <sj@kernel.org>
 248 Description:    Writing to and reading from this file sets and gets the metric
 249                 check interval of the watermarks for the scheme in
 250                 microseconds.
 251
 252 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/high
 253 Date:           Mar 2022
 254 Contact:        SeongJae Park <sj@kernel.org>
 255 Description:    Writing to and reading from this file sets and gets the high
 256                 watermark of the scheme in permil.
 257
 258 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/mid
 259 Date:           Mar 2022
 260 Contact:        SeongJae Park <sj@kernel.org>
 261 Description:    Writing to and reading from this file sets and gets the mid
 262                 watermark of the scheme in permil.
 263
 264 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/low
 265 Date:           Mar 2022
 266 Contact:        SeongJae Park <sj@kernel.org>
 267 Description:    Writing to and reading from this file sets and gets the low
 268                 watermark of the scheme in permil.
 269
 270 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/nr_filters
 271 Date:           Dec 2022
 272 Contact:        SeongJae Park <sj@kernel.org>
 273 Description:    Writing a number 'N' to this file creates the number of
 274                 directories for setting filters of the scheme named '0' to
 275                 'N-1' under the filters/ directory.
 276
 277 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/type
 278 Date:           Dec 2022
 279 Contact:        SeongJae Park <sj@kernel.org>
 280 Description:    Writing to and reading from this file sets and gets the type of
 281                 the memory of the interest.  'anon' for anonymous pages,
 282                 'memcg' for specific memory cgroup, 'addr' for address range
 283                 (an open-ended interval), or 'target' for DAMON monitoring
 284                 target can be written and read.
 285
 286 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/memcg_path
 287 Date:           Dec 2022
 288 Contact:        SeongJae Park <sj@kernel.org>
 289 Description:    If 'memcg' is written to the 'type' file, writing to and
 290                 reading from this file sets and gets the path to the memory
 291                 cgroup of the interest.
 292
 293 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_start
 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 start 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>/addr_end
 301 Date:           Jul 2023
 302 Contact:        SeongJae Park <sj@kernel.org>
 303 Description:    If 'addr' is written to the 'type' file, writing to or reading
 304                 from this file sets or gets the end address of the address
 305                 range for the filter.
 306
 307 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/target_idx
 308 Date:           Dec 2022
 309 Contact:        SeongJae Park <sj@kernel.org>
 310 Description:    If 'target' is written to the 'type' file, writing to or
 311                 reading from this file sets or gets the index of the DAMON
 312                 monitoring target of the interest.
 313
 314 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/matching
 315 Date:           Dec 2022
 316 Contact:        SeongJae Park <sj@kernel.org>
 317 Description:    Writing 'Y' or 'N' to this file sets whether to filter out
 318                 pages that do or do not match to the 'type' and 'memcg_path',
 319                 respectively.  Filter out means the action of the scheme will
 320                 not be applied to.
 321
 322 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_tried
 323 Date:           Mar 2022
 324 Contact:        SeongJae Park <sj@kernel.org>
 325 Description:    Reading this file returns the number of regions that the action
 326                 of the scheme has tried to be applied.
 327
 328 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_tried
 329 Date:           Mar 2022
 330 Contact:        SeongJae Park <sj@kernel.org>
 331 Description:    Reading this file returns the total size of regions that the
 332                 action of the scheme has tried to be applied in bytes.
 333
 334 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_applied
 335 Date:           Mar 2022
 336 Contact:        SeongJae Park <sj@kernel.org>
 337 Description:    Reading this file returns the number of regions that the action
 338                 of the scheme has successfully applied.
 339
 340 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_applied
 341 Date:           Mar 2022
 342 Contact:        SeongJae Park <sj@kernel.org>
 343 Description:    Reading this file returns the total size of regions that the
 344                 action of the scheme has successfully applied in bytes.
 345
 346 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/qt_exceeds
 347 Date:           Mar 2022
 348 Contact:        SeongJae Park <sj@kernel.org>
 349 Description:    Reading this file returns the number of the exceed events of
 350                 the scheme's quotas.
 351
 352 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/total_bytes
 353 Date:           Jul 2023
 354 Contact:        SeongJae Park <sj@kernel.org>
 355 Description:    Reading this file returns the total amount of memory that
 356                 corresponding DAMON-based Operation Scheme's action has tried
 357                 to be applied.
 358
 359 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/start
 360 Date:           Oct 2022
 361 Contact:        SeongJae Park <sj@kernel.org>
 362 Description:    Reading this file returns the start 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>/end
 367 Date:           Oct 2022
 368 Contact:        SeongJae Park <sj@kernel.org>
 369 Description:    Reading this file returns the end address 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>/nr_accesses
 374 Date:           Oct 2022
 375 Contact:        SeongJae Park <sj@kernel.org>
 376 Description:    Reading this file returns the 'nr_accesses' of a memory region
 377                 that corresponding DAMON-based Operation Scheme's action has
 378                 tried to be applied.
 379
 380 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/tried_regions/<R>/age
 381 Date:           Oct 2022
 382 Contact:        SeongJae Park <sj@kernel.org>
 383 Description:    Reading this file returns the 'age' of a memory region that
 384                 corresponding DAMON-based Operation Scheme's action has tried
 385                 to be applied.