[PATCH 0/8] mm/damon: add sysfs dirs for managing DAMOS filters based on handling layers

[PATCH 0/8] mm/damon: add sysfs dirs for managing DAMOS filters based on handling layers

[SeongJae Park]

DAMOS filters are categorized into two groups based on their handling
layers, namely core and operations layers.  The categorization affects
when each filter is evaluated.  Core layer handled filters are evaluated
first.  The order meant nothing before, but introduction of allow
filters changed that.

DAMOS sysfs interface provides single directory for filters, namely
'filters'.  Users can install any filters in any order there.  DAMON
will internally categorize those into core and operations layer handled
ones, and apply the evaluation order rule.  The ordering rule is clearly
documented.  But the interface could still confuse users since it is
allowed to install filters on the directory in mixed ways.

Add two sysfs directories for managing filters by handling layer, namely
'core_filters' and 'ops_filters' for filters that handled by core and
operations layer, respectively.  Those are avoided to be used for
installing filters that not handled by the assumed layer.

For backward compatibility, keep 'filters' directory with its curernt
behavior.  Filters installed in the directory will be added to DAMON
after those of 'core_filters' and 'ops_filters' directories, with the
automatic categorizations.  Also recommend users to use the new
directories, and noticee 'filters' directory could be deprecated in
future.

Note that new directories provide all features that were provided with
'filters', but just in a more clear way.  Deprecating 'filters' is not
expected to make an irreversal breakge.

Also note that this patch series depend on filters default
behavior change patch series[1].

[1] https://lore.kernel.org/20250220193509.36379-1-sj@kernel.org

SeongJae Park (8):
  mm/damon/sysfs-schemes: let damon_sysfs_scheme_set_filters() be used
    for different named directories
  mm/damon/sysfs-schemes: implement core_filters and ops_filters
    directories
  mm/damon/sysfs-schemes: commit filters in {core,ops}_filters
    directories
  mm/damon/core: expose damos_filter_for_ops() to DAMON kernel API
    callers
  mm/damon/sysfs-schemes: set filters handling layer of directories
  mm/damon/sysfs-schemes: return error for wrong filter type on given
    directory
  Docs/ABI/damon: document {core,ops}_filters directories
  Docs/admin-guide/mm/damon/usage: update for {core,ops}_filters
    directories

 .../ABI/testing/sysfs-kernel-mm-damon         |  16 +++
 Documentation/admin-guide/mm/damon/usage.rst  |  31 +++--
 include/linux/damon.h                         |   1 +
 mm/damon/core.c                               |   9 +-
 mm/damon/sysfs-schemes.c                      | 119 ++++++++++++++++--
 5 files changed, 153 insertions(+), 23 deletions(-)


base-commit: c6ff92c642d665270c718aece87bc33d264d2c00
-- 
2.39.5

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

[SeongJae Park]

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

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/admin-guide/mm/damon/usage.rst | 31 ++++++++++++++------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
index dc37bba96273..4b25c25d4f4f 100644
--- a/Documentation/admin-guide/mm/damon/usage.rst
+++ b/Documentation/admin-guide/mm/damon/usage.rst
@@ -82,7 +82,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
@@ -282,9 +282,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
@@ -395,13 +396,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.
@@ -410,7 +422,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
@@ -430,6 +442,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
-- 
2.39.5

Re: [PATCH 0/8] mm/damon: add sysfs dirs for managing DAMOS filters based on handling layers

[SeongJae Park]

[...]
> Also note that this patch series depend on filters default
> behavior change patch series[1].
> 
> [1] https://lore.kernel.org/20250220193509.36379-1-sj@kernel.org

This is an RFC that depends on another RFC patch series I listed above.  But I
made yet another mistake on the subject.  Sorry if it made any confusion.


Thanks,
SJ

[...]

Re: [PATCH 8/8] Docs/admin-guide/mm/damon/usage: update for {core,ops}_filters directories

[SeongJae Park]

On Thu, 20 Feb 2025 11:46:46 -0800 SeongJae Park <sj@kernel.org> wrote:

> Document {core,ops}_filters directories on usage document.
> 
> Signed-off-by: SeongJae Park <sj@kernel.org>
> ---
>  Documentation/admin-guide/mm/damon/usage.rst | 31 ++++++++++++++------
>  1 file changed, 22 insertions(+), 9 deletions(-)
> 
> diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
> index dc37bba96273..4b25c25d4f4f 100644
> --- a/Documentation/admin-guide/mm/damon/usage.rst
> +++ b/Documentation/admin-guide/mm/damon/usage.rst
> @@ -82,7 +82,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
> @@ -282,9 +282,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
> @@ -395,13 +396,24 @@ The ``interval`` should written in microseconds unit.
>  
>  .. _sysfs_filters:
>  
> -schemes/<N>/filters/
> ---------------------
> +schemes/<N>/{core_,ops_,}filters/
> +-------------------------------

Just found this causes below document build warning and error during 'make
htmldocs':

    Documentation/admin-guide/mm/damon/usage.rst:425: WARNING: Title underline too short.
    Documentation/admin-guide/mm/damon/usage.rst:425: ERROR: Unknown target name: "core".

I will fix this in the next spin as below.

    -schemes/<N>/{core_,ops_,}filters/
    --------------------------------
    +schemes/<N>/{core\_,ops\_,}filters/
    +-----------------------------------


Thanks,
SJ

[...]

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

[SeongJae Park]

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

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/admin-guide/mm/damon/usage.rst | 31 ++++++++++++++------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
index de549dd18107..ced2013db3df 100644
--- a/Documentation/admin-guide/mm/damon/usage.rst
+++ b/Documentation/admin-guide/mm/damon/usage.rst
@@ -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
-- 
2.39.5