1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4Detailed Usages 5=============== 6 7DAMON provides below interfaces for different users. 8 9- *DAMON user space tool.* 10 `This <https://github.com/awslabs/damo>`_ is for privileged people such as 11 system administrators who want a just-working human-friendly interface. 12 Using this, users can use the DAMON’s major features in a human-friendly way. 13 It may not be highly tuned for special cases, though. For more detail, 14 please refer to its `usage document 15 <https://github.com/awslabs/damo/blob/next/USAGE.md>`_. 16- *sysfs interface.* 17 :ref:`This <sysfs_interface>` is for privileged user space programmers who 18 want more optimized use of DAMON. Using this, users can use DAMON’s major 19 features by reading from and writing to special sysfs files. Therefore, 20 you can write and use your personalized DAMON sysfs wrapper programs that 21 reads/writes the sysfs files instead of you. The `DAMON user space tool 22 <https://github.com/awslabs/damo>`_ is one example of such programs. 23- *Kernel Space Programming Interface.* 24 :doc:`This </mm/damon/api>` is for kernel space programmers. Using this, 25 users can utilize every feature of DAMON most flexibly and efficiently by 26 writing kernel space DAMON application programs for you. You can even extend 27 DAMON for various address spaces. For detail, please refer to the interface 28 :doc:`document </mm/damon/api>`. 29- *debugfs interface. (DEPRECATED!)* 30 :ref:`This <debugfs_interface>` is almost identical to :ref:`sysfs interface 31 <sysfs_interface>`. This is deprecated, so users should move to the 32 :ref:`sysfs interface <sysfs_interface>`. If you depend on this and cannot 33 move, please report your usecase to damon@lists.linux.dev and 34 linux-mm@kvack.org. 35 36.. _sysfs_interface: 37 38sysfs Interface 39=============== 40 41DAMON sysfs interface is built when ``CONFIG_DAMON_SYSFS`` is defined. It 42creates multiple directories and files under its sysfs directory, 43``<sysfs>/kernel/mm/damon/``. You can control DAMON by writing to and reading 44from the files under the directory. 45 46For a short example, users can monitor the virtual address space of a given 47workload as below. :: 48 49 # cd /sys/kernel/mm/damon/admin/ 50 # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts 51 # echo vaddr > kdamonds/0/contexts/0/operations 52 # echo 1 > kdamonds/0/contexts/0/targets/nr_targets 53 # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target 54 # echo on > kdamonds/0/state 55 56Files Hierarchy 57--------------- 58 59The files hierarchy of DAMON sysfs interface is shown below. In the below 60figure, parents-children relations are represented with indentations, each 61directory is having ``/`` suffix, and files in each directory are separated by 62comma (","). :: 63 64 /sys/kernel/mm/damon/admin 65 │ kdamonds/nr_kdamonds 66 │ │ 0/state,pid 67 │ │ │ contexts/nr_contexts 68 │ │ │ │ 0/avail_operations,operations 69 │ │ │ │ │ monitoring_attrs/ 70 │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us 71 │ │ │ │ │ │ nr_regions/min,max 72 │ │ │ │ │ targets/nr_targets 73 │ │ │ │ │ │ 0/pid_target 74 │ │ │ │ │ │ │ regions/nr_regions 75 │ │ │ │ │ │ │ │ 0/start,end 76 │ │ │ │ │ │ │ │ ... 77 │ │ │ │ │ │ ... 78 │ │ │ │ │ schemes/nr_schemes 79 │ │ │ │ │ │ 0/action,apply_interval_us 80 │ │ │ │ │ │ │ access_pattern/ 81 │ │ │ │ │ │ │ │ sz/min,max 82 │ │ │ │ │ │ │ │ nr_accesses/min,max 83 │ │ │ │ │ │ │ │ age/min,max 84 │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms 85 │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil 86 │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low 87 │ │ │ │ │ │ │ filters/nr_filters 88 │ │ │ │ │ │ │ │ 0/type,matching,memcg_id 89 │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds 90 │ │ │ │ │ │ │ tried_regions/total_bytes 91 │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age 92 │ │ │ │ │ │ │ │ ... 93 │ │ │ │ │ │ ... 94 │ │ │ │ ... 95 │ │ ... 96 97Root 98---- 99 100The root of the DAMON sysfs interface is ``<sysfs>/kernel/mm/damon/``, and it 101has one directory named ``admin``. The directory contains the files for 102privileged user space programs' control of DAMON. User space tools or daemons 103having the root permission could use this directory. 104 105kdamonds/ 106--------- 107 108Under the ``admin`` directory, one directory, ``kdamonds``, which has files for 109controlling the kdamonds (refer to 110:ref:`design <damon_design_execution_model_and_data_structures>` for more 111details) exists. In the beginning, this directory has only one file, 112``nr_kdamonds``. Writing a number (``N``) to the file creates the number of 113child directories named ``0`` to ``N-1``. Each directory represents each 114kdamond. 115 116kdamonds/<N>/ 117------------- 118 119In each kdamond directory, two files (``state`` and ``pid``) and one directory 120(``contexts``) exist. 121 122Reading ``state`` returns ``on`` if the kdamond is currently running, or 123``off`` if it is not running. Writing ``on`` or ``off`` makes the kdamond be 124in the state. Writing ``commit`` to the ``state`` file makes kdamond reads the 125user inputs in the sysfs files except ``state`` file again. Writing 126``update_schemes_stats`` to ``state`` file updates the contents of stats files 127for each DAMON-based operation scheme of the kdamond. For details of the 128stats, please refer to :ref:`stats section <sysfs_schemes_stats>`. 129 130Writing ``update_schemes_tried_regions`` to ``state`` file updates the 131DAMON-based operation scheme action tried regions directory for each 132DAMON-based operation scheme of the kdamond. Writing 133``update_schemes_tried_bytes`` to ``state`` file updates only 134``.../tried_regions/total_bytes`` files. Writing 135``clear_schemes_tried_regions`` to ``state`` file clears the DAMON-based 136operating scheme action tried regions directory for each DAMON-based operation 137scheme of the kdamond. For details of the DAMON-based operation scheme action 138tried regions directory, please refer to :ref:`tried_regions section 139<sysfs_schemes_tried_regions>`. 140 141If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. 142 143``contexts`` directory contains files for controlling the monitoring contexts 144that this kdamond will execute. 145 146kdamonds/<N>/contexts/ 147---------------------- 148 149In the beginning, this directory has only one file, ``nr_contexts``. Writing a 150number (``N``) to the file creates the number of child directories named as 151``0`` to ``N-1``. Each directory represents each monitoring context (refer to 152:ref:`design <damon_design_execution_model_and_data_structures>` for more 153details). At the moment, only one context per kdamond is supported, so only 154``0`` or ``1`` can be written to the file. 155 156.. _sysfs_contexts: 157 158contexts/<N>/ 159------------- 160 161In each context directory, two files (``avail_operations`` and ``operations``) 162and three directories (``monitoring_attrs``, ``targets``, and ``schemes``) 163exist. 164 165DAMON supports multiple types of monitoring operations, including those for 166virtual address space and the physical address space. You can get the list of 167available monitoring operations set on the currently running kernel by reading 168``avail_operations`` file. Based on the kernel configuration, the file will 169list some or all of below keywords. 170 171 - vaddr: Monitor virtual address spaces of specific processes 172 - fvaddr: Monitor fixed virtual address ranges 173 - paddr: Monitor the physical address space of the system 174 175Please refer to :ref:`regions sysfs directory <sysfs_regions>` for detailed 176differences between the operations sets in terms of the monitoring target 177regions. 178 179You can set and get what type of monitoring operations DAMON will use for the 180context by writing one of the keywords listed in ``avail_operations`` file and 181reading from the ``operations`` file. 182 183.. _sysfs_monitoring_attrs: 184 185contexts/<N>/monitoring_attrs/ 186------------------------------ 187 188Files for specifying attributes of the monitoring including required quality 189and efficiency of the monitoring are in ``monitoring_attrs`` directory. 190Specifically, two directories, ``intervals`` and ``nr_regions`` exist in this 191directory. 192 193Under ``intervals`` directory, three files for DAMON's sampling interval 194(``sample_us``), aggregation interval (``aggr_us``), and update interval 195(``update_us``) exist. You can set and get the values in micro-seconds by 196writing to and reading from the files. 197 198Under ``nr_regions`` directory, two files for the lower-bound and upper-bound 199of DAMON's monitoring regions (``min`` and ``max``, respectively), which 200controls the monitoring overhead, exist. You can set and get the values by 201writing to and rading from the files. 202 203For more details about the intervals and monitoring regions range, please refer 204to the Design document (:doc:`/mm/damon/design`). 205 206contexts/<N>/targets/ 207--------------------- 208 209In the beginning, this directory has only one file, ``nr_targets``. Writing a 210number (``N``) to the file creates the number of child directories named ``0`` 211to ``N-1``. Each directory represents each monitoring target. 212 213targets/<N>/ 214------------ 215 216In each target directory, one file (``pid_target``) and one directory 217(``regions``) exist. 218 219If you wrote ``vaddr`` to the ``contexts/<N>/operations``, each target should 220be a process. You can specify the process to DAMON by writing the pid of the 221process to the ``pid_target`` file. 222 223.. _sysfs_regions: 224 225targets/<N>/regions 226------------------- 227 228When ``vaddr`` monitoring operations set is being used (``vaddr`` is written to 229the ``contexts/<N>/operations`` file), DAMON automatically sets and updates the 230monitoring target regions so that entire memory mappings of target processes 231can be covered. However, users could want to set the initial monitoring region 232to specific address ranges. 233 234In contrast, DAMON do not automatically sets and updates the monitoring target 235regions when ``fvaddr`` or ``paddr`` monitoring operations sets are being used 236(``fvaddr`` or ``paddr`` have written to the ``contexts/<N>/operations``). 237Therefore, users should set the monitoring target regions by themselves in the 238cases. 239 240For such cases, users can explicitly set the initial monitoring target regions 241as they want, by writing proper values to the files under this directory. 242 243In the beginning, this directory has only one file, ``nr_regions``. Writing a 244number (``N``) to the file creates the number of child directories named ``0`` 245to ``N-1``. Each directory represents each initial monitoring target region. 246 247regions/<N>/ 248------------ 249 250In each region directory, you will find two files (``start`` and ``end``). You 251can set and get the start and end addresses of the initial monitoring target 252region by writing to and reading from the files, respectively. 253 254Each region should not overlap with others. ``end`` of directory ``N`` should 255be equal or smaller than ``start`` of directory ``N+1``. 256 257contexts/<N>/schemes/ 258--------------------- 259 260The directory for DAMON-based Operation Schemes (:ref:`DAMOS 261<damon_design_damos>`). Users can get and set the schemes by reading from and 262writing to files under this directory. 263 264In the beginning, this directory has only one file, ``nr_schemes``. Writing a 265number (``N``) to the file creates the number of child directories named ``0`` 266to ``N-1``. Each directory represents each DAMON-based operation scheme. 267 268schemes/<N>/ 269------------ 270 271In each scheme directory, five directories (``access_pattern``, ``quotas``, 272``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and two files 273(``action`` and ``apply_interval``) exist. 274 275The ``action`` file is for setting and getting the scheme's :ref:`action 276<damon_design_damos_action>`. The keywords that can be written to and read 277from the file and their meaning are as below. 278 279Note that support of each action depends on the running DAMON operations set 280:ref:`implementation <sysfs_contexts>`. 281 282 - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED``. 283 Supported by ``vaddr`` and ``fvaddr`` operations set. 284 - ``cold``: Call ``madvise()`` for the region with ``MADV_COLD``. 285 Supported by ``vaddr`` and ``fvaddr`` operations set. 286 - ``pageout``: Call ``madvise()`` for the region with ``MADV_PAGEOUT``. 287 Supported by ``vaddr``, ``fvaddr`` and ``paddr`` operations set. 288 - ``hugepage``: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``. 289 Supported by ``vaddr`` and ``fvaddr`` operations set. 290 - ``nohugepage``: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``. 291 Supported by ``vaddr`` and ``fvaddr`` operations set. 292 - ``lru_prio``: Prioritize the region on its LRU lists. 293 Supported by ``paddr`` operations set. 294 - ``lru_deprio``: Deprioritize the region on its LRU lists. 295 Supported by ``paddr`` operations set. 296 - ``stat``: Do nothing but count the statistics. 297 Supported by all operations sets. 298 299The ``apply_interval_us`` file is for setting and getting the scheme's 300:ref:`apply_interval <damon_design_damos>` in microseconds. 301 302schemes/<N>/access_pattern/ 303--------------------------- 304 305The directory for the target access :ref:`pattern 306<damon_design_damos_access_pattern>` of the given DAMON-based operation scheme. 307 308Under the ``access_pattern`` directory, three directories (``sz``, 309``nr_accesses``, and ``age``) each having two files (``min`` and ``max``) 310exist. You can set and get the access pattern for the given scheme by writing 311to and reading from the ``min`` and ``max`` files under ``sz``, 312``nr_accesses``, and ``age`` directories, respectively. Note that the ``min`` 313and the ``max`` form a closed interval. 314 315schemes/<N>/quotas/ 316------------------- 317 318The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given 319DAMON-based operation scheme. 320 321Under ``quotas`` directory, three files (``ms``, ``bytes``, 322``reset_interval_ms``) and one directory (``weights``) having three files 323(``sz_permil``, ``nr_accesses_permil``, and ``age_permil``) in it exist. 324 325You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and 326``reset interval`` in milliseconds by writing the values to the three files, 327respectively. Then, DAMON tries to use only up to ``time quota`` milliseconds 328for applying the ``action`` to memory regions of the ``access_pattern``, and to 329apply the action to only up to ``bytes`` bytes of memory regions within the 330``reset_interval_ms``. Setting both ``ms`` and ``bytes`` zero disables the 331quota limits. 332 333You can also set the :ref:`prioritization weights 334<damon_design_damos_quotas_prioritization>` for size, access frequency, and age 335in per-thousand unit by writing the values to the three files under the 336``weights`` directory. 337 338schemes/<N>/watermarks/ 339----------------------- 340 341The directory for the :ref:`watermarks <damon_design_damos_watermarks>` of the 342given DAMON-based operation scheme. 343 344Under the watermarks directory, five files (``metric``, ``interval_us``, 345``high``, ``mid``, and ``low``) for setting the metric, the time interval 346between check of the metric, and the three watermarks exist. You can set and 347get the five values by writing to the files, respectively. 348 349Keywords and meanings of those that can be written to the ``metric`` file are 350as below. 351 352 - none: Ignore the watermarks 353 - free_mem_rate: System's free memory rate (per thousand) 354 355The ``interval`` should written in microseconds unit. 356 357schemes/<N>/filters/ 358-------------------- 359 360The directory for the :ref:`filters <damon_design_damos_filters>` of the given 361DAMON-based operation scheme. 362 363In the beginning, this directory has only one file, ``nr_filters``. Writing a 364number (``N``) to the file creates the number of child directories named ``0`` 365to ``N-1``. Each directory represents each filter. The filters are evaluated 366in the numeric order. 367 368Each filter directory contains six files, namely ``type``, ``matcing``, 369``memcg_path``, ``addr_start``, ``addr_end``, and ``target_idx``. To ``type`` 370file, you can write one of four special keywords: ``anon`` for anonymous pages, 371``memcg`` for specific memory cgroup, ``addr`` for specific address range (an 372open-ended interval), or ``target`` for specific DAMON monitoring target 373filtering. In case of the memory cgroup filtering, you can specify the memory 374cgroup of the interest by writing the path of the memory cgroup from the 375cgroups mount point to ``memcg_path`` file. In case of the address range 376filtering, you can specify the start and end address of the range to 377``addr_start`` and ``addr_end`` files, respectively. For the DAMON monitoring 378target filtering, you can specify the index of the target between the list of 379the DAMON context's monitoring targets list to ``target_idx`` file. You can 380write ``Y`` or ``N`` to ``matching`` file to filter out pages that does or does 381not match to the type, respectively. Then, the scheme's action will not be 382applied to the pages that specified to be filtered out. 383 384For example, below restricts a DAMOS action to be applied to only non-anonymous 385pages of all memory cgroups except ``/having_care_already``.:: 386 387 # echo 2 > nr_filters 388 # # filter out anonymous pages 389 echo anon > 0/type 390 echo Y > 0/matching 391 # # further filter out all cgroups except one at '/having_care_already' 392 echo memcg > 1/type 393 echo /having_care_already > 1/memcg_path 394 echo N > 1/matching 395 396Note that ``anon`` and ``memcg`` filters are currently supported only when 397``paddr`` :ref:`implementation <sysfs_contexts>` is being used. 398 399Also, memory regions that are filtered out by ``addr`` or ``target`` filters 400are not counted as the scheme has tried to those, while regions that filtered 401out by other type filters are counted as the scheme has tried to. The 402difference is applied to :ref:`stats <damos_stats>` and 403:ref:`tried regions <sysfs_schemes_tried_regions>`. 404 405.. _sysfs_schemes_stats: 406 407schemes/<N>/stats/ 408------------------ 409 410DAMON counts the total number and bytes of regions that each scheme is tried to 411be applied, the two numbers for the regions that each scheme is successfully 412applied, and the total number of the quota limit exceeds. This statistics can 413be used for online analysis or tuning of the schemes. 414 415The statistics can be retrieved by reading the files under ``stats`` directory 416(``nr_tried``, ``sz_tried``, ``nr_applied``, ``sz_applied``, and 417``qt_exceeds``), respectively. The files are not updated in real time, so you 418should ask DAMON sysfs interface to update the content of the files for the 419stats by writing a special keyword, ``update_schemes_stats`` to the relevant 420``kdamonds/<N>/state`` file. 421 422.. _sysfs_schemes_tried_regions: 423 424schemes/<N>/tried_regions/ 425-------------------------- 426 427This directory initially has one file, ``total_bytes``. 428 429When a special keyword, ``update_schemes_tried_regions``, is written to the 430relevant ``kdamonds/<N>/state`` file, DAMON updates the ``total_bytes`` file so 431that reading it returns the total size of the scheme tried regions, and creates 432directories named integer starting from ``0`` under this directory. Each 433directory contains files exposing detailed information about each of the memory 434region that the corresponding scheme's ``action`` has tried to be applied under 435this directory, during next :ref:`apply interval <damon_design_damos>` of the 436corresponding scheme. The information includes address range, ``nr_accesses``, 437and ``age`` of the region. 438 439Writing ``update_schemes_tried_bytes`` to the relevant ``kdamonds/<N>/state`` 440file will only update the ``total_bytes`` file, and will not create the 441subdirectories. 442 443The directories will be removed when another special keyword, 444``clear_schemes_tried_regions``, is written to the relevant 445``kdamonds/<N>/state`` file. 446 447The expected usage of this directory is investigations of schemes' behaviors, 448and query-like efficient data access monitoring results retrievals. For the 449latter use case, in particular, users can set the ``action`` as ``stat`` and 450set the ``access pattern`` as their interested pattern that they want to query. 451 452tried_regions/<N>/ 453------------------ 454 455In each region directory, you will find four files (``start``, ``end``, 456``nr_accesses``, and ``age``). Reading the files will show the start and end 457addresses, ``nr_accesses``, and ``age`` of the region that corresponding 458DAMON-based operation scheme ``action`` has tried to be applied. 459 460Example 461~~~~~~~ 462 463Below commands applies a scheme saying "If a memory region of size in [4KiB, 4648KiB] is showing accesses per aggregate interval in [0, 5] for aggregate 465interval in [10, 20], page out the region. For the paging out, use only up to 46610ms per second, and also don't page out more than 1GiB per second. Under the 467limitation, page out memory regions having longer age first. Also, check the 468free memory rate of the system every 5 seconds, start the monitoring and paging 469out when the free memory rate becomes lower than 50%, but stop it if the free 470memory rate becomes larger than 60%, or lower than 30%". :: 471 472 # cd <sysfs>/kernel/mm/damon/admin 473 # # populate directories 474 # echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts; 475 # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes 476 # cd kdamonds/0/contexts/0/schemes/0 477 # # set the basic access pattern and the action 478 # echo 4096 > access_pattern/sz/min 479 # echo 8192 > access_pattern/sz/max 480 # echo 0 > access_pattern/nr_accesses/min 481 # echo 5 > access_pattern/nr_accesses/max 482 # echo 10 > access_pattern/age/min 483 # echo 20 > access_pattern/age/max 484 # echo pageout > action 485 # # set quotas 486 # echo 10 > quotas/ms 487 # echo $((1024*1024*1024)) > quotas/bytes 488 # echo 1000 > quotas/reset_interval_ms 489 # # set watermark 490 # echo free_mem_rate > watermarks/metric 491 # echo 5000000 > watermarks/interval_us 492 # echo 600 > watermarks/high 493 # echo 500 > watermarks/mid 494 # echo 300 > watermarks/low 495 496Please note that it's highly recommended to use user space tools like `damo 497<https://github.com/awslabs/damo>`_ rather than manually reading and writing 498the files as above. Above is only for an example. 499 500.. _tracepoint: 501 502Tracepoints for Monitoring Results 503================================== 504 505Users can get the monitoring results via the :ref:`tried_regions 506<sysfs_schemes_tried_regions>`. The interface is useful for getting a 507snapshot, but it could be inefficient for fully recording all the monitoring 508results. For the purpose, two trace points, namely ``damon:damon_aggregated`` 509and ``damon:damos_before_apply``, are provided. ``damon:damon_aggregated`` 510provides the whole monitoring results, while ``damon:damos_before_apply`` 511provides the monitoring results for regions that each DAMON-based Operation 512Scheme (:ref:`DAMOS <damon_design_damos>`) is gonna be applied. Hence, 513``damon:damos_before_apply`` is more useful for recording internal behavior of 514DAMOS, or DAMOS target access 515:ref:`pattern <damon_design_damos_access_pattern>` based query-like efficient 516monitoring results recording. 517 518While the monitoring is turned on, you could record the tracepoint events and 519show results using tracepoint supporting tools like ``perf``. For example:: 520 521 # echo on > monitor_on 522 # perf record -e damon:damon_aggregated & 523 # sleep 5 524 # kill 9 $(pidof perf) 525 # echo off > monitor_on 526 # perf script 527 kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864 528 [...] 529 530Each line of the perf script output represents each monitoring region. The 531first five fields are as usual other tracepoint outputs. The sixth field 532(``target_id=X``) shows the ide of the monitoring target of the region. The 533seventh field (``nr_regions=X``) shows the total number of monitoring regions 534for the target. The eighth field (``X-Y:``) shows the start (``X``) and end 535(``Y``) addresses of the region in bytes. The ninth field (``X``) shows the 536``nr_accesses`` of the region (refer to 537:ref:`design <damon_design_region_based_sampling>` for more details of the 538counter). Finally the tenth field (``X``) shows the ``age`` of the region 539(refer to :ref:`design <damon_design_age_tracking>` for more details of the 540counter). 541 542If the event was ``damon:damos_beofre_apply``, the ``perf script`` output would 543be somewhat like below:: 544 545 kdamond.0 47293 [000] 80801.060214: damon:damos_before_apply: ctx_idx=0 scheme_idx=0 target_idx=0 nr_regions=11 121932607488-135128711168: 0 136 546 [...] 547 548Each line of the output represents each monitoring region that each DAMON-based 549Operation Scheme was about to be applied at the traced time. The first five 550fields are as usual. It shows the index of the DAMON context (``ctx_idx=X``) 551of the scheme in the list of the contexts of the context's kdamond, the index 552of the scheme (``scheme_idx=X``) in the list of the schemes of the context, in 553addition to the output of ``damon_aggregated`` tracepoint. 554 555 556.. _debugfs_interface: 557 558debugfs Interface (DEPRECATED!) 559=============================== 560 561.. note:: 562 563 THIS IS DEPRECATED! 564 565 DAMON debugfs interface is deprecated, so users should move to the 566 :ref:`sysfs interface <sysfs_interface>`. If you depend on this and cannot 567 move, please report your usecase to damon@lists.linux.dev and 568 linux-mm@kvack.org. 569 570DAMON exports eight files, ``attrs``, ``target_ids``, ``init_regions``, 571``schemes``, ``monitor_on``, ``kdamond_pid``, ``mk_contexts`` and 572``rm_contexts`` under its debugfs directory, ``<debugfs>/damon/``. 573 574 575Attributes 576---------- 577 578Users can get and set the ``sampling interval``, ``aggregation interval``, 579``update interval``, and min/max number of monitoring target regions by 580reading from and writing to the ``attrs`` file. To know about the monitoring 581attributes in detail, please refer to the :doc:`/mm/damon/design`. For 582example, below commands set those values to 5 ms, 100 ms, 1,000 ms, 10 and 5831000, and then check it again:: 584 585 # cd <debugfs>/damon 586 # echo 5000 100000 1000000 10 1000 > attrs 587 # cat attrs 588 5000 100000 1000000 10 1000 589 590 591Target IDs 592---------- 593 594Some types of address spaces supports multiple monitoring target. For example, 595the virtual memory address spaces monitoring can have multiple processes as the 596monitoring targets. Users can set the targets by writing relevant id values of 597the targets to, and get the ids of the current targets by reading from the 598``target_ids`` file. In case of the virtual address spaces monitoring, the 599values should be pids of the monitoring target processes. For example, below 600commands set processes having pids 42 and 4242 as the monitoring targets and 601check it again:: 602 603 # cd <debugfs>/damon 604 # echo 42 4242 > target_ids 605 # cat target_ids 606 42 4242 607 608Users can also monitor the physical memory address space of the system by 609writing a special keyword, "``paddr\n``" to the file. Because physical address 610space monitoring doesn't support multiple targets, reading the file will show a 611fake value, ``42``, as below:: 612 613 # cd <debugfs>/damon 614 # echo paddr > target_ids 615 # cat target_ids 616 42 617 618Note that setting the target ids doesn't start the monitoring. 619 620 621Initial Monitoring Target Regions 622--------------------------------- 623 624In case of the virtual address space monitoring, DAMON automatically sets and 625updates the monitoring target regions so that entire memory mappings of target 626processes can be covered. However, users can want to limit the monitoring 627region to specific address ranges, such as the heap, the stack, or specific 628file-mapped area. Or, some users can know the initial access pattern of their 629workloads and therefore want to set optimal initial regions for the 'adaptive 630regions adjustment'. 631 632In contrast, DAMON do not automatically sets and updates the monitoring target 633regions in case of physical memory monitoring. Therefore, users should set the 634monitoring target regions by themselves. 635 636In such cases, users can explicitly set the initial monitoring target regions 637as they want, by writing proper values to the ``init_regions`` file. The input 638should be a sequence of three integers separated by white spaces that represent 639one region in below form.:: 640 641 <target idx> <start address> <end address> 642 643The ``target idx`` should be the index of the target in ``target_ids`` file, 644starting from ``0``, and the regions should be passed in address order. For 645example, below commands will set a couple of address ranges, ``1-100`` and 646``100-200`` as the initial monitoring target region of pid 42, which is the 647first one (index ``0``) in ``target_ids``, and another couple of address 648ranges, ``20-40`` and ``50-100`` as that of pid 4242, which is the second one 649(index ``1``) in ``target_ids``.:: 650 651 # cd <debugfs>/damon 652 # cat target_ids 653 42 4242 654 # echo "0 1 100 \ 655 0 100 200 \ 656 1 20 40 \ 657 1 50 100" > init_regions 658 659Note that this sets the initial monitoring target regions only. In case of 660virtual memory monitoring, DAMON will automatically updates the boundary of the 661regions after one ``update interval``. Therefore, users should set the 662``update interval`` large enough in this case, if they don't want the 663update. 664 665 666Schemes 667------- 668 669Users can get and set the DAMON-based operation :ref:`schemes 670<damon_design_damos>` by reading from and writing to ``schemes`` debugfs file. 671Reading the file also shows the statistics of each scheme. To the file, each 672of the schemes should be represented in each line in below form:: 673 674 <target access pattern> <action> <quota> <watermarks> 675 676You can disable schemes by simply writing an empty string to the file. 677 678Target Access Pattern 679~~~~~~~~~~~~~~~~~~~~~ 680 681The target access :ref:`pattern <damon_design_damos_access_pattern>` of the 682scheme. The ``<target access pattern>`` is constructed with three ranges in 683below form:: 684 685 min-size max-size min-acc max-acc min-age max-age 686 687Specifically, bytes for the size of regions (``min-size`` and ``max-size``), 688number of monitored accesses per aggregate interval for access frequency 689(``min-acc`` and ``max-acc``), number of aggregate intervals for the age of 690regions (``min-age`` and ``max-age``) are specified. Note that the ranges are 691closed interval. 692 693Action 694~~~~~~ 695 696The ``<action>`` is a predefined integer for memory management :ref:`actions 697<damon_design_damos_action>`. The supported numbers and their meanings are as 698below. 699 700 - 0: Call ``madvise()`` for the region with ``MADV_WILLNEED``. Ignored if 701 ``target`` is ``paddr``. 702 - 1: Call ``madvise()`` for the region with ``MADV_COLD``. Ignored if 703 ``target`` is ``paddr``. 704 - 2: Call ``madvise()`` for the region with ``MADV_PAGEOUT``. 705 - 3: Call ``madvise()`` for the region with ``MADV_HUGEPAGE``. Ignored if 706 ``target`` is ``paddr``. 707 - 4: Call ``madvise()`` for the region with ``MADV_NOHUGEPAGE``. Ignored if 708 ``target`` is ``paddr``. 709 - 5: Do nothing but count the statistics 710 711Quota 712~~~~~ 713 714Users can set the :ref:`quotas <damon_design_damos_quotas>` of the given scheme 715via the ``<quota>`` in below form:: 716 717 <ms> <sz> <reset interval> <priority weights> 718 719This makes DAMON to try to use only up to ``<ms>`` milliseconds for applying 720the action to memory regions of the ``target access pattern`` within the 721``<reset interval>`` milliseconds, and to apply the action to only up to 722``<sz>`` bytes of memory regions within the ``<reset interval>``. Setting both 723``<ms>`` and ``<sz>`` zero disables the quota limits. 724 725For the :ref:`prioritization <damon_design_damos_quotas_prioritization>`, users 726can set the weights for the three properties in ``<priority weights>`` in below 727form:: 728 729 <size weight> <access frequency weight> <age weight> 730 731Watermarks 732~~~~~~~~~~ 733 734Users can specify :ref:`watermarks <damon_design_damos_watermarks>` of the 735given scheme via ``<watermarks>`` in below form:: 736 737 <metric> <check interval> <high mark> <middle mark> <low mark> 738 739``<metric>`` is a predefined integer for the metric to be checked. The 740supported numbers and their meanings are as below. 741 742 - 0: Ignore the watermarks 743 - 1: System's free memory rate (per thousand) 744 745The value of the metric is checked every ``<check interval>`` microseconds. 746 747If the value is higher than ``<high mark>`` or lower than ``<low mark>``, the 748scheme is deactivated. If the value is lower than ``<mid mark>``, the scheme 749is activated. 750 751.. _damos_stats: 752 753Statistics 754~~~~~~~~~~ 755 756It also counts the total number and bytes of regions that each scheme is tried 757to be applied, the two numbers for the regions that each scheme is successfully 758applied, and the total number of the quota limit exceeds. This statistics can 759be used for online analysis or tuning of the schemes. 760 761The statistics can be shown by reading the ``schemes`` file. Reading the file 762will show each scheme you entered in each line, and the five numbers for the 763statistics will be added at the end of each line. 764 765Example 766~~~~~~~ 767 768Below commands applies a scheme saying "If a memory region of size in [4KiB, 7698KiB] is showing accesses per aggregate interval in [0, 5] for aggregate 770interval in [10, 20], page out the region. For the paging out, use only up to 77110ms per second, and also don't page out more than 1GiB per second. Under the 772limitation, page out memory regions having longer age first. Also, check the 773free memory rate of the system every 5 seconds, start the monitoring and paging 774out when the free memory rate becomes lower than 50%, but stop it if the free 775memory rate becomes larger than 60%, or lower than 30%".:: 776 777 # cd <debugfs>/damon 778 # scheme="4096 8192 0 5 10 20 2" # target access pattern and action 779 # scheme+=" 10 $((1024*1024*1024)) 1000" # quotas 780 # scheme+=" 0 0 100" # prioritization weights 781 # scheme+=" 1 5000000 600 500 300" # watermarks 782 # echo "$scheme" > schemes 783 784 785Turning On/Off 786-------------- 787 788Setting the files as described above doesn't incur effect unless you explicitly 789start the monitoring. You can start, stop, and check the current status of the 790monitoring by writing to and reading from the ``monitor_on`` file. Writing 791``on`` to the file starts the monitoring of the targets with the attributes. 792Writing ``off`` to the file stops those. DAMON also stops if every target 793process is terminated. Below example commands turn on, off, and check the 794status of DAMON:: 795 796 # cd <debugfs>/damon 797 # echo on > monitor_on 798 # echo off > monitor_on 799 # cat monitor_on 800 off 801 802Please note that you cannot write to the above-mentioned debugfs files while 803the monitoring is turned on. If you write to the files while DAMON is running, 804an error code such as ``-EBUSY`` will be returned. 805 806 807Monitoring Thread PID 808--------------------- 809 810DAMON does requested monitoring with a kernel thread called ``kdamond``. You 811can get the pid of the thread by reading the ``kdamond_pid`` file. When the 812monitoring is turned off, reading the file returns ``none``. :: 813 814 # cd <debugfs>/damon 815 # cat monitor_on 816 off 817 # cat kdamond_pid 818 none 819 # echo on > monitor_on 820 # cat kdamond_pid 821 18594 822 823 824Using Multiple Monitoring Threads 825--------------------------------- 826 827One ``kdamond`` thread is created for each monitoring context. You can create 828and remove monitoring contexts for multiple ``kdamond`` required use case using 829the ``mk_contexts`` and ``rm_contexts`` files. 830 831Writing the name of the new context to the ``mk_contexts`` file creates a 832directory of the name on the DAMON debugfs directory. The directory will have 833DAMON debugfs files for the context. :: 834 835 # cd <debugfs>/damon 836 # ls foo 837 # ls: cannot access 'foo': No such file or directory 838 # echo foo > mk_contexts 839 # ls foo 840 # attrs init_regions kdamond_pid schemes target_ids 841 842If the context is not needed anymore, you can remove it and the corresponding 843directory by putting the name of the context to the ``rm_contexts`` file. :: 844 845 # echo foo > rm_contexts 846 # ls foo 847 # ls: cannot access 'foo': No such file or directory 848 849Note that ``mk_contexts``, ``rm_contexts``, and ``monitor_on`` files are in the 850root directory only. 851