mm/damon/usage.rst

1 .. SPDX-License-Identifier: GPL-2.0
9 - *DAMON user space tool.*
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.
16 - *sysfs interface.*
23 - *Kernel Space Programming Interface.*
51 ---------------
54 figure, parents-children relations are represented with indentations, each
58 .. parsed-literal::
87     │ │ │ │ │ │ │ │ 0/type,matching,allow,memcg_path,addr_start,addr_end,target_idx,min,max
99 ----
109 ---------
116 child directories named ``0`` to ``N-1``.  Each directory represents each
122 -------------
132 - ``on``: Start running.
133 - ``off``: Stop running.
134 - ``commit``: Read the user inputs in the sysfs files except ``state`` file
136 - ``update_tuned_intervals``: Update the contents of ``sample_us`` and
137   ``aggr_us`` files of the kdamond with the auto-tuning applied ``sampling
141 - ``commit_schemes_quota_goals``: Read the DAMON-based operation schemes'
143 - ``update_schemes_stats``: Update the contents of stats files for each
144   DAMON-based operation scheme of the kdamond.  For details of the stats,
146 - ``update_schemes_tried_regions``: Update the DAMON-based operation scheme
147   action tried regions directory for each DAMON-based operation scheme of the
148   kdamond.  For details of the DAMON-based operation scheme action tried
151 - ``update_schemes_tried_bytes``: Update only ``.../tried_regions/total_bytes``
153 - ``clear_schemes_tried_regions``: Clear the DAMON-based operating scheme
154   action tried regions directory for each DAMON-based operation scheme of the
156 - ``update_schemes_effective_quotas``: Update the contents of
157   ``effective_bytes`` files for each DAMON-based operation scheme of the
168 ----------------------
172 ``0`` to ``N-1``.  Each directory represents each monitoring context (refer to
180 -------------
189 monitoring operations set on the currently running kernel by reading
195 You can set and get what type of monitoring operations DAMON will use for the
202 ------------------------------
211 (``update_us``) exist.  You can set and get the values in micro-seconds by
214 Under ``nr_regions`` directory, two files for the lower-bound and upper-bound
216 controls the monitoring overhead, exist.  You can set and get the values by
225 -------------------------------------------------------
229 Under the directory, four files for the auto-tuning control, namely
236 names.  The tuning starts with the user-set ``sample_us`` and ``aggr_us``.  The
237 tuning-applied current values of the two intervals can be read from the
244 ---------------------
248 to ``N-1``.  Each directory represents each monitoring target.
253 ------------
265 -------------------
268 required to set the monitoring target address ranges.  In case of ``vaddr``
269 operations set, it is not mandatory, but users can optionally set the initial
273 For such cases, users can explicitly set the initial monitoring target regions
278 to ``N-1``.  Each directory represents each initial monitoring target region.
283 ------------
286 can set and get the start and end addresses of the initial monitoring target
295 ---------------------
297 The directory for DAMON-based Operation Schemes (:ref:`DAMOS
298 <damon_design_damos>`).  Users can get and set the schemes by reading from and
303 to ``N-1``.  Each directory represents each DAMON-based operation scheme.
308 ------------
330 ---------------------------
333 <damon_design_damos_access_pattern>` of the given DAMON-based operation scheme.
337 exist.  You can set and get the access pattern for the given scheme by writing
345 -------------------
348 DAMON-based operation scheme.
354 You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and
356 respectively.  Then, DAMON tries to use only up to ``time quota`` milliseconds
361 set.
363 The time quota is internally transformed to a size quota.  Between the
364 transformed size quota and user-specified size quota, smaller one is applied.
365 Based on the user-specified :ref:`goal <sysfs_schemes_quota_goals>`, the
367 the current effective size quota.  The file is not updated in real time, so
374 You can set the :ref:`prioritization weights
376 in per-thousand unit by writing the values to the three files under the
382 -------------------------
385 <damon_design_damos_quotas_auto_tuning>` of the given DAMON-based operation
390 to ``N-1``.  Each directory represents each goal and current achievement.
394 ``target_value`` and ``current_value``.  Users can set and get the three
395 parameters for the quota auto-tuning goals that specified on the :ref:`design
404 -----------------------
407 given DAMON-based operation scheme.
410 ``high``, ``mid``, and ``low``) for setting the metric, the time interval
411 between check of the metric, and the three watermarks exist.  You can set and
417  - none: Ignore the watermarks
418  - free_mem_rate: System's free memory rate (per thousand)
425 -----------------------------------
428 DAMON-based operation scheme.
431 the DAMON core layer and operations set layer, respectively.  ``filters``
443 to ``N-1``.  Each directory represents each filter.  The filters are evaluated
447 ``allow``, ``memcg_path``, ``addr_start``, ``addr_end``, ``min``, ``max``
455 address of the range (open-ended interval) to ``addr_start`` and ``addr_end``
464 ``allow`` file to specify if applying the action to the memory that satisfies
467 For example, below restricts a DAMOS action to be applied to only non-anonymous
475     echo N > 0/allow
480     echo N > 1/allow
484 of different ``allow`` works, when each of the filters are supported, and
490 ------------------
499 updated in real time, so you should ask DAMON sysfs interface to update the
506 --------------------------
529 and query-like efficient data access monitoring results retrievals.  For the
530 latter use case, in particular, users can set the ``action`` as ``stat`` and
531 set the ``access pattern`` as their interested pattern that they want to query.
536 ------------------
540 show the properties of the region that corresponding DAMON-based operation
560     # # set the basic access pattern and the action
568     # # set quotas
572     # # set watermark
594 provides the monitoring results for regions that each DAMON-based Operation
598 :ref:`pattern <damon_design_damos_access_pattern>` based query-like efficient
605     # perf record -e damon:damon_aggregated &
610 …7] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864
617 for the target.  The eighth field (``X-Y:``) shows the start (``X``) and end
628 …os_before_apply: ctx_idx=0 scheme_idx=0 target_idx=0 nr_regions=11 121932607488-135128711168: 0 136
631 Each line of the output represents each monitoring region that each DAMON-based
632 Operation Scheme was about to be applied at the traced time.  The first five