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/damonitor/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/damonitor/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/damonitor/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 30.. _sysfs_interface: 31 32sysfs Interface 33=============== 34 35DAMON sysfs interface is built when ``CONFIG_DAMON_SYSFS`` is defined. It 36creates multiple directories and files under its sysfs directory, 37``<sysfs>/kernel/mm/damon/``. You can control DAMON by writing to and reading 38from the files under the directory. 39 40For a short example, users can monitor the virtual address space of a given 41workload as below. :: 42 43 # cd /sys/kernel/mm/damon/admin/ 44 # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts 45 # echo vaddr > kdamonds/0/contexts/0/operations 46 # echo 1 > kdamonds/0/contexts/0/targets/nr_targets 47 # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target 48 # echo on > kdamonds/0/state 49 50Files Hierarchy 51--------------- 52 53The files hierarchy of DAMON sysfs interface is shown below. In the below 54figure, parents-children relations are represented with indentations, each 55directory is having ``/`` suffix, and files in each directory are separated by 56comma (","). 57 58.. parsed-literal:: 59 60 :ref:`/sys/kernel/mm/damon <sysfs_root>`/admin 61 │ :ref:`kdamonds <sysfs_kdamonds>`/nr_kdamonds 62 │ │ :ref:`0 <sysfs_kdamond>`/state,pid 63 │ │ │ :ref:`contexts <sysfs_contexts>`/nr_contexts 64 │ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations 65 │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/ 66 │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us 67 │ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us 68 │ │ │ │ │ │ nr_regions/min,max 69 │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets 70 │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target 71 │ │ │ │ │ │ │ :ref:`regions <sysfs_regions>`/nr_regions 72 │ │ │ │ │ │ │ │ :ref:`0 <sysfs_region>`/start,end 73 │ │ │ │ │ │ │ │ ... 74 │ │ │ │ │ │ ... 75 │ │ │ │ │ :ref:`schemes <sysfs_schemes>`/nr_schemes 76 │ │ │ │ │ │ :ref:`0 <sysfs_scheme>`/action,target_nid,apply_interval_us 77 │ │ │ │ │ │ │ :ref:`access_pattern <sysfs_access_pattern>`/ 78 │ │ │ │ │ │ │ │ sz/min,max 79 │ │ │ │ │ │ │ │ nr_accesses/min,max 80 │ │ │ │ │ │ │ │ age/min,max 81 │ │ │ │ │ │ │ :ref:`quotas <sysfs_quotas>`/ms,bytes,reset_interval_ms,effective_bytes 82 │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil 83 │ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals>`/nr_goals 84 │ │ │ │ │ │ │ │ │ 0/target_metric,target_value,current_value 85 │ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks>`/metric,interval_us,high,mid,low 86 │ │ │ │ │ │ │ :ref:`{core_,ops_,}filters <sysfs_filters>`/nr_filters 87 │ │ │ │ │ │ │ │ 0/type,matching,allow,memcg_path,addr_start,addr_end,target_idx,min,max 88 │ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats>`/nr_tried,sz_tried,nr_applied,sz_applied,sz_ops_filter_passed,qt_exceeds 89 │ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions>`/total_bytes 90 │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age,sz_filter_passed 91 │ │ │ │ │ │ │ │ ... 92 │ │ │ │ │ │ ... 93 │ │ │ │ ... 94 │ │ ... 95 96.. _sysfs_root: 97 98Root 99---- 100 101The root of the DAMON sysfs interface is ``<sysfs>/kernel/mm/damon/``, and it 102has one directory named ``admin``. The directory contains the files for 103privileged user space programs' control of DAMON. User space tools or daemons 104having the root permission could use this directory. 105 106.. _sysfs_kdamonds: 107 108kdamonds/ 109--------- 110 111Under the ``admin`` directory, one directory, ``kdamonds``, which has files for 112controlling the kdamonds (refer to 113:ref:`design <damon_design_execution_model_and_data_structures>` for more 114details) exists. In the beginning, this directory has only one file, 115``nr_kdamonds``. Writing a number (``N``) to the file creates the number of 116child directories named ``0`` to ``N-1``. Each directory represents each 117kdamond. 118 119.. _sysfs_kdamond: 120 121kdamonds/<N>/ 122------------- 123 124In each kdamond directory, two files (``state`` and ``pid``) and one directory 125(``contexts``) exist. 126 127Reading ``state`` returns ``on`` if the kdamond is currently running, or 128``off`` if it is not running. 129 130Users can write below commands for the kdamond to the ``state`` file. 131 132- ``on``: Start running. 133- ``off``: Stop running. 134- ``commit``: Read the user inputs in the sysfs files except ``state`` file 135 again. 136- ``update_tuned_intervals``: Update the contents of ``sample_us`` and 137 ``aggr_us`` files of the kdamond with the auto-tuning applied ``sampling 138 interval`` and ``aggregation interval`` for the files. Please refer to 139 :ref:`intervals_goal section <damon_usage_sysfs_monitoring_intervals_goal>` 140 for more details. 141- ``commit_schemes_quota_goals``: Read the DAMON-based operation schemes' 142 :ref:`quota goals <sysfs_schemes_quota_goals>`. 143- ``update_schemes_stats``: Update the contents of stats files for each 144 DAMON-based operation scheme of the kdamond. For details of the stats, 145 please refer to :ref:`stats section <sysfs_schemes_stats>`. 146- ``update_schemes_tried_regions``: Update the DAMON-based operation scheme 147 action tried regions directory for each DAMON-based operation scheme of the 148 kdamond. For details of the DAMON-based operation scheme action tried 149 regions directory, please refer to 150 :ref:`tried_regions section <sysfs_schemes_tried_regions>`. 151- ``update_schemes_tried_bytes``: Update only ``.../tried_regions/total_bytes`` 152 files. 153- ``clear_schemes_tried_regions``: Clear the DAMON-based operating scheme 154 action tried regions directory for each DAMON-based operation scheme of the 155 kdamond. 156- ``update_schemes_effective_quotas``: Update the contents of 157 ``effective_bytes`` files for each DAMON-based operation scheme of the 158 kdamond. For more details, refer to :ref:`quotas directory <sysfs_quotas>`. 159 160If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. 161 162``contexts`` directory contains files for controlling the monitoring contexts 163that this kdamond will execute. 164 165.. _sysfs_contexts: 166 167kdamonds/<N>/contexts/ 168---------------------- 169 170In the beginning, this directory has only one file, ``nr_contexts``. Writing a 171number (``N``) to the file creates the number of child directories named as 172``0`` to ``N-1``. Each directory represents each monitoring context (refer to 173:ref:`design <damon_design_execution_model_and_data_structures>` for more 174details). At the moment, only one context per kdamond is supported, so only 175``0`` or ``1`` can be written to the file. 176 177.. _sysfs_context: 178 179contexts/<N>/ 180------------- 181 182In each context directory, two files (``avail_operations`` and ``operations``) 183and three directories (``monitoring_attrs``, ``targets``, and ``schemes``) 184exist. 185 186DAMON supports multiple types of :ref:`monitoring operations 187<damon_design_configurable_operations_set>`, including those for virtual address 188space and the physical address space. You can get the list of available 189monitoring operations set on the currently running kernel by reading 190``avail_operations`` file. Based on the kernel configuration, the file will 191list different available operation sets. Please refer to the :ref:`design 192<damon_operations_set>` for the list of all available operation sets and their 193brief explanations. 194 195You can set and get what type of monitoring operations DAMON will use for the 196context by writing one of the keywords listed in ``avail_operations`` file and 197reading from the ``operations`` file. 198 199.. _sysfs_monitoring_attrs: 200 201contexts/<N>/monitoring_attrs/ 202------------------------------ 203 204Files for specifying attributes of the monitoring including required quality 205and efficiency of the monitoring are in ``monitoring_attrs`` directory. 206Specifically, two directories, ``intervals`` and ``nr_regions`` exist in this 207directory. 208 209Under ``intervals`` directory, three files for DAMON's sampling interval 210(``sample_us``), aggregation interval (``aggr_us``), and update interval 211(``update_us``) exist. You can set and get the values in micro-seconds by 212writing to and reading from the files. 213 214Under ``nr_regions`` directory, two files for the lower-bound and upper-bound 215of DAMON's monitoring regions (``min`` and ``max``, respectively), which 216controls the monitoring overhead, exist. You can set and get the values by 217writing to and rading from the files. 218 219For more details about the intervals and monitoring regions range, please refer 220to the Design document (:doc:`/mm/damon/design`). 221 222.. _damon_usage_sysfs_monitoring_intervals_goal: 223 224contexts/<N>/monitoring_attrs/intervals/intervals_goal/ 225------------------------------------------------------- 226 227Under the ``intervals`` directory, one directory for automated tuning of 228``sample_us`` and ``aggr_us``, namely ``intervals_goal`` directory also exists. 229Under the directory, four files for the auto-tuning control, namely 230``access_bp``, ``aggrs``, ``min_sample_us`` and ``max_sample_us`` exist. 231Please refer to the :ref:`design document of the feature 232<damon_design_monitoring_intervals_autotuning>` for the internal of the tuning 233mechanism. Reading and writing the four files under ``intervals_goal`` 234directory shows and updates the tuning parameters that described in the 235:ref:design doc <damon_design_monitoring_intervals_autotuning>` with the same 236names. The tuning starts with the user-set ``sample_us`` and ``aggr_us``. The 237tuning-applied current values of the two intervals can be read from the 238``sample_us`` and ``aggr_us`` files after writing ``update_tuned_intervals`` to 239the ``state`` file. 240 241.. _sysfs_targets: 242 243contexts/<N>/targets/ 244--------------------- 245 246In the beginning, this directory has only one file, ``nr_targets``. Writing a 247number (``N``) to the file creates the number of child directories named ``0`` 248to ``N-1``. Each directory represents each monitoring target. 249 250.. _sysfs_target: 251 252targets/<N>/ 253------------ 254 255In each target directory, one file (``pid_target``) and one directory 256(``regions``) exist. 257 258If you wrote ``vaddr`` to the ``contexts/<N>/operations``, each target should 259be a process. You can specify the process to DAMON by writing the pid of the 260process to the ``pid_target`` file. 261 262.. _sysfs_regions: 263 264targets/<N>/regions 265------------------- 266 267In case of ``fvaddr`` or ``paddr`` monitoring operations sets, users are 268required to set the monitoring target address ranges. In case of ``vaddr`` 269operations set, it is not mandatory, but users can optionally set the initial 270monitoring region to specific address ranges. Please refer to the :ref:`design 271<damon_design_vaddr_target_regions_construction>` for more details. 272 273For such cases, users can explicitly set the initial monitoring target regions 274as they want, by writing proper values to the files under this directory. 275 276In the beginning, this directory has only one file, ``nr_regions``. Writing a 277number (``N``) to the file creates the number of child directories named ``0`` 278to ``N-1``. Each directory represents each initial monitoring target region. 279 280.. _sysfs_region: 281 282regions/<N>/ 283------------ 284 285In each region directory, you will find two files (``start`` and ``end``). You 286can set and get the start and end addresses of the initial monitoring target 287region by writing to and reading from the files, respectively. 288 289Each region should not overlap with others. ``end`` of directory ``N`` should 290be equal or smaller than ``start`` of directory ``N+1``. 291 292.. _sysfs_schemes: 293 294contexts/<N>/schemes/ 295--------------------- 296 297The directory for DAMON-based Operation Schemes (:ref:`DAMOS 298<damon_design_damos>`). Users can get and set the schemes by reading from and 299writing to files under this directory. 300 301In the beginning, this directory has only one file, ``nr_schemes``. Writing a 302number (``N``) to the file creates the number of child directories named ``0`` 303to ``N-1``. Each directory represents each DAMON-based operation scheme. 304 305.. _sysfs_scheme: 306 307schemes/<N>/ 308------------ 309 310In each scheme directory, seven directories (``access_pattern``, ``quotas``, 311``watermarks``, ``core_filters``, ``ops_filters``, ``filters``, ``stats``, and 312``tried_regions``) and three files (``action``, ``target_nid`` and 313``apply_interval``) exist. 314 315The ``action`` file is for setting and getting the scheme's :ref:`action 316<damon_design_damos_action>`. The keywords that can be written to and read 317from the file and their meaning are same to those of the list on 318:ref:`design doc <damon_design_damos_action>`. 319 320The ``target_nid`` file is for setting the migration target node, which is 321only meaningful when the ``action`` is either ``migrate_hot`` or 322``migrate_cold``. 323 324The ``apply_interval_us`` file is for setting and getting the scheme's 325:ref:`apply_interval <damon_design_damos>` in microseconds. 326 327.. _sysfs_access_pattern: 328 329schemes/<N>/access_pattern/ 330--------------------------- 331 332The directory for the target access :ref:`pattern 333<damon_design_damos_access_pattern>` of the given DAMON-based operation scheme. 334 335Under the ``access_pattern`` directory, three directories (``sz``, 336``nr_accesses``, and ``age``) each having two files (``min`` and ``max``) 337exist. You can set and get the access pattern for the given scheme by writing 338to and reading from the ``min`` and ``max`` files under ``sz``, 339``nr_accesses``, and ``age`` directories, respectively. Note that the ``min`` 340and the ``max`` form a closed interval. 341 342.. _sysfs_quotas: 343 344schemes/<N>/quotas/ 345------------------- 346 347The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given 348DAMON-based operation scheme. 349 350Under ``quotas`` directory, four files (``ms``, ``bytes``, 351``reset_interval_ms``, ``effective_bytes``) and two directores (``weights`` and 352``goals``) exist. 353 354You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and 355``reset interval`` in milliseconds by writing the values to the three files, 356respectively. Then, DAMON tries to use only up to ``time quota`` milliseconds 357for applying the ``action`` to memory regions of the ``access_pattern``, and to 358apply the action to only up to ``bytes`` bytes of memory regions within the 359``reset_interval_ms``. Setting both ``ms`` and ``bytes`` zero disables the 360quota limits unless at least one :ref:`goal <sysfs_schemes_quota_goals>` is 361set. 362 363The time quota is internally transformed to a size quota. Between the 364transformed size quota and user-specified size quota, smaller one is applied. 365Based on the user-specified :ref:`goal <sysfs_schemes_quota_goals>`, the 366effective size quota is further adjusted. Reading ``effective_bytes`` returns 367the current effective size quota. The file is not updated in real time, so 368users should ask DAMON sysfs interface to update the content of the file for 369the stats by writing a special keyword, ``update_schemes_effective_quotas`` to 370the relevant ``kdamonds/<N>/state`` file. 371 372Under ``weights`` directory, three files (``sz_permil``, 373``nr_accesses_permil``, and ``age_permil``) exist. 374You can set the :ref:`prioritization weights 375<damon_design_damos_quotas_prioritization>` for size, access frequency, and age 376in per-thousand unit by writing the values to the three files under the 377``weights`` directory. 378 379.. _sysfs_schemes_quota_goals: 380 381schemes/<N>/quotas/goals/ 382------------------------- 383 384The directory for the :ref:`automatic quota tuning goals 385<damon_design_damos_quotas_auto_tuning>` of the given DAMON-based operation 386scheme. 387 388In the beginning, this directory has only one file, ``nr_goals``. Writing a 389number (``N``) to the file creates the number of child directories named ``0`` 390to ``N-1``. Each directory represents each goal and current achievement. 391Among the multiple feedback, the best one is used. 392 393Each goal directory contains three files, namely ``target_metric``, 394``target_value`` and ``current_value``. Users can set and get the three 395parameters for the quota auto-tuning goals that specified on the :ref:`design 396doc <damon_design_damos_quotas_auto_tuning>` by writing to and reading from each 397of the files. Note that users should further write 398``commit_schemes_quota_goals`` to the ``state`` file of the :ref:`kdamond 399directory <sysfs_kdamond>` to pass the feedback to DAMON. 400 401.. _sysfs_watermarks: 402 403schemes/<N>/watermarks/ 404----------------------- 405 406The directory for the :ref:`watermarks <damon_design_damos_watermarks>` of the 407given DAMON-based operation scheme. 408 409Under the watermarks directory, five files (``metric``, ``interval_us``, 410``high``, ``mid``, and ``low``) for setting the metric, the time interval 411between check of the metric, and the three watermarks exist. You can set and 412get the five values by writing to the files, respectively. 413 414Keywords and meanings of those that can be written to the ``metric`` file are 415as below. 416 417 - none: Ignore the watermarks 418 - free_mem_rate: System's free memory rate (per thousand) 419 420The ``interval`` should written in microseconds unit. 421 422.. _sysfs_filters: 423 424schemes/<N>/{core\_,ops\_,}filters/ 425----------------------------------- 426 427Directories for :ref:`filters <damon_design_damos_filters>` of the given 428DAMON-based operation scheme. 429 430``core_filters`` and ``ops_filters`` directories are for the filters handled by 431the DAMON core layer and operations set layer, respectively. ``filters`` 432directory can be used for installing filters regardless of their handled 433layers. Filters that requested by ``core_filters`` and ``ops_filters`` will be 434installed before those of ``filters``. All three directories have same files. 435 436Use of ``filters`` directory can make expecting evaluation orders of given 437filters with the files under directory bit confusing. Users are hence 438recommended to use ``core_filters`` and ``ops_filters`` directories. The 439``filters`` directory could be deprecated in future. 440 441In the beginning, the directory has only one file, ``nr_filters``. Writing a 442number (``N``) to the file creates the number of child directories named ``0`` 443to ``N-1``. Each directory represents each filter. The filters are evaluated 444in the numeric order. 445 446Each filter directory contains nine files, namely ``type``, ``matching``, 447``allow``, ``memcg_path``, ``addr_start``, ``addr_end``, ``min``, ``max`` 448and ``target_idx``. To ``type`` file, you can write the type of the filter. 449Refer to :ref:`the design doc <damon_design_damos_filters>` for available type 450names, their meaning and on what layer those are handled. 451 452For ``memcg`` type, you can specify the memory cgroup of the interest by 453writing the path of the memory cgroup from the cgroups mount point to 454``memcg_path`` file. For ``addr`` type, you can specify the start and end 455address of the range (open-ended interval) to ``addr_start`` and ``addr_end`` 456files, respectively. For ``hugepage_size`` type, you can specify the minimum 457and maximum size of the range (closed interval) to ``min`` and ``max`` files, 458respectively. For ``target`` type, you can specify the index of the target 459between the list of the DAMON context's monitoring targets list to 460``target_idx`` file. 461 462You can write ``Y`` or ``N`` to ``matching`` file to specify whether the filter 463is for memory that matches the ``type``. You can write ``Y`` or ``N`` to 464``allow`` file to specify if applying the action to the memory that satisfies 465the ``type`` and ``matching`` should be allowed or not. 466 467For example, below restricts a DAMOS action to be applied to only non-anonymous 468pages of all memory cgroups except ``/having_care_already``.:: 469 470 # cd ops_filters/0/ 471 # echo 2 > nr_filters 472 # # disallow anonymous pages 473 echo anon > 0/type 474 echo Y > 0/matching 475 echo N > 0/allow 476 # # further filter out all cgroups except one at '/having_care_already' 477 echo memcg > 1/type 478 echo /having_care_already > 1/memcg_path 479 echo Y > 1/matching 480 echo N > 1/allow 481 482Refer to the :ref:`DAMOS filters design documentation 483<damon_design_damos_filters>` for more details including how multiple filters 484of different ``allow`` works, when each of the filters are supported, and 485differences on stats. 486 487.. _sysfs_schemes_stats: 488 489schemes/<N>/stats/ 490------------------ 491 492DAMON counts statistics for each scheme. This statistics can be used for 493online analysis or tuning of the schemes. Refer to :ref:`design doc 494<damon_design_damos_stat>` for more details about the stats. 495 496The statistics can be retrieved by reading the files under ``stats`` directory 497(``nr_tried``, ``sz_tried``, ``nr_applied``, ``sz_applied``, 498``sz_ops_filter_passed``, and ``qt_exceeds``), respectively. The files are not 499updated in real time, so you should ask DAMON sysfs interface to update the 500content of the files for the stats by writing a special keyword, 501``update_schemes_stats`` to the relevant ``kdamonds/<N>/state`` file. 502 503.. _sysfs_schemes_tried_regions: 504 505schemes/<N>/tried_regions/ 506-------------------------- 507 508This directory initially has one file, ``total_bytes``. 509 510When a special keyword, ``update_schemes_tried_regions``, is written to the 511relevant ``kdamonds/<N>/state`` file, DAMON updates the ``total_bytes`` file so 512that reading it returns the total size of the scheme tried regions, and creates 513directories named integer starting from ``0`` under this directory. Each 514directory contains files exposing detailed information about each of the memory 515region that the corresponding scheme's ``action`` has tried to be applied under 516this directory, during next :ref:`apply interval <damon_design_damos>` of the 517corresponding scheme. The information includes address range, ``nr_accesses``, 518and ``age`` of the region. 519 520Writing ``update_schemes_tried_bytes`` to the relevant ``kdamonds/<N>/state`` 521file will only update the ``total_bytes`` file, and will not create the 522subdirectories. 523 524The directories will be removed when another special keyword, 525``clear_schemes_tried_regions``, is written to the relevant 526``kdamonds/<N>/state`` file. 527 528The expected usage of this directory is investigations of schemes' behaviors, 529and query-like efficient data access monitoring results retrievals. For the 530latter use case, in particular, users can set the ``action`` as ``stat`` and 531set the ``access pattern`` as their interested pattern that they want to query. 532 533.. _sysfs_schemes_tried_region: 534 535tried_regions/<N>/ 536------------------ 537 538In each region directory, you will find five files (``start``, ``end``, 539``nr_accesses``, ``age``, and ``sz_filter_passed``). Reading the files will 540show the properties of the region that corresponding DAMON-based operation 541scheme ``action`` has tried to be applied. 542 543Example 544~~~~~~~ 545 546Below commands applies a scheme saying "If a memory region of size in [4KiB, 5478KiB] is showing accesses per aggregate interval in [0, 5] for aggregate 548interval in [10, 20], page out the region. For the paging out, use only up to 54910ms per second, and also don't page out more than 1GiB per second. Under the 550limitation, page out memory regions having longer age first. Also, check the 551free memory rate of the system every 5 seconds, start the monitoring and paging 552out when the free memory rate becomes lower than 50%, but stop it if the free 553memory rate becomes larger than 60%, or lower than 30%". :: 554 555 # cd <sysfs>/kernel/mm/damon/admin 556 # # populate directories 557 # echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts; 558 # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes 559 # cd kdamonds/0/contexts/0/schemes/0 560 # # set the basic access pattern and the action 561 # echo 4096 > access_pattern/sz/min 562 # echo 8192 > access_pattern/sz/max 563 # echo 0 > access_pattern/nr_accesses/min 564 # echo 5 > access_pattern/nr_accesses/max 565 # echo 10 > access_pattern/age/min 566 # echo 20 > access_pattern/age/max 567 # echo pageout > action 568 # # set quotas 569 # echo 10 > quotas/ms 570 # echo $((1024*1024*1024)) > quotas/bytes 571 # echo 1000 > quotas/reset_interval_ms 572 # # set watermark 573 # echo free_mem_rate > watermarks/metric 574 # echo 5000000 > watermarks/interval_us 575 # echo 600 > watermarks/high 576 # echo 500 > watermarks/mid 577 # echo 300 > watermarks/low 578 579Please note that it's highly recommended to use user space tools like `damo 580<https://github.com/damonitor/damo>`_ rather than manually reading and writing 581the files as above. Above is only for an example. 582 583.. _tracepoint: 584 585Tracepoints for Monitoring Results 586================================== 587 588Users can get the monitoring results via the :ref:`tried_regions 589<sysfs_schemes_tried_regions>`. The interface is useful for getting a 590snapshot, but it could be inefficient for fully recording all the monitoring 591results. For the purpose, two trace points, namely ``damon:damon_aggregated`` 592and ``damon:damos_before_apply``, are provided. ``damon:damon_aggregated`` 593provides the whole monitoring results, while ``damon:damos_before_apply`` 594provides the monitoring results for regions that each DAMON-based Operation 595Scheme (:ref:`DAMOS <damon_design_damos>`) is gonna be applied. Hence, 596``damon:damos_before_apply`` is more useful for recording internal behavior of 597DAMOS, or DAMOS target access 598:ref:`pattern <damon_design_damos_access_pattern>` based query-like efficient 599monitoring results recording. 600 601While the monitoring is turned on, you could record the tracepoint events and 602show results using tracepoint supporting tools like ``perf``. For example:: 603 604 # echo on > kdamonds/0/state 605 # perf record -e damon:damon_aggregated & 606 # sleep 5 607 # kill 9 $(pidof perf) 608 # echo off > kdamonds/0/state 609 # perf script 610 kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864 611 [...] 612 613Each line of the perf script output represents each monitoring region. The 614first five fields are as usual other tracepoint outputs. The sixth field 615(``target_id=X``) shows the ide of the monitoring target of the region. The 616seventh field (``nr_regions=X``) shows the total number of monitoring regions 617for the target. The eighth field (``X-Y:``) shows the start (``X``) and end 618(``Y``) addresses of the region in bytes. The ninth field (``X``) shows the 619``nr_accesses`` of the region (refer to 620:ref:`design <damon_design_region_based_sampling>` for more details of the 621counter). Finally the tenth field (``X``) shows the ``age`` of the region 622(refer to :ref:`design <damon_design_age_tracking>` for more details of the 623counter). 624 625If the event was ``damon:damos_beofre_apply``, the ``perf script`` output would 626be somewhat like below:: 627 628 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 629 [...] 630 631Each line of the output represents each monitoring region that each DAMON-based 632Operation Scheme was about to be applied at the traced time. The first five 633fields are as usual. It shows the index of the DAMON context (``ctx_idx=X``) 634of the scheme in the list of the contexts of the context's kdamond, the index 635of the scheme (``scheme_idx=X``) in the list of the schemes of the context, in 636addition to the output of ``damon_aggregated`` tracepoint. 637