[PATCH v6 0/7] docs/zh_CN: update DAMON translations

[PATCH v6 0/7] docs/zh_CN: update DAMON translations

[Doehyun Baek]

Update the Simplified Chinese DAMON documentation translations.  The
series is split by file, as requested.  It is based on mm-new after the
English DAMON documentation fixes have landed.

The intention of this series is to update
Documentation/translations/zh_CN/admin-guide/mm/damon/.  This required
choosing how to handle Documentation/translations/zh_CN/mm/damon/: do not
update it at all, update only design.rst, or update it fully.  I chose to
update only design.rst, because the admin-guide updates need its zh_CN
anchors and references.  Updating the other files would broaden the scope
beyond the requested admin-guide refresh.  I would do otherwise if
requested.

I checked the updated translations paragraph by paragraph and sentence by
sentence.  Given the size of the update, some issues may remain.  In
particular, usage.rst and design.rst were significantly outdated and needed
near-complete updates.

Doehyun Baek (7):
  docs/zh_CN: update DAMON design translation
  docs/zh_CN: add DAMON_STAT usage translation
  docs/zh_CN: update DAMON index translation
  docs/zh_CN: update DAMON start translation
  docs/zh_CN: update DAMON usage translation
  docs/zh_CN: update DAMON reclaim translation
  docs/zh_CN: update DAMON LRU sort translation

 .../zh_CN/admin-guide/mm/damon/index.rst      |  15 +-
 .../zh_CN/admin-guide/mm/damon/lru_sort.rst   |  68 +-
 .../zh_CN/admin-guide/mm/damon/reclaim.rst    |  82 ++-
 .../zh_CN/admin-guide/mm/damon/start.rst      |  63 +-
 .../zh_CN/admin-guide/mm/damon/stat.rst       |  94 +++
 .../zh_CN/admin-guide/mm/damon/usage.rst      | 521 +++++++++++---
 .../translations/zh_CN/mm/damon/design.rst    | 665 +++++++++++++++++-
 7 files changed, 1343 insertions(+), 165 deletions(-)
 create mode 100644 Documentation/translations/zh_CN/admin-guide/mm/damon/stat.rst


base-commit: db6ed2a3d31068ca5577466591b2521dee0508ca
-- 
2.43.0

[PATCH v6 1/7] docs/zh_CN: update DAMON design translation

[Doehyun Baek]

Update the Chinese translation of .../mm/damon/design.rst.

Update the translation through commit c24a7f497cb5
("Docs/mm/damon/design: update for DAMOS_QUOTA_NODE_ELIGIBLE_MEM_BP").

Signed-off-by: Doehyun Baek <doehyunbaek@gmail.com>
---
 .../translations/zh_CN/mm/damon/design.rst    | 665 +++++++++++++++++-
 1 file changed, 634 insertions(+), 31 deletions(-)

diff --git a/Documentation/translations/zh_CN/mm/damon/design.rst b/Documentation/translations/zh_CN/mm/damon/design.rst
index 16e3db34a7dd..6bf1f78801ef 100644
--- a/Documentation/translations/zh_CN/mm/damon/design.rst
+++ b/Documentation/translations/zh_CN/mm/damon/design.rst
@@ -13,35 +13,83 @@
 设计
 ====
 
-可配置的层
-==========
 
-DAMON提供了数据访问监控功能，同时使其准确性和开销可控。基本的访问监控需要依赖于目标地址空间
-并为之优化的基元。另一方面，作为DAMON的核心，准确性和开销的权衡机制是在纯逻辑空间中。DAMON
-将这两部分分离在不同的层中，并定义了它的接口，以允许各种低层次的基元实现与核心逻辑的配置。
+.. _damon_design_execution_model_and_data_structures_zh_CN:
 
-由于这种分离的设计和可配置的接口，用户可以通过配置核心逻辑和适当的低级基元实现来扩展DAMON的
-任何地址空间。如果没有提供合适的，用户可以自己实现基元。
+执行模型和数据结构
+==================
 
-例如，物理内存、虚拟内存、交换空间、那些特定的进程、NUMA节点、文件和支持的内存设备将被支持。
-另外，如果某些架构或设备支持特殊的优化访问检查基元，这些基元将很容易被配置。
+与监测相关的信息，包括监测请求规格和基于 DAMON 的操作方案，都存储在名为
+DAMON ``context`` 的数据结构中。DAMON 使用名为 ``kdamond`` 的内核线程执行
+每个上下文。多个 kdamond 可以并行运行，用于不同类型的监测。
 
+要了解用户空间如何进行配置并启动或停止 DAMON，请参考 :ref:`DAMON sysfs
+接口 <sysfs_interface_zh_CN>` 文档。
 
-特定地址空间基元的参考实现
-==========================
+用户还可以请求暂停和恢复每个上下文的执行。当上下文被暂停时，kdamond 除了应用
+在线参数更新外不做任何事情。
 
-基本访问监测的低级基元被定义为两部分。:
+要了解用户空间如何暂停或恢复每个上下文，请参考 :ref:`DAMON sysfs 上下文
+<sysfs_context_zh_CN>` 使用文档。
 
-1. 确定地址空间的监测目标地址范围
-2. 目标空间中特定地址范围的访问检查。
+总体架构
+========
 
-DAMON目前为物理和虚拟地址空间提供了基元的实现。下面两个小节描述了这些工作的方式。
+DAMON 子系统由三层构成，包括
 
+- :ref:`操作集 <damon_operations_set_zh_CN>`：实现依赖于给定监测目标地址空间
+  和可用软硬件基元集合的 DAMON 基本操作，
+- :ref:`核心 <damon_core_logic_zh_CN>`：在操作集层之上，实现包括监测开销/准确性
+  控制和访问感知系统操作在内的核心逻辑，以及
+- :ref:`模块 <damon_modules_zh_CN>`：在核心层之上，实现用于各种目的、并向用户空间
+  提供接口的内核模块。
+
+
+.. _damon_operations_set_zh_CN:
+
+操作集层
+========
+
+.. _damon_design_configurable_operations_set_zh_CN:
+
+为了进行数据访问监测和其他低层工作，DAMON 需要一组针对给定目标地址空间、
+并依赖于和优化于该地址空间的特定操作实现。例如，下面两个用于访问监测的操作
+依赖于地址空间。
+
+1. 确定该地址空间的监测目标地址范围。
+2. 检查目标空间中特定地址范围的访问。
+
+DAMON 将这些实现整合到称为 DAMON 操作集的层中，并定义它和上层之间的接口。
+上层专用于 DAMON 的核心逻辑，包括控制监测准确性和开销的机制。
+
+因此，DAMON 可以通过配置核心逻辑使用适当的操作集，轻松扩展到任意地址空间
+和/或可用硬件功能。如果给定目的没有可用操作集，也可以按照层间接口实现新的
+操作集。
+
+例如，物理内存、虚拟内存、交换空间、特定进程、NUMA 节点、文件和后端内存设备
+都可以被支持。另外，如果某些架构或设备支持特殊的优化访问检查功能，也可以很容易
+进行配置。
+
+DAMON 当前提供以下三个操作集。下面三个小节描述它们如何工作。
+
+ - vaddr：监测特定进程的虚拟地址空间
+ - fvaddr：监测固定虚拟地址范围
+ - paddr：监测系统的物理地址空间
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 进行配置，
+请参考文档的 :ref:`operations <sysfs_context_zh_CN>` 文件部分。
+
+
+.. _damon_design_vaddr_target_regions_construction_zh_CN:
 
 基于VMA的目标地址范围构造
 -------------------------
 
-这仅仅是针对虚拟地址空间基元的实现。对于物理地址空间，只是要求用户手动设置监控目标地址范围。
+``vaddr`` DAMON 操作集的一种机制，会自动初始化并更新监测目标地址区域，
+以覆盖目标进程的整个内存映射。
+
+该机制仅用于 ``vaddr`` 操作集。对于 ``fvaddr`` 和 ``paddr`` 操作集，
+用户需要手动设置监测目标地址范围。
 
 在进程的超级巨大的虚拟地址空间中，只有小部分被映射到物理内存并被访问。因此，跟踪未映射的地
 址区域只是一种浪费。然而，由于DAMON可以使用自适应区域调整机制来处理一定程度的噪声，所以严
@@ -50,7 +98,7 @@ DAMON目前为物理和虚拟地址空间提供了基元的实现。下面两个
 
 出于这个原因，这个实现将复杂的映射转换为三个不同的区域，覆盖地址空间的每个映射区域。这三个
 区域之间的两个空隙是给定地址空间中两个最大的未映射区域。这两个最大的未映射区域是堆和最上面
-的mmap()区域之间的间隙，以及在大多数情况下最下面的mmap()区域和堆之间的间隙。因为这些间隙
+的mmap()区域之间的间隙，以及在大多数情况下最下面的mmap()区域和栈之间的间隙。因为这些间隙
 在通常的地址空间中是异常巨大的，排除这些间隙就足以做出合理的权衡。下面详细说明了这一点::
 
     <heap>
@@ -69,19 +117,48 @@ DAMON目前为物理和虚拟地址空间提供了基元的实现。下面两个
 找到相关的PTE访问位的方式。虚拟地址的实现是为该地址的目标任务查找页表，而物理地址的实现则
 是查找与该地址有映射关系的每一个页表。通过这种方式，实现者找到并清除下一个采样目标地址的位，
 并检查该位是否在一个采样周期后再次设置。这可能会干扰其他使用访问位的内核子系统，即空闲页跟
-踪和回收逻辑。为了避免这种干扰，DAMON使其与空闲页面跟踪相互排斥，并使用 ``PG_idle`` 和
-``PG_young`` 页面标志来解决与回收逻辑的冲突，就像空闲页面跟踪那样。
+踪和回收逻辑。DAMON 不做任何事情来避免干扰空闲页跟踪，因此处理这种干扰是系统管理员的责任。
+不过，它会像空闲页跟踪一样，使用 ``PG_idle`` 和 ``PG_young`` 页面标志解决与回收逻辑的冲突。
+
+
+.. _damon_design_addr_unit_zh_CN:
+
+地址单位
+--------
 
+DAMON 核心层使用 ``unsigned long`` 类型表示监测目标地址范围。在某些情况下，
+给定操作集的地址空间可能过大，无法用该类型处理。带有大物理地址扩展的
+ARM（32 位）就是一个例子。对于这类情况，提供了一个称为 ``address unit`` 的
+逐操作集参数。它表示一个缩放因子，需要乘以核心层地址，才能计算给定地址
+空间中的真实地址。是否支持 ``address unit`` 参数取决于每个操作集实现。
+``paddr`` 是唯一支持该参数的操作集实现。
 
-独立于地址空间的核心机制
-========================
+如果该值小于 ``PAGE_SIZE``，则只能使用 2 的幂。
+
+
+.. _damon_core_logic_zh_CN:
+
+核心逻辑
+========
+
+.. _damon_design_monitoring_zh_CN:
+
+监测
+----
 
 下面四个部分分别描述了DAMON的核心机制和五个监测属性，即 ``采样间隔`` 、 ``聚集间隔`` 、
 ``更新间隔`` 、 ``最小区域数`` 和 ``最大区域数`` 。
 
+请注意，``最小区域数`` 必须为 3 或更高。这是因为虚拟地址空间监测被设计为至少处理三个区域，
+以容纳普通虚拟地址空间中常见的两个大型未映射区域。虽然对 ``paddr`` 这类其他操作集来说，
+这一限制可能并非严格必要，但为了保持一致性，目前会对所有 DAMON 操作强制执行。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置这些属性，
+请参考文档的 :ref:`monitoring_attrs <sysfs_monitoring_attrs_zh_CN>` 部分。
+
 
 访问频率监测
-------------
+~~~~~~~~~~~~
 
 DAMON的输出显示了在给定的时间内哪些页面的访问频率是多少。访问频率的分辨率是通过设置
 ``采样间隔`` 和 ``聚集间隔`` 来控制的。详细地说，DAMON检查每个 ``采样间隔`` 对每
@@ -103,38 +180,564 @@ DAMON的输出显示了在给定的时间内哪些页面的访问频率是多少
 这种机制的监测开销将随着目标工作负载规模的增长而任意增加。
 
 
+.. _damon_design_region_based_sampling_zh_CN:
+
 基于区域的抽样调查
-------------------
+~~~~~~~~~~~~~~~~~~
 
 为了避免开销的无限制增加，DAMON将假定具有相同访问频率的相邻页面归入一个区域。只要保持
 这个假设（一个区域内的页面具有相同的访问频率），该区域内就只需要检查一个页面。因此，对
 于每个 ``采样间隔`` ，DAMON在每个区域中随机挑选一个页面，等待一个 ``采样间隔`` ，检
-查该页面是否同时被访问，如果被访问则增加该区域的访问频率。因此，监测开销是可以通过设置
-区域的数量来控制的。DAMON允许用户设置最小和最大的区域数量来进行权衡。
+查该页面是否同时被访问，如果被访问则增加该区域的访问频率计数器。该计数器称为区域的
+``nr_accesses``。因此，监测开销是可以通过设置区域的数量来控制的。DAMON允许用户设置最小
+和最大的区域数量来进行权衡。
 
 然而，如果假设没有得到保证，这个方案就不能保持输出的质量。
 
 
+.. _damon_design_adaptive_regions_adjustment_zh_CN:
+
 适应性区域调整
---------------
+~~~~~~~~~~~~~~
 
 即使最初的监测目标区域被很好地构建以满足假设（同一区域内的页面具有相似的访问频率），数
 据访问模式也会被动态地改变。这将导致监测质量下降。为了尽可能地保持假设，DAMON根据每个
 区域的访问频率自适应地进行合并和拆分。
 
-对于每个 ``聚集区间`` ，它比较相邻区域的访问频率，如果频率差异较小，就合并这些区域。
-然后，在它报告并清除每个区域的聚合接入频率后，如果区域总数不超过用户指定的最大区域数，
-它将每个区域拆分为两个或三个区域。
+对于每个 ``聚集区间`` ，它比较相邻区域的访问频率（``nr_accesses``）。如果差异较小，
+并且两个区域的大小之和小于总区域大小除以 ``最小区域数``，DAMON 就会合并这两个区域。如果
+合并后的总区域数仍然高于 ``最大区域数``，它会增大访问频率差异阈值并重复合并，直到满足区域
+数上限，或者阈值高于可能的最大值（``聚集间隔`` 除以 ``采样间隔``）。然后，在它报告并清除
+每个区域的聚合访问频率后，如果拆分后的区域总数不超过用户指定的最大区域数，它会把每个区域
+拆分为两个或三个区域。
 
 通过这种方式，DAMON提供了其最佳的质量和最小的开销，同时保持了用户为其权衡设定的界限。
 
