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