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