+.. _damon_design_age_tracking_zh_CN:
+
+年龄跟踪
+~~~~~~~~
+
+通过分析监测结果，用户还可以发现某个区域当前的访问模式已经保持了多长时间。这可用于更好地理解
+访问模式。例如，可以利用访问频率和时近性实现页面放置算法。为了让这种访问模式保持时间分析更容
+易，DAMON 在每个区域中维护另一个名为 ``age`` 的计数器。对于每个 ``聚集间隔``，DAMON 检查该
+区域的大小和访问频率（``nr_accesses``）是否发生了显著变化。如果发生了变化，该计数器会被重置为
+零。否则，该计数器会增加。
+
+
+.. _damon_design_data_attrs_monitoring_zh_CN:
+
+数据属性监测
+~~~~~~~~~~~~
+
+数据访问模式只是数据属性的一种类型。在某些用例中，用户需要了解更多数据属性
+信息。例如，用户可能需要知道给定热或冷内存区域中有多少由匿名页支持，或者属于
+某个特定 cgroup。为此，提供了数据属性监测功能。
+
+使用该功能时，用户可以把感兴趣的数据属性注册到 DAMON :ref:`上下文
+<damon_design_execution_model_and_data_structures_zh_CN>` 中。注册通过为每个属性
+指定一个探针完成。每个探针指定一个规则，用于判断给定内存区域是否具有相关
+属性。该规则由多个过滤器构成。除支持的过滤器类型不同外，这些过滤器的工作方式
+与 :ref:`DAMOS 过滤器 <damon_design_damos_filters_zh_CN>` 相同。目前，数据属性
+监测只支持 ``anon`` 和 ``memcg`` 过滤器类型。
+
+如果注册了这类探针，DAMON 在进行访问 :ref:`采样
+<damon_design_region_based_sampling_zh_CN>` 时，会对每个区域的采样内存执行这些
+探针。每个 :ref:`聚集间隔 <damon_design_monitoring_zh_CN>` 中被识别为具有数据
+属性（命中探针）的样本数量，会计入每区域、每探针的计数器。因此，用户可以在
+每个聚集间隔后读取每区域、每探针的探针命中计数器，从而了解给定 DAMON 区域
+有多少具有特定数据属性。
+
+这是基于采样的机制。因此，它很轻量，但输出可能包含一些测量误差。用户应在
+充分理解统计意义的基础上使用输出。
+
+另一种更高精度的方式是使用 ``stat`` :ref:`动作
+<damon_design_damos_action_zh_CN>` 的 :ref:`DAMOS 过滤器
+<damon_design_damos_filters_zh_CN>`，并使用 ``sz_ops_filter_passed`` :ref:`统计
+<damon_design_damos_stat_zh_CN>`。这种方式以页级别提供数据属性信息。不过，由于
+它在页级别操作，开销与内存大小成正比。
 
 动态目标空间更新处理
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 监测目标地址范围可以动态改变。例如，虚拟内存可以动态地被映射和解映射。物理内存可以被
 热插拔。
 
 由于在某些情况下变化可能相当频繁，DAMON允许监控操作检查动态变化，包括内存映射变化，
 并仅在用户指定的时间间隔（ ``更新间隔`` ）中的每个时间段，将其应用于监控操作相关的
