Docs/mm/damon: misc DAMOS filters documentation fixes and improves

PATCH Applied SeongJae Park 1 participant 6 messages Feb 18, 2025

Subsystems (4)

Memory management Documentation MM misc DAMON

lore

Share & tools

lore

SeongJae Park

author maintainer

2025-02-18 22:37 UTC #0 lore raw

cover Docs/mm/damon: misc DAMOS filters documentation fixes and improves

Fix and improve DAMOS filters documentation by fixing a copy-paste typo, adding hugepage_size filter documentation on design doc, moving logic details from usage to design, clarify DAMOS filters handling sequence based on handling layer, and re-organizing the filters type list for easier understanding of the handling sequence.

SeongJae Park (5):
Docs/mm/damon/design: fix typo on DAMOS filters usage doc link Docs/mm/damon/design: document hugepage_size filter Docs/damon: move DAMOS filter type names and meaning to design doc Docs/mm/damon/design: clarify handling layer based filters evaluation
sequence
Docs/mm/damon/design: categorize DAMOS filter types based on handling
layer

 Documentation/admin-guide/mm/damon/usage.rst | 28 ++++-----
 Documentation/mm/damon/design.rst            | 63 ++++++++++----------
 2 files changed, 45 insertions(+), 46 deletions(-)

base-commit: 754c08bc32083abf5b6b43362b8d6977d99cd9df

Signature · 1 line

2.39.5

SeongJae Park

author maintainer

2025-02-18 22:37 UTC #1 lore raw

PATCH 1/5 Docs/mm/damon/design: fix typo on DAMOS filters usage doc link

The link from DAMOS filters design doc to usage doc has a typo calling filters as watermarks. Fix it.

Fixes d31f5626a0e1 ("Docs/mm/damon/design: add links to sections of DAMON sysfs interface usage doc")

Signed-off-by SeongJae Park <[email protected]>

---
 Documentation/mm/damon/design.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

Documentation/mm/damon/design.rst +1 -1

index e28c6a1b40ae..12ae7e1209c8 100644
@@ -617,7 +617,7 @@ Below ``type`` of filters are currently supported.
     - Applied to pages that belonging to a given DAMON monitoring target.
     - Handled by the core logic.
 
