Documentation/translations/zh_CN/admin-guide/mm/damon/usage.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2 .. include:: ../../../disclaimer-zh_CN.rst
   3
   4 :Original: Documentation/admin-guide/mm/damon/usage.rst
   5
   6 :翻译:
   7
   8  司延腾 Yanteng Si <siyanteng@loongson.cn>
   9
  10 :校译:
  11
  12 ========
  13 详细用法
  14 ========
  15
  16 DAMON 为不同的用户提供了下面这些接口。
  17
  18 - *DAMON用户空间工具。*
  19   `这 <https://github.com/damonitor/damo>`_ 为有这特权的人， 如系统管理员，希望有一个刚好
  20   可以工作的人性化界面。
  21   使用它，用户可以以人性化的方式使用DAMON的主要功能。不过，它可能不会为特殊情况进行高度调整。
  22   它同时支持虚拟和物理地址空间的监测。更多细节，请参考它的 `使用文档
  23   <https://github.com/damonitor/damo/blob/next/USAGE.md>`_。
  24 - *sysfs接口。*
  25   :ref:`这 <sysfs_interface>` 是为那些希望更高级的使用DAMON的特权用户空间程序员准备的。
  26   使用它，用户可以通过读取和写入特殊的sysfs文件来使用DAMON的主要功能。因此，你可以编写和使
  27   用你个性化的DAMON sysfs包装程序，代替你读/写sysfs文件。  `DAMON用户空间工具
  28   <https://github.com/damonitor/damo>`_ 就是这种程序的一个例子  它同时支持虚拟和物理地址
  29   空间的监测。
  30 - *内核空间编程接口。*
  31   :doc:`这 </mm/damon/api>` 这是为内核空间程序员准备的。使用它，用户可以通过为你编写内
  32   核空间的DAMON应用程序，最灵活有效地利用DAMON的每一个功能。你甚至可以为各种地址空间扩展DAMON。
  33   详细情况请参考接口 :doc:`文件 </mm/damon/api>`。
  34
  35 sysfs接口
  36 =========
  37 DAMON的sysfs接口是在定义 ``CONFIG_DAMON_SYSFS`` 时建立的。它在其sysfs目录下创建多
  38 个目录和文件， ``<sysfs>/kernel/mm/damon/`` 。你可以通过对该目录下的文件进行写入和
  39 读取来控制DAMON。
  40
  41 对于一个简短的例子，用户可以监测一个给定工作负载的虚拟地址空间，如下所示::
  42
  43     # cd /sys/kernel/mm/damon/admin/
  44     # echo 1 > kdamonds/nr_kdamonds && echo 1 > kdamonds/0/contexts/nr_contexts
  45     # echo vaddr > kdamonds/0/contexts/0/operations
  46     # echo 1 > kdamonds/0/contexts/0/targets/nr_targets
  47     # echo $(pidof <workload>) > kdamonds/0/contexts/0/targets/0/pid_target
  48     # echo on > kdamonds/0/state
  49
  50 文件层次结构
  51 ------------
  52
  53 DAMON sysfs接口的文件层次结构如下图所示。在下图中，父子关系用缩进表示，每个目录有
  54 ``/`` 后缀，每个目录中的文件用逗号（","）分开。 ::
  55
  56     /sys/kernel/mm/damon/admin
  57     │ kdamonds/nr_kdamonds
  58     │ │ 0/state,pid
  59     │ │ │ contexts/nr_contexts
  60     │ │ │ │ 0/operations
  61     │ │ │ │ │ monitoring_attrs/
  62     │ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
  63     │ │ │ │ │ │ nr_regions/min,max
  64     │ │ │ │ │ targets/nr_targets
  65     │ │ │ │ │ │ 0/pid_target
  66     │ │ │ │ │ │ │ regions/nr_regions
  67     │ │ │ │ │ │ │ │ 0/start,end
  68     │ │ │ │ │ │ │ │ ...
  69     │ │ │ │ │ │ ...
  70     │ │ │ │ │ schemes/nr_schemes
  71     │ │ │ │ │ │ 0/action
  72     │ │ │ │ │ │ │ access_pattern/
  73     │ │ │ │ │ │ │ │ sz/min,max
  74     │ │ │ │ │ │ │ │ nr_accesses/min,max
  75     │ │ │ │ │ │ │ │ age/min,max
  76     │ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms
  77     │ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil
  78     │ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low
  79     │ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds
  80     │ │ │ │ │ │ │ tried_regions/
  81     │ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age
  82     │ │ │ │ │ │ │ │ ...
  83     │ │ │ │ │ │ ...
  84     │ │ │ │ ...
  85     │ │ ...
  86
  87 根
  88 --
  89
  90 DAMON sysfs接口的根是 ``<sysfs>/kernel/mm/damon/`` ，它有一个名为 ``admin`` 的
  91 目录。该目录包含特权用户空间程序控制DAMON的文件。拥有根权限的用户空间工具或deamons可以
  92 使用这个目录。
  93
  94 kdamonds/
  95 ---------
  96
  97 与监测相关的信息包括请求规格和结果被称为DAMON上下文。DAMON用一个叫做kdamond的内核线程
  98 执行每个上下文，多个kdamonds可以并行运行。
  99
 100 在 ``admin`` 目录下，有一个目录，即``kdamonds``，它有控制kdamonds的文件存在。在开始
 101 时，这个目录只有一个文件，``nr_kdamonds``。向该文件写入一个数字（``N``），就会创建名为
 102 ``0`` 到 ``N-1`` 的子目录数量。每个目录代表每个kdamond。
 103
 104 kdamonds/<N>/
 105 -------------
 106
 107 在每个kdamond目录中，存在两个文件（``state`` 和 ``pid`` ）和一个目录( ``contexts`` )。
 108
 109 读取 ``state`` 时，如果kdamond当前正在运行，则返回 ``on`` ，如果没有运行则返回 ``off`` 。
 110 写入 ``on`` 或 ``off`` 使kdamond处于状态。向 ``state`` 文件写 ``update_schemes_stats`` ，
 111 更新kdamond的每个基于DAMON的操作方案的统计文件的内容。关于统计信息的细节，请参考
 112 :ref:`stats section <sysfs_schemes_stats>`. 将 ``update_schemes_tried_regions`` 写到
 113 ``state`` 文件，为kdamond的每个基于DAMON的操作方案，更新基于DAMON的操作方案动作的尝试区域目录。
 114 将`clear_schemes_tried_regions`写入`state`文件，清除kdamond的每个基于DAMON的操作方案的动作
 115 尝试区域目录。 关于基于DAMON的操作方案动作尝试区域目录的细节，请参考:ref:tried_regions 部分
 116 <sysfs_schemes_tried_regions>`。
 117
 118 如果状态为 ``on``，读取 ``pid`` 显示kdamond线程的pid。
 119
 120 ``contexts`` 目录包含控制这个kdamond要执行的监测上下文的文件。
 121
 122 kdamonds/<N>/contexts/
 123 ----------------------
 124
 125 在开始时，这个目录只有一个文件，即 ``nr_contexts`` 。向该文件写入一个数字( ``N`` )，就会创
 126 建名为``0`` 到 ``N-1`` 的子目录数量。每个目录代表每个监测背景。目前，每个kdamond只支持
 127 一个上下文，所以只有 ``0`` 或 ``1`` 可以被写入文件。
 128
 129 contexts/<N>/
 130 -------------
 131
 132 在每个上下文目录中，存在一个文件(``operations``)和三个目录(``monitoring_attrs``,
 133 ``targets``, 和 ``schemes``)。
 134
 135 DAMON支持多种类型的监测操作，包括对虚拟地址空间和物理地址空间的监测。你可以通过向文件
 136 中写入以下关键词之一，并从文件中读取，来设置和获取DAMON将为上下文使用何种类型的监测操作。
 137
 138  - vaddr: 监测特定进程的虚拟地址空间
 139  - paddr: 监视系统的物理地址空间
 140
 141 contexts/<N>/monitoring_attrs/
 142 ------------------------------
 143
 144 用于指定监测属性的文件，包括所需的监测质量和效率，都在 ``monitoring_attrs`` 目录中。
 145 具体来说，这个目录下有两个目录，即 ``intervals`` 和 ``nr_regions`` 。
 146
 147 在 ``intervals`` 目录下，存在DAMON的采样间隔(``sample_us``)、聚集间隔(``aggr_us``)
 148 和更新间隔(``update_us``)三个文件。你可以通过写入和读出这些文件来设置和获取微秒级的值。
 149
 150 在 ``nr_regions`` 目录下，有两个文件分别用于DAMON监测区域的下限和上限（``min`` 和 ``max`` ），
 151 这两个文件控制着监测的开销。你可以通过向这些文件的写入和读出来设置和获取这些值。
 152
 153 关于间隔和监测区域范围的更多细节，请参考设计文件 (:doc:`/mm/damon/design`)。
 154
 155 contexts/<N>/targets/
 156 ---------------------
 157
 158 在开始时，这个目录只有一个文件 ``nr_targets`` 。向该文件写入一个数字(``N``)，就可以创建
 159 名为 ``0`` 到 ``N-1`` 的子目录的数量。每个目录代表每个监测目标。
 160
 161 targets/<N>/
 162 ------------
 163
 164 在每个目标目录中，存在一个文件(``pid_target``)和一个目录(``regions``)。
 165
 166 如果你把 ``vaddr`` 写到 ``contexts/<N>/operations`` 中，每个目标应该是一个进程。你
 167 可以通过将进程的pid写到 ``pid_target`` 文件中来指定DAMON的进程。
 168
 169 targets/<N>/regions
 170 -------------------
 171
 172 当使用 ``vaddr`` 监测操作集时（ ``vaddr`` 被写入 ``contexts/<N>/operations`` 文
 173 件），DAMON自动设置和更新监测目标区域，这样就可以覆盖目标进程的整个内存映射。然而，用户可
 174 能希望将初始监测区域设置为特定的地址范围。
 175
 176 相反，当使用 ``paddr`` 监测操作集时，DAMON不会自动设置和更新监测目标区域（ ``paddr``
 177 被写入 ``contexts/<N>/operations`` 中）。因此，在这种情况下，用户应该自己设置监测目标
 178 区域。
 179
 180 在这种情况下，用户可以按照自己的意愿明确设置初始监测目标区域，将适当的值写入该目录下的文件。
 181
 182 开始时，这个目录只有一个文件， ``nr_regions`` 。向该文件写入一个数字(``N``)，就可以创
 183 建名为 ``0`` 到  ``N-1`` 的子目录。每个目录代表每个初始监测目标区域。
 184
 185 regions/<N>/
 186 ------------
 187
 188 在每个区域目录中，你会发现两个文件（ ``start``  和  ``end`` ）。你可以通过向文件写入
 189 和从文件中读出，分别设置和获得初始监测目标区域的起始和结束地址。
 190
 191 每个区域不应该与其他区域重叠。 目录“N”的“结束”应等于或小于目录“N+1”的“开始”。
 192
 193 contexts/<N>/schemes/
 194 ---------------------
 195
 196 对于一版的基于DAMON的数据访问感知的内存管理优化，用户通常希望系统对特定访问模式的内存区
 197 域应用内存管理操作。DAMON从用户那里接收这种形式化的操作方案，并将这些方案应用于目标内存
 198 区域。用户可以通过读取和写入这个目录下的文件来获得和设置这些方案。
 199
 200 在开始时，这个目录只有一个文件，``nr_schemes``。向该文件写入一个数字(``N``)，就可以
 201 创建名为``0``到``N-1``的子目录的数量。每个目录代表每个基于DAMON的操作方案。
 202
 203 schemes/<N>/
 204 ------------
 205
 206 在每个方案目录中，存在五个目录(``access_pattern``、``quotas``、``watermarks``、
 207 ``stats`` 和 ``tried_regions``)和一个文件(``action``)。
 208
 209 ``action`` 文件用于设置和获取你想应用于具有特定访问模式的内存区域的动作。可以写入文件
 210 和从文件中读取的关键词及其含义如下。
 211
 212  - ``willneed``: 对有 ``MADV_WILLNEED`` 的区域调用 ``madvise()`` 。
 213  - ``cold``: 对具有 ``MADV_COLD`` 的区域调用 ``madvise()`` 。
 214  - ``pageout``: 为具有 ``MADV_PAGEOUT`` 的区域调用 ``madvise()`` 。
 215  - ``hugepage``: 为带有 ``MADV_HUGEPAGE`` 的区域调用 ``madvise()`` 。
 216  - ``nohugepage``: 为带有 ``MADV_NOHUGEPAGE`` 的区域调用 ``madvise()``。
 217  - ``lru_prio``: 在其LRU列表上对区域进行优先排序。
 218  - ``lru_deprio``: 对区域的LRU列表进行降低优先处理。
 219  - ``stat``: 什么都不做，只计算统计数据
 220
 221 schemes/<N>/access_pattern/
 222 ---------------------------
 223
 224 每个基于DAMON的操作方案的目标访问模式由三个范围构成，包括以字节为单位的区域大小、每个
 225 聚合区间的监测访问次数和区域年龄的聚合区间数。
 226
 227 在 ``access_pattern`` 目录下，存在三个目录（ ``sz``, ``nr_accesses``, 和 ``age`` ），
 228 每个目录有两个文件（``min`` 和 ``max`` ）。你可以通过向  ``sz``, ``nr_accesses``, 和
 229 ``age``  目录下的 ``min`` 和 ``max`` 文件分别写入和读取来设置和获取给定方案的访问模式。
 230
 231 schemes/<N>/quotas/
 232 -------------------
 233
 234 每个 ``动作`` 的最佳 ``目标访问模式`` 取决于工作负载，所以不容易找到。更糟糕的是，将某些动作
 235 的方案设置得过于激进会造成严重的开销。为了避免这种开销，用户可以为每个方案限制时间和大小配额。
 236 具体来说，用户可以要求DAMON尽量只使用特定的时间（``时间配额``）来应用动作，并且在给定的时间间
 237 隔（``重置间隔``）内，只对具有目标访问模式的内存区域应用动作，而不使用特定数量（``大小配额``）。
 238
 239 当预计超过配额限制时，DAMON会根据 ``目标访问模式`` 的大小、访问频率和年龄，对找到的内存区域
 240 进行优先排序。为了进行个性化的优先排序，用户可以为这三个属性设置权重。
 241
 242 在 ``quotas`` 目录下，存在三个文件（``ms``, ``bytes``, ``reset_interval_ms``）和一个
 243 目录(``weights``)，其中有三个文件(``sz_permil``, ``nr_accesses_permil``, 和
 244 ``age_permil``)。
 245
 246 你可以设置以毫秒为单位的 ``时间配额`` ，以字节为单位的 ``大小配额`` ，以及以毫秒为单位的 ``重
 247 置间隔`` ，分别向这三个文件写入数值。你还可以通过向 ``weights`` 目录下的三个文件写入数值来设
 248 置大小、访问频率和年龄的优先权，单位为千分之一。
 249
 250 schemes/<N>/watermarks/
 251 -----------------------
 252
 253 为了便于根据系统状态激活和停用每个方案，DAMON提供了一个称为水位的功能。该功能接收五个值，称为
 254 ``度量`` 、``间隔`` 、``高`` 、``中`` 、``低`` 。``度量值`` 是指可以测量的系统度量值，如
 255 自由内存比率。如果系统的度量值 ``高`` 于memoent的高值或 ``低`` 于低值，则该方案被停用。如果
 256 该值低于 ``中`` ，则该方案被激活。
 257
 258 在水位目录下，存在五个文件(``metric``, ``interval_us``,``high``, ``mid``, and ``low``)
 259 用于设置每个值。你可以通过向这些文件的写入来分别设置和获取这五个值。
 260
 261 可以写入 ``metric`` 文件的关键词和含义如下。
 262
 263  - none: 忽略水位
 264  - free_mem_rate: 系统的自由内存率（千分比）。
 265
 266 ``interval`` 应以微秒为单位写入。
 267
 268 schemes/<N>/stats/
 269 ------------------
 270
 271 DAMON统计每个方案被尝试应用的区域的总数量和字节数，每个方案被成功应用的区域的两个数字，以及
 272 超过配额限制的总数量。这些统计数据可用于在线分析或调整方案。
 273
 274 可以通过读取 ``stats`` 目录下的文件(``nr_tried``, ``sz_tried``, ``nr_applied``,
 275 ``sz_applied``, 和 ``qt_exceeds``)）分别检索这些统计数据。这些文件不是实时更新的，所以
 276 你应该要求DAMON sysfs接口通过在相关的 ``kdamonds/<N>/state`` 文件中写入一个特殊的关键字
 277 ``update_schemes_stats`` 来更新统计信息的文件内容。
 278
 279 schemes/<N>/tried_regions/
 280 --------------------------
 281
 282 当一个特殊的关键字 ``update_schemes_tried_regions`` 被写入相关的 ``kdamonds/<N>/state``
 283 文件时，DAMON会在这个目录下创建从 ``0`` 开始命名的整数目录。每个目录包含的文件暴露了关于每个
 284 内存区域的详细信息，在下一个 :ref:`聚集区间 <sysfs_monitoring_attrs>`，相应的方案的 ``动作``
 285 已经尝试在这个目录下应用。这些信息包括地址范围、``nr_accesses`` 以及区域的 ``年龄`` 。
 286
 287 当另一个特殊的关键字 ``clear_schemes_tried_regions`` 被写入相关的 ``kdamonds/<N>/state``
 288 文件时，这些目录将被删除。
 289
 290 tried_regions/<N>/
 291 ------------------
 292
 293 在每个区域目录中，你会发现四个文件(``start``, ``end``, ``nr_accesses``, and ``age``)。
 294 读取这些文件将显示相应的基于DAMON的操作方案 ``动作`` 试图应用的区域的开始和结束地址、``nr_accesses``
 295 和 ``年龄`` 。
 296
 297 用例
 298 ~~~~
 299
 300 下面的命令应用了一个方案：”如果一个大小为[4KiB, 8KiB]的内存区域在[10, 20]的聚合时间间隔内
 301 显示出每一个聚合时间间隔[0, 5]的访问量，请分页该区域。对于分页，每秒最多只能使用10ms，而且每
 302 秒分页不能超过1GiB。在这一限制下，首先分页出具有较长年龄的内存区域。另外，每5秒钟检查一次系统
 303 的可用内存率，当可用内存率低于50%时开始监测和分页，但如果可用内存率大于60%，或低于30%，则停
 304 止监测。“ ::
 305
 306     # cd <sysfs>/kernel/mm/damon/admin
 307     # # populate directories
 308     # echo 1 > kdamonds/nr_kdamonds; echo 1 > kdamonds/0/contexts/nr_contexts;
 309     # echo 1 > kdamonds/0/contexts/0/schemes/nr_schemes
 310     # cd kdamonds/0/contexts/0/schemes/0
 311     # # set the basic access pattern and the action
 312     # echo 4096 > access_pattern/sz/min
 313     # echo 8192 > access_pattern/sz/max
 314     # echo 0 > access_pattern/nr_accesses/min
 315     # echo 5 > access_pattern/nr_accesses/max
 316     # echo 10 > access_pattern/age/min
 317     # echo 20 > access_pattern/age/max
 318     # echo pageout > action
 319     # # set quotas
 320     # echo 10 > quotas/ms
 321     # echo $((1024*1024*1024)) > quotas/bytes
 322     # echo 1000 > quotas/reset_interval_ms
 323     # # set watermark
 324     # echo free_mem_rate > watermarks/metric
 325     # echo 5000000 > watermarks/interval_us
 326     # echo 600 > watermarks/high
 327     # echo 500 > watermarks/mid
 328     # echo 300 > watermarks/low
 329
 330 请注意，我们强烈建议使用用户空间的工具，如 `damo <https://github.com/damonitor/damo>`_ ，
 331 而不是像上面那样手动读写文件。以上只是一个例子。
 332
 333
 334 监测结果的监测点
 335 ================
 336
 337 DAMON通过一个tracepoint ``damon:damon_aggregated`` 提供监测结果.  当监测开启时，你可
 338 以记录追踪点事件，并使用追踪点支持工具如perf显示结果。比如说::
 339
 340     # echo on > monitor_on_DEPRECATED
 341     # perf record -e damon:damon_aggregated &
 342     # sleep 5
 343     # kill 9 $(pidof perf)
 344     # echo off > monitor_on_DEPRECATED
 345     # perf script