Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Docs/admin-guide/mm/damon/usage: add links to sysfs files hierarchy
'Sysfs Files Hierarchy' section of DAMON usage document shows whole
picture of the interface. Then sections for detailed explanation of the
files follow. Due to the amount of the files, navigating between the
whole picture and the section for specific files sometimes require no
subtle amount of scrolling. Add links from the whole picture to the
dedicated sections for making the navigation easier.
Link: https://lkml.kernel.org/r/20231213190338.54146-6-sj@kernel.org
Signed-off-by: SeongJae Park <sj@kernel.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
authored by
SeongJae Park
and committed by
Andrew Morton
9c8c315d
c7ae9634
+48
-20
+48
-20
Documentation/admin-guide/mm/damon/usage.rst
+48
-20
Documentation/admin-guide/mm/damon/usage.rst
···
59
59
The files hierarchy of DAMON sysfs interface is shown below. In the below
60
60
figure, parents-children relations are represented with indentations, each
61
61
directory is having ``/`` suffix, and files in each directory are separated by
62
-
comma (","). ::
62
+
comma (",").
63
63
64
-
/sys/kernel/mm/damon/admin
65
-
│ kdamonds/nr_kdamonds
66
-
│ │ 0/state,pid
67
-
│ │ │ contexts/nr_contexts
68
-
│ │ │ │ 0/avail_operations,operations
69
-
│ │ │ │ │ monitoring_attrs/
64
+
.. parsed-literal::
65
+
66
+
:ref:`/sys/kernel/mm/damon <sysfs_root>`/admin
67
+
│ :ref:`kdamonds <sysfs_kdamonds>`/nr_kdamonds
68
+
│ │ :ref:`0 <sysfs_kdamond>`/state,pid
69
+
│ │ │ :ref:`contexts <sysfs_contexts>`/nr_contexts
70
+
│ │ │ │ :ref:`0 <sysfs_context>`/avail_operations,operations
71
+
│ │ │ │ │ :ref:`monitoring_attrs <sysfs_monitoring_attrs>`/
70
72
│ │ │ │ │ │ intervals/sample_us,aggr_us,update_us
71
73
│ │ │ │ │ │ nr_regions/min,max
72
-
│ │ │ │ │ targets/nr_targets
73
-
│ │ │ │ │ │ 0/pid_target
74
-
│ │ │ │ │ │ │ regions/nr_regions
75
-
│ │ │ │ │ │ │ │ 0/start,end
74
+
│ │ │ │ │ :ref:`targets <sysfs_targets>`/nr_targets
75
+
│ │ │ │ │ │ :ref:`0 <sysfs_target>`/pid_target
76
+
│ │ │ │ │ │ │ :ref:`regions <sysfs_regions>`/nr_regions
77
+
│ │ │ │ │ │ │ │ :ref:`0 <sysfs_region>`/start,end
76
78
│ │ │ │ │ │ │ │ ...
77
79
│ │ │ │ │ │ ...
78
-
│ │ │ │ │ schemes/nr_schemes
79
-
│ │ │ │ │ │ 0/action,apply_interval_us
80
-
│ │ │ │ │ │ │ access_pattern/
80
+
│ │ │ │ │ :ref:`schemes <sysfs_schemes>`/nr_schemes
81
+
│ │ │ │ │ │ :ref:`0 <sysfs_scheme>`/action,apply_interval_us
82
+
│ │ │ │ │ │ │ :ref:`access_pattern <sysfs_access_pattern>`/
81
83
│ │ │ │ │ │ │ │ sz/min,max
82
84
│ │ │ │ │ │ │ │ nr_accesses/min,max
83
85
│ │ │ │ │ │ │ │ age/min,max
84
-
│ │ │ │ │ │ │ quotas/ms,bytes,reset_interval_ms
86
+
│ │ │ │ │ │ │ :ref:`quotas <sysfs_quotas>`/ms,bytes,reset_interval_ms
85
87
│ │ │ │ │ │ │ │ weights/sz_permil,nr_accesses_permil,age_permil
86
-
│ │ │ │ │ │ │ │ goals/nr_goals
88
+
│ │ │ │ │ │ │ │ :ref:`goals <sysfs_schemes_quota_goals>`/nr_goals
87
89
│ │ │ │ │ │ │ │ │ 0/target_value,current_value
88
-
│ │ │ │ │ │ │ watermarks/metric,interval_us,high,mid,low
89
-
│ │ │ │ │ │ │ filters/nr_filters
90
+
│ │ │ │ │ │ │ :ref:`watermarks <sysfs_watermarks>`/metric,interval_us,high,mid,low
91
+
│ │ │ │ │ │ │ :ref:`filters <sysfs_filters>`/nr_filters
90
92
│ │ │ │ │ │ │ │ 0/type,matching,memcg_id
91
-
│ │ │ │ │ │ │ stats/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds
92
-
│ │ │ │ │ │ │ tried_regions/total_bytes
93
+
│ │ │ │ │ │ │ :ref:`stats <sysfs_schemes_stats>`/nr_tried,sz_tried,nr_applied,sz_applied,qt_exceeds
94
+
│ │ │ │ │ │ │ :ref:`tried_regions <sysfs_schemes_tried_regions>`/total_bytes
93
95
│ │ │ │ │ │ │ │ 0/start,end,nr_accesses,age
94
96
│ │ │ │ │ │ │ │ ...
95
97
│ │ │ │ │ │ ...
96
98
│ │ │ │ ...
97
99
│ │ ...
100
+
101
+
.. _sysfs_root:
98
102
99
103
Root
100
104
----
···
107
103
has one directory named ``admin``. The directory contains the files for
108
104
privileged user space programs' control of DAMON. User space tools or daemons
109
105
having the root permission could use this directory.
106
+
107
+
.. _sysfs_kdamonds:
110
108
111
109
kdamonds/
112
110
---------
···
159
153
160
154
``contexts`` directory contains files for controlling the monitoring contexts
161
155
that this kdamond will execute.
156
+
157
+
.. _sysfs_contexts:
162
158
163
159
kdamonds/<N>/contexts/
164
160
----------------------
···
222
214
For more details about the intervals and monitoring regions range, please refer
223
215
to the Design document (:doc:`/mm/damon/design`).
224
216
217
+
.. _sysfs_targets:
218
+
225
219
contexts/<N>/targets/
226
220
---------------------
227
221
228
222
In the beginning, this directory has only one file, ``nr_targets``. Writing a
229
223
number (``N``) to the file creates the number of child directories named ``0``
230
224
to ``N-1``. Each directory represents each monitoring target.
225
+
226
+
.. _sysfs_target:
231
227
232
228
targets/<N>/
233
229
------------
···
267
255
number (``N``) to the file creates the number of child directories named ``0``
268
256
to ``N-1``. Each directory represents each initial monitoring target region.
269
257
258
+
.. _sysfs_region:
259
+
270
260
regions/<N>/
271
261
------------
272
262
···
278
264
279
265
Each region should not overlap with others. ``end`` of directory ``N`` should
280
266
be equal or smaller than ``start`` of directory ``N+1``.
267
+
268
+
.. _sysfs_schemes:
281
269
282
270
contexts/<N>/schemes/
283
271
---------------------
···
291
275
In the beginning, this directory has only one file, ``nr_schemes``. Writing a
292
276
number (``N``) to the file creates the number of child directories named ``0``
293
277
to ``N-1``. Each directory represents each DAMON-based operation scheme.
278
+
279
+
.. _sysfs_scheme:
294
280
295
281
schemes/<N>/
296
282
------------
···
328
310
The ``apply_interval_us`` file is for setting and getting the scheme's
329
311
:ref:`apply_interval <damon_design_damos>` in microseconds.
330
312
313
+
.. _sysfs_access_pattern:
314
+
331
315
schemes/<N>/access_pattern/
332
316
---------------------------
333
317
···
342
322
to and reading from the ``min`` and ``max`` files under ``sz``,
343
323
``nr_accesses``, and ``age`` directories, respectively. Note that the ``min``
344
324
and the ``max`` form a closed interval.
325
+
326
+
.. _sysfs_quotas:
345
327
346
328
schemes/<N>/quotas/
347
329
-------------------
···
391
369
``commit_schemes_quota_goals`` to the ``state`` file of the :ref:`kdamond
392
370
directory <sysfs_kdamond>` to pass the feedback to DAMON.
393
371
372
+
.. _sysfs_watermarks:
373
+
394
374
schemes/<N>/watermarks/
395
375
-----------------------
396
376
···
411
387
- free_mem_rate: System's free memory rate (per thousand)
412
388
413
389
The ``interval`` should written in microseconds unit.
390
+
391
+
.. _sysfs_filters:
414
392
415
393
schemes/<N>/filters/
416
394
--------------------
···
508
482
and query-like efficient data access monitoring results retrievals. For the
509
483
latter use case, in particular, users can set the ``action`` as ``stat`` and
510
484
set the ``access pattern`` as their interested pattern that they want to query.
485
+
486
+
.. _sysfs_schemes_tried_region:
511
487
512
488
tried_regions/<N>/
513
489
------------------