[RFC PATCH v0] Docs/mm/damon/design: document data attributes report infra design (beyond page table accessed-bit milestone 2)

[RFC PATCH v0] Docs/mm/damon/design: document data attributes report infra design (beyond page table accessed-bit milestone 2)

[SJ Park]

The "beyond page table accessed-bit DAMON extension" project [1]
milestone 2 is for building the basic infrastructure for continued
extension.  After starting it, I studied perf event little and found a
few demons in details.  I therefore spent time on high level design.  As
it started looks like making sense to me, I'd like to share the humble
design first and get feedback from more eyeballs.

Add a blueprint of the milestone 2 as a high level design document.
Describe the API and ABI of data attribute report infrastructure, and an
example use case of it for per-CPUs write-only monitoring.  The API and
ABI will later be extended for more data attributes reporters utilizing
AMD IBS, Intel PEBS, Arm SPEs like h/w features and any possible
DAMON-external reporter kernel components.

Request for comments
====================

This is an RFC for high level design discussion, so no implementation is
provided.  Comments I want to receive include but not limited to below.

Does the idea for perf CPU cycle sampling based access monitoring makes
sense?

Does the design provides clear idea about how it can be extended for the
future extensions that already scoped for milestone 3 (AMD IBS, Intel
PEBS, Arm SPE)?

For the foreseeable extensions (AMD IBS, Intel PEBS, Arm SPE), would the
required change minimum and maintainable?

Next steps
==========

I will start implementing the infrastructure and perf CPU cycle sampling
based access monitoring as described in this patch.  It will go through
the normal development process.  Delivery of it will be the completion
of the milestone 2.  As set on the initial roadmap [1], ETA of the
delivery is LSFMMBPF'27.  No delay is expected so far.

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

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

diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index a465e34bb1d9c..1e699e3f8a496 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -433,6 +433,50 @@ monitoring.
 Refer to the :ref:`admin guide <damon_usage_sysfs_probes>` to know how users
 can use the mode.
 
+Data Attributes Reporting
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Infrastructure for receiving attribute information from DAMON-external kernel
+components.
+
+Because DAMON is not hooked in every place but runs in its own worker thread,
+it cannot retrieve some types of data attribute information by itself.  Many of
+those are available to DAMON-external kernel components such as perf event
+callbacks and page fault handler.  For such cases, DAMON provides attributes
+reporting infrastructure.  Using its API, any kernel components can report
+their finding to DAMON.
+
+The API for doing the report is a function, damon_report_attrs().  The function
+receives the attribute information and saves it in DAMON's internal buffer.
+The function is safe to be called in any context including NMI.  The internal
+buffer has a fixed size and keeps only latest reports of the size.  Because one
+buffer size doesn't fit all, multiple report buffers of different size and
+rules can be generated and shared by multiple reporters.  DAMON provides API
+for such management of report buffers.  damon_report_attrs() can specify into
+which buffer the report should be saved.  DAMON user interface (ABI) for doing
+the buffer setup, and enable/disable reports of supported types is also
+supported.
+
+The data attribute probe supports the reports.  The probes can be configured to
+hit for a given memory region depending on the existence of specific types of
+reports that associated with the memory region in given report buffers.
+
+For example, per-CPUs write-only monitoring can be configured using this
+infrastructure like below.
+
+The user sets a report buffer and enable CPU instruction sampling report for
+the buffer.  DAMON will enable perf event counter for CPU cycles sampling.  The
+sampling callback will save the sampling time CPU instruction and the id of the
+CPU that was executing it, into the DAMON report buffer, using
+damon_report_attrs().  DAMON can automatically adjust the perf event sampling
+frequency to minimize old report drops due to the buffer size limit.
+
+The user further sets a DAMON probe.  The probe hits for a given DAMON region
+if a store instruction for a memory in the region that was executed from a
+given CPUs group exists in the report buffer.  As a result, the probe hit
+counts represent relative frequency of writes from a given CPUs group to a
+given memory region.
+
 Dynamic Target Space Updates Handling
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

