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

[SeongJae Park <sj@kernel.org>]

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