-数据结构，如抽象的监控目标内存区。
\ No newline at end of file
+数据结构，如抽象的监控目标内存区。
+
+用户空间可以通过 DAMON sysfs 接口和/或 tracepoints 获取监测结果。更多细节请分别参考
+:ref:`DAMOS 尝试区域 <sysfs_schemes_tried_regions_zh_CN>` 和 :ref:`监测点 <tracepoint_zh_CN>`
+文档。
+
+
+.. _damon_design_monitoring_params_tuning_guide_zh_CN:
+
+监测参数调优指南
+~~~~~~~~~~~~~~~~
+
+简而言之，应设置 ``聚集间隔``，使其能够为使用目的捕获有意义数量的访问。访问数量可以用聚集后
+监测结果快照中各区域的 ``nr_accesses`` 和 ``age`` 来衡量。该间隔的默认值 ``100ms`` 在许多情况
+下被证明过短。应按 ``聚集间隔`` 的比例设置 ``采样间隔``。默认推荐比例为 ``1/20``。
+
+``聚集间隔`` 应设置为工作负载可在该间隔内为监测目的产生一定数量访问的时间间隔。如果该间隔过短，
+只能捕获少量访问。结果是，监测结果会看起来像所有内容都同样只是很少被访问。对许多目的而言，这
+将毫无用处。不过，如果该间隔过长，根据给定目的的时间尺度，区域通过 :ref:`区域调整机制
+<damon_design_adaptive_regions_adjustment_zh_CN>` 收敛所需的时间可能过长。如果工作负载实际只产生
+很少访问，而用户却认为监测目的所需的访问数量很高，就可能发生这种情况。对于这种情况，应仔细重
+新考虑每个 ``聚集间隔`` 要捕获的目标访问数量。还要注意，捕获的访问数量不仅用 ``nr_accesses``
+表示，也用 ``age`` 表示。例如，即使监测结果中的每个区域都显示 ``nr_accesses`` 为零，仍然可以
+用 ``age`` 值作为时近性信息来区分区域。
+
+因此，``聚集间隔`` 的最佳值取决于工作负载的访问密集程度。用户应根据每个聚集后的监测结果快照
+中捕获的访问数量来调优该间隔。
+
+请注意，该间隔的默认值是 100 毫秒，在许多情况下都太短，尤其是在大型系统上。
+
+``采样间隔`` 定义每次聚集的分辨率。如果它设置得过大，监测结果会看起来像每个区域都同样很少被
+访问，或者同样频繁地被访问。也就是说，区域将无法根据访问模式区分，因此结果在许多用例中都会无
+用。如果 ``采样间隔`` 过小，它不会降低分辨率，但会增加监测开销。如果它已经足以为给定目的提供
+足够的监测结果分辨率，就不应再不必要地降低。建议将它按 ``聚集间隔`` 的比例设置。默认比例设为
+``1/20``，并且仍然推荐该比例。
+
+基于手动调优指南，DAMON 提供了更直观的、基于调节项的间隔自动调优机制。更多细节请参考
+:ref:`该功能的设计文档 <damon_design_monitoring_intervals_autotuning_zh_CN>`。
+
+基于上述指南的示例调优，请参考英文文档 Documentation/mm/damon/monitoring_intervals_tuning_example.rst。
+
+
+.. _damon_design_monitoring_intervals_autotuning_zh_CN:
+
+监测间隔自动调优
+~~~~~~~~~~~~~~~~
+
+DAMON 基于 :ref:`调优指南的思路 <damon_design_monitoring_params_tuning_guide_zh_CN>`，提供了
+对 ``采样间隔`` 和 ``聚集间隔`` 的自动调优机制。该调优机制允许用户设置希望 DAMON 在给定时间间隔
+内观测到的访问事件数量目标。用户可以把该目标指定为 DAMON 观测到的访问事件数量与理论最大事件数
+量之间的比例（``access_bp``），该比例在给定数量的聚集中测量（``aggrs``）。
+
+DAMON 观测到的访问事件基于 DAMON :ref:`区域假设 <damon_design_region_based_sampling_zh_CN>`
+按字节粒度计算。例如，如果发现大小为 ``X`` 字节、``nr_accesses`` 为 ``Y`` 的区域，就意味着
+DAMON 观测到了 ``X * Y`` 个访问事件。该区域的理论最大访问事件也以相同方式计算，但会把 ``Y``
+替换为理论最大 ``nr_accesses``，即 ``聚集间隔 / 采样间隔``。
+
+该机制会计算 ``aggrs`` 次聚集期间的访问事件比例。如果观测到的访问比例低于或高于目标值，就按
+相同比例增大或减小 ``采样间隔`` 和 ``聚集间隔``。间隔变化比例按当前采样比例与目标比例之间的
+距离决定。
+
+用户还可以通过两个参数（``min_sample_us`` 和 ``max_sample_us``）进一步设置调优机制可设置的
+最小和最大 ``采样间隔``。由于调优机制总是以相同比例改变 ``采样间隔`` 和 ``聚集间隔``，所以
+每次调优变化后的最小和最大 ``聚集间隔`` 也可以自动一起设置。
+
+该调优默认关闭，需要由用户显式设置。根据经验法则和帕累托原则，推荐使用 4% 的访问样本比例目标。
+请注意，这里应用了两次帕累托原则（80/20 规则）。也就是说，假设以 4%（20% 的 20%）的 DAMON
+观测访问事件比例（来源），捕获 64%（80% 乘以 80%）的真实访问事件（结果）。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 使用该功能，请参考文档
+的 :ref:`intervals_goal <damon_usage_sysfs_monitoring_intervals_goal_zh_CN>` 部分。
+
+
+.. _damon_design_damos_zh_CN:
+
+操作方案
+--------
+
+数据访问监测的一个常见目的，是实现访问感知的系统效率优化。例如：
+
+    换出超过两分钟未被访问的内存区域
+
+或者：
+
+    对大于 2 MiB 且显示高访问频率超过一分钟的内存区域使用 THP。
+
+这类方案的一种直接做法是基于剖析的优化。也就是说，使用 DAMON 获取工作负载
+或系统的数据访问监测结果，通过分析监测结果找到具有特殊特征的内存区域，并针对
+这些区域进行系统操作变更。这些变更可以通过修改软件（应用程序和/或内核）或向
+其提供建议来完成，也可以通过重新配置硬件来完成。离线和在线两种方式都可以使用。
+
+其中，在运行时向内核提供建议会比较灵活且有效，因此被广泛使用。不过，实现这类
+方案可能引入不必要的冗余和低效。如果关注的类型很常见，剖析可能是冗余的。在
+内核和用户空间之间交换包括监测结果和操作建议在内的信息，也可能效率较低。
+
+为了让用户通过卸载这些工作来减少这种冗余和低效，DAMON 提供了一个名为基于
+数据访问监测的操作方案（DAMOS）的功能。它允许用户以高层次指定期望的方案。
+对于这类规格，DAMON 会开始监测，找到具有感兴趣访问模式的区域，并在每个用户
+指定的时间间隔（称为 ``apply_interval``）把用户期望的操作动作应用于这些区域。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置
+``apply_interval``，请参考文档的 :ref:`apply_interval_us <sysfs_scheme_zh_CN>`
+部分。
+
+
+.. _damon_design_damos_action_zh_CN:
+
+操作动作
+~~~~~~~~
+
+用户希望应用到其感兴趣区域的管理动作。例如，换出、为下一次回收受害者选择提高
+优先级、建议 ``khugepaged`` 折叠或拆分，或者什么也不做而只收集区域统计信息。
+
+支持的动作列表在 DAMOS 中定义，但每个动作的实现位于 DAMON 操作集层，因为实现
+通常依赖于监测目标地址空间。例如，换出特定虚拟地址范围的代码会不同于换出物理
+地址范围的代码。监测操作实现集也不被要求支持列表中的所有动作。因此，特定 DAMOS
+动作是否可用取决于选择一起使用的操作集。
+
+支持的动作列表、含义以及支持每个动作的 DAMON 操作集如下。
+
+ - ``willneed``：对带有 ``MADV_WILLNEED`` 的区域调用 ``madvise()``。
+   ``vaddr`` 和 ``fvaddr`` 操作集支持。
+ - ``cold``：对带有 ``MADV_COLD`` 的区域调用 ``madvise()``。
+   ``vaddr`` 和 ``fvaddr`` 操作集支持。
+ - ``pageout``：回收该区域。
+   ``vaddr``、``fvaddr`` 和 ``paddr`` 操作集支持。
+ - ``hugepage``：对带有 ``MADV_HUGEPAGE`` 的区域调用 ``madvise()``。
+   ``vaddr`` 和 ``fvaddr`` 操作集支持。当禁用 TRANSPARENT_HUGEPAGE 时，
+   应用该动作只会失败。
+ - ``nohugepage``：对带有 ``MADV_NOHUGEPAGE`` 的区域调用 ``madvise()``。
+   ``vaddr`` 和 ``fvaddr`` 操作集支持。当禁用 TRANSPARENT_HUGEPAGE 时，
+   应用该动作只会失败。
+ - ``collapse``：对带有 ``MADV_COLLAPSE`` 的区域调用 ``madvise()``。
+   ``vaddr`` 和 ``fvaddr`` 操作集支持。当禁用 TRANSPARENT_HUGEPAGE 时，
+   应用该动作只会失败。
+ - ``lru_prio``：提高该区域在其 LRU 链表上的优先级。
+   ``paddr`` 操作集支持。
+ - ``lru_deprio``：降低该区域在其 LRU 链表上的优先级。
+   ``paddr`` 操作集支持。
+ - ``migrate_hot``：迁移区域，并优先迁移更热的区域。
+   ``vaddr``、``fvaddr`` 和 ``paddr`` 操作集支持。
+ - ``migrate_cold``：迁移区域，并优先迁移更冷的区域。
+   ``vaddr``、``fvaddr`` 和 ``paddr`` 操作集支持。
+ - ``stat``：什么也不做，只统计信息。
+   所有操作集都支持。
+
+把除 ``stat`` 外的动作应用到某个区域，会被认为改变了该区域的特征。因此，
+当任何这类动作被应用到区域时，DAMOS 会重置这些区域的 age。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置
+动作，请参考文档的 :ref:`action <sysfs_scheme_zh_CN>` 部分。
+
+
+.. _damon_design_damos_access_pattern_zh_CN:
+
+目标访问模式
+~~~~~~~~~~~~
+
+方案感兴趣的访问模式。这些模式由 DAMON 监测结果提供的属性构成，具体包括
+大小、访问频率和年龄。用户可以通过设置这三个属性的最小值和最大值，描述
+自己感兴趣的访问模式。如果某个区域的这三个属性都在范围内，DAMOS 就把它
+分类为该方案感兴趣的区域之一。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置
+访问模式，请参考文档的 :ref:`access_pattern <sysfs_access_pattern_zh_CN>`
+部分。
+
+
+.. _damon_design_damos_quotas_zh_CN:
+
+配额
+~~~~
+
+DAMOS 的开销上界控制功能。如果目标访问模式没有正确调优，DAMOS 可能带来高开销。
+例如，如果发现一个具有感兴趣访问模式的巨大内存区域，把方案动作应用到该巨大区域
+的所有页面可能消耗不可接受的大量系统资源。通过调优访问模式来防止这类问题可能
+很有挑战，特别是在工作负载的访问模式高度动态时。
+
+为缓解这种情况，DAMOS 提供了一个称为配额的开销上界控制功能。它允许用户指定
+DAMOS 可用于应用动作的时间上限，和/或在用户指定的时间段内可应用动作的最大内存
+区域字节数。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置基本
+配额，请参考文档的 :ref:`quotas <sysfs_quotas_zh_CN>` 部分。
+
+
+.. _damon_design_damos_quotas_prioritization_zh_CN:
+
+优先级
+^^^^^^
+
+一种在配额限制下作出良好决策的机制。当由于配额限制而无法把动作应用到所有感兴趣
+区域时，DAMOS 会对区域排序，并只把动作应用到优先级足够高、且不会超过配额的区域。
+
+每个动作的优先级机制应该不同。例如，很少被访问（更冷）的内存区域应在 page-out
+方案动作中被优先处理。相反，对于大页折叠方案动作，更冷的区域应被降低优先级。
+因此，每个动作的优先级机制与动作一起，在各个 DAMON 操作集中实现。
+
+虽然实现取决于 DAMON 操作集，但通常会使用区域的访问模式属性来计算优先级。有些
+用户可能希望针对自己的特定场景个性化这些机制。例如，有些用户可能希望该机制更重视
+时近性（``age``）而不是访问频率（``nr_accesses``）。DAMOS 允许用户指定每个访问模式
+属性的权重，并把这些信息传递给底层机制。不过，权重如何被尊重，甚至是否被尊重，
+都取决于底层优先级机制实现。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置优先级
+权重，请参考文档的 :ref:`weights <sysfs_quotas_zh_CN>` 部分。
+
+
+.. _damon_design_damos_quotas_failed_memory_charging_ratio_zh_CN:
+
+动作失败内存计费比率
+^^^^^^^^^^^^^^^^^^^^
+
+对给定区域执行 DAMOS 动作时，区域中某些内存子集可能失败。例如，如果动作是
+``pageout``，而该区域包含一些不可回收页，则把该动作应用到这些页会失败。
+这类失败动作应用消耗的系统资源量通常不同于成功动作应用。对于这类情况，用户可以
+为失败内存设置不同的计费比率。该比率可以用 ``fail_charge_num`` 和
+``fail_charge_denom`` 参数指定。这两个参数分别表示比率的分子和分母。只有当
+``fail_charge_denom`` 不为零时，该功能才启用。
+
+例如，假设某个 DAMOS 动作被应用到大小为 1,000 MiB 的区域。该动作只成功应用到
+该区域的 700 MiB。``fail_charge_num`` 和 ``fail_charge_denom`` 分别设置为 ``1``
+和 ``1024``。那么只会计费 700 MiB 和 300 KiB 的大小（``700 MiB + 300 MiB * 1 /
+1024``）。
+
+
+.. _damon_design_damos_quotas_auto_tuning_zh_CN:
+
+面向目标的反馈驱动自动调优
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+自动反馈驱动的配额调优。用户可以不设置绝对配额值，而是指定自己感兴趣的指标，
+以及希望该指标达到的目标值。随后，DAMOS 会自动调优对应方案的激进程度（配额）。
+例如，如果 DAMOS 未达到目标，DAMOS 会自动增加配额。如果 DAMOS 超过目标，则会
+减少配额。
+
+用户可以按需要选择两种这样的调优算法。
+
+- ``consist``：基于比例反馈环的算法。尝试找到一个应持续保持的最佳配额，以便持续
+  达成目标。适用于动态和长时间运行环境中的内核内部操作。这是默认选择。如果不确定，
+  请使用它。
+- ``temporal``：更直接的算法。尝试尽快达成目标，使用允许的最大配额，但只持续短暂
+  时间。当配额未达成时，该算法持续把配额调优到允许的最大值。一旦配额[超过]达成，
+  它就把配额设置为零。适用于需要确定性控制的环境。
+
+目标可以用五个参数指定，即 ``target_metric``、``target_value``、``current_value``、
+``nid`` 和 ``path``。自动调优机制尝试使 ``target_metric`` 的 ``current_value``
+等于 ``target_value``。
+
+- ``user_input``：用户提供的值。用户可以使用任何自己感兴趣的指标作为该值。用户空间
+  主工作负载的延迟或吞吐量、空闲内存率或内存压力停滞时间（PSI）等系统指标都可以
+  作为示例。请注意，在这种情况下，用户应自己显式设置 ``current_value``。换言之，
+  用户应反复提供反馈。
+- ``some_mem_psi_us``：系统范围的 ``some`` 内存压力停滞信息，单位为微秒，从上一次
+  配额重置到下一次配额重置之间测量。DAMOS 自行进行测量，所以用户只需要在初始时
+  设置 ``target_value``。换言之，DAMOS 会自反馈。
+- ``node_mem_used_bp``：特定 NUMA 节点的已用内存比率，单位为 bp（1/10,000）。
+- ``node_mem_free_bp``：特定 NUMA 节点的空闲内存比率，单位为 bp（1/10,000）。
+- ``node_memcg_used_bp``：特定 cgroup 在特定 NUMA 节点上的节点已用内存比率，
+  单位为 bp（1/10,000）。
+- ``node_memcg_free_bp``：特定 cgroup 在特定 NUMA 节点上的节点未用内存比率，
+  单位为 bp（1/10,000）。
+- ``active_mem_bp``：活跃内存相对活跃 + 非活跃（LRU）内存大小的比率，单位为 bp
+  （1/10,000）。
+- ``inactive_mem_bp``：非活跃内存相对活跃 + 非活跃（LRU）内存大小的比率，单位为 bp
+  （1/10,000）。
+- ``node_eligible_mem_bp``：节点中符合方案目标访问模式条件的内存比率，单位为 bp
+  （1/10,000）。
+
+对于 ``node_mem_used_bp``、``node_mem_free_bp``、``node_memcg_used_bp``、
+``node_memcg_free_bp`` 和 ``node_eligible_mem_bp``，``nid`` 是可选必需的，
+用于指向特定 NUMA 节点。
+
+只有 ``node_memcg_used_bp`` 和 ``node_memcg_free_bp`` 可选必需 ``path``，用于
+指向 cgroup 路径。该值应是从 cgroups 挂载点开始的内存 cgroup 路径。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置调优
+目标指标、目标值和/或当前值，请参考文档的 :ref:`quota goals
+<sysfs_schemes_quota_goals_zh_CN>` 部分。
+
+
+.. _damon_design_damos_watermarks_zh_CN:
+
+水位
+~~~~
+
+条件式 DAMOS（去）激活自动化。用户可能希望 DAMOS 只在特定情况下运行。例如，
+当保证有足够空闲内存时，运行主动回收方案只会消耗不必要的系统资源。为避免这类
+消耗，用户需要手动监测一些指标（例如空闲内存率），并打开或关闭 DAMON/DAMOS。
+
+DAMOS 允许用户使用三个水位卸载这类工作。它允许用户配置自己感兴趣的指标，以及
+三个水位值，即高、中和低。如果指标值高于高水位或低于低水位，该方案会被停用。
+如果指标值低于中水位但高于低水位，该方案会被激活。如果所有方案都被水位停用，
+监测也会被停用。在这种情况下，DAMON 工作线程只会周期性地检查水位，因此几乎
+不会产生开销。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置水位，
+请参考文档的 :ref:`watermarks <sysfs_watermarks_zh_CN>` 部分。
+
+
+.. _damon_design_damos_filters_zh_CN:
+
+过滤器
+~~~~~~
+
+非访问模式式的目标内存区域过滤。如果用户运行自己编写的程序或拥有好的剖析工具，
+他们可能比内核知道更多信息，例如未来的访问模式或针对特定内存类型的一些特殊需求。
+例如，一些用户可能知道只有匿名页会影响其程序性能。他们也可以拥有一组延迟关键进程
+列表。
+
+为了让用户用这类特殊知识优化 DAMOS 方案，DAMOS 提供了一个称为 DAMOS 过滤器的功能。
+该功能允许用户为每个方案设置任意数量的过滤器。每个过滤器指定：
+
+- 一种内存类型（``type``），
+- 它是针对该类型的内存，还是针对该类型以外的所有内存（``matching``），以及
+- 是否允许（包含）或拒绝（排除）把方案动作应用到该内存（``allow``）。
+
+为了高效处理过滤器，一些类型的过滤器由核心层处理，而其他类型由操作集处理。因此，
+在后一种情况下，是否支持过滤器类型取决于 DAMON 操作集。对于核心层处理的过滤器，
+被过滤器排除的内存区域不会计入方案已尝试应用的区域。相反，如果内存区域被操作集层
+处理的过滤器过滤，它会计入方案已尝试。这种差异会影响统计信息。
+
+安装多个过滤器时，由核心层处理的一组过滤器首先求值。之后，由操作层处理的一组过滤器
+求值。每组过滤器内部按安装顺序求值。如果某部分内存匹配某个过滤器，后续过滤器会被
+忽略。如果该部分因为没有匹配任何过滤器而通过过滤器求值阶段，则是否对其应用方案动作
+取决于最后一个过滤器的 allow 类型。如果最后一个过滤器是允许型，该部分内存会被拒绝，
+反之亦然。
+
+例如，假设按顺序安装了 1）一个允许匿名页的过滤器，和 2）另一个拒绝年轻页的过滤器。
+如果某个符合方案动作应用条件的区域中的页面是匿名页，不论它是否年轻，方案动作都会应用
+到该页，因为它匹配第一个允许过滤器。如果该页不是匿名页但年轻，则方案动作不会应用，
+因为第二个拒绝过滤器阻止了它。如果该页既不是匿名页也不年轻，由于没有匹配过滤器，
+该页会通过过滤器求值阶段，并且动作会应用到该页。
+
+当前支持以下 ``type`` 的过滤器。
+
+- 核心层处理
+    - addr
+        - 应用于属于给定地址范围的页面。
+    - target
+        - 应用于属于给定 DAMON 监测目标的页面。
+- 操作层处理，只有 ``paddr`` 操作集支持。
+    - anon
+        - 应用于包含未存储在文件中的数据的页面。
+    - active
+        - 应用于活跃页。
+    - memcg
+        - 应用于属于给定 cgroup 的页面。
+    - young
+        - 应用于自方案上次访问检查以来被访问过的页面。
+    - hugepage_size
+        - 应用于以给定大小范围管理的页面。
+    - unmapped
+        - 应用于未映射的页面。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 设置过滤器，
+请参考文档的 :ref:`filters <sysfs_filters_zh_CN>` 部分。
+
+.. _damon_design_damos_stat_zh_CN:
+
+统计信息
+~~~~~~~~
+
+DAMOS 行为的统计信息，用于帮助监测、调优和调试 DAMOS。
+
+DAMOS 从方案执行开始起，为每个方案统计以下信息。
+
+- ``nr_tried``：方案尝试应用的区域总数。
+- ``sz_tried``：方案尝试应用的区域总大小。
+- ``sz_ops_filter_passed``：通过操作集层处理的 DAMOS 过滤器的总字节数。
+- ``nr_applied``：方案已应用的区域总数。
+- ``sz_applied``：方案已应用的区域总大小。
+- ``qt_exceeds``：方案配额被超过的总次数。
+- ``nr_snapshots``：方案尝试应用的 DAMON 快照总数。
+- ``max_nr_snapshots``：``nr_snapshots`` 的上限。
+
+“方案尝试应用到某个区域”表示 DAMOS 核心逻辑判断该区域符合应用方案
+:ref:`动作 <damon_design_damos_action_zh_CN>` 的条件。核心逻辑处理的
+:ref:`访问模式 <damon_design_damos_access_pattern_zh_CN>`、:ref:`配额
+<damon_design_damos_quotas_zh_CN>`、:ref:`水位 <damon_design_damos_watermarks_zh_CN>`
+和 :ref:`过滤器 <damon_design_damos_filters_zh_CN>` 可能影响这一判断。核心逻辑
+只会请求底层 :ref:`操作集 <damon_operations_set_zh_CN>` 对该区域应用动作，因此
+该动作是否真正应用并不明确。这就是它被称为“尝试”的原因。
+
+“方案应用到某个区域”表示 :ref:`操作集 <damon_operations_set_zh_CN>` 已经把动作
+应用到该区域的至少一部分。操作集处理的 :ref:`过滤器
+<damon_design_damos_filters_zh_CN>`、:ref:`动作 <damon_design_damos_action_zh_CN>`
+类型以及该区域中的页面类型都可能影响这一点。例如，如果过滤器设置为排除匿名页且
+该区域只有匿名页，或者动作是 ``pageout`` 而该区域的所有页面都不可回收，则把动作
+应用到该区域会失败。
+
+不同于普通统计信息，``max_nr_snapshots`` 由用户设置。如果它设置为非零，且
+``nr_snapshots`` 等于或大于 ``max_nr_snapshots``，该方案会被停用。
+
+要了解用户空间如何通过 :ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 读取统计
+信息，请参考文档的 :ref:`stats <sysfs_schemes_stats_zh_CN>` 部分。
+
+
+区域遍历
+~~~~~~~~
+
+DAMOS 功能允许用户访问刚刚应用了 DAMOS 动作的每个区域。使用该功能，DAMON
+:ref:`API <damon_design_api_zh_CN>` 允许用户访问这些区域的完整属性，包括访问监测结果以及
+区域内部通过 DAMOS 过滤器的内存量。:ref:`DAMON sysfs 接口 <sysfs_interface_zh_CN>` 也允许
+用户通过特殊 :ref:`文件 <sysfs_schemes_tried_regions_zh_CN>` 读取这些数据。
+
+.. _damon_design_api_zh_CN:
+
+应用编程接口
+------------
+
+用于内核空间数据访问感知应用的编程接口。DAMON 是一个框架，所以它本身什么也不做。相反，
+它只帮助子系统和模块等其他内核组件使用 DAMON 的核心功能构建它们的数据访问感知应用。为此，
+DAMON 通过其应用编程接口，即 ``include/linux/damon.h``，向其他内核组件暴露所有功能。接口
+细节请参考 API :doc:`文档 <api>`。
+
+
+.. _damon_modules_zh_CN:
+
+模块
+====
+
+由于 DAMON 的核心是供内核组件使用的框架，它本身不向用户空间提供任何直接接口。相反，这些接口
+应由每个使用 DAMON API 的内核组件来实现。DAMON 子系统本身实现了这类 DAMON API 用户模块，
+它们分别用于通用目的的 DAMON 控制和特定目的的数据访问感知系统操作，并为用户空间提供稳定的应
+用二进制接口（ABI）。用户空间可以使用这些接口构建高效的数据访问感知应用程序。
+
+
+通用目的用户接口模块
+--------------------
+
+DAMON 模块为运行时的通用目的 DAMON 用法提供用户空间 ABI。
+
+与许多其他 ABI 一样，这些模块会在类似 ``sysfs`` 的伪文件系统上创建文件，允许用户通过写入和读
+取这些文件来向 DAMON 指定请求并获取回答。作为这类 I/O 的响应，DAMON 用户接口模块会通过 DAMON
+API 按用户请求控制 DAMON 并获取结果，然后把结果返回给用户空间。
+
+这些 ABI 是为用户空间应用程序开发而设计的，而不是为人工手动操作而设计的。建议人工用户使用这类
+用户空间工具。一个用 Python 编写的此类用户空间工具可在 Github
+（https://github.com/damonitor/damo）、Pypi（https://pypistats.org/packages/damo）以及多个发行
+版（https://repology.org/project/damo/versions）中获取。
+
+目前，该类型有一个模块可用，即 ``DAMON sysfs interface``。关于接口细节，请参考 ABI
+:ref:`文档 <sysfs_interface_zh_CN>`。
+
+
+.. _damon_modules_special_purpose_zh_CN:
+
+专用访问感知内核模块
+--------------------
+
+DAMON 模块为特定目的的 DAMON 用法提供用户空间 ABI。
+
+DAMON 用户接口模块用于在运行时完整控制所有 DAMON 功能。对于每种专用的、系统范围的数据访问感知
+系统操作，例如主动回收或 LRU 链表均衡，可以通过移除该特定目的不需要的调节项来简化接口，并扩展
+为启动时甚至编译时控制。用于该用途的 DAMON 控制参数默认值也需要针对该目的进行优化。
+
+为支持这些场景，DAMON 还提供了更多使用 DAMON API 的内核模块，它们提供更简单且更优化的用户空间
+接口。目前提供了用于访问监测统计、主动回收和 LRU 链表操作的三个模块。更多细节请阅读这些模块的
+使用文档（:doc:`../../admin-guide/mm/damon/stat`,
+:doc:`../../admin-guide/mm/damon/reclaim` 和
+:doc:`../../admin-guide/mm/damon/lru_sort`）。
+
+.. _damon_design_special_purpose_modules_exclusivity_zh_CN:
+
+请注意，这些模块当前以互斥方式运行。如果其中一个模块已经在运行，其他模块在收到启动请求时将返回
+``-EBUSY``。
+
+示例 DAMON 模块
+----------------
+
+DAMON 模块提供 DAMON 内核 API 用法示例。
+
+内核程序员可以使用 DAMON 内核 API 构建自己的专用或通用目的 DAMON 模块。为了帮助他们容易理解
+如何使用 DAMON 内核 API，Linux 源码树的 ``samples/damon/`` 目录下提供了一些示例模块。请注意，
+这些模块不是为实际产品使用而开发的，而只是为了展示如何以简单方式使用 DAMON 内核 API。
-- 
2.43.0