base-commit: 366c6418699768dba5826d412700a29d562ca039
-- 
2.47.3

Re: [RFC PATCH v0] Docs/mm/damon/design: document data attributes report infra design (beyond page table accessed-bit milestone 2)

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Medium] Docs/mm/damon: CPU cycle instruction sampling lacks target memory address
--

commit a164f9ff38c8cd1963db3e0c7ea062dbc93135a3
Author: SJ Park <sj@kernel.org>

Docs/mm/damon/design: document data attributes report infra design (beyond page table accessed-bit milestone 2)

This patch documents the high-level design for DAMON's data attributes
reporting infrastructure, including the damon_report_attrs() API and an
example use case for per-CPU write-only monitoring using perf CPU cycles
sampling.

> diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
> index a465e34bb1d9c..1e699e3f8a496 100644
> --- a/Documentation/mm/damon/design.rst
> +++ b/Documentation/mm/damon/design.rst
> @@ -433,6 +433,50 @@ monitoring.
>  Refer to the :ref:`admin guide <damon_usage_sysfs_probes>` to know how users
>  can use the mode.
>  
> +Data Attributes Reporting
> +~~~~~~~~~~~~~~~~~~~~~~~~~

[ ... ]

> +For example, per-CPUs write-only monitoring can be configured using this
> +infrastructure like below.
> +
> +The user sets a report buffer and enable CPU instruction sampling report for
> +the buffer.  DAMON will enable perf event counter for CPU cycles sampling.  The
> +sampling callback will save the sampling time CPU instruction and the id of the
> +CPU that was executing it, into the DAMON report buffer, using
> +damon_report_attrs().  DAMON can automatically adjust the perf event sampling
> +frequency to minimize old report drops due to the buffer size limit.
> +
> +The user further sets a DAMON probe.  The probe hits for a given DAMON region
> +if a store instruction for a memory in the region that was executed from a
> +given CPUs group exists in the report buffer.  As a result, the probe hit
> +counts represent relative frequency of writes from a given CPUs group to a
> +given memory region.

[Severity: Medium]
In the Data Attributes Reporting section of Documentation/mm/damon/design.rst,
how can the DAMON probe determine whether a sampled store instruction targeted
a given DAMON memory region if the callback only saves the CPU instruction and
CPU ID from a generic CPU cycles counter?

A sampled instruction (or instruction pointer) only encodes the opcode and
register operands, not the effective virtual or physical data address being
written. Saving only the instruction and executing CPU ID via
damon_report_attrs() does not appear to provide the target memory address
needed to match against a DAMON region when the probe inspects the buffer.

Even if the perf overflow callback attempted to resolve the target data
address at NMI time, generic CPU cycle counter interrupts
(PERF_COUNT_HW_CPU_CYCLES) are non-precise on out-of-order CPUs and suffer
from skid. At NMI time, regs->ip typically points to a subsequent instruction
rather than the instruction that caused the overflow, and the register values
in struct pt_regs may already have been modified.

Furthermore, without hardware data-address sampling features (such as Intel
PEBS, AMD IBS, or Arm SPE populating perf_sample_data->addr or phys_addr,
which are scoped for Milestone 3), resolving the effective address from a raw
instruction would require fetching instruction bytes in NMI context, running
an architecture-specific instruction decoder and address-calculation emulator,
and translating virtual addresses to physical addresses for paddr monitoring.

How is the target memory address intended to be obtained and matched to DAMON
regions in Milestone 2 with generic CPU cycle sampling?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261017195747.89961-1-sj@kernel.org?part=1

Re: [RFC PATCH v0] Docs/mm/damon/design: document data attributes report infra design (beyond page table accessed-bit milestone 2)

[SJ Park]

On Sun, 18 Oct 2026 19:58:01 +0000 sashiko-bot@kernel.org wrote:

> Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
> - [Medium] Docs/mm/damon: CPU cycle instruction sampling lacks target memory address
> --
> 
> commit a164f9ff38c8cd1963db3e0c7ea062dbc93135a3
> Author: SJ Park <sj@kernel.org>
> 
> Docs/mm/damon/design: document data attributes report infra design (beyond page table accessed-bit milestone 2)
> 
> This patch documents the high-level design for DAMON's data attributes
> reporting infrastructure, including the damon_report_attrs() API and an
> example use case for per-CPU write-only monitoring using perf CPU cycles
> sampling.
> 
> > diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
> > index a465e34bb1d9c..1e699e3f8a496 100644
> > --- a/Documentation/mm/damon/design.rst
> > +++ b/Documentation/mm/damon/design.rst
> > @@ -433,6 +433,50 @@ monitoring.
> >  Refer to the :ref:`admin guide <damon_usage_sysfs_probes>` to know how users
> >  can use the mode.
> >  
> > +Data Attributes Reporting
> > +~~~~~~~~~~~~~~~~~~~~~~~~~
> 
> [ ... ]
> 
> > +For example, per-CPUs write-only monitoring can be configured using this
> > +infrastructure like below.
> > +
> > +The user sets a report buffer and enable CPU instruction sampling report for
> > +the buffer.  DAMON will enable perf event counter for CPU cycles sampling.  The
> > +sampling callback will save the sampling time CPU instruction and the id of the
> > +CPU that was executing it, into the DAMON report buffer, using
> > +damon_report_attrs().  DAMON can automatically adjust the perf event sampling
> > +frequency to minimize old report drops due to the buffer size limit.
> > +
> > +The user further sets a DAMON probe.  The probe hits for a given DAMON region
> > +if a store instruction for a memory in the region that was executed from a
> > +given CPUs group exists in the report buffer.  As a result, the probe hit
> > +counts represent relative frequency of writes from a given CPUs group to a
> > +given memory region.
> 
> [Severity: Medium]
> In the Data Attributes Reporting section of Documentation/mm/damon/design.rst,
> how can the DAMON probe determine whether a sampled store instruction targeted
> a given DAMON memory region if the callback only saves the CPU instruction and
> CPU ID from a generic CPU cycles counter?
> 
> A sampled instruction (or instruction pointer) only encodes the opcode and
> register operands, not the effective virtual or physical data address being
> written. Saving only the instruction and executing CPU ID via
> damon_report_attrs() does not appear to provide the target memory address
> needed to match against a DAMON region when the probe inspects the buffer.
> 
> Even if the perf overflow callback attempted to resolve the target data
> address at NMI time, generic CPU cycle counter interrupts
> (PERF_COUNT_HW_CPU_CYCLES) are non-precise on out-of-order CPUs and suffer
> from skid. At NMI time, regs->ip typically points to a subsequent instruction
> rather than the instruction that caused the overflow, and the register values
> in struct pt_regs may already have been modified.
> 
> Furthermore, without hardware data-address sampling features (such as Intel
> PEBS, AMD IBS, or Arm SPE populating perf_sample_data->addr or phys_addr,
> which are scoped for Milestone 3), resolving the effective address from a raw
> instruction would require fetching instruction bytes in NMI context, running
> an architecture-specific instruction decoder and address-calculation emulator,
> and translating virtual addresses to physical addresses for paddr monitoring.
> 
> How is the target memory address intended to be obtained and matched to DAMON
> regions in Milestone 2 with generic CPU cycle sampling?

Good question.  damon_report_attr() will save the register contents and pid
into report, too.  And the probe in kdamond context will decode the instruction
and get the memory address.  For physical address, it will also do the page
table walk of the process of the pid.

> 
> -- 
> Sashiko AI review · https://sashiko.dev/#/patchset/20261017195747.89961-1-sj@kernel.org?part=1


Thanks,
SJ