Some of DAMON documents are outdated, or having minor typos or grammar
erros. Especially, the design doc has not updated for DAMOS, which is
an important part of DAMON. Fix the minor issues and update documents.
SeongJae Park (10):
Docs/mm/damon/faq: remove old questions
Docs/mm/damon/maintainer-profile: fix typos and grammar errors
Docs/mm/damon/design: add a section for overall architecture
Docs/mm/damon/design: update the layout based on the layers
Docs/mm/damon/design: rewrite configurable layers
Docs/mm/damon/design: add a section for the relation between Core and
Modules layer
Docs/mm/damon/design: add sections for basic parts of DAMOS
Docs/mm/damon/design: add sections for advanced features of DAMOS
Docs/mm/damon/design: add a section for DAMON core API
Docs/mm/damon/design: add a section for the modules layer
Documentation/mm/damon/design.rst | 309 ++++++++++++++++--
Documentation/mm/damon/faq.rst | 23 --
Documentation/mm/damon/maintainer-profile.rst | 4 +-
3 files changed, 285 insertions(+), 51 deletions(-)
--
2.25.1
DAMON design document is describing only the operations set layer and
monitoring part of the core logic. Update the layout based on the
DAMON's layers, so that more parts of DAMON including DAMOS core logic
and DAMON modules can easily be added.
Signed-off-by: SeongJae Park <[email protected]>
---
Documentation/mm/damon/design.rst | 24 ++++++++++++++----------
1 file changed, 14 insertions(+), 10 deletions(-)
diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 3b4ce873fa71..eaf52f3a9144 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -19,8 +19,8 @@ DAMON subsystem is configured with three layers including
interfaces for the user space, on top of the core layer.
-Configurable Layers
-===================
+Configurable Operations Set
+---------------------------
DAMON provides data access monitoring functionality while making the accuracy
and the overhead controllable. The fundamental access monitorings require
@@ -42,8 +42,8 @@ Also, if some architectures or devices support special optimized access check
primitives, those will be easily configurable.
-Reference Implementations of Address Space Specific Monitoring Operations
-=========================================================================
+Operations Set Layer
+====================
The monitoring operations are defined in two parts:
@@ -105,8 +105,12 @@ conflict with the reclaim logic using ``PG_idle`` and ``PG_young`` page flags,
as Idle page tracking does.
-Address Space Independent Core Mechanisms
-=========================================
+Core Logics
+===========
+
+
+Monitoring
+----------
Below four sections describe each of the DAMON core mechanisms and the five
monitoring attributes, ``sampling interval``, ``aggregation interval``,
@@ -115,7 +119,7 @@ regions``.
Access Frequency Monitoring
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
The output of DAMON says what pages are how frequently accessed for a given
duration. The resolution of the access frequency is controlled by setting
@@ -142,7 +146,7 @@ size of the target workload grows.
Region Based Sampling
----------------------
+~~~~~~~~~~~~~~~~~~~~~
To avoid the unbounded increase of the overhead, DAMON groups adjacent pages
that assumed to have the same access frequencies into a region. As long as the
@@ -159,7 +163,7 @@ assumption is not guaranteed.
Adaptive Regions Adjustment
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
Even somehow the initial monitoring target regions are well constructed to
fulfill the assumption (pages in same region have similar access frequencies),
@@ -178,7 +182,7 @@ keeping the bounds users set for their trade-off.
Dynamic Target Space Updates Handling
--------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The monitoring target address range could dynamically changed. For example,
virtual memory could be dynamically mapped and unmapped. Physical memory could
--
2.25.1
Add a section for covering DAMON modules layer to the design document.
Signed-off-by: SeongJae Park <[email protected]>
---
Documentation/mm/damon/design.rst | 61 +++++++++++++++++++++++++++++++
1 file changed, 61 insertions(+)
diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 0ccdd2f6af9f..da110e89cab4 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -370,3 +370,64 @@ access-aware applications using DAMON's core features. For this, DAMON exposes
its all features to other kernel components via its application programming
interface, namely ``include/linux/damon.h``. Please refer to the API
:doc:`document </mm/damon/api>` for details of the interface.
+
+
+Modules
+=======
+
+Because the core of DAMON is a framework for kernel components, it doesn't
+provide any direct interface for the user space. Such interfaces should be
+implemented by each DAMON API user kernel components, instead. DAMON subsystem
+itself implements such DAMON API user modules, which are supposed to be used
+for general purpose DAMON control and special purpose data access-aware system
+operations, and provides stable application binary interfaces (ABI) for the
+user space. The user space can build their efficient data access-aware
+applications using the interfaces.
+
+
+General Purpose User Interface Modules
+--------------------------------------
+
+DAMON modules that provide user space ABIs for general purpose DAMON usage in
+runtime.
+
+DAMON user interface modules, namely 'DAMON sysfs interface' and 'DAMON debugfs
+interface' are DAMON API user kernel modules that provide ABIs to the
+user-space. Please note that DAMON debugfs interface is currently deprecated.
+
+Like many other ABIs, the modules create files on sysfs and debugfs, allow
+users to specify their requests to and get the answers from DAMON by writing to
+and reading from the files. As a response to such I/O, DAMON user interface
+modules control DAMON and retrieve the results as user requested via the DAMON
+API, and return the results to the user-space.
+
+The ABIs are designed to be used for user space applications development,
+rather than human beings' fingers. Human users are recommended to use such
+user space tools. One such Python-written user space tool is available at
+Github (https://github.com/awslabs/damo), Pypi
+(https://pypistats.org/packages/damo), and Fedora
+(https://packages.fedoraproject.org/pkgs/python-damo/damo/).
+
+Please refer to the ABI :doc:`document </admin-guide/mm/damon/usage>` for
+details of the interfaces.
+
+
+Special-Purpose Access-aware Kernel Modules
+-------------------------------------------
+
+DAMON modules that provide user space ABI for specific purpose DAMON usage.
+
+DAMON sysfs/debugfs user interfaces are for full control of all DAMON features
+in runtime. For each special-purpose system-wide data access-aware system
+operations such as proactive reclamation or LRU lists balancing, the interfaces
+could be simplified by removing unnecessary knobs for the specific purpose, and
+extended for boot-time and even compile time control. Default values of DAMON
+control parameters for the usage would also need to be optimized for the
+purpose.
+
+To support such cases, yet more DAMON API user kernel modules that provide more
+simple and optimized user space interfaces are available. Currently, two
+modules for proactive reclamation and LRU lists manipulation are provided. For
+more detail, please read the usage documents for those
+(:doc:`/admin-guide/mm/damon/reclaim` and
+:doc:`/admin-guide/mm/damon/lru_sort`).
--
2.25.1
DAMOS is an important part of DAMON, but the design doc is not covering
it. Add sections for covering the basic part of DAMOS.
Signed-off-by: SeongJae Park <[email protected]>
---
Documentation/mm/damon/design.rst | 70 +++++++++++++++++++++++++++++++
1 file changed, 70 insertions(+)
diff --git a/Documentation/mm/damon/design.rst b/Documentation/mm/damon/design.rst
index 41abd0430dd7..9f9253529c3d 100644
--- a/Documentation/mm/damon/design.rst
+++ b/Documentation/mm/damon/design.rst
@@ -202,3 +202,73 @@ monitoring operations to check dynamic changes including memory mapping changes
and applies it to monitoring operations-related data structures such as the
abstracted monitoring target memory area only for each of a user-specified time
interval (``update interval``).
+
+
+Operation Schemes
+-----------------
+
+One common purpose of data access monitoring is access-aware system efficiency
+optimizations. For example,
+
+ paging out memory regions that are not accessed for more than two minutes
+
+or
+
+ using THP for memory regions that are larger than 2 MiB and showing a high
+ access frequency for more than one minute.
+
+One straightforward approach for such schemes would be profile-guided
+optimizations. That is, getting data access monitoring results of the
+workloads or the system using DAMON, finding memory regions of special
+characteristics by profiling the monitoring results, and making system
+operation changes for the regions. The changes could be made by modifying or
+providing advice to the software (the application and/or the kernel), or
+reconfiguring the hardware. Both offline and online approaches could be
+available.
+
+Among those, providing advice to the kernel at runtime would be flexible and
+effective, and therefore widely be used. However, implementing such schemes
+could impose unnecessary redundancy and inefficiency. The profiling could be
+redundant if the type of interest is common. Exchanging the information
+including monitoring results and operation advice between kernel and user
+spaces could be inefficient.
+
+To allow users to reduce such redundancy and inefficiencies by offloading the
+works, DAMON provides a feature called Data Access Monitoring-based Operation
+Schemes (DAMOS). It lets users specify their desired schemes at a high
+level. For such specifications, DAMON starts monitoring, finds regions having
+the access pattern of interest, and applies the user-desired operation actions
+to the regions as soon as found.
+
+
+Operation Action
+~~~~~~~~~~~~~~~~
+
+The management action that the users desire to apply to the regions of their
+interest. For example, paging out, prioritizing for next reclamation victim
+selection, advising ``khugepaged`` to collapse or split, or doing nothing but
+collecting statistics of the regions.
+
+The list of supported actions is defined in DAMOS, but the implementation of
+each action is in the DAMON operations set layer because the implementation
+normally depends on the monitoring target address space. For example, the code
+for paging specific virtual address ranges out would be different from that for
+physical address ranges. And the monitoring operations implementation sets are
+not mandated to support all actions of the list. Hence, the availability of
+specific DAMOS action depends on what operations set is selected to be used
+together.
+
+Applying an action to a region is considered as changing the region's
+characteristics. Hence, DAMOS resets the age of regions when an action is
+applied to those.
+
+
+Target Access Pattern
+~~~~~~~~~~~~~~~~~~~~~
+
+The access pattern of the schemes' interest. The patterns are constructed with
+the properties that DAMON's monitoring results provide, specifically the size,
+the access frequency, and the age. Users can describe their access pattern of
+interest by setting minimum and maximum values of the three properties. If a
+region's three properties are in the ranges, DAMOS classifies it as one of the
+regions that the scheme is having an interest in.
--
2.25.1
On Thu, 25 May 2023 21:43:04 +0000 SeongJae Park <[email protected]> wrote:
> Some of DAMON documents are outdated, or having minor typos or grammar
> erros. Especially, the design doc has not updated for DAMOS, which is
> an important part of DAMON. Fix the minor issues and update documents.
By the way, I started writing this patchset before LSFMM, but Michal's feedback
about DAMON documentation has definitely motivated this work, and was helpful.
Thank you, Michal. I just wanted to say that. Of course, more documentation
improvement works will be continued.
Thanks,
SJ
>
> SeongJae Park (10):
> Docs/mm/damon/faq: remove old questions
> Docs/mm/damon/maintainer-profile: fix typos and grammar errors
> Docs/mm/damon/design: add a section for overall architecture
> Docs/mm/damon/design: update the layout based on the layers
> Docs/mm/damon/design: rewrite configurable layers
> Docs/mm/damon/design: add a section for the relation between Core and
> Modules layer
> Docs/mm/damon/design: add sections for basic parts of DAMOS
> Docs/mm/damon/design: add sections for advanced features of DAMOS
> Docs/mm/damon/design: add a section for DAMON core API
> Docs/mm/damon/design: add a section for the modules layer
>
> Documentation/mm/damon/design.rst | 309 ++++++++++++++++--
> Documentation/mm/damon/faq.rst | 23 --
> Documentation/mm/damon/maintainer-profile.rst | 4 +-
> 3 files changed, 285 insertions(+), 51 deletions(-)
>
> --
> 2.25.1
>