[PATCH v6 2/7] docs/zh_CN: add DAMON_STAT usage translation

[Doehyun Baek]

Translate .../admin-guide/mm/damon/stat.rst into Chinese.

Update the translation through commit c9380cdd949d
("Docs/{admin-guide,mm}/damon: fix DAMON documentation details").

Signed-off-by: Doehyun Baek <doehyunbaek@gmail.com>
---
 .../zh_CN/admin-guide/mm/damon/stat.rst       | 94 +++++++++++++++++++
 1 file changed, 94 insertions(+)
 create mode 100644 Documentation/translations/zh_CN/admin-guide/mm/damon/stat.rst

diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/stat.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/stat.rst
new file mode 100644
index 000000000000..129748a5ea1f
--- /dev/null
+++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/stat.rst
@@ -0,0 +1,94 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: ../../../disclaimer-zh_CN.rst
+
+:Original: Documentation/admin-guide/mm/damon/stat.rst
+
+:翻译:
+
+ Doehyun Baek <doehyunbaek@gmail.com>
+
+====================
+数据访问监测结果统计
+====================
+
+数据访问监测结果统计（DAMON_STAT）是一个静态内核模块，旨在用于简单的
+访问模式监测。它使用 DAMON 监测系统整个物理内存上的访问，并提供简化的
+访问监测结果统计，即空闲时间百分位数和估计的内存带宽。
+
+.. _damon_stat_monitoring_accuracy_overhead_zh_CN:
+
+监测精度和开销
+==============
+
+DAMON_STAT 使用监测间隔
+:ref:`自动调优 <damon_design_monitoring_intervals_autotuning_zh_CN>` 来提高
+精度并最小化开销。它会自动调优间隔，目标是在每个快照中捕获 4 % 的
+可观测访问事件，同时将得到的采样间隔限制在最小 5 毫秒、最大 10 秒。
+在少数生产服务器系统上，它的结果是只消耗 0.x % 的单个 CPU 时间，同时
+捕获质量合理的访问模式。调优得到的间隔可以通过
+``aggr_interval_us`` :ref:`参数 <damon_stat_aggr_interval_us_zh_CN>` 获取。
+
+接口：模块参数
+==============
+
+要使用这个功能，首先应确保你的系统运行在构建时启用了
+``CONFIG_DAMON_STAT=y`` 的内核上。通过将
+``CONFIG_DAMON_STAT_ENABLED_DEFAULT`` 设置为 true，可以在构建时默认
+启用该功能。
+
+为了让系统管理员在启动时和/或运行时启用或禁用它，并读取监测结果，
+DAMON_STAT 提供了模块参数。下面的章节描述这些参数。
+
+enabled
+-------
+
+启用或禁用 DAMON_STAT。
+
+你可以将该参数的值设置为 ``Y`` 来启用 DAMON_STAT。设置为 ``N`` 会
+禁用 DAMON_STAT。默认值由 ``CONFIG_DAMON_STAT_ENABLED_DEFAULT`` 构建
+配置选项设置。
+
+请注意，该模块（damon_stat）不能与其他基于 DAMON 的专用模块同时运行。
+更多细节请参考 :ref:`DAMON 设计文档的专用模块互斥性 <damon_design_special_purpose_modules_exclusivity_zh_CN>`。
+
+.. _damon_stat_aggr_interval_us_zh_CN:
+
+aggr_interval_us
+----------------
+
+自动调优后的聚集时间间隔，单位是微秒。
+
+用户可以读取 DAMON_STAT 使用的 DAMON 实例的聚集间隔。它会被
+:ref:`自动调优 <damon_stat_monitoring_accuracy_overhead_zh_CN>`，因此该值
+会动态变化。
+
+estimated_memory_bandwidth
+--------------------------
+
+系统的估计内存带宽消耗（字节/秒）。
+
+DAMON_STAT 读取当前 DAMON 结果快照上的观测访问事件，并将其转换为以
+字节/秒为单位的内存带宽消耗估计。得到的指标通过这个只读参数向用户
+公开。由于 DAMON 使用采样，所以这只是访问强度的估计，而不是精确的
+内存带宽。
+
+memory_idle_ms_percentiles
+--------------------------
+
+系统的逐字节空闲时间（毫秒）百分位数。
+
+DAMON_STAT 基于当前 DAMON 结果快照，计算内存中每个字节到现在为止未被
+访问的时间（空闲时间）。对于访问频率（nr_accesses）大于零的区域，当前
+访问频率水平保持的时间乘以 ``-1``，就是该区域每个字节的空闲时间。如果
+某个区域的访问频率（nr_accesses）为零，则该区域保持零访问频率的时间
+（age）就是该区域每个字节的空闲时间。然后，DAMON_STAT 通过这个只读参数
+公开空闲时间值的百分位数。读取该参数会返回 101 个以毫秒为单位、用逗号
+分隔的空闲时间值。每个值分别表示第 0、第 1、第 2、第 3、……、第 99 和
+第 100 百分位的空闲时间。
+
+kdamond_pid
+-----------
+
+DAMON 线程的 PID。
+
+如果 DAMON_STAT 已启用，这将成为工作线程的 PID。否则为 -1。
-- 
2.43.0

[PATCH v6 3/7] docs/zh_CN: update DAMON index translation

[Doehyun Baek]

Update the Chinese translation of .../admin-guide/mm/damon/index.rst.

Update the translation through commit c9380cdd949d
("Docs/{admin-guide,mm}/damon: fix DAMON documentation details").

Signed-off-by: Doehyun Baek <doehyunbaek@gmail.com>
---
 .../zh_CN/admin-guide/mm/damon/index.rst          | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst
index 6f8676a50b38..77bbfa7c25dc 100644
--- a/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst
+++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst
@@ -9,12 +9,12 @@
 
 :校译:
 
-============
-监测数据访问
-============
+========================================
+DAMON：数据访问监测和访问感知系统操作
+========================================
 
-:doc:`DAMON </mm/damon/index>` 允许轻量级的数据访问监测。使用DAMON，
-用户可以分析他们系统的内存访问模式，并优化它们。
+:doc:`DAMON <../../../mm/damon/index>` 是一个 Linux 内核子系统，用于高效的
+数据访问监测和访问感知系统操作。
 
 .. toctree::
    :maxdepth: 2
@@ -23,7 +23,4 @@
    usage
    reclaim
    lru_sort
-
-
-
-
+   stat
-- 
2.43.0

[PATCH v6 4/7] docs/zh_CN: update DAMON start translation

[Doehyun Baek]

Update the Chinese translation of .../admin-guide/mm/damon/start.rst.

Update the translation through commit c9380cdd949d
("Docs/{admin-guide,mm}/damon: fix DAMON documentation details").

Signed-off-by: Doehyun Baek <doehyunbaek@gmail.com>
---
 .../zh_CN/admin-guide/mm/damon/start.rst      | 63 ++++++++++++++++---
 1 file changed, 54 insertions(+), 9 deletions(-)

diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst
index cff7b6f98c59..1a7f3382dd15 100644
--- a/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst
+++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/start.rst
@@ -35,18 +35,63 @@ https://github.com/damonitor/damo找到。下面的例子假设DAMO在你的$PAT
 这并不是强制性的。
 
 因为DAMO使用了DAMON的sysfs接口（详情请参考:doc:`usage`），你应该确保
-:doc:`sysfs </filesystems/sysfs>` 被挂载。
+``sysfs`` 被挂载。
+
+
+拍摄数据访问模式快照
+====================
+
+下面的命令展示程序在执行时刻的内存访问模式。::
+
+    $ git clone https://github.com/sjp38/masim; cd masim; make
+    $ sudo damo start "./masim ./configs/stairs.cfg --quiet"
+    $ sudo damo report access
+    heatmap: 641111111000000000000000000000000000000000000000000000[...]33333333333333335557984444[...]7
+    # min/max temperatures: -1,840,000,000, 370,010,000, column size: 3.925 MiB
+    0   addr 86.182 TiB   size 8.000 KiB   access 0 %   age 14.900 s
+    1   addr 86.182 TiB   size 8.000 KiB   access 60 %  age 0 ns
+    2   addr 86.182 TiB   size 3.422 MiB   access 0 %   age 4.100 s
+    3   addr 86.182 TiB   size 2.004 MiB   access 95 %  age 2.200 s
+    4   addr 86.182 TiB   size 29.688 MiB  access 0 %   age 14.100 s
+    5   addr 86.182 TiB   size 29.516 MiB  access 0 %   age 16.700 s
+    6   addr 86.182 TiB   size 29.633 MiB  access 0 %   age 17.900 s
+    7   addr 86.182 TiB   size 117.652 MiB access 0 %   age 18.400 s
+    8   addr 126.990 TiB  size 62.332 MiB  access 0 %   age 9.500 s
+    9   addr 126.990 TiB  size 13.980 MiB  access 0 %   age 5.200 s
+    10  addr 126.990 TiB  size 9.539 MiB   access 100 % age 3.700 s
+    11  addr 126.990 TiB  size 16.098 MiB  access 0 %   age 6.400 s
+    12  addr 127.987 TiB  size 132.000 KiB access 0 %   age 2.900 s
+    total size: 314.008 MiB
+    $ sudo damo stop
+
+上面示例的第一条命令下载并构建一个名为 ``masim`` 的人工内存访问
+生成程序。第二条命令要求 DAMO 用给定命令启动该程序，并让 DAMON
+监测新启动的进程。第三条命令从 DAMON 取回该进程当前被监测访问
+模式的快照，并以人类可读的格式显示该模式。
+
+输出的第一行以单行热图格式显示各区域的相对访问温度（热度）。热图
+中的每一列表示被监测虚拟地址空间上大小相同的区域。列在该行中的
+位置和列上的数字表示该区域的相对位置和访问温度。``[...]`` 表示
+虚拟地址空间中未映射的巨大区域。第二行显示帮助理解热图的附加信息。
+
+从第三行开始，输出的每一行显示进程的哪个虚拟地址范围
+（``addr XX size XX``）被访问得有多频繁（``access XX %``），以及
+持续了多长时间（``age XX``）。例如，大小约为 9.5 MiB 的第十一个
+区域在最近 3.7 秒内被访问得最频繁。最后，第四条命令停止 DAMON。
+
+请注意，DAMON 不仅能监测虚拟地址空间，还能监测包括物理地址空间在内
+的多种地址空间。
+
 
 记录数据访问模式
 ================
 
 下面的命令记录了一个程序的内存访问模式，并将监测结果保存到文件中。 ::
 
-    $ git clone https://github.com/sjp38/masim
-    $ cd masim; make; ./masim ./configs/zigzag.cfg &
+    $ ./masim ./configs/zigzag.cfg &
     $ sudo damo record -o damon.data $(pidof masim)
 
-命令的前两行下载了一个人工内存访问生成器程序并在后台运行。生成器将重复地逐一访问两个
+第一行命令再次运行该人工内存访问生成器程序。生成器将重复地逐一访问两个
 100 MiB大小的内存区域。你可以用你的真实工作负载来代替它。最后一行要求 ``damo`` 将
 访问模式记录在 ``damon.data`` 文件中。
 
@@ -57,7 +102,7 @@ https://github.com/damonitor/damo找到。下面的例子假设DAMO在你的$PAT
 你可以在heatmap中直观地看到这种模式，显示哪个内存区域（X轴）何时被访问（Y轴）以及访
 问的频率（数字）。::
 
-    $ sudo damo report heats --heatmap stdout
+    $ sudo damo report heatmap
     22222222222222222222222222222222222222211111111111111111111111111111111111111100
     44444444444444444444444444444444444444434444444444444444444444444444444444443200
     44444444444444444444444444444444444444433444444444444444444444444444444444444200
@@ -117,8 +162,8 @@ https://github.com/damonitor/damo找到。下面的例子假设DAMO在你的$PAT
 数据访问模式感知的内存管理
 ==========================
 
-以下三个命令使每一个大小>=4K的内存区域在你的工作负载中没有被访问>=60秒，就会被换掉。 ::
+以下命令使每一个大小>=4K的内存区域在你的工作负载中没有被访问>=60秒，就会被换掉。 ::
 
-    $ echo "#min-size max-size min-acc max-acc min-age max-age action" > test_scheme
-    $ echo "4K        max      0       0       60s     max     pageout" >> test_scheme
-    $ damo schemes -c test_scheme <pid of your workload>
+    $ sudo damo start --damos_access_rate 0 0 --damos_sz_region 4K max \
+                      --damos_age 60s max --damos_action pageout \
+                      --target_pid <pid of your workload>
-- 
2.43.0

[PATCH v6 5/7] docs/zh_CN: update DAMON usage translation

[Doehyun Baek]

Update the Chinese translation of .../admin-guide/mm/damon/usage.rst.

Update the translation through commit c9380cdd949d
("Docs/{admin-guide,mm}/damon: fix DAMON documentation details").

Signed-off-by: Doehyun Baek <doehyunbaek@gmail.com>
---
 .../zh_CN/admin-guide/mm/damon/usage.rst      | 521 ++++++++++++++----
 1 file changed, 411 insertions(+), 110 deletions(-)

diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst
index 9d7cb51be493..835de081fb64 100644
--- a/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst
+++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst
@@ -15,22 +15,27 @@
 
 DAMON 为不同的用户提供了下面这些接口。
 
