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>/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.