[RFC PATCH v2 07/10] Docs/mm/damon/design: document pass/block filters behaviors

[SeongJae Park <sj@kernel.org>]

Update DAMOS filters design document to describe the pass/block
behavior of filters.

Signed-off-by: SeongJae Park <sj@kernel.org>
---
 Documentation/mm/damon/design.rst | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 5ebb572d0999..0265aaef2544 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -504,9 +504,30 @@ have a list of latency-critical processes.
 
 To let users optimize DAMOS schemes with such special knowledge, DAMOS provides
 a feature called DAMOS filters.  The feature allows users to set an arbitrary
-number of filters for each scheme.  Each filter specifies the type of target
-memory, and whether it should exclude the memory of the type (filter-out), or
-all except the memory of the type (filter-in).
+number of filters for each scheme.  Each filter specifies
+
+- a type of memory (``type``),
+- whether it is for the memory of the type or all except the type
+  (``matching``), and
+- whether it is to allow (pass through the filter) or reject (block) applying
+  the scheme's action to the memory (``pass``).
+
+When multiple filters are installed, each filter is applied in the installed
+order.  If a memory is matched to one of the filter, followup filters are
+ignored.  For example, let's assume a filter for passing anonymous pages and
+another filter for blocking young pages are installed in the order.  If a page
+of a region that eligible to apply the scheme's action is an anonymous page,
+the scheme's action will be applied to the page regardless of whether it is
+young, since it matches with the first filter.  On the other hand, if a page of
+the region is a non-anonymous page, the scheme's action will be applied only if
+the page is young, since the second filter is also applied.
+
+Note that DAMOS action is eligible to be applied to any memory that satisfies
+other conditions if no filter is isntalled.  Meanwhile, DAMOS filters work for
+only memory that satisfies ``type`` and ``matching``.  It means installing only
+pass filters is same to installing no filter, because pass filters dont' block
+memory of type that not specified to pass.  For any use case, at least one
+block filter should be installed as the last one.
 
 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,
@@ -516,7 +537,7 @@ 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 types of filters are currently supported.
+Below ``type`` of filters are currently supported.
 
 - anonymous page
     - Applied to pages that containing data that not stored in files.
-- 
2.39.5