-To know how user-space can set the watermarks via :ref:`DAMON sysfs interface
+To know how user-space can set the filters via :ref:`DAMON sysfs interface
 <sysfs_interface>`, refer to :ref:`filters <sysfs_filters>` part of the
 documentation.

Signature · 1 line

2.39.5

SeongJae Park

author maintainer

2025-02-18 22:37 UTC #2 lore raw

PATCH 2/5 Docs/mm/damon/design: document hugepage_size filter

In reply to SeongJae Park

'hugepage_size' DAMOS filter type is not documented on the design doc. Add a description of the type.

Signed-off-by SeongJae Park <[email protected]>

---
 Documentation/mm/damon/design.rst | 3 +++
 1 file changed, 3 insertions(+)

Documentation/mm/damon/design.rst +3 -0

index 12ae7e1209c8..a959c081bc59 100644
@@ -610,6 +610,9 @@ Below ``type`` of filters are currently supported.
     - Applied to pages that are accessed after the last access check from the
       scheme.
     - Handled by operations set layer.  Supported by only ``paddr`` set.
+- pages that managed in a given size range
+    - Applied to pages that managed in a given size range.
+    - Handled by operations set layer.  Supported by only ``paddr`` set.
 - address range
     - Applied to pages that belonging to a given address range.
     - Handled by the core logic.

Signature · 1 line

2.39.5

SeongJae Park

author maintainer

2025-02-18 22:37 UTC #3 lore raw

PATCH 3/5 Docs/damon: move DAMOS filter type names and meaning to design doc

In reply to SeongJae Park

DAMON sysfs usage doc is describing DAMOS filter type names and their meanings in short. The design doc is providing the short meaning and detailed descriptions, too. This is unnecessary duplicates and confuses where to document new DAMOS filter types and features. Move the details from usage to design doc.

Signed-off-by SeongJae Park <[email protected]>

---
 Documentation/admin-guide/mm/damon/usage.rst | 28 +++++++++-----------
 Documentation/mm/damon/design.rst            | 12 ++++-----
 2 files changed, 19 insertions(+), 21 deletions(-)

Documentation/admin-guide/mm/damon/usage.rst +13 ~~-15~~

index 51af66c208c5..dc37bba96273 100644
@@ -408,21 +408,19 @@ in the numeric order.
 
 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 one of six special
-keywords: ``anon`` for anonymous pages, ``memcg`` for specific memory cgroup,
-``young`` for young pages, ``addr`` for specific address range (an open-ended
-interval), ``hugepage_size`` for large folios of a specific size range [``min``,
-``max``] or ``target`` for specific DAMON monitoring target filtering.  Meaning
-of the types are same to the description on the :ref:`design doc
-<damon_design_damos_filters>`.
-
-In case of the memory cgroup filtering, you can specify the memory cgroup of
-the interest by writing the path of the memory cgroup from the cgroups mount
-point to ``memcg_path`` file.  In case of the address range filtering, you can
-specify the start and end address of the range to ``addr_start`` and
-``addr_end`` files, respectively.  For the DAMON monitoring target filtering,
-you can specify the index of the target between the list of the DAMON context's
-monitoring targets list to ``target_idx`` file.
+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.
+
+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
+``memcg_path`` file.  For ``addr`` type, you can specify the start and end
+address of the range (open-ended interval) to ``addr_start`` and ``addr_end``
+files, respectively.  For ``hugepage_size`` type, you can specify the minimum
+and maximum size of the range (closed interval) to ``min`` and ``max`` files,
+respectively.  For ``target`` type, you can specify the index of the target
+between the list of the DAMON context's monitoring targets list to
+``target_idx`` file.
 
 You can write ``Y`` or ``N`` to ``matching`` file to specify whether the filter
 is for memory that matches the ``type``.  You can write ``Y`` or ``N`` to

Documentation/mm/damon/design.rst +6 -6

index a959c081bc59..7360e5ac0d06 100644
@@ -600,23 +600,23 @@ counted as the scheme has tried.  This difference affects the statistics.
 
 Below ``type`` of filters are currently supported.
 
-- anonymous page
+- anon
     - Applied to pages that containing data that not stored in files.
     - Handled by operations set layer.  Supported by only ``paddr`` set.
-- memory cgroup
+- memcg
     - Applied to pages that belonging to a given cgroup.
     - Handled by operations set layer.  Supported by only ``paddr`` set.
-- young page
+- young
     - Applied to pages that are accessed after the last access check from the
       scheme.
     - Handled by operations set layer.  Supported by only ``paddr`` set.
-- pages that managed in a given size range
+- hugepage_size
     - Applied to pages that managed in a given size range.
     - Handled by operations set layer.  Supported by only ``paddr`` set.
-- address range
+- addr
     - Applied to pages that belonging to a given address range.
     - Handled by the core logic.
-- DAMON monitoring target
+- target
     - Applied to pages that belonging to a given DAMON monitoring target.
     - Handled by the core logic.

Signature · 1 line

2.39.5

SeongJae Park

author maintainer

2025-02-18 22:37 UTC #4 lore raw

PATCH 4/5 Docs/mm/damon/design: clarify handling layer based filters evaluation sequence

In reply to SeongJae Park

If an element of memory matches a DAMOS filter, filters that installed after that get no chance to make any effect to the element. Hence in what order DAMOS filters are handled is important, if both allow filters and reject filters are used together.

The ordering is affected by both the installation order and which layter the filters are handled. The design document is not clearly documenting the latter part. Clarify it on the design doc.

Signed-off-by SeongJae Park <[email protected]>

---
 Documentation/mm/damon/design.rst | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

Documentation/mm/damon/design.rst +15 ~~-13~~

index 7360e5ac0d06..8b9727d91434 100644
@@ -569,11 +569,21 @@ number of filters for each scheme.  Each filter specifies
 - whether it is to allow (include) or reject (exclude) applying
   the scheme's action to the memory (``allow``).
 
-When multiple filters are installed, each filter is evaluated in the installed
-order.  If a part of memory is matched to one of the filter, next filters are
-ignored.  If the memory passes through the filters evaluation stage because it
-is not matched to any of the filters, applying the scheme's action to it is
-allowed, same to the behavior when no filter exists.
+For efficient handling of filters, some types of filters are handled by the
+core layer, while others are handled by operations set.  In the latter case,
+hence, support of the filter types depends on the DAMON operations set.  In
+case of the core layer-handled filters, the memory regions that excluded by the
+filter are not counted as the scheme has tried to the region.  In contrast, if
+a memory regions is filtered by an operations set layer-handled filter, it is
+counted as the scheme has tried.  This difference affects the statistics.
+
+When multiple filters are installed, the group of filters that handled by the
+core layer are evaluated first.  After that, the group of filters that handled
+by the operations layer are evaluated.  Filters in each of the groups are
+evaluated in the installed order.  If a part of memory is matched to one of the
+filter, next filters are ignored.  If the memory passes through the filters
+evaluation stage because it is not matched to any of the filters, applying the
+scheme's action to it is allowed, same to the behavior when no filter exists.
 
 For example, let's assume 1) a filter for allowing anonymous pages and 2)
 another filter for rejecting young pages are installed in the order.  If a page

@@ -590,14 +600,6 @@ filter-allowed or filters evaluation stage passed.  It means that installing
 allow-filters at the end of the list makes no practical change but only
 filters-checking overhead.
 
-For efficient handling of filters, some types of filters are handled by the
-core layer, while others are handled by operations set.  In the latter case,
-hence, support of the filter types depends on the DAMON operations set.  In
-case of the core layer-handled filters, the memory regions that excluded by the
-filter are not counted as the scheme has tried to the region.  In contrast, if
-a memory regions is filtered by an operations set layer-handled filter, it is
-counted as the scheme has tried.  This difference affects the statistics.
-
 Below ``type`` of filters are currently supported.
 
 - anon

Signature · 1 line

2.39.5

SeongJae Park

author maintainer

2025-02-18 22:37 UTC #5 lore raw

PATCH 5/5 Docs/mm/damon/design: categorize DAMOS filter types based on handling layer

In reply to SeongJae Park

On what DAMON layer a DAMOS filter is handled is important to expect in what order filters will be evaluated. Re-organize the DAMOS filter types list on the design doc to categorize types based on the handling layer, to let users more easily understand the handling order.

Signed-off-by SeongJae Park <[email protected]>

---
 Documentation/mm/damon/design.rst | 34 ++++++++++++++-----------------
 1 file changed, 15 insertions(+), 19 deletions(-)

Documentation/mm/damon/design.rst +15 ~~-19~~

index 8b9727d91434..6a66aa0833fd 100644
@@ -602,25 +602,21 @@ filters-checking overhead.
 
 Below ``type`` of filters are currently supported.
 
-- anon
-    - Applied to pages that containing data that not stored in files.
-    - Handled by operations set layer.  Supported by only ``paddr`` set.
-- memcg
-    - Applied to pages that belonging to a given cgroup.
-    - Handled by operations set layer.  Supported by only ``paddr`` set.
-- young
-    - Applied to pages that are accessed after the last access check from the
-      scheme.
-    - Handled by operations set layer.  Supported by only ``paddr`` set.
-- hugepage_size
-    - Applied to pages that managed in a given size range.
-    - Handled by operations set layer.  Supported by only ``paddr`` set.
-- addr
-    - Applied to pages that belonging to a given address range.
-    - Handled by the core logic.
-- target
-    - Applied to pages that belonging to a given DAMON monitoring target.
-    - Handled by the core logic.
+- Core layer handled
+    - addr
+        - Applied to pages that belonging to a given address range.
+    - target
+        - Applied to pages that belonging to a given DAMON monitoring target.
+- Operations layer handled, supported by only ``paddr`` operations set.
+    - anon
+        - Applied to pages that containing data that not stored in files.
+    - memcg
+        - Applied to pages that belonging to a given cgroup.
+    - young
+        - Applied to pages that are accessed after the last access check from the
+          scheme.
+    - hugepage_size
+        - Applied to pages that managed in a given size range.
 
 To know how user-space can set the filters via :ref:`DAMON sysfs interface
 <sysfs_interface>`, refer to :ref:`filters <sysfs_filters>` part of the

Signature · 1 line

2.39.5