[RFC PATCH v3 00/37] mm/damon: introduce per-CPUs/threads/write/read monitoring

[RFC PATCH v3 00/37] mm/damon: introduce per-CPUs/threads/write/read monitoring

[SeongJae Park]

Extend DAMON for monitoring accesses generated by given CPUs/threads
and/or for writes.  It is aimed to be used for general NUMA-aware page
migration, cache-aware scheduling and live migration target VM decision.
This lengthy patch series does that in three parts.

The first part extends DAMON API to let any kernel component report
their observed access events to DAMON.

The second part adds a hacky change to change_protection() and page
fault handler for reporting page faults on DAMON-specified sampling
pages to DAMON, using the report API that is implemented by the first
part.  Please read the "Hacks on NUMA Hinting Fault" section below for
my apology and clarification about why I'm doing this.

The third part extends DAMON on the page fault based sampling to allow
doing the monitoring for accesses generated by specific CPUs and/or
threads, or for writes.

Note that this RFC, especially the hack of page fault handler is not
aiming to be upstreamed as-is.  This RFC is shared rather for giving an
example of ideas that will be discussed in a session [0] of the special
purpose memory microconf at LPC'25, and a stable interface for early
testers.

Background
----------

Existing DAMON operations set implementations, namely paddr, vaddr, and
fvaddr, use Accessed bits of page tables as the main source of the
access information.  Accessed bits have some restrictions.  For example,
it cannot tell which CPU, GPU or thread made the access, whether the
access was read or write, and which part of the mapped entity was really
accessed.

Depending on the use case, the limitations can be problematic.  Because
the issue stems from the nature of the page table Accessed bit, utilizing
access information from different sources can mitigate the issue.  Page
faults, memory access instructions sampling interrupts, system calls, or
any information from other kernel space friends such as subsystems or
device drivers of CXL or GPUs could be examples of the different
sources.

DAMON separates its core and operation set layer for easy extensions.
The core layer handles high level work such as access information
sampling target setup and region-based overhead/accuracy control.  The
operation set layer executes the low level (sampling-purpose) access
information handling.  And DAMON API callers can implement and use their
operation set.  That is one of the ways to extend DAMON to use the
different sources.  The core layer features will still be available with
the new sources, without additional changes.

Nevertheless, the current interface between the core and the operation
set layers is optimized for the Accessed bits case.  Specifically, the
interface asks the operation set if a given part of memory has been
accessed or not in a given time period (last sampling interval).  It is
easy for the Accessed bit use case, since the information is stored in
page tables.  Operation set can simply read the current value of the
Accessed bit.

For some sources other than Accessed bits, such as page faults or
instruction sampling interrupts, the operation set may need to collect
and keep the access information in its internal memory until the core
layer asks the access information.  Only after answering the question,
the information could be dropped.

Implementing such operation set internal memory management would be not
very trivial.  Also it could end up multiple similar operation set
implementations having their own internal memory management code that is
unnecessarily duplicated.

Core Layer Changes for Reporting-based Monitoring
-------------------------------------------------

Optimize such possible duplicated efforts, by updating DAMON core layer
to support real time access reporting.  The updated interface allows
operations set implementations to report their information to the core
layer, on their preferred schedule.  DAMON core layer will handle the
reports by managing meta data and updating the final monitoring results
(DAMON regions) accordingly.

For flexible control of the reports from different access check
primitives (or, sources), add a new data structure to DAMON core API,
namely damon_sample_control.  The data structure can be used to
selectively using the low level access check primitives (e.g., page
table accessed bit and page fault events), and filtering generated
samples based on additional information on the samples, including
access-generator CPU and/or thread, and whether the access was for write
or read.

Hacks on NUMA Hinting Faults
----------------------------

Hack NUMA hinting faults code in change_protection() and page fault
handler, to make the first DAMON access reporter.  Update
change_protection() to install the NUMA hinting faults-purpose
protection on arbitrary pages, and do the protection install for
DAMON-desired access check sample pages.  Update NUMA hinting faults
handling code to report the information to DAMON, when NUMA balancing is
turned off.