+- *专用 DAMON 模块。*
+  :ref:`这 <damon_modules_special_purpose_zh_CN>` 是为那些正在构建、发布和/或管理
+  带有专用 DAMON 用法的内核的人准备的。使用它，用户可以在构建、启动或运行时，
+  以简单的方式为给定目的使用 DAMON 的主要功能。
 - *DAMON用户空间工具。*
   `这 <https://github.com/damonitor/damo>`_ 为有这特权的人， 如系统管理员，希望有一个刚好
   可以工作的人性化界面。
   使用它，用户可以以人性化的方式使用DAMON的主要功能。不过，它可能不会为特殊情况进行高度调整。
-  它同时支持虚拟和物理地址空间的监测。更多细节，请参考它的 `使用文档
+  更多细节，请参考它的 `使用文档
   <https://github.com/damonitor/damo/blob/next/USAGE.md>`_。
 - *sysfs接口。*
-  :ref:`这 <sysfs_interface>` 是为那些希望更高级的使用DAMON的特权用户空间程序员准备的。
+  :ref:`这 <sysfs_interface_zh_CN>` 是为那些希望更高级的使用DAMON的特权用户空间程序员准备的。
   使用它，用户可以通过读取和写入特殊的sysfs文件来使用DAMON的主要功能。因此，你可以编写和使
   用你个性化的DAMON sysfs包装程序，代替你读/写sysfs文件。  `DAMON用户空间工具
-  <https://github.com/damonitor/damo>`_ 就是这种程序的一个例子  它同时支持虚拟和物理地址
-  空间的监测。
+  <https://github.com/damonitor/damo>`_ 就是这种程序的一个例子。
 - *内核空间编程接口。*
-  :doc:`这 </mm/damon/api>` 这是为内核空间程序员准备的。使用它，用户可以通过为你编写内
+  :doc:`这 <../../../mm/damon/api>` 这是为内核空间程序员准备的。使用它，用户可以通过为你编写内
   核空间的DAMON应用程序，最灵活有效地利用DAMON的每一个功能。你甚至可以为各种地址空间扩展DAMON。
-  详细情况请参考接口 :doc:`文件 </mm/damon/api>`。
+  详细情况请参考接口 :doc:`文件 <../../../mm/damon/api>`。
+
+.. _sysfs_interface_zh_CN:
 
 sysfs接口
 =========
@@ -51,39 +56,61 @@ DAMON的sysfs接口是在定义 ``CONFIG_DAMON_SYSFS`` 时建立的。它在其s
 ------------
 
 DAMON sysfs接口的文件层次结构如下图所示。在下图中，父子关系用缩进表示，每个目录有
-``/`` 后缀，每个目录中的文件用逗号（","）分开。 ::
-
-    /sys/kernel/mm/damon/admin
-    │ kdamonds/nr_kdamonds
-    │ │ 0/state,pid
-    │ │ │ contexts/nr_contexts
-    │ │ │ │ 0/operations
-    │ │ │ │ │ monitoring_attrs/
+``/`` 后缀，每个目录中的文件用逗号（","）分开。
+
+.. parsed-literal::
+
+    :ref:`/sys/kernel/mm/damon <sysfs_root_zh_CN>`/admin
+    │ :ref:`kdamonds <sysfs_kdamonds_zh_CN>`/nr_kdamonds
+    │ │ :ref:`0 <sysfs_kdamond_zh_CN>`/state,pid,refresh_ms
+    │ │ │ :ref:`contexts <sysfs_contexts_zh_CN>`/nr_contexts
+    │ │ │ │ :ref:`0 <sysfs_context_zh_CN>`/avail_operations,operations,addr_unit,
+    │ │ │ │   pause
+    │ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs_zh_CN>`/
     │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
+    │ │ │ │ │ │ │ intervals_goal/access_bp,aggrs,min_sample_us,max_sample_us
     │ │ │ │ │ │ nr_regions/min,max
-    │ │ │ │ │ targets/nr_targets
-    │ │ │ │ │ │ 0/pid_target
-    │ │ │ │ │ │ │ regions/nr_regions
-    │ │ │ │ │ │ │ │ 0/start,end
+    │ │ │ │ │ │ :ref:`probes <damon_usage_sysfs_probes_zh_CN>`/nr_probes
+    │ │ │ │ │ │ │ 0/filters/nr_filters
+    │ │ │ │ │ │ │ │ 0/type,matching,allow,path
+    │ │ │ │ │ │ │ │ ...
+    │ │ │ │ │ │ │ ...
+    │ │ │ │ │ :ref:`targets <sysfs_targets_zh_CN>`/nr_targets
+    │ │ │ │ │ │ :ref:`0 <sysfs_target_zh_CN>`/pid_target,obsolete_target
+    │ │ │ │ │ │ │ :ref:`regions <sysfs_regions_zh_CN>`/nr_regions
+    │ │ │ │ │ │ │ │ :ref:`0 <sysfs_region_zh_CN>`/start,end
     │ │ │ │ │ │ │ │ ...
     │ │ │ │ │ │ ...
-    │ │ │ │ │ schemes/nr_schemes
-    │ │ │ │ │ │ 0/action
-    │ │ │ │ │ │ │ access_pattern/
+    │ │ │ │ │ :ref:`schemes <sysfs_schemes_zh_CN>`/nr_schemes
+    │ │ │ │ │ │ :ref:`0 <sysfs_scheme_zh_CN>`/action,target_nid,apply_interval_us
+    │ │ │ │ │ │ │ :ref:`access_pattern <sysfs_access_pattern_zh_CN>`/
     │ │ │ │ │ │ │ │ sz/min,max
     │ │ │ │ │ │ │ │ nr_accesses/min,max
     │ │ │ │ │ │ │ │ age/min,max
-    │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms
+    │ │ │ │ │ │ │ :ref:`quotas <sysfs_quotas_zh_CN>`/ms,bytes,reset_interval_ms,
+    │ │ │ │ │ │ │     effective_bytes,goal_tuner,
+    │ │ │ │ │ │ │     fail_charge_num,fail_charge_denom
     │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil
-    │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low
-    │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds
-    │ │ │ │ │ │ │ tried_regions/
-    │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age
+    │ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals_zh_CN>`/nr_goals
+    │ │ │ │ │ │ │ │ │ 0/target_metric,target_value,current_value,nid,path
+    │ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks_zh_CN>`/metric,interval_us,high,mid,low
+    │ │ │ │ │ │ │ :ref:`{core_,ops_,}filters <sysfs_filters_zh_CN>`/nr_filters
+    │ │ │ │ │ │ │ │ 0/type,matching,allow,memcg_path,addr_start,addr_end,damon_target_idx,min,max
+    │ │ │ │ │ │ │ :ref:`dests <damon_sysfs_dests_zh_CN>`/nr_dests
+    │ │ │ │ │ │ │ │ 0/id,weight
+    │ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats_zh_CN>`/nr_tried,sz_tried,nr_applied,sz_applied,sz_ops_filter_passed,qt_exceeds,nr_snapshots,max_nr_snapshots
+    │ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions_zh_CN>`/total_bytes
+    │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age,sz_filter_passed
+    │ │ │ │ │ │ │ │ │ probes
+    │ │ │ │ │ │ │ │ │ │ 0/hits
+    │ │ │ │ │ │ │ │ │ │ ...
     │ │ │ │ │ │ │ │ ...
     │ │ │ │ │ │ ...
     │ │ │ │ ...
     │ │ ...
 
+.. _sysfs_root_zh_CN:
+
 根
 --
 
@@ -91,58 +118,100 @@ DAMON sysfs接口的根是 ``<sysfs>/kernel/mm/damon/`` ，它有一个名为 ``
 目录。该目录包含特权用户空间程序控制DAMON的文件。拥有根权限的用户空间工具或deamons可以
 使用这个目录。
 
+.. _sysfs_kdamonds_zh_CN:
+
 kdamonds/
 ---------
 
-与监测相关的信息包括请求规格和结果被称为DAMON上下文。DAMON用一个叫做kdamond的内核线程
-执行每个上下文，多个kdamonds可以并行运行。
-
-在 ``admin`` 目录下，有一个目录，即``kdamonds``，它有控制kdamonds的文件存在。在开始
+在 ``admin`` 目录下，有一个目录，即``kdamonds``，它有控制kdamonds的文件存在（更多
+细节请参考 :ref:`设计 <damon_design_execution_model_and_data_structures_zh_CN>`）。在开始
 时，这个目录只有一个文件，``nr_kdamonds``。向该文件写入一个数字（``N``），就会创建名为
 ``0`` 到 ``N-1`` 的子目录数量。每个目录代表每个kdamond。
 
+.. _sysfs_kdamond_zh_CN:
+
 kdamonds/<N>/
 -------------
 
-在每个kdamond目录中，存在两个文件（``state`` 和 ``pid`` ）和一个目录( ``contexts`` )。
+在每个kdamond目录中，存在三个文件（``state`` 、 ``pid`` 和 ``refresh_ms`` ）和一个目录( ``contexts`` )。
 
 读取 ``state`` 时，如果kdamond当前正在运行，则返回 ``on`` ，如果没有运行则返回 ``off`` 。
-写入 ``on`` 或 ``off`` 使kdamond处于状态。向 ``state`` 文件写 ``update_schemes_stats`` ，
-更新kdamond的每个基于DAMON的操作方案的统计文件的内容。关于统计信息的细节，请参考
-:ref:`stats section <sysfs_schemes_stats>`. 将 ``update_schemes_tried_regions`` 写到
-``state`` 文件，为kdamond的每个基于DAMON的操作方案，更新基于DAMON的操作方案动作的尝试区域目录。
-将`clear_schemes_tried_regions`写入`state`文件，清除kdamond的每个基于DAMON的操作方案的动作
-尝试区域目录。 关于基于DAMON的操作方案动作尝试区域目录的细节，请参考:ref:tried_regions 部分
-<sysfs_schemes_tried_regions>`。
+
+用户可以向 ``state`` 文件写入以下kdamond命令。
+
+- ``on``：开始运行。
+- ``off``：停止运行。
+- ``commit``：再次读取除 ``state`` 文件之外的 sysfs 文件中的用户输入。
+  如果没有指定目标区域，也会忽略监测 :ref:`目标区域 <sysfs_regions_zh_CN>`
+  输入。
+- ``update_tuned_intervals``：用自动调优后的 ``sampling interval`` 和
+  ``aggregation interval`` 更新该 kdamond 的 ``sample_us`` 和
+  ``aggr_us`` 文件内容。更多细节请参考 :ref:`intervals_goal 章节
+  <damon_usage_sysfs_monitoring_intervals_goal_zh_CN>`。
+- ``commit_schemes_quota_goals``：读取基于 DAMON 的操作方案的
+  :ref:`配额目标 <sysfs_schemes_quota_goals_zh_CN>`。
+- ``update_schemes_stats``：更新该 kdamond 的每个基于 DAMON 的操作方案的
+  统计文件内容。关于统计信息的细节，请参考 :ref:`stats 章节
+  <sysfs_schemes_stats_zh_CN>`。
+- ``update_schemes_tried_regions``：为该 kdamond 的每个基于 DAMON 的
+  操作方案，更新基于 DAMON 的操作方案动作尝试区域目录。关于基于 DAMON
+  的操作方案动作尝试区域目录的细节，请参考 :ref:`tried_regions 章节
+  <sysfs_schemes_tried_regions_zh_CN>`。
+- ``update_schemes_tried_bytes``：只更新 ``.../tried_regions/total_bytes``
+  文件。
+- ``clear_schemes_tried_regions``：为该 kdamond 的每个基于 DAMON 的
+  操作方案，清除基于 DAMON 的操作方案动作尝试区域目录。
+- ``update_schemes_effective_quotas``：更新该 kdamond 的每个基于 DAMON
+  的操作方案的 ``effective_bytes`` 文件内容。更多细节请参考
+  :ref:`quotas 目录 <sysfs_quotas_zh_CN>`。
 
 如果状态为 ``on``，读取 ``pid`` 显示kdamond线程的pid。
 
+用户可以要求内核周期性地更新显示自动调优参数和 DAMOS 统计信息的文件，
+而不是手动向 ``state`` 文件写入 ``update_tuned_intervals`` 这类关键字。
+为此，用户应将所需的更新时间间隔（毫秒）写入 ``refresh_ms`` 文件。如果
+该间隔为零，则禁用周期性更新。读取该文件会显示当前设置的时间间隔。
+
 ``contexts`` 目录包含控制这个kdamond要执行的监测上下文的文件。
 
+.. _sysfs_contexts_zh_CN:
+
 kdamonds/<N>/contexts/
 ----------------------
 
 在开始时，这个目录只有一个文件，即 ``nr_contexts`` 。向该文件写入一个数字( ``N`` )，就会创
-建名为``0`` 到 ``N-1`` 的子目录数量。每个目录代表每个监测背景。目前，每个kdamond只支持
+建名为``0`` 到 ``N-1`` 的子目录数量。每个目录代表每个监测背景（更多细节请参考
+:ref:`设计 <damon_design_execution_model_and_data_structures_zh_CN>`）。目前，每个kdamond只支持
 一个上下文，所以只有 ``0`` 或 ``1`` 可以被写入文件。
 
+.. _sysfs_context_zh_CN:
+
 contexts/<N>/
 -------------
 
