Commit 114b4808 authored by SeongJae Park's avatar SeongJae Park Committed by Andrew Morton
Browse files

Docs/admin-guide/mm/damon/usage: update for {core,ops}_filters directories 

Document {core,ops}_filters directories on usage document.

Link: https://lkml.kernel.org/r/20250305222733.59089-9-sj@kernel.org


Signed-off-by: default avatarSeongJae Park <sj@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
parent 899e4c14

Documentation/admin-guide/mm/damon/usage.rst

+22 −9
Original line number Diff line number Diff line
@@ -83,7 +83,7 @@ comma (","). 
    │ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals>`/nr_goals

    │ │ │ │ │ │ │ │ │ 0/target_metric,target_value,current_value

    │ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks>`/metric,interval_us,high,mid,low

    │ │ │ │ │ │ │ :ref:`filters <sysfs_filters>`/nr_filters

    │ │ │ │ │ │ │ :ref:`{core_,ops_,}filters <sysfs_filters>`/nr_filters

    │ │ │ │ │ │ │ │ 0/type,matching,allow,memcg_path,addr_start,addr_end,target_idx,min,max

    │ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats>`/nr_tried,sz_tried,nr_applied,sz_applied,sz_ops_filter_passed,qt_exceeds

    │ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions>`/total_bytes
@@ -307,9 +307,10 @@ to ``N-1``. Each directory represents each DAMON-based operation scheme. 
schemes/<N>/

------------



In each scheme directory, five directories (``access_pattern``, ``quotas``,

``watermarks``, ``filters``, ``stats``, and ``tried_regions``) and three files

(``action``, ``target_nid`` and ``apply_interval``) exist.

In each scheme directory, seven directories (``access_pattern``, ``quotas``,

``watermarks``, ``core_filters``, ``ops_filters``, ``filters``, ``stats``, and

``tried_regions``) and three files (``action``, ``target_nid`` and

``apply_interval``) exist.



The ``action`` file is for setting and getting the scheme's :ref:`action

<damon_design_damos_action>`.  The keywords that can be written to and read
@@ -420,13 +421,24 @@ The ``interval`` should written in microseconds unit. 


.. _sysfs_filters:



schemes/<N>/filters/

--------------------

schemes/<N>/{core\_,ops\_,}filters/

-----------------------------------



The directory for the :ref:`filters <damon_design_damos_filters>` of the given

Directories for :ref:`filters <damon_design_damos_filters>` of the given

DAMON-based operation scheme.



In the beginning, this directory has only one file, ``nr_filters``.  Writing a

``core_filters`` and ``ops_filters`` directories are for the filters handled by

the DAMON core layer and operations set layer, respectively.  ``filters``

directory can be used for installing filters regardless of their handled

layers.  Filters that requested by ``core_filters`` and ``ops_filters`` will be

installed before those of ``filters``.  All three directories have same files.



Use of ``filters`` directory can make expecting evaluation orders of given

filters with the files under directory bit confusing.  Users are hence

recommended to use ``core_filters`` and ``ops_filters`` directories.  The

``filters`` directory could be deprecated in future.



In the beginning, the directory has only one file, ``nr_filters``.  Writing a

number (``N``) to the file creates the number of child directories named ``0``

to ``N-1``.  Each directory represents each filter.  The filters are evaluated

in the numeric order.
@@ -435,7 +447,7 @@ Each filter directory contains nine files, namely ``type``, ``matching``, 
``allow``, ``memcg_path``, ``addr_start``, ``addr_end``, ``min``, ``max``

and ``target_idx``.  To ``type`` file, you can write the type of the filter.

Refer to :ref:`the design doc <damon_design_damos_filters>` for available type

names and their meanings.

names, their meaning and on what layer those are handled.



For ``memcg`` type, you can specify the memory cgroup of the interest by

writing the path of the memory cgroup from the cgroups mount point to
@@ -455,6 +467,7 @@ the ``type`` and ``matching`` should be allowed or not. 
For example, below restricts a DAMOS action to be applied to only non-anonymous

pages of all memory cgroups except ``/having_care_already``.::



    # cd ops_filters/0/

    # echo 2 > nr_filters

    # # disallow anonymous pages

    echo anon > 0/type