This is never upstreamable design and implementation.  Actually concerns
about this were raised in the previous version of this series.
Unfortunately I had no time to address those.  As a result, this version
is not addressing any of the concerns.  Please forgive me for polluting
your inbox with this immature patch.  But please know that I'm not
ignoring the previous concerns.  I'm sharing it as-is though, to get
feedback on DAMON-side changes first.  I will establish discussions with
all stakeholders including NUMA balancing and MM core maintainers, after
the DAMON-side changes discussion is more progressed.

Per-CPUs/threads/write/read Monitoring
--------------------------------------

Extend the data structure for access check samples filtering,
damon_sample_control, for filtering reported data access sample results
based on the source CPUs/threads of the access, and whether the access
was for write.  Expose the damon_sample_control to DAMON sysfs
interface, so that DAMON ABI users can also utilize the features.

Expected Users: NUMA Page Migrations, VM Live Migration and Scheduling
----------------------------------------------------------------------

We have ongoing public/private discussions of expected use cases of this
patch series.  We expect the per-CPUs monitoring can be useful for
NUMA-aware page migrations.  AWS has shown their interest in using
write-only monitoring for finding the best live migration target VM.
Some folks showed interest in per-threads monitoring for L3 cache
utilization-aware threads scheduling.

Also I believe this can be extended for not only per-CPU but any access
entities including GPU-like accelerators, who expose their memory as
NUMA nodes in some setups.  With that, I think we could make a holistic
and efficient access-aware NUMA pages migration system.

Patches Sequence
----------------

The first twelve patches (patches 1-12) are for the first (extending
DAMON for reporting-based access monitoring) and second (adding the
gross hack for stealing NUMA_HINT_FUALT on page fault handling) parts.
As a result, it makes DAMON be able to do page fault events based
monitoring.

The following thirteen patches (patches 13-25) are for implementing
per-CPUs access monitoring.  It implements the framework for doing
access reports filtering based on additional information such as
access-origin CPU, and implements it for the CPU information.

The next seven patches (patches 26-32) are for implementing per-threads
access monitoring.  It extends the access reports filtering for the
threads based information.

Final five patches (patches 33-37) are for implementing read/write-only
monitoring.  It again extends the access reports filtering for the
purpose.

Plan for Dropping RFC
---------------------

This RFC is having pretty immature and dirty hacks.  This is never
upstreamable as-is.  I'm sharing this, though, for the following
reasons.

Firstly, to discuss the overall idea and DAMON-side design.  The idea
was floating around for a long time, and recently has been more specific
with 'damon_report_access() API plan [1] that discussed at LSFMMBPF'25.
We will also discuss this focusing on NUMA-aware page migration use
case, on special purpose memory management microconf at LPC'25.

Secondly, some people started testing the early version of the
implementation on my damon/next tree.  The implementation is hacky,
having only an experimental interface with no documentation at all.
This RFC is for giving a more stable interface and documentation to such
early testers.

I expect final upstreaming of this series will take a long time.  The
NUMA hinting fault part hack is the most challenging in my opinion.  And
this version is not addressing any concern about it that was raised to
the previous version.  Please know that I'm not ignoring the concerns,
but only having capacity limitations at the moment.  I will establish
discussions with all stakeholders including maintainers of NUMA
balancing and MM core, by LSFMMBPF'26.  Only after we make a good
alignment with all stakeholders, will this be able to be upstreamed.

Revision History
----------------

Changes from RFC v2
(https://lore.kernel.org/20250727201813.53858-1-sj@kernel.org)
- Use damon_sample_control instead of new ops (paddr_fault)
- Implement per-CPUs,threads, write-only monitoring.

Changes from RFC v1
(https://lore.kernel.org/20250629201443.52569-1-sj@kernel.org)
- Fixup report reading logic for access absence accounting.
- Implement page faults based operations set (paddr_fault).

[0] https://lpc.events/event/19/contributions/2066/
[1] https://lwn.net/Articles/1016525/

SeongJae Park (37):
  mm/damon/core: implement damon_report_access()
  mm/damon: define struct damon_sample_control
  mm/damon/core: commit damon_sample_control
  mm/damon/core: implement damon_report_page_fault()
  mm/{mprotect,memory}: (no upstream-aimed hack) implement MM_CP_DAMON
  mm/damon/paddr: support page fault access check primitive
  mm/damon/core: apply access reports to high level snapshot
  mm/damon/sysfs: implement monitoring_attrs/sample/ dir
  mm/damon/sysfs: implement sample/primitives/ dir
  mm/damon/sysfs: connect primitives directory with core
  Docs/mm/damon/design: document page fault sampling primitive
  Docs/admin-guide/mm/damon/usage: document sample primitives dir
  mm/damon: extend damon_access_report for origin CPU reporting
  mm/damon/core: report access origin cpu of page faults
  mm/damon: implement sample filter data structure for cpus-only
    monitoring
  mm/damon/core: implement damon_sample_filter manipulations
  mm/damon/core: commit damon_sample_filters
  mm/damon/core: apply sample filter to access reports
  mm/damon/sysfs: implement sample/filters/ directory
  mm/damon/sysfs: implement sample filter directory
  mm/damon/sysfs: implement type, matching, allow files under sample
    filter dir
  mm/damon/sysfs: implement cpumask file under sample filter dir
  mm/damon/sysfs: connect sample filters with core layer
  Docs/mm/damon/design: document sample filters
  Docs/admin-guide/mm/damon/usage: document sample filters dir
  mm/damon: extend damon_access_report for access-origin thread info
  mm/damon/core: report access-generated thread id of the fault event
  mm/damon: extend damon_sample_filter for threads
  mm/damon/core: support threads type sample filter
  mm/damon/sysfs: support thread based access sample filtering
  Docs/mm/damon/design: document threads type sample filter
  Docs/admin-guide/mm/damon/usage: document tids_arr file
  mm/damon: support reporting write access
  mm/damon/core: report whether the page fault was for writing
  mm/damon/core: support write access sample filter
  mm/damon/sysfs: support write-type access sample filter
  Docs/mm/damon/design: document write access sample filter type

 Documentation/admin-guide/mm/damon/usage.rst |  43 +-
 Documentation/mm/damon/design.rst            |  76 +++
 include/linux/damon.h                        | 133 ++++
 include/linux/mm.h                           |   1 +
 mm/damon/core.c                              | 339 +++++++++-
 mm/damon/paddr.c                             |  66 +-
 mm/damon/sysfs.c                             | 622 +++++++++++++++++++
 mm/memory.c                                  |  60 +-
 mm/mprotect.c                                |   5 +
 9 files changed, 1338 insertions(+), 7 deletions(-)


base-commit: 120d322d058f56f6cb92115b5a589ee9b4f07664
-- 
2.47.3

[RFC PATCH v3 11/37] Docs/mm/damon/design: document page fault sampling primitive

[SeongJae Park]

Update DAMON design document for support of page fault events based
access check sampling primitives.

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

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 7fd819b8bbf7..a21973b33bc3 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -117,6 +117,7 @@ to make a reasonable trade-off.  Below shows this in detail::
     <BIG UNMAPPED REGION 2>
     <stack>
 
+.. _damon_design_pte_accessed_bit_access_check:
 
 PTE Accessed-bit Based Access Check
 -----------------------------------
@@ -135,6 +136,23 @@ the interference is the responsibility of sysadmins.  However, it solves the
 conflict with the reclaim logic using ``PG_idle`` and ``PG_young`` page flags,
 as Idle page tracking does.
 
+.. _damon_design_page_fault_access_check:
+
+Monitoring-purpose Page Faults Based Access Check
+-------------------------------------------------
+
+The operation set implementation for the physical address space (``paddr``) can
+do the access check using monitoring-purpose page fault events in a way similar
+to NUMA balancing hinting faults.  When it is being used, ``paddr`` installs
+the page protection in a way similar to that of NUMA balancing hinting faults.
+Then the page fault handler reports the faults happend by the installed page
+protection to DAMON core layer.
+
+``paddr`` uses :ref:`accessed-bit based check
+<damon_design_pte_accessed_bit_access_check>` by default, and users can change
+it to use this page faults based one, using :ref:`access sampling primitives
+selection <damon_design_sampling_primitives_selection>`.
+
 .. _damon_design_addr_unit:
 
 Address Unit
@@ -244,6 +262,21 @@ maximum number of regions after the split.
 In this way, DAMON provides its best-effort quality and minimal overhead while
 keeping the bounds users set for their trade-off.
 
+.. _damon_design_sampling_primitives_selection:
+
+Access Sampling Primitives Selection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some operations set implementations could utilize multiple access sampling
+primitives.  For example, the operations set implementation for physical
+address space (``paddr``) support two promitives at the moment: 1) page tables'
+Accessed bits, and access monitoring-purpose page fault events.  In future, it
+could be extended for more hardware features such as AMD IBS or CXL HMU, and
+support from the operations set implementation for virtual address spaces
+(``vaddr``).  DAMON API callers or ABI users can select what primitives to use.
+
+At the moment, only exclusive use of the primitives is supported.
+
 
 .. _damon_design_age_tracking:
 
-- 
2.47.3

[RFC PATCH v3 12/37] Docs/admin-guide/mm/damon/usage: document sample primitives dir

[SeongJae Park]

Update DAMON usage document for the selective access sampling primitives
activation, which is essential for using page fault events as the access
check sampling primitive.

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

diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
index 7da4c002cb39..897a89950351 100644
--- a/Documentation/admin-guide/mm/damon/usage.rst
+++ b/Documentation/admin-guide/mm/damon/usage.rst
@@ -65,6 +65,7 @@ comma (",").
     │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/
     │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
     │ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us
+    │ │ │ │ │ │ sample/primitives/page_table,page_faults
     │ │ │ │ │ │ nr_regions/min,max
     │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
     │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target,obsolete_target
@@ -215,9 +216,9 @@ contexts/<N>/monitoring_attrs/
 ------------------------------
 
 Files for specifying attributes of the monitoring including required quality
-and efficiency of the monitoring are in ``monitoring_attrs`` directory.
-Specifically, two directories, ``intervals`` and ``nr_regions`` exist in this
-directory.
+and efficiency of the monitoring, and types of accesses to monitor are in
+``monitoring_attrs`` directory.  Specifically, three directories, ``intervals``
+, ``nr_regions`` and ``sample`` exist in this directory.
 
 Under ``intervals`` directory, three files for DAMON's sampling interval
 (``sample_us``), aggregation interval (``aggr_us``), and update interval
@@ -232,6 +233,18 @@ 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`).
 
+Under ``sample`` directory, a directory, ``primitives`` exists.
+
+contexts/<N>/monitoring_attrs/sample/primitives/
+------------------------------------------------
+
+This directory is for the access sampling primitives :ref:`selection
+<damon_design_sampling_primitives_selection>`.  Under ``primitives`` directory,
+two files, ``page_table`` and ``page_faults`` exist.  By writing ``Y`` or ``N``
+to these files, users can select whether to use the :ref:`page table accessed
+bit <damon_design_pte_accessed_bit_access_check>` and :ref:`page fault events
+<damon_design_page_fault_access_check>`, respectively.
+
 .. _damon_usage_sysfs_monitoring_intervals_goal:
 
 contexts/<N>/monitoring_attrs/intervals/intervals_goal/
-- 
2.47.3

[RFC PATCH v3 24/37] Docs/mm/damon/design: document sample filters

[SeongJae Park]

Update DAMON design document for the access sample results filtering.

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

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index a21973b33bc3..9a4679de437f 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -146,12 +146,17 @@ do the access check using monitoring-purpose page fault events in a way similar
 to NUMA balancing hinting faults.  When it is being used, ``paddr`` installs
 the page protection in a way similar to that of NUMA balancing hinting faults.
 Then the page fault handler reports the faults happend by the installed page
-protection to DAMON core layer.
+protection to DAMON core layer.  Compared to the accessed-bit based one, this
+approach gives more information to DAMON, such as the access-generated
+CPU.
 
 ``paddr`` uses :ref:`accessed-bit based check
 <damon_design_pte_accessed_bit_access_check>` by default, and users can change
 it to use this page faults based one, using :ref:`access sampling primitives
-selection <damon_design_sampling_primitives_selection>`.
+selection <damon_design_sampling_primitives_selection>`.  Also, the addtional
+information can be used for doing monitoring of only specific type accesses,
+using :ref:`access sampling results filters
+<damon_design_sampling_results_filters>`.
 
 .. _damon_design_addr_unit:
 
@@ -277,6 +282,39 @@ support from the operations set implementation for virtual address spaces
 
 At the moment, only exclusive use of the primitives is supported.
 
+.. _damon_design_sampling_results_filters:
+
+Access Sampling Results Filter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Depending on the access sampling primitives that used, the sampling results
+could inform more than whether an access is made, such as the CPU or the thread
+the sampled access was made from, and whether the sampled access was for
+writing or reading.  By filtering the results based on the additional
+information, DAMON can perform for more detailed access monitoring, such as
+per-CPUs/threads or read/write-only monitoring.
+
+For such special types of monitoring, DAMON provides a feature called "sampling
+results filter".  The feature allows users to set an arbitrary number of
+filters for the sampling results.  Each of the filters specifies
+
+- a type of the additional information (``type``),
+- whether it is for the sampling results of the type or all except the type
+  (``matching``), and
+- whether it is to allow (include) or reject (exclude) consuming of the type of
+  sampling results.
+
+Each filter is applied in the order of the installation.  Only sampling results
+that allowed by previous filters are continue to be evaluated by the next
+filters.  If a sampling result is decided to be rejected by a filter, it is
+just discarded and no later filter is applied.
+
+Below ``type`` of access sampling results filter are currently supported.
+
+- cpumask
+    - Whether the sampled access was generated by a cpu that included in a
+      given cpumask.
+
 
 .. _damon_design_age_tracking:
 
-- 
2.47.3

[RFC PATCH v3 25/37] Docs/admin-guide/mm/damon/usage: document sample filters dir

[SeongJae Park]

Update DAMON usage document for the added DAMON sysfs files for
installing and setting the access sample results filtering.

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

diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
index 897a89950351..365a4548a5ba 100644
--- a/Documentation/admin-guide/mm/damon/usage.rst
+++ b/Documentation/admin-guide/mm/damon/usage.rst
@@ -66,6 +66,8 @@ comma (",").
     │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
     │ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us
     │ │ │ │ │ │ sample/primitives/page_table,page_faults
+    │ │ │ │ │ │ sample/filters/nr_filters
+    │ │ │ │ │ │ │ 0/type,matching,allow,cpumask
     │ │ │ │ │ │ nr_regions/min,max
     │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
     │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target,obsolete_target
@@ -233,7 +235,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`).
 
-Under ``sample`` directory, a directory, ``primitives`` exists.
+Under ``sample`` directory, two directories, ``primitives`` and ``filters``
+exist.
 
 contexts/<N>/monitoring_attrs/sample/primitives/
 ------------------------------------------------
@@ -245,6 +248,26 @@ to these files, users can select whether to use the :ref:`page table accessed
 bit <damon_design_pte_accessed_bit_access_check>` and :ref:`page fault events
 <damon_design_page_fault_access_check>`, respectively.
 
+contexts/<N>/monitoring_attrs/sample/filters/
+---------------------------------------------
+
+This directory is for control of the :ref:`access sampling results filters
+<damon_design_sampling_results_filters>`.  At the beginning, this directory has
+only one file, ``nr_filters``.  Writing a positive integer ``<n>`` to the file
+generates directories of the number, named ``0`` to ``<n - 1>``.  The generated
+directories represent the sampling result filters to install to the DAMON
+context, in the order of the directory names.  Writing ``0`` to ``nr_filters``
+removes the directories.
+
+Under the individual filter directory, five files, ``type``, ``matching``,
+``allow``, and ``cpumask`` exist.  The first three files are same to the
+properties of the filter specified on the :ref:`design doc
+<damon_design_sampling_results_filters>`.
+
+Users can specify the cpumask of the filter by writing it to ``cpumask``.  The
+format for ``cpumask`` input is same to that for other cpumask inputs like that
+for cgroup cpusets.
+
 .. _damon_usage_sysfs_monitoring_intervals_goal:
 
 contexts/<N>/monitoring_attrs/intervals/intervals_goal/
-- 
2.47.3

[RFC PATCH v3 31/37] Docs/mm/damon/design: document threads type sample filter

[SeongJae Park]

Update DAMON design document for threads type access sample results
filtering.

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

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 9a4679de437f..4c6d83263a7b 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -148,7 +148,7 @@ the page protection in a way similar to that of NUMA balancing hinting faults.
 Then the page fault handler reports the faults happend by the installed page
 protection to DAMON core layer.  Compared to the accessed-bit based one, this
 approach gives more information to DAMON, such as the access-generated
-CPU.
+CPU/threads.
 
 ``paddr`` uses :ref:`accessed-bit based check
 <damon_design_pte_accessed_bit_access_check>` by default, and users can change
@@ -314,6 +314,9 @@ Below ``type`` of access sampling results filter are currently supported.
 - cpumask
     - Whether the sampled access was generated by a cpu that included in a
       given cpumask.
+- threads
+    - Whether the sampled access was generated by a thread that having a thread
+      (task) id that exist in a given array of ids.
 
 
 .. _damon_design_age_tracking:
-- 
2.47.3

[RFC PATCH v3 32/37] Docs/admin-guide/mm/damon/usage: document tids_arr file

[SeongJae Park]

Update DAMON usage document for the threads based access sampling
results filtering.

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

diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
index 365a4548a5ba..d22d80710355 100644
--- a/Documentation/admin-guide/mm/damon/usage.rst
+++ b/Documentation/admin-guide/mm/damon/usage.rst
@@ -67,7 +67,7 @@ comma (",").
     │ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us
     │ │ │ │ │ │ sample/primitives/page_table,page_faults
     │ │ │ │ │ │ sample/filters/nr_filters
-    │ │ │ │ │ │ │ 0/type,matching,allow,cpumask
+    │ │ │ │ │ │ │ 0/type,matching,allow,cpumask,tid_arr
     │ │ │ │ │ │ nr_regions/min,max
     │ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
     │ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target,obsolete_target
@@ -260,13 +260,14 @@ context, in the order of the directory names.  Writing ``0`` to ``nr_filters``
 removes the directories.
 
 Under the individual filter directory, five files, ``type``, ``matching``,
-``allow``, and ``cpumask`` exist.  The first three files are same to the
-properties of the filter specified on the :ref:`design doc
+``allow``, ``cpumask`` and ``tid_arr`` exist.  The first three files are same
+to the properties of the filter specified on the :ref:`design doc
 <damon_design_sampling_results_filters>`.
 
-Users can specify the cpumask of the filter by writing it to ``cpumask``.  The
-format for ``cpumask`` input is same to that for other cpumask inputs like that
-for cgroup cpusets.
+Users can specify the cpumask and thread id array of the filter by writing
+those to ``cpumask`` and ``tid_arr``.  The format for ``cpumask`` input is same
+to that for other cpumask inputs like that for cgroup cpusets.  For
+``tid_arr``, users can write array of the thread ids, separated by a comma.
 
 .. _damon_usage_sysfs_monitoring_intervals_goal:
 
-- 
2.47.3

[RFC PATCH v3 37/37] Docs/mm/damon/design: document write access sample filter type

[SeongJae Park]

Update DAMON design document for the write access sample results
filtering.

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

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 4c6d83263a7b..b194bf4a6519 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -148,7 +148,7 @@ the page protection in a way similar to that of NUMA balancing hinting faults.
 Then the page fault handler reports the faults happend by the installed page
 protection to DAMON core layer.  Compared to the accessed-bit based one, this
 approach gives more information to DAMON, such as the access-generated
-CPU/threads.
+CPU/threads and whether it was for writing or reading.
 
 ``paddr`` uses :ref:`accessed-bit based check
 <damon_design_pte_accessed_bit_access_check>` by default, and users can change
@@ -317,6 +317,8 @@ Below ``type`` of access sampling results filter are currently supported.
 - threads
     - Whether the sampled access was generated by a thread that having a thread
       (task) id that exist in a given array of ids.
+- write
+    - Whether the sampled access was for writing.
 
 
 .. _damon_design_age_tracking:
-- 
2.47.3