-在每个上下文目录中，存在一个文件(``operations``)和三个目录(``monitoring_attrs``,
+在每个上下文目录中，存在四个文件(``avail_operations``、``operations``、
+``addr_unit`` 和 ``pause``)和三个目录(``monitoring_attrs``,
 ``targets``, 和 ``schemes``)。
 
-DAMON支持多种类型的监测操作，包括对虚拟地址空间和物理地址空间的监测。你可以通过向文件
-中写入以下关键词之一，并从文件中读取，来设置和获取DAMON将为上下文使用何种类型的监测操作。
+DAMON支持多种 :ref:`监测操作 <damon_design_configurable_operations_set_zh_CN>` 类型，
+包括对虚拟地址空间和物理地址空间的监测。你可以通过读取 ``avail_operations`` 文件，
+获取当前运行内核上可用的监测操作集列表。根据内核配置，该文件会列出不同的可用
+操作集。所有可用操作集及其简要说明请参考 :ref:`设计 <damon_operations_set_zh_CN>`。
+
+你可以通过向 ``operations`` 文件写入 ``avail_operations`` 文件中列出的一个关键词，
+并从 ``operations`` 文件中读取，来设置和获取DAMON将为上下文使用何种类型的监测操作。
+
+``addr_unit`` 文件用于设置和获取该操作集的 :ref:`地址单位 <damon_design_addr_unit_zh_CN>` 参数。
+
+``pause`` 文件用于设置和获取该上下文的 :ref:`暂停请求 <damon_design_execution_model_and_data_structures_zh_CN>` 参数。
 
- - vaddr: 监测特定进程的虚拟地址空间
- - paddr: 监视系统的物理地址空间
+.. _sysfs_monitoring_attrs_zh_CN:
 
 contexts/<N>/monitoring_attrs/
 ------------------------------
 
 用于指定监测属性的文件，包括所需的监测质量和效率，都在 ``monitoring_attrs`` 目录中。
-具体来说，这个目录下有两个目录，即 ``intervals`` 和 ``nr_regions`` 。
+具体来说，这个目录下有三个目录，即 ``intervals``、``nr_regions`` 和 ``probes``。
 
 在 ``intervals`` 目录下，存在DAMON的采样间隔(``sample_us``)、聚集间隔(``aggr_us``)
 和更新间隔(``update_us``)三个文件。你可以通过写入和读出这些文件来设置和获取微秒级的值。
@@ -150,7 +219,44 @@ contexts/<N>/monitoring_attrs/
 在 ``nr_regions`` 目录下，有两个文件分别用于DAMON监测区域的下限和上限（``min`` 和 ``max`` ），
 这两个文件控制着监测的开销。你可以通过向这些文件的写入和读出来设置和获取这些值。
 
-关于间隔和监测区域范围的更多细节，请参考设计文件 (:doc:`/mm/damon/design`)。
+关于间隔和监测区域范围的更多细节，请参考设计文件 (:ref:`设计 <damon_design_monitoring_zh_CN>`)。
+
+.. _damon_usage_sysfs_monitoring_intervals_goal_zh_CN:
+
+contexts/<N>/monitoring_attrs/intervals/intervals_goal/
+-------------------------------------------------------
+
+在 ``intervals`` 目录下，还存在一个用于自动调优 ``sample_us`` 和
+``aggr_us`` 的目录，即 ``intervals_goal`` 目录。在该目录下，存在四个
+用于自动调优控制的文件，即 ``access_bp``、``aggrs``、``min_sample_us``
+和 ``max_sample_us``。关于调优机制的内部实现，请参考该功能的
+:ref:`设计文档 <damon_design_monitoring_intervals_autotuning_zh_CN>`。读取和写入
+``intervals_goal`` 目录下的四个文件，会显示并更新 :ref:`设计文档 <damon_design_monitoring_intervals_autotuning_zh_CN>` 中描述的同名调优参数。调优
+从用户设置的 ``sample_us`` 和 ``aggr_us`` 开始。向 ``state`` 文件写入
+``update_tuned_intervals`` 后，可以从 ``sample_us`` 和 ``aggr_us`` 文件
+读取应用调优后的两个间隔的当前值。
+
+.. _damon_usage_sysfs_probes_zh_CN:
+
+contexts/<N>/monitoring_attrs/probes/
+-------------------------------------
+
+用于注册 :ref:`数据属性监测 <damon_design_data_attrs_monitoring_zh_CN>` 探针的目录。
+
+开始时，该目录只有一个文件 ``nr_probes``。向该文件写入一个数字
+（``N``）会创建数量为该数字的子目录，命名为 ``0`` 到 ``N-1``。每个
+目录表示一个监测探针。
+
+在每个探针目录中，存在一个目录 ``filters``。该目录包含为探针安装过滤器
+的文件，该过滤器用于确定探针的数据属性。
+
+开始时，``filters`` 目录只有一个文件 ``nr_filters``。向该文件写入一个
+数字（``N``）会创建数量为该数字的子目录，命名为 ``0`` 到 ``N-1``。每个
+目录表示一个过滤器，其工作方式类似于 :ref:`DAMOS 过滤器
+<sysfs_filters_zh_CN>`。当过滤器 ``type`` 为 ``memcg`` 时，``path`` 文件
+作为 :ref:`DAMOS 过滤器 <sysfs_filters_zh_CN>` 的 ``memcg_path`` 使用。
+
+.. _sysfs_targets_zh_CN:
 
 contexts/<N>/targets/
 ---------------------
@@ -158,30 +264,43 @@ contexts/<N>/targets/
 在开始时，这个目录只有一个文件 ``nr_targets`` 。向该文件写入一个数字(``N``)，就可以创建
 名为 ``0`` 到 ``N-1`` 的子目录的数量。每个目录代表每个监测目标。
 
+.. _sysfs_target_zh_CN:
+
 targets/<N>/
 ------------
 
-在每个目标目录中，存在一个文件(``pid_target``)和一个目录(``regions``)。
+在每个目标目录中，存在两个文件（``pid_target`` 和 ``obsolete_target``）和一个目录(``regions``)。
 
 如果你把 ``vaddr`` 写到 ``contexts/<N>/operations`` 中，每个目标应该是一个进程。你
 可以通过将进程的pid写到 ``pid_target`` 文件中来指定DAMON的进程。
 
+用户可以通过向 ``obsolete_target`` 文件写入非零值并提交它（向 ``state``
+文件写入 ``commit``），有选择地移除目标数组中间的目标。DAMON 会从内部
+目标数组中移除匹配的目标。用户负责重新构建目标目录，使其正确表示变更后的
+内部目标数组。
+
+
+.. _sysfs_regions_zh_CN:
+
 targets/<N>/regions
 -------------------
 
-当使用 ``vaddr`` 监测操作集时（ ``vaddr`` 被写入 ``contexts/<N>/operations`` 文
-件），DAMON自动设置和更新监测目标区域，这样就可以覆盖目标进程的整个内存映射。然而，用户可
-能希望将初始监测区域设置为特定的地址范围。
+在使用 ``fvaddr`` 或 ``paddr`` 监测操作集时，用户需要设置监测目标地址
+范围。在使用 ``vaddr`` 操作集时，这不是必须的，但用户可以选择将初始
+监测区域设置为特定地址范围。更多细节请参考 :ref:`设计 <damon_design_vaddr_target_regions_construction_zh_CN>`。
 
-相反，当使用 ``paddr`` 监测操作集时，DAMON不会自动设置和更新监测目标区域（ ``paddr``
-被写入 ``contexts/<N>/operations`` 中）。因此，在这种情况下，用户应该自己设置监测目标
-区域。
-
-在这种情况下，用户可以按照自己的意愿明确设置初始监测目标区域，将适当的值写入该目录下的文件。
+对于这类情况，用户可以按照自己的需要，向该目录下的文件写入适当的值，
+显式设置初始监测目标区域。
 
 开始时，这个目录只有一个文件， ``nr_regions`` 。向该文件写入一个数字(``N``)，就可以创
 建名为 ``0`` 到  ``N-1`` 的子目录。每个目录代表每个初始监测目标区域。
 
+如果在线提交新的 DAMON 参数时（向 :ref:`kdamond <sysfs_kdamond_zh_CN>` 的
+``state`` 文件写入 ``commit``）``nr_regions`` 为零，则提交逻辑会忽略
+目标区域。换言之，该目标当前的监测结果会被保留。
+
+.. _sysfs_region_zh_CN:
+
 regions/<N>/
 ------------
 
@@ -190,6 +309,8 @@ regions/<N>/
 
 每个区域不应该与其他区域重叠。 目录“N”的“结束”应等于或小于目录“N+1”的“开始”。
 
+.. _sysfs_schemes_zh_CN:
+
 contexts/<N>/schemes/
 ---------------------
 
@@ -200,99 +321,249 @@ contexts/<N>/schemes/
 在开始时，这个目录只有一个文件，``nr_schemes``。向该文件写入一个数字(``N``)，就可以
 创建名为``0``到``N-1``的子目录的数量。每个目录代表每个基于DAMON的操作方案。
 
+.. _sysfs_scheme_zh_CN:
+
 schemes/<N>/
 ------------
 
-在每个方案目录中，存在五个目录(``access_pattern``、``quotas``、``watermarks``、
-``stats`` 和 ``tried_regions``)和一个文件(``action``)。
+在每个方案目录中，存在九个目录（``access_pattern``、``quotas``、
+``watermarks``、``core_filters``、``ops_filters``、``filters``、
+``dests``、``stats`` 和 ``tried_regions``）以及三个文件（``action``、
+``target_nid`` 和 ``apply_interval_us``）。
 
-``action`` 文件用于设置和获取你想应用于具有特定访问模式的内存区域的动作。可以写入文件
-和从文件中读取的关键词及其含义如下。
+``action`` 文件用于设置和获取方案的 :ref:`动作 <damon_design_damos_action_zh_CN>`。可写入和读取该文件的关键字及其含义，与
+:ref:`设计文档 <damon_design_damos_action_zh_CN>` 中列表的内容相同。
 
- - ``willneed``: 对有 ``MADV_WILLNEED`` 的区域调用 ``madvise()`` 。
- - ``cold``: 对具有 ``MADV_COLD`` 的区域调用 ``madvise()`` 。
- - ``pageout``: 为具有 ``MADV_PAGEOUT`` 的区域调用 ``madvise()`` 。
- - ``hugepage``: 为带有 ``MADV_HUGEPAGE`` 的区域调用 ``madvise()`` 。
- - ``nohugepage``: 为带有 ``MADV_NOHUGEPAGE`` 的区域调用 ``madvise()``。
- - ``lru_prio``: 在其LRU列表上对区域进行优先排序。
- - ``lru_deprio``: 对区域的LRU列表进行降低优先处理。
- - ``stat``: 什么都不做，只计算统计数据
+``target_nid`` 文件用于设置迁移目标节点，只有当 ``action`` 为
+``migrate_hot`` 或 ``migrate_cold`` 时才有意义。
+
+``apply_interval_us`` 文件用于以微秒为单位设置和获取方案的
+:ref:`apply_interval <damon_design_damos_zh_CN>`。
+
+.. _sysfs_access_pattern_zh_CN:
 
 schemes/<N>/access_pattern/
 ---------------------------
 
-每个基于DAMON的操作方案的目标访问模式由三个范围构成，包括以字节为单位的区域大小、每个
-聚合区间的监测访问次数和区域年龄的聚合区间数。
+用于给定基于 DAMON 的操作方案的目标访问 :ref:`模式
+<damon_design_damos_access_pattern_zh_CN>` 的目录。
 
 在 ``access_pattern`` 目录下，存在三个目录（ ``sz``, ``nr_accesses``, 和 ``age`` ），
 每个目录有两个文件（``min`` 和 ``max`` ）。你可以通过向  ``sz``, ``nr_accesses``, 和
 ``age``  目录下的 ``min`` 和 ``max`` 文件分别写入和读取来设置和获取给定方案的访问模式。
+请注意，``min`` 和 ``max`` 形成闭区间。
+
+.. _sysfs_quotas_zh_CN:
 
 schemes/<N>/quotas/
 -------------------
 
-每个 ``动作`` 的最佳 ``目标访问模式`` 取决于工作负载，所以不容易找到。更糟糕的是，将某些动作
-的方案设置得过于激进会造成严重的开销。为了避免这种开销，用户可以为每个方案限制时间和大小配额。
-具体来说，用户可以要求DAMON尽量只使用特定的时间（``时间配额``）来应用动作，并且在给定的时间间
-隔（``重置间隔``）内，只对具有目标访问模式的内存区域应用动作，而不使用特定数量（``大小配额``）。
+用于给定基于 DAMON 的操作方案的 :ref:`配额 <damon_design_damos_quotas_zh_CN>` 的目录。
+
+在 ``quotas`` 目录下，存在七个文件（``ms``、``bytes``、
+``reset_interval_ms``、``effective_bytes``、``goal_tuner``、
+``fail_charge_num`` 和 ``fail_charge_denom``）以及两个目录（``weights``
+和 ``goals``）。
 
-当预计超过配额限制时，DAMON会根据 ``目标访问模式`` 的大小、访问频率和年龄，对找到的内存区域
-进行优先排序。为了进行个性化的优先排序，用户可以为这三个属性设置权重。
+你可以分别向这三个文件写入值，设置以毫秒为单位的 ``time quota``、以字节
+为单位的 ``size quota`` 以及以毫秒为单位的 ``reset interval``。随后，
+DAMON 会尝试在 ``reset_interval_ms`` 内，只使用最多 ``time quota``
+毫秒把 ``action`` 应用于符合 ``access_pattern`` 的内存区域，并且只将该
+动作应用于最多 ``bytes`` 字节的内存区域。将 ``ms`` 和 ``bytes`` 都设置
+为零会禁用配额限制，除非至少设置了一个 :ref:`目标
+<sysfs_schemes_quota_goals_zh_CN>`。
 
-在 ``quotas`` 目录下，存在三个文件（``ms``, ``bytes``, ``reset_interval_ms``）和一个
-目录(``weights``)，其中有三个文件(``sz_permil``, ``nr_accesses_permil``, 和
-``age_permil``)。
+你可以向 ``goal_tuner`` 文件写入算法名称，设置要使用的基于目标的有效
+配额自动调优算法。读取该文件会返回当前选择的调优算法。关于该功能的背景
+设计以及可选择算法的名称，请参考 :ref:`自动配额调优目标 <damon_design_damos_quotas_auto_tuning_zh_CN>` 的设计文档。关于目标设置，请参考
+:ref:`goals 目录 <sysfs_schemes_quota_goals_zh_CN>`。
 
-你可以设置以毫秒为单位的 ``时间配额`` ，以字节为单位的 ``大小配额`` ，以及以毫秒为单位的 ``重
-置间隔`` ，分别向这三个文件写入数值。你还可以通过向 ``weights`` 目录下的三个文件写入数值来设
-置大小、访问频率和年龄的优先权，单位为千分之一。
+你可以分别向 ``fail_charge_num`` 和 ``fail_charge_denom`` 文件写入该比率的
+分子和分母，设置动作失败内存配额计费比率。读取这些文件会返回当前设置的值。
+关于该比率功能的更多细节，请参考 :ref:`设计 <damon_design_damos_quotas_failed_memory_charging_ratio_zh_CN>`。
+
+时间配额会在内部转换为大小配额。在转换后的大小配额和用户指定的大小配额之间，
+会应用较小者。根据用户指定的 :ref:`目标
+<sysfs_schemes_quota_goals_zh_CN>`，有效大小配额会被进一步调整。读取
+``effective_bytes`` 会返回当前有效大小配额。该文件不会实时更新，所以用户
+应通过向相关 ``kdamonds/<N>/state`` 文件写入特殊关键字
+``update_schemes_effective_quotas``，要求 DAMON sysfs 接口为统计信息更新该
+文件内容。
+
+在 ``weights`` 目录下，存在三个文件（``sz_permil``、
+``nr_accesses_permil`` 和 ``age_permil``）。你可以向 ``weights`` 目录下的
+三个文件写入值，设置大小、访问频率和年龄的 :ref:`优先级权重 <damon_design_damos_quotas_prioritization_zh_CN>`，单位为千分之一。
+
+.. _sysfs_schemes_quota_goals_zh_CN:
+
+schemes/<N>/quotas/goals/
+-------------------------
+
+用于给定基于 DAMON 的操作方案的 :ref:`自动配额调优目标 <damon_design_damos_quotas_auto_tuning_zh_CN>` 的目录。
+
+开始时，该目录只有一个文件 ``nr_goals``。向该文件写入一个数字（``N``）
+会创建数量为该数字的子目录，命名为 ``0`` 到 ``N-1``。每个目录表示一个
+目标和当前达成情况。在多个反馈中，会使用最好的一个。
+
+每个目标目录包含五个文件，即 ``target_metric``、``target_value``、
+``current_value``、``nid`` 和 ``path``。用户可以通过写入和读取每个文件，
+设置和获取 :ref:`设计文档 <damon_design_damos_quotas_auto_tuning_zh_CN>` 中指定的
+配额自动调优目标的五个参数。因为内核不会更新 ``current_value``，所以只有
+当 ``target_metric`` 为 ``user_input`` 时，读取它才有意义。请注意，用户还应
+向 :ref:`kdamond 目录 <sysfs_kdamond_zh_CN>` 的 ``state`` 文件写入
+``commit_schemes_quota_goals``，以便将反馈传递给 DAMON。
+
+.. _sysfs_watermarks_zh_CN:
 
 schemes/<N>/watermarks/
 -----------------------
 
-为了便于根据系统状态激活和停用每个方案，DAMON提供了一个称为水位的功能。该功能接收五个值，称为
-``度量`` 、``间隔`` 、``高`` 、``中`` 、``低`` 。``度量值`` 是指可以测量的系统度量值，如
-自由内存比率。如果系统的度量值 ``高`` 于memoent的高值或 ``低`` 于低值，则该方案被停用。如果
-该值低于 ``中`` ，则该方案被激活。
+用于给定基于 DAMON 的操作方案的 :ref:`水位 <damon_design_damos_watermarks_zh_CN>` 的目录。
+
+在 watermarks 目录下，存在五个文件（``metric``、``interval_us``、``high``、
+``mid`` 和 ``low``），用于设置度量指标、度量指标检查之间的时间间隔以及三个
+水位。你可以分别通过写入和读取这些文件来设置和获取这五个值。
+
+可写入 ``metric`` 文件的关键字及其含义如下。
+
+ - none：忽略水位
+ - free_mem_rate：系统空闲内存率（千分之一）
+
+``interval_us`` 应以微秒为单位写入。
+
+.. _sysfs_filters_zh_CN:
+
+schemes/<N>/{core\_,ops\_,}filters/
+-----------------------------------
+
+用于给定基于 DAMON 的操作方案的 :ref:`过滤器 <damon_design_damos_filters_zh_CN>` 的目录。
+
+``core_filters`` 和 ``ops_filters`` 目录分别用于由 DAMON 核心层和操作集层
+处理的过滤器。``filters`` 目录可用于安装过滤器，而不管它们由哪一层处理。
+``core_filters`` 和 ``ops_filters`` 请求的过滤器会先于 ``filters`` 中的
+过滤器安装。这三个目录具有相同的文件。
+
+使用 ``filters`` 目录会使过滤器求值顺序难以预期。因此，``filters`` 目录
+已被弃用。它仍然可以工作，但计划在不久的将来移除。用户应改用
+``core_filters`` 和 ``ops_filters`` 目录。
+
+开始时，该目录只有一个文件 ``nr_filters``。向该文件写入一个数字（``N``）
+会创建数量为该数字的子目录，命名为 ``0`` 到 ``N-1``。每个目录表示一个
+过滤器。过滤器按数字顺序求值。
+
+每个过滤器目录包含九个文件，即 ``type``、``matching``、``allow``、
+``memcg_path``、``addr_start``、``addr_end``、``min``、``max`` 和
+``damon_target_idx``。你可以向 ``type`` 文件写入过滤器类型。关于可用
+类型名称、它们的含义以及它们由哪一层处理，请参考 :ref:`设计文档 <damon_design_damos_filters_zh_CN>`。
 
-在水位目录下，存在五个文件(``metric``, ``interval_us``,``high``, ``mid``, and ``low``)
-用于设置每个值。你可以通过向这些文件的写入来分别设置和获取这五个值。
+对于 ``memcg`` 类型，你可以向 ``memcg_path`` 文件写入从 cgroups 挂载点
+开始的内存 cgroup 路径，指定感兴趣的内存 cgroup。对于 ``addr`` 类型，
+你可以分别向 ``addr_start`` 和 ``addr_end`` 文件写入范围（左闭右开区间）
+的起始和结束地址。对于 ``hugepage_size`` 类型，你可以分别向 ``min`` 和
+``max`` 文件写入范围（闭区间）的最小和最大大小。对于 ``target`` 类型，
+你可以向 ``damon_target_idx`` 文件写入 DAMON 上下文的监测目标列表中目标的
+索引。
 
-可以写入 ``metric`` 文件的关键词和含义如下。
+你可以向 ``matching`` 文件写入 ``Y`` 或 ``N``，指定过滤器是否用于匹配
+``type`` 的内存。你可以向 ``allow`` 文件写入 ``Y`` 或 ``N``，指定是否允许
+将动作应用于满足 ``type`` 和 ``matching`` 的内存。
 
- - none: 忽略水位
- - free_mem_rate: 系统的自由内存率（千分比）。
+例如，下面的操作将 DAMOS 动作限制为只应用于除 ``/having_care_already`` 之外
+所有内存 cgroup 的非匿名页。::
 
-``interval`` 应以微秒为单位写入。
+    # cd ops_filters/0/
+    # echo 2 > nr_filters
+    # # disallow anonymous pages
+    echo anon > 0/type
+    echo Y > 0/matching
+    echo N > 0/allow
+    # # further filter out all cgroups except one at '/having_care_already'
+    echo memcg > 1/type
+    echo /having_care_already > 1/memcg_path
+    echo Y > 1/matching
+    echo N > 1/allow
+
+更多细节请参考 :ref:`DAMOS 过滤器设计文档 <damon_design_damos_filters_zh_CN>`，
+其中包括不同 ``allow`` 的多个过滤器如何工作、每个过滤器何时受支持，以及
+统计信息上的差异。
+
+.. _damon_sysfs_dests_zh_CN:
+
+schemes/<N>/dests/
+------------------
+
+用于指定给定基于 DAMON 的操作方案动作的目的地的目录。如果给定方案的动作
+不支持多个目的地，则该目录会被忽略。只有 ``DAMOS_MIGRATE_{HOT,COLD}`` 动作
+支持多个目的地。
+
+开始时，该目录只有一个文件 ``nr_dests``。向该文件写入一个数字（``N``）
+会创建数量为该数字的子目录，命名为 ``0`` 到 ``N-1``。每个目录表示一个
+动作目的地。
+
+每个目的地目录包含两个文件，即 ``id`` 和 ``weight``。用户可以向 ``id``
+文件写入目的地标识符，并从中读取它。对于 ``DAMOS_MIGRATE_{HOT,COLD}`` 动作，
+应将迁移目的节点的节点 id 写入 ``id`` 文件。用户可以向 ``weight`` 文件写入
+该目的地在给定目的地中的权重，并从中读取它。权重可以是任意整数。当 DAMOS
+将动作应用于内存区域的每个实体时，它会根据目的地的相对权重选择该动作的
+目的地。
+
+.. _sysfs_schemes_stats_zh_CN:
 
 schemes/<N>/stats/
 ------------------
 
-DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个方案被成功应用的区域的两个数字，以及
-超过配额限制的总数量。这些统计数据可用于在线分析或调整方案。
+DAMON 为每个方案统计信息。这些统计信息可用于方案的在线分析或调优。关于
+这些统计信息的更多细节，请参考 :ref:`设计文档 <damon_design_damos_stat_zh_CN>`。
+
+可以分别通过读取 ``stats`` 目录下的文件（``nr_tried``、``sz_tried``、
+``nr_applied``、``sz_applied``、``sz_ops_filter_passed``、``qt_exceeds``、
+``nr_snapshots`` 和 ``max_nr_snapshots``）来获取这些统计信息。
 
-可以通过读取 ``stats`` 目录下的文件(``nr_tried``, ``sz_tried``, ``nr_applied``,
-``sz_applied``, 和 ``qt_exceeds``)）分别检索这些统计数据。这些文件不是实时更新的，所以
-你应该要求DAMON sysfs接口通过在相关的 ``kdamonds/<N>/state`` 文件中写入一个特殊的关键字
-``update_schemes_stats`` 来更新统计信息的文件内容。
+默认情况下，这些文件不会实时更新。用户应要求 DAMON sysfs 接口使用
+``refresh_ms`` 周期性地更新这些文件，或者向相关 ``kdamonds/<N>/state`` 文件
+写入特殊关键字 ``update_schemes_stats`` 来进行一次性更新。更多细节请参考
+:ref:`kdamond 目录 <sysfs_kdamond_zh_CN>`。
+
+.. _sysfs_schemes_tried_regions_zh_CN:
 
 schemes/<N>/tried_regions/
 --------------------------
 
-当一个特殊的关键字 ``update_schemes_tried_regions`` 被写入相关的 ``kdamonds/<N>/state``
-文件时，DAMON会在这个目录下创建从 ``0`` 开始命名的整数目录。每个目录包含的文件暴露了关于每个
-内存区域的详细信息，在下一个 :ref:`聚集区间 <sysfs_monitoring_attrs>`，相应的方案的 ``动作``
-已经尝试在这个目录下应用。这些信息包括地址范围、``nr_accesses`` 以及区域的 ``年龄`` 。
+该目录初始时有一个文件 ``total_bytes``。
+
+当特殊关键字 ``update_schemes_tried_regions`` 被写入相关
+``kdamonds/<N>/state`` 文件时，DAMON 会更新 ``total_bytes`` 文件，使读取
+它时返回该方案尝试区域的总大小，并在该目录下创建从 ``0`` 开始以整数命名的
+目录。每个目录包含一些文件，暴露该目录下对应方案的 ``action`` 在对应方案的
+下一个 :ref:`应用间隔 <damon_design_damos_zh_CN>` 内尝试应用的每个内存区域的详细
+信息。这些信息包括该区域的地址范围、``nr_accesses`` 和 ``age``。
+
+向相关 ``kdamonds/<N>/state`` 文件写入 ``update_schemes_tried_bytes`` 只会
+更新 ``total_bytes`` 文件，而不会创建子目录。
+
+当另一个特殊关键字 ``clear_schemes_tried_regions`` 被写入相关
+``kdamonds/<N>/state`` 文件时，这些目录会被删除。
+
+该目录的预期用途是调查方案行为，以及类似查询的高效数据访问监测结果获取。
+特别是对于后一种用例，用户可以将 ``action`` 设置为 ``stat``，并将
+``access pattern`` 设置为他们感兴趣、想要查询的模式。
 
-当另一个特殊的关键字 ``clear_schemes_tried_regions`` 被写入相关的 ``kdamonds/<N>/state``
-文件时，这些目录将被删除。
+.. _sysfs_schemes_tried_region_zh_CN:
 
 tried_regions/<N>/
 ------------------
 
-在每个区域目录中，你会发现四个文件(``start``, ``end``, ``nr_accesses``, and ``age``)。
-读取这些文件将显示相应的基于DAMON的操作方案 ``动作`` 试图应用的区域的开始和结束地址、``nr_accesses``
-和 ``年龄`` 。
+在每个区域目录中，你会发现五个文件（``start``、``end``、``nr_accesses``、
+``age`` 和 ``sz_filter_passed``）。读取这些文件将显示相应的基于DAMON的操作方案
+``action`` 试图应用的区域属性。
+
+tried_regions/<N>/probes/
+-------------------------
+
+在每个区域目录中，还存在一个目录（``probes``）。在该目录中，存在命名为
+``0`` 到 ``N-1`` 的子目录。``N`` 是已安装探针的数量。在每个数字命名的
+目录中，存在一个文件（``hits``）。读取该文件会显示该区域的数据属性监测
+探针命中正样本的数量。
 
 用例
 ~~~~
@@ -330,16 +601,46 @@ tried_regions/<N>/
 请注意，我们强烈建议使用用户空间的工具，如 `damo <https://github.com/damonitor/damo>`_ ，
 而不是像上面那样手动读写文件。以上只是一个例子。
 
+.. _tracepoint_zh_CN:
 
 监测结果的监测点
 ================
 
-DAMON通过一个tracepoint ``damon:damon_aggregated`` 提供监测结果.  当监测开启时，你可
-以记录追踪点事件，并使用追踪点支持工具如perf显示结果。比如说::
+用户可以通过 :ref:`tried_regions <sysfs_schemes_tried_regions_zh_CN>` 获取
+监测结果。该接口适合获取快照，但用于完整记录所有监测结果时可能效率不高。
+为此，提供了两个tracepoint，即 ``damon:damon_aggregated`` 和
+``damon:damos_before_apply``。``damon:damon_aggregated`` 提供完整的监测
+结果，而 ``damon:damos_before_apply`` 提供每个基于 DAMON 的操作方案
+（:ref:`DAMOS <damon_design_damos_zh_CN>`）将要应用到的区域的监测结果。因此，
+``damon:damos_before_apply`` 更适合记录 DAMOS 的内部行为，或者基于 DAMOS
+目标访问 :ref:`模式 <damon_design_damos_access_pattern_zh_CN>` 的类似查询的高效
+监测结果记录。
 
-    # echo on > monitor_on_DEPRECATED
+监测开启时，你可以记录追踪点事件，并使用追踪点支持工具如 ``perf`` 显示结果。比如说::
+
+    # echo on > kdamonds/0/state
     # perf record -e damon:damon_aggregated &
     # sleep 5
     # kill 9 $(pidof perf)
-    # echo off > monitor_on_DEPRECATED
+    # echo off > kdamonds/0/state
     # perf script
+    kdamond.0 46568 [027] 79357.842179: damon:damon_aggregated: target_id=0 nr_regions=11 122509119488-135708762112: 0 864
+    [...]
+
+``perf script`` 输出的每一行表示一个监测区域。前五个字段与其他跟踪点输出
+一样。第六个字段 ``target_id=X`` 显示该区域的监测目标 id。第七个字段
+``nr_regions=X`` 显示该目标的监测区域总数。第八个字段 ``X-Y:`` 显示
+该区域的起始地址 ``X`` 和结束地址 ``Y``，单位为字节。第九个字段 ``X``
+显示该区域的 ``nr_accesses`` （关于该计数器的更多细节请参考 :ref:`设计 <damon_design_region_based_sampling_zh_CN>`）。最后，第十个字段 ``X`` 显示该区域
+的 ``age`` （关于该计数器的更多细节请参考 :ref:`设计 <damon_design_age_tracking_zh_CN>`）。
+
+如果事件是 ``damon:damos_before_apply``，``perf script`` 输出大致如下::
+
+    kdamond.0 47293 [000] 80801.060214: damon:damos_before_apply: ctx_idx=0 scheme_idx=0 target_idx=0 nr_regions=11 121932607488-135128711168: 0 136
+    [...]
+
+输出的每一行表示在被跟踪的时间点，每个基于 DAMON 的操作方案即将应用到的
+一个监测区域。前五个字段与通常一样。除了 ``damon_aggregated`` 跟踪点的
+输出之外，它还显示方案所属 DAMON 上下文在该上下文的 kdamond 的上下文列表
+中的索引（``ctx_idx=X``），以及该方案在该上下文的方案列表中的索引
+（``scheme_idx=X``）。
-- 
2.43.0

[PATCH v6 6/7] docs/zh_CN: update DAMON reclaim translation

[Doehyun Baek]

Update the Chinese translation of .../admin-guide/mm/damon/reclaim.rst.

Update the translation through commit c9380cdd949d
("Docs/{admin-guide,mm}/damon: fix DAMON documentation details").

Signed-off-by: Doehyun Baek <doehyunbaek@gmail.com>
---
 .../zh_CN/admin-guide/mm/damon/reclaim.rst    | 82 ++++++++++++++++++-
 1 file changed, 80 insertions(+), 2 deletions(-)

diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst
index d14ba32f7788..1e9375947295 100644
--- a/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst
+++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/reclaim.rst
@@ -58,6 +58,19 @@ enabled
 DAMON_RECLAIM。注意，由于基于水位的激活条件，DAMON_RECLAIM不能进行真正的监测和回收。
 这一点请参考下面关于水位参数的描述。
 
+commit_inputs
+-------------
+
+让 DAMON_RECLAIM 再次读取除 ``enabled`` 外的输入参数。
+
+DAMON_RECLAIM 运行期间更新的输入参数默认不会应用。一旦该参数被设置为
+``Y``，DAMON_RECLAIM 会再次读取除 ``enabled`` 外的参数值。重新读取完成后，
+该参数会被设置为 ``N``。如果重新读取时发现无效参数，DAMON_RECLAIM 会被
+禁用。
+
+一旦向该参数写入 ``Y``，用户在再次读取 ``commit_inputs`` 返回 ``N`` 之前，
+不得写入任何参数。如果用户违反该规则，内核可能表现出未定义行为。
+
 min_age
 -------
 
@@ -68,6 +81,15 @@ min_age
 
 默认为120秒。
 
+autotune_monitoring_intervals
+-----------------------------
+
+如果该参数设置为 ``Y``，DAMON_RECLAIM 会自动调优 DAMON 的采样和聚集间隔。
+自动调优的目标是在每个 DAMON 快照中捕获有意义数量的访问事件，同时将采样
+间隔限制在最小 5 毫秒、最大 10 秒。将其设置为 ``N`` 会禁用自动调优。
+
+默认禁用。
+
 quota_ms
 --------
 
@@ -98,6 +120,29 @@ quota_reset_interval_ms
 
 默认为1秒。
 
+quota_mem_pressure_us
+---------------------
+
+期望的内存压力停滞时间水平，单位为微秒。
+
+在保持其他配额设置的上限的同时，DAMON_RECLAIM 会自动增减配额的有效水平，
+目标是产生该水平的内存压力。系统范围的 ``some`` 内存 PSI 会按每个配额重置
+间隔（``quota_reset_interval_ms``）以微秒为单位收集，并与该值比较，以判断
+目标是否满足。值为零表示禁用该自动调优功能。
+
+默认禁用。
+
+quota_autotune_feedback
+-----------------------
+
+用户可指定的有效配额自动调优反馈。
+
+在保持其他配额设置的上限的同时，DAMON_RECLAIM 会自动增减配额的有效水平，
+目标是从用户接收到值为 ``10,000`` 的反馈。DAMON_RECLAIM 假定反馈值和配额
+成正比。值为零表示禁用该自动调优功能。
+
+默认禁用。
+
 wmarks_interval
 ---------------
 
@@ -149,6 +194,8 @@ min_nr_regions
 DAMON用于冷内存监测的最小监测区域数。这可以用来设置监测质量的下限。但是，设
 置的太高可能会导致监测开销的增加。更多细节请参考DAMON文档 (:doc:`usage`) 。
 
+请注意，该值必须为 3 或更高。该下限的理由请参考设计文档的 :ref:`监测 <damon_design_monitoring_zh_CN>` 章节。
+
 max_nr_regions
 --------------
 
@@ -163,7 +210,7 @@ monitor_region_start
 目标内存区域的物理地址起点。
 
 DAMON_RECLAIM将对其进行工作的内存区域的起始物理地址。也就是说，DAMON_RECLAIM
-将在这个区域中找到冷的内存区域并进行回收。默认情况下，该区域使用最大系统内存区。
+将在这个区域中找到冷的内存区域并进行回收。默认情况下，该区域使用系统的整个物理内存。
 
 monitor_region_end
 ------------------
@@ -171,7 +218,35 @@ monitor_region_end
 目标内存区域的结束物理地址。
 
 DAMON_RECLAIM将对其进行工作的内存区域的末端物理地址。也就是说，DAMON_RECLAIM将
-在这个区域内找到冷的内存区域并进行回收。默认情况下，该区域使用最大系统内存区。
+在这个区域内找到冷的内存区域并进行回收。默认情况下，该区域使用系统的整个物理内存。
+
+addr_unit
+---------
+
+内存地址和字节数的缩放因子。
+
+该参数用于设置和获取 DAMON_RECLAIM 的 DAMON 实例的 :ref:`地址单位 <damon_design_addr_unit_zh_CN>` 参数。
+
+``monitor_region_start`` 和 ``monitor_region_end`` 应以该单位提供。例如，
+假设 ``addr_unit``、``monitor_region_start`` 和 ``monitor_region_end``
+分别设置为 ``1024``、``0`` 和 ``10``。那么 DAMON_RECLAIM 将处理从地址零
+开始、长度为 10 KiB 的物理地址范围（以字节表示为
+``[0 * 1024, 10 * 1024)``）。
+
+``bytes_reclaim_tried_regions`` 和 ``bytes_reclaimed_regions`` 也使用该单位。
+例如，假设 ``addr_unit``、``bytes_reclaim_tried_regions`` 和
+``bytes_reclaimed_regions`` 的值分别为 ``1024``、``42`` 和 ``32``。那么这
+表示 DAMON_RECLAIM 总共尝试回收 42 KiB 内存，并成功回收了 32 KiB 内存。
+
+如果不确定，只使用默认值（``1``）并忘记这个参数即可。
+
+skip_anon
+---------
+
+跳过匿名页回收。
+
+如果该参数设置为 ``Y``，DAMON_RECLAIM 不会回收匿名页。默认值为 ``N``。
+
 
 kdamond_pid
 -----------
@@ -223,6 +298,9 @@ DAMON_RECLAIM再次什么都不做，这样我们就可以退回到基于LRU列
     # echo 200 > wmarks_low
     # echo Y > enabled
 
+请注意，该模块（damon_reclaim）不能与其他基于 DAMON 的专用模块同时运行。
+更多细节请参考 :ref:`DAMON 设计文档的专用模块互斥性 <damon_design_special_purpose_modules_exclusivity_zh_CN>`。
+
 .. [1] https://research.google/pubs/pub48551/
 .. [2] https://lwn.net/Articles/787611/
 .. [3] https://www.kernel.org/doc/html/latest/mm/free_page_reporting.html
-- 
2.43.0

[PATCH v6 7/7] docs/zh_CN: update DAMON LRU sort translation

[Doehyun Baek]

Update the Chinese translation of .../admin-guide/mm/damon/lru_sort.rst.

Update the translation through commit c9380cdd949d
("Docs/{admin-guide,mm}/damon: fix DAMON documentation details").

Signed-off-by: Doehyun Baek <doehyunbaek@gmail.com>
---
 .../zh_CN/admin-guide/mm/damon/lru_sort.rst   | 68 +++++++++++++++++--
 1 file changed, 64 insertions(+), 4 deletions(-)

diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst
index 03d33c710604..6af0dd59ef5d 100644
--- a/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst
+++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/lru_sort.rst
@@ -48,7 +48,7 @@ DAMON_LRU_SORT使用DAMON寻找热页（范围内的页面访问频率高于用
 
 为了让系统管理员打开或者关闭并且调节指定的系统，DAMON_LRU_SORT设计了模块参数。
 这意味着，你可以添加 ``damon_lru_sort.<parameter>=<value>`` 到内核的启动命令行
-参数，或者在 ``/sys/modules/damon_lru_sort/parameters/<parameter>`` 写入正确的
+参数，或者在 ``/sys/module/damon_lru_sort/parameters/<parameter>`` 写入正确的
 值。
 
 下边是每个参数的描述
@@ -71,6 +71,41 @@ commit_inputs
 ，DAMON_LRU_SORT会再次读取除了 ``enabled`` 之外的参数。读取完成后，这个参数会被
 设置为 ``N`` 。如果在读取时发现有无效参数，DAMON_LRU_SORT会被关闭。
 
+一旦向该参数写入 ``Y``，用户在再次读取 ``commit_inputs`` 返回 ``N`` 之前，
+不得写入任何参数。如果用户违反该规则，内核可能表现出未定义行为。
+
+active_mem_bp
+-------------
+
+期望的活跃内存与[非]活跃内存比率，单位为 bp（1/10,000）。
+
+在保持其他配额设置的上限的同时，DAMON_LRU_SORT 会自动增减配额的有效水平，
+目标是让热/冷内存的 LRU [降低]优先级处理产生该活跃内存与[非]活跃内存比率。
+值为零表示禁用该自动调优功能。
+
+默认禁用。
+
+autotune_monitoring_intervals
+-----------------------------
+
+如果该参数设置为 ``Y``，DAMON_LRU_SORT 会自动调优 DAMON 的采样和聚集间隔。
+自动调优的目标是在每个 DAMON 快照中捕获有意义数量的访问事件，同时将采样
+间隔限制在最小 5 毫秒、最大 10 秒。将其设置为 ``N`` 会禁用自动调优。
+
+默认禁用。
+
+filter_young_pages
+------------------
+
+相应地为 LRU [降低]优先级处理过滤[非]年轻页。
+
+如果设置该参数，则在每次 LRU [降低]优先级处理操作前再次检查页级访问
+（年轻性）。如果该页自上次检查以来未被访问（不年轻），则跳过 LRU 提高
+优先级操作。如果该页自上次检查以来已被访问（年轻），则跳过 LRU 降低优先级
+操作。当该参数分别设置为 ``Y`` 或 ``N`` 时，会启用或禁用该功能。
+
+默认禁用。
+
 hot_thres_access_freq
 ---------------------
 
@@ -163,6 +198,8 @@ min_nr_regions
 对冷内存区域监测的最小数量。这个值可以作为监测质量的下限。不过，这个值设置的过
 大会增加开销。更多细节请参考DAMON文档 (:doc:`usage`) 。默认值为10。
 
+请注意，该值必须为 3 或更高。该下限的理由请参考设计文档的 :ref:`监测 <damon_design_monitoring_zh_CN>` 章节。
+
 max_nr_regions
 --------------
 
@@ -176,14 +213,34 @@ monitor_region_start
 
 目标内存区域的起始物理地址。
 
-DAMON_LRU_SORT要处理的目标内存区域的起始物理地址。默认，使用系统最大内存。
+DAMON_LRU_SORT要处理的目标内存区域的起始物理地址。默认，使用系统的整个物理内存。
 
 monitor_region_end
 ------------------
 
 目标内存区域的结束物理地址。
 
-DAMON_LRU_SORT要处理的目标内存区域的结束物理地址。默认，使用系统最大内存。
+DAMON_LRU_SORT要处理的目标内存区域的结束物理地址。默认，使用系统的整个物理内存。
+
+addr_unit
+---------
+
+内存地址和字节数的缩放因子。
+
+该参数用于设置和获取 DAMON_RECLAIM 的 DAMON 实例的 :ref:`地址单位 <damon_design_addr_unit_zh_CN>` 参数。
+
+``monitor_region_start`` 和 ``monitor_region_end`` 应以该单位提供。例如，
+假设 ``addr_unit``、``monitor_region_start`` 和 ``monitor_region_end``
+分别设置为 ``1024``、``0`` 和 ``10``。那么 DAMON_LRU_SORT 将处理从地址零
+开始、长度为 10 KiB 的物理地址范围（以字节表示为
+``[0 * 1024, 10 * 1024)``）。
+
+带有 ``bytes_`` 前缀的统计参数也使用该单位。例如，假设 ``addr_unit``、
+``bytes_lru_sort_tried_hot_regions`` 和 ``bytes_lru_sorted_hot_regions`` 的值
+分别为 ``1024``、``42`` 和 ``32``。那么这表示 DAMON_LRU_SORT 尝试对
+42 KiB 热内存进行 LRU 排序，并总共成功对其中 32 KiB 内存进行了 LRU 排序。
+
+如果不确定，只使用默认值（``1``）并忘记这个参数即可。
 
 kdamond_pid
 -----------
@@ -252,7 +309,7 @@ LRU的优先级的提升，同时降低那些超过120秒无人访问的内存
 进展且空闲内存低于20%，再次让DAMON_LRU_SORT停止工作，以此回退到以LRU链表为基础
 以页面为单位的内存回收上。 ::
 
-    # cd /sys/modules/damon_lru_sort/parameters
+    # cd /sys/module/damon_lru_sort/parameters
     # echo 500 > hot_thres_access_freq
     # echo 120000000 > cold_min_age
     # echo 10 > quota_ms
@@ -261,3 +318,6 @@ LRU的优先级的提升，同时降低那些超过120秒无人访问的内存
     # echo 400 > wmarks_mid
     # echo 200 > wmarks_low
     # echo Y > enabled
+
+请注意，该模块（damon_lru_sort）不能与其他基于 DAMON 的专用模块同时运行。
+更多细节请参考 :ref:`DAMON 设计文档的专用模块互斥性 <damon_design_special_purpose_modules_exclusivity_zh_CN>`。
-- 
2.43.0

Re: [PATCH v6 2/7] docs/zh_CN: add DAMON_STAT usage translation

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] The newly added translation file `stat.rst` is not included in the `toctree` of the subsystem's corresponding index file, which will result in a Sphinx build warning.
--

--- Patch [2]: [PATCH v6 2/7] docs/zh_CN: add DAMON_STAT usage translation ---
commit 13f1c819e6520a41dcd7c6bb3035887d18f621e8
Author: Doehyun Baek <doehyunbaek@gmail.com>

docs/zh_CN: add DAMON_STAT usage translation
    
This commit translates the admin-guide/mm/damon/stat.rst documentation into
Chinese. It also updates the translation to include recent changes from the
English documentation.

> diff --git a/Documentation/translations/zh_CN/admin-guide/mm/damon/stat.rst b/Documentation/translations/zh_CN/admin-guide/mm/damon/stat.rst
> new file mode 100644
> index 0000000000000..129748a5ea1f0
> --- /dev/null
> +++ b/Documentation/translations/zh_CN/admin-guide/mm/damon/stat.rst
> @@ -0,0 +1,94 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: ../../../disclaimer-zh_CN.rst

[ ... ]

> +kdamond_pid
> +-----------
> +
> +DAMON 线程的 PID。
> +
> +如果 DAMON_STAT 已启用，这将成为工作线程的 PID。否则为 -1。

[Severity: Low]
Is a toctree entry for this new file missing from the index?

Because the newly added documentation file stat.rst is not linked from any
index, Sphinx will emit a "document isn't included in any toctree" warning
during documentation builds.

It appears stat.rst should be added to the toctree block in
Documentation/translations/zh_CN/admin-guide/mm/damon/index.rst:

.. toctree::
   :maxdepth: 2

   start
   usage
   reclaim
   lru_sort

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260708073246.1652828-1-doehyunbaek@gmail.com?part=2