diff options
Diffstat (limited to 'Documentation/admin-guide/mm/damon/usage.rst')
| -rw-r--r-- | Documentation/admin-guide/mm/damon/usage.rst | 147 |
1 files changed, 104 insertions, 43 deletions
diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst index da94feb97ed1..9d23144bf985 100644 --- a/Documentation/admin-guide/mm/damon/usage.rst +++ b/Documentation/admin-guide/mm/damon/usage.rst @@ -59,41 +59,47 @@ Files Hierarchy The files hierarchy of DAMON sysfs interface is shown below. In the below figure, parents-children relations are represented with indentations, each directory is having ``/`` suffix, and files in each directory are separated by -comma (","). :: - - /sys/kernel/mm/damon/admin - │ kdamonds/nr_kdamonds - │ │ 0/state,pid - │ │ │ contexts/nr_contexts - │ │ │ │ 0/avail_operations,operations - │ │ │ │ │ monitoring_attrs/ +comma (","). + +.. parsed-literal:: + + :ref:`/sys/kernel/mm/damon <sysfs_root>`/admin + │ :ref:`kdamonds <sysfs_kdamonds>`/nr_kdamonds + │ │ :ref:`0 <sysfs_kdamond>`/state,pid + │ │ │ :ref:`contexts <sysfs_contexts>`/nr_contexts + │ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations + │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/ │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us │ │ │ │ │ │ nr_regions/min,max - │ │ │ │ │ targets/nr_targets - │ │ │ │ │ │ 0/pid_target - │ │ │ │ │ │ │ regions/nr_regions - │ │ │ │ │ │ │ │ 0/start,end + │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets + │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target + │ │ │ │ │ │ │ :ref:`regions <sysfs_regions>`/nr_regions + │ │ │ │ │ │ │ │ :ref:`0 <sysfs_region>`/start,end │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... - │ │ │ │ │ schemes/nr_schemes - │ │ │ │ │ │ 0/action,apply_interval_us - │ │ │ │ │ │ │ access_pattern/ + │ │ │ │ │ :ref:`schemes <sysfs_schemes>`/nr_schemes + │ │ │ │ │ │ :ref:`0 <sysfs_scheme>`/action,apply_interval_us + │ │ │ │ │ │ │ :ref:`access_pattern <sysfs_access_pattern>`/ │ │ │ │ │ │ │ │ sz/min,max │ │ │ │ │ │ │ │ nr_accesses/min,max │ │ │ │ │ │ │ │ age/min,max - │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms + │ │ │ │ │ │ │ :ref:`quotas <sysfs_quotas>`/ms,bytes,reset_interval_ms │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil - │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low - │ │ │ │ │ │ │ filters/nr_filters + │ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals>`/nr_goals + │ │ │ │ │ │ │ │ │ 0/target_value,current_value + │ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks>`/metric,interval_us,high,mid,low + │ │ │ │ │ │ │ :ref:`filters <sysfs_filters>`/nr_filters │ │ │ │ │ │ │ │ 0/type,matching,memcg_id - │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds - │ │ │ │ │ │ │ tried_regions/total_bytes + │ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats>`/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds + │ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions>`/total_bytes │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age │ │ │ │ │ │ │ │ ... │ │ │ │ │ │ ... │ │ │ │ ... │ │ ... +.. _sysfs_root: + Root ---- @@ -102,6 +108,8 @@ has one directory named ``admin``. The directory contains the files for privileged user space programs' control of DAMON. User space tools or daemons having the root permission could use this directory. +.. _sysfs_kdamonds: + kdamonds/ --------- @@ -113,6 +121,8 @@ details) exists. In the beginning, this directory has only one file, child directories named ``0`` to ``N-1``. Each directory represents each kdamond. +.. _sysfs_kdamond: + kdamonds/<N>/ ------------- @@ -120,29 +130,37 @@ In each kdamond directory, two files (``state`` and ``pid``) and one directory (``contexts``) exist. Reading ``state`` returns ``on`` if the kdamond is currently running, or -``off`` if it is not running. Writing ``on`` or ``off`` makes the kdamond be -in the state. Writing ``commit`` to the ``state`` file makes kdamond reads the -user inputs in the sysfs files except ``state`` file again. Writing -``update_schemes_stats`` to ``state`` file updates the contents of stats files -for each DAMON-based operation scheme of the kdamond. For details of the -stats, please refer to :ref:`stats section <sysfs_schemes_stats>`. - -Writing ``update_schemes_tried_regions`` to ``state`` file updates the -DAMON-based operation scheme action tried regions directory for each -DAMON-based operation scheme of the kdamond. Writing -``update_schemes_tried_bytes`` to ``state`` file updates only -``.../tried_regions/total_bytes`` files. Writing -``clear_schemes_tried_regions`` to ``state`` file clears the DAMON-based -operating scheme action tried regions directory for each DAMON-based operation -scheme of the kdamond. For details of the DAMON-based operation scheme action -tried regions directory, please refer to :ref:`tried_regions section -<sysfs_schemes_tried_regions>`. +``off`` if it is not running. + +Users can write below commands for the kdamond to the ``state`` file. + +- ``on``: Start running. +- ``off``: Stop running. +- ``commit``: Read the user inputs in the sysfs files except ``state`` file + again. +- ``commit_schemes_quota_goals``: Read the DAMON-based operation schemes' + :ref:`quota goals <sysfs_schemes_quota_goals>`. +- ``update_schemes_stats``: Update the contents of stats files for each + DAMON-based operation scheme of the kdamond. For details of the stats, + please refer to :ref:`stats section <sysfs_schemes_stats>`. +- ``update_schemes_tried_regions``: Update the DAMON-based operation scheme + action tried regions directory for each DAMON-based operation scheme of the + kdamond. For details of the DAMON-based operation scheme action tried + regions directory, please refer to + :ref:`tried_regions section <sysfs_schemes_tried_regions>`. +- ``update_schemes_tried_bytes``: Update only ``.../tried_regions/total_bytes`` + files. +- ``clear_schemes_tried_regions``: Clear the DAMON-based operating scheme + action tried regions directory for each DAMON-based operation scheme of the + kdamond. If the state is ``on``, reading ``pid`` shows the pid of the kdamond thread. ``contexts`` directory contains files for controlling the monitoring contexts that this kdamond will execute. +.. _sysfs_contexts: + kdamonds/<N>/contexts/ ---------------------- @@ -153,7 +171,7 @@ number (``N``) to the file creates the number of child directories named as details). At the moment, only one context per kdamond is supported, so only ``0`` or ``1`` can be written to the file. -.. _sysfs_contexts: +.. _sysfs_context: contexts/<N>/ ------------- @@ -203,6 +221,8 @@ writing to and rading from the files. For more details about the intervals and monitoring regions range, please refer to the Design document (:doc:`/mm/damon/design`). +.. _sysfs_targets: + contexts/<N>/targets/ --------------------- @@ -210,6 +230,8 @@ In the beginning, this directory has only one file, ``nr_targets``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each monitoring target. +.. _sysfs_target: + targets/<N>/ ------------ @@ -244,6 +266,8 @@ In the beginning, this directory has only one file, ``nr_regions``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each initial monitoring target region. +.. _sysfs_region: + regions/<N>/ ------------ @@ -254,6 +278,8 @@ region by writing to and reading from the files, respectively. Each region should not overlap with others. ``end`` of directory ``N`` should be equal or smaller than ``start`` of directory ``N+1``. +.. _sysfs_schemes: + contexts/<N>/schemes/ --------------------- @@ -265,6 +291,8 @@ In the beginning, this directory has only one file, ``nr_schemes``. Writing a number (``N``) to the file creates the number of child directories named ``0`` to ``N-1``. Each directory represents each DAMON-based operation scheme. +.. _sysfs_scheme: + schemes/<N>/ ------------ @@ -277,7 +305,7 @@ The ``action`` file is for setting and getting the scheme's :ref:`action from the file and their meaning are as below. Note that support of each action depends on the running DAMON operations set -:ref:`implementation <sysfs_contexts>`. +:ref:`implementation <sysfs_context>`. - ``willneed``: Call ``madvise()`` for the region with ``MADV_WILLNEED``. Supported by ``vaddr`` and ``fvaddr`` operations set. @@ -299,6 +327,8 @@ Note that support of each action depends on the running DAMON operations set The ``apply_interval_us`` file is for setting and getting the scheme's :ref:`apply_interval <damon_design_damos>` in microseconds. +.. _sysfs_access_pattern: + schemes/<N>/access_pattern/ --------------------------- @@ -312,6 +342,8 @@ to and reading from the ``min`` and ``max`` files under ``sz``, ``nr_accesses``, and ``age`` directories, respectively. Note that the ``min`` and the ``max`` form a closed interval. +.. _sysfs_quotas: + schemes/<N>/quotas/ ------------------- @@ -319,8 +351,7 @@ The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given DAMON-based operation scheme. Under ``quotas`` directory, three files (``ms``, ``bytes``, -``reset_interval_ms``) and one directory (``weights``) having three files -(``sz_permil``, ``nr_accesses_permil``, and ``age_permil``) in it exist. +``reset_interval_ms``) and two directores (``weights`` and ``goals``) exist. You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and ``reset interval`` in milliseconds by writing the values to the three files, @@ -330,11 +361,37 @@ apply the action to only up to ``bytes`` bytes of memory regions within the ``reset_interval_ms``. Setting both ``ms`` and ``bytes`` zero disables the quota limits. -You can also set the :ref:`prioritization weights +Under ``weights`` directory, three files (``sz_permil``, +``nr_accesses_permil``, and ``age_permil``) exist. +You can set the :ref:`prioritization weights <damon_design_damos_quotas_prioritization>` for size, access frequency, and age in per-thousand unit by writing the values to the three files under the ``weights`` directory. +.. _sysfs_schemes_quota_goals: + +schemes/<N>/quotas/goals/ +------------------------- + +The directory for the :ref:`automatic quota tuning goals +<damon_design_damos_quotas_auto_tuning>` of the given DAMON-based operation +scheme. + +In the beginning, this directory has only one file, ``nr_goals``. Writing a +number (``N``) to the file creates the number of child directories named ``0`` +to ``N-1``. Each directory represents each goal and current achievement. +Among the multiple feedback, the best one is used. + +Each goal directory contains two files, namely ``target_value`` and +``current_value``. Users can set and get any number to those files to set the +feedback. User space main workload's latency or throughput, system metrics +like free memory ratio or memory pressure stall time (PSI) could be example +metrics for the values. Note that users should write +``commit_schemes_quota_goals`` to the ``state`` file of the :ref:`kdamond +directory <sysfs_kdamond>` to pass the feedback to DAMON. + +.. _sysfs_watermarks: + schemes/<N>/watermarks/ ----------------------- @@ -354,6 +411,8 @@ as below. The ``interval`` should written in microseconds unit. +.. _sysfs_filters: + schemes/<N>/filters/ -------------------- @@ -394,7 +453,7 @@ pages of all memory cgroups except ``/having_care_already``.:: echo N > 1/matching Note that ``anon`` and ``memcg`` filters are currently supported only when -``paddr`` :ref:`implementation <sysfs_contexts>` is being used. +``paddr`` :ref:`implementation <sysfs_context>` is being used. Also, memory regions that are filtered out by ``addr`` or ``target`` filters are not counted as the scheme has tried to those, while regions that filtered @@ -449,6 +508,8 @@ and query-like efficient data access monitoring results retrievals. For the latter use case, in particular, users can set the ``action`` as ``stat`` and set the ``access pattern`` as their interested pattern that they want to query. +.. _sysfs_schemes_tried_region: + tried_regions/<N>/ ------------------ |