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
  31 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/pid
  32 Date:           Mar 2022
  33 Contact:        SeongJae Park <sj@kernel.org>
  34 Description:    Reading this file returns the pid of the kdamond if it is
  35                 running.
  36
  37 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/nr_contexts
  38 Date:           Mar 2022
  39 Contact:        SeongJae Park <sj@kernel.org>
  40 Description:    Writing a number 'N' to this file creates the number of
  41                 directories for controlling each DAMON context named '0' to
  42                 'N-1' under the contexts/ directory.
  43
  44 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/avail_operations
  45 Date:           Apr 2022
  46 Contact:        SeongJae Park <sj@kernel.org>
  47 Description:    Reading this file returns the available monitoring operations
  48                 sets on the currently running kernel.
  49
  50 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/operations
  51 Date:           Mar 2022
  52 Contact:        SeongJae Park <sj@kernel.org>
  53 Description:    Writing a keyword for a monitoring operations set ('vaddr' for
  54                 virtual address spaces monitoring, 'fvaddr' for fixed virtual
  55                 address ranges monitoring, and 'paddr' for the physical address
  56                 space monitoring) to this file makes the context to use the
  57                 operations set.  Reading the file returns the keyword for the
  58                 operations set the context is set to use.
  59
  60                 Note that only the operations sets that listed in
  61                 'avail_operations' file are valid inputs.
  62
  63 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/sample_us
  64 Date:           Mar 2022
  65 Contact:        SeongJae Park <sj@kernel.org>
  66 Description:    Writing a value to this file sets the sampling interval of the
  67                 DAMON context in microseconds as the value.  Reading this file
  68                 returns the value.
  69
  70 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/aggr_us
  71 Date:           Mar 2022
  72 Contact:        SeongJae Park <sj@kernel.org>
  73 Description:    Writing a value to this file sets the aggregation interval of
  74                 the DAMON context in microseconds as the value.  Reading this
  75                 file returns the value.
  76
  77 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/update_us
  78 Date:           Mar 2022
  79 Contact:        SeongJae Park <sj@kernel.org>
  80 Description:    Writing a value to this file sets the update interval of the
  81                 DAMON context in microseconds as the value.  Reading this file
  82                 returns the value.
  83
  84 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/min
  85
  86 WDate:          Mar 2022
  87 Contact:        SeongJae Park <sj@kernel.org>
  88 Description:    Writing a value to this file sets the minimum number of
  89                 monitoring regions of the DAMON context as the value.  Reading
  90                 this file returns the value.
  91
  92 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/max
  93 Date:           Mar 2022
  94 Contact:        SeongJae Park <sj@kernel.org>
  95 Description:    Writing a value to this file sets the maximum number of
  96                 monitoring regions of the DAMON context as the value.  Reading
  97                 this file returns the value.
  98
  99 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/nr_targets
 100 Date:           Mar 2022
 101 Contact:        SeongJae Park <sj@kernel.org>
 102 Description:    Writing a number 'N' to this file creates the number of
 103                 directories for controlling each DAMON target of the context
 104                 named '0' to 'N-1' under the contexts/ directory.
 105
 106 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/pid_target
 107 Date:           Mar 2022
 108 Contact:        SeongJae Park <sj@kernel.org>
 109 Description:    Writing to and reading from this file sets and gets the pid of
 110                 the target process if the context is for virtual address spaces
 111                 monitoring, respectively.
 112
 113 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/nr_regions
 114 Date:           Mar 2022
 115 Contact:        SeongJae Park <sj@kernel.org>
 116 Description:    Writing a number 'N' to this file creates the number of
 117                 directories for setting each DAMON target memory region of the
 118                 context named '0' to 'N-1' under the regions/ directory.  In
 119                 case of the virtual address space monitoring, DAMON
 120                 automatically sets the target memory region based on the target
 121                 processes' mappings.
 122
 123 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/start
 124 Date:           Mar 2022
 125 Contact:        SeongJae Park <sj@kernel.org>
 126 Description:    Writing to and reading from this file sets and gets the start
 127                 address of the monitoring region.
 128
 129 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/end
 130 Date:           Mar 2022
 131 Contact:        SeongJae Park <sj@kernel.org>
 132 Description:    Writing to and reading from this file sets and gets the end
 133                 address of the monitoring region.
 134
 135 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/nr_schemes
 136 Date:           Mar 2022
 137 Contact:        SeongJae Park <sj@kernel.org>
 138 Description:    Writing a number 'N' to this file creates the number of
 139                 directories for controlling each DAMON-based operation scheme
 140                 of the context named '0' to 'N-1' under the schemes/ directory.
 141
 142 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/action
 143 Date:           Mar 2022
 144 Contact:        SeongJae Park <sj@kernel.org>
 145 Description:    Writing to and reading from this file sets and gets the action
 146                 of the scheme.
 147
 148 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/min
 149 Date:           Mar 2022
 150 Contact:        SeongJae Park <sj@kernel.org>
 151 Description:    Writing to and reading from this file sets and gets the mimimum
 152                 size of the scheme's target regions in bytes.
 153
 154 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/max
 155 Date:           Mar 2022
 156 Contact:        SeongJae Park <sj@kernel.org>
 157 Description:    Writing to and reading from this file sets and gets the maximum
 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/nr_accesses/min
 161 Date:           Mar 2022
 162 Contact:        SeongJae Park <sj@kernel.org>
 163 Description:    Writing to and reading from this file sets and gets the manimum
 164                 'nr_accesses' of the scheme's target regions.
 165
 166 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/max
 167 Date:           Mar 2022
 168 Contact:        SeongJae Park <sj@kernel.org>
 169 Description:    Writing to and reading from this file sets and gets the maximum
 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/age/min
 173 Date:           Mar 2022
 174 Contact:        SeongJae Park <sj@kernel.org>
 175 Description:    Writing to and reading from this file sets and gets the minimum
 176                 'age' of the scheme's target regions.
 177
 178 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/max
 179 Date:           Mar 2022
 180 Contact:        SeongJae Park <sj@kernel.org>
 181 Description:    Writing to and reading from this file sets and gets the maximum
 182                 'age' of the scheme's target regions.
 183
 184 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/ms
 185 Date:           Mar 2022
 186 Contact:        SeongJae Park <sj@kernel.org>
 187 Description:    Writing to and reading from this file sets and gets the time
 188                 quota of the scheme in milliseconds.
 189
 190 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/bytes
 191 Date:           Mar 2022
 192 Contact:        SeongJae Park <sj@kernel.org>
 193 Description:    Writing to and reading from this file sets and gets the size
 194                 quota of the scheme in bytes.
 195
 196 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/reset_interval_ms
 197 Date:           Mar 2022
 198 Contact:        SeongJae Park <sj@kernel.org>
 199 Description:    Writing to and reading from this file sets and gets the quotas
 200                 charge reset interval of the scheme in milliseconds.
 201
 202 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/sz_permil
 203 Date:           Mar 2022
 204 Contact:        SeongJae Park <sj@kernel.org>
 205 Description:    Writing to and reading from this file sets and gets the
 206                 under-quota limit regions prioritization weight for 'size' in
 207                 permil.
 208
 209 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/nr_accesses_permil
 210 Date:           Mar 2022
 211 Contact:        SeongJae Park <sj@kernel.org>
 212 Description:    Writing to and reading from this file sets and gets the
 213                 under-quota limit regions prioritization weight for
 214                 'nr_accesses' in permil.
 215
 216 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/age_permil
 217 Date:           Mar 2022
 218 Contact:        SeongJae Park <sj@kernel.org>
 219 Description:    Writing to and reading from this file sets and gets the
 220                 under-quota limit regions prioritization weight for 'age' in
 221                 permil.
 222
 223 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/metric
 224 Date:           Mar 2022
 225 Contact:        SeongJae Park <sj@kernel.org>
 226 Description:    Writing to and reading from this file sets and gets the metric
 227                 of the watermarks for the scheme.  The writable/readable
 228                 keywords for this file are 'none' for disabling the watermarks
 229                 feature, or 'free_mem_rate' for the system's global free memory
 230                 rate in permil.
 231
 232 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/interval_us
 233 Date:           Mar 2022
 234 Contact:        SeongJae Park <sj@kernel.org>
 235 Description:    Writing to and reading from this file sets and gets the metric
 236                 check interval of the watermarks for the scheme in
 237                 microseconds.
 238
 239 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/high
 240 Date:           Mar 2022
 241 Contact:        SeongJae Park <sj@kernel.org>
 242 Description:    Writing to and reading from this file sets and gets the high
 243                 watermark of the scheme in permil.
 244
 245 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/mid
 246 Date:           Mar 2022
 247 Contact:        SeongJae Park <sj@kernel.org>
 248 Description:    Writing to and reading from this file sets and gets the mid
 249                 watermark of the scheme in permil.
 250
 251 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/low
 252 Date:           Mar 2022
 253 Contact:        SeongJae Park <sj@kernel.org>
 254 Description:    Writing to and reading from this file sets and gets the low
 255                 watermark of the scheme in permil.
 256
 257 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_tried
 258 Date:           Mar 2022
 259 Contact:        SeongJae Park <sj@kernel.org>
 260 Description:    Reading this file returns the number of regions that the action
 261                 of the scheme has tried to be applied.
 262
 263 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_tried
 264 Date:           Mar 2022
 265 Contact:        SeongJae Park <sj@kernel.org>
 266 Description:    Reading this file returns the total size of regions that the
 267                 action of the scheme has tried to be applied in bytes.
 268
 269 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_applied
 270 Date:           Mar 2022
 271 Contact:        SeongJae Park <sj@kernel.org>
 272 Description:    Reading this file returns the number of regions that the action
 273                 of the scheme has successfully applied.
 274
 275 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_applied
 276 Date:           Mar 2022
 277 Contact:        SeongJae Park <sj@kernel.org>
 278 Description:    Reading this file returns the total size of regions that the
 279                 action of the scheme has successfully applied in bytes.
 280
 281 What:           /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/qt_exceeds
 282 Date:           Mar 2022
 283 Contact:        SeongJae Park <sj@kernel.org>
 284 Description:    Reading this file returns the number of the exceed events of
 285                 the scheme's quotas.