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