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