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