On Fri, Feb 25, 2022 at 02:15:40PM +0000, SeongJae Park wrote:
On Fri, 25 Feb 2022 14:10:07 +0000 SeongJae Park sj@kernel.org wrote:
Hello Gregg,
On Fri, 25 Feb 2022 13:23:00 +0000 SeongJae Park sj@kernel.org wrote:
On Fri, 25 Feb 2022 14:18:59 +0100 Greg KH gregkh@linuxfoundation.org wrote:
On Fri, Feb 25, 2022 at 01:07:12PM +0000, SeongJae Park wrote:
This commit adds DAMON sysfs interface ABI document under Documentation/ABI/testing.
Signed-off-by: SeongJae Park sj@kernel.org
.../ABI/testing/sysfs-kernel-mm-damon | 276 ++++++++++++++++++ MAINTAINERS | 1 + 2 files changed, 277 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-kernel-mm-damon
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon new file mode 100644 index 000000000000..11984c3a4b55 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -0,0 +1,276 @@ +what: /sys/kernel/mm/damon/ +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Interface for Data Access MONitoring (DAMON).
See Documentation/admin-guide/mm/damon/index.rst for details.Ick, no. Put the real details in here please. That way it works with our tools.
Ok, thanks for the quick comment!
Before sending the full series again, I'd like to get your comment if you're ok. What do you think about below?
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon new file mode 100644 index 000000000000..11984c3a4b55 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -0,0 +1,276 @@ +what: /sys/kernel/mm/damon/ +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Interface for Data Access MONitoring (DAMON).
See Documentation/admin-guide/mm/damon/index.rst for details.Oops, I pasted wrong, sorry. Please read below:
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-damon b/Documentation/ABI/testing/sysfs-kernel-mm-damon new file mode 100644 index 000000000000..e58d844b4f82 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-damon @@ -0,0 +1,273 @@ +what: /sys/kernel/mm/damon/ +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Interface for Data Access MONitoring (DAMON). Contains files
for controlling DAMON.
For this entry, point people at your larger documentation.
+What: /sys/kernel/mm/damon/admin/ +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Interface for privileged users of DAMON. Contains files for
controlling DAMON that aimed to be used by privileged users.+What: /sys/kernel/mm/damon/admin/kdamonds/nr_kdamonds +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a number 'N' to this file creates the number of
directories for controlling each DAMON worker thread (kdamond)named '0' to 'N-1' under the kdamonds/ directory.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/state +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing 'on' or 'off' to this file makes the kdamond starts or
stops, respectively. Reading the file returns the keywordsbased on the current status. Writing 'update_schemes_stats' tothe file updates contents of schemes stats files of thekdamond.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/pid +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Reading this file returns the pid of the kdamond if it is
running.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/nr_contexts +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a number 'N' to this file creates the number of
directories for controlling each DAMON context named '0' to'N-1' under the contexts/ directory.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/operations +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a keyword for a monitoring operations set ('vaddr' for
virtual address spaces monitoring, and 'paddr' for the physicaladdress space monitoring) to this file makes the context to usethe operations set. Reading the file returns the keyword forthe operations set the context is set to use.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/sample_us +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a value to this file sets the sampling interval of the
DAMON context in microseconds as the value. Reading this filereturns the value.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/aggr_us +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a value to this file sets the aggregation interval of
the DAMON context in microseconds as the value. Reading thisfile returns the value.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/intervals/update_us +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a value to this file sets the update interval of the
DAMON context in microseconds as the value. Reading this filereturns the value.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/min
+WDate: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a value to this file sets the minimum number of
monitoring regions of the DAMON context as the value. Readingthis file returns the value.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/monitoring_attrs/nr_regions/max +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a value to this file sets the maximum number of
monitoring regions of the DAMON context as the value. Readingthis file returns the value.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/nr_targets +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a number 'N' to this file creates the number of
directories for controlling each DAMON target of the contextnamed '0' to 'N-1' under the contexts/ directory.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/pid_target +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the pid of
the target process if the context is for virtual address spacesmonitoring, respectively.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/nr_regions +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a number 'N' to this file creates the number of
directories for setting each DAMON target memory region of thecontext named '0' to 'N-1' under the regions/ directory. Incase of the virtual address space monitoring, DAMONautomatically sets the target memory region based on the targetprocesses' mappings.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/start +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the start
address of the monitoring region.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/targets/<T>/regions/<R>/end +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the end
address of the monitoring region.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/nr_schemes +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing a number 'N' to this file creates the number of
directories for controlling each DAMON-based operation schemeof the context named '0' to 'N-1' under the schemes/ directory.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/action +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the action
of the scheme.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/min +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the mimimum
size of the scheme's target regions in bytes.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/sz/max +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the maximum
size of the scheme's target regions in bytes.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/min +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the manimum
'nr_accesses' of the scheme's target regions.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/nr_accesses/max +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the maximum
'nr_accesses' of the scheme's target regions.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/min +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the minimum
'age' of the scheme's target regions.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/access_pattern/age/max +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the maximum
'age' of the scheme's target regions.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/ms +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the time
quota of the scheme in milliseconds.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/bytes +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the size
quota of the scheme in bytes.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/reset_interval_ms +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the quotas
charge reset interval of the scheme in milliseconds.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/sz_permil +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the
under-quota limit regions prioritization weight for 'size' inpermil.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/nr_accesses_permil +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the
under-quota limit regions prioritization weight for'nr_accesses' in permil.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/quotas/weights/age_permil +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the
under-quota limit regions prioritization weight for 'age' inpermil.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/metric +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the metric
of the watermarks for the scheme. The writable/readablekeywords for this file are 'none' for disabling the watermarksfeature, or 'free_mem_rate' for the system's global free memoryrate in permil.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/interval_us +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the metric
check interval of the watermarks for the scheme inmicroseconds.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/high +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the high
watermark of the scheme in permil.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/mid +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the mid
watermark of the scheme in permil.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/watermarks/low +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Writing to and reading from this file sets and gets the low
watermark of the scheme in permil.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_tried +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Reading this file returns the number of regions that the action
of the scheme has tried to be applied.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_tried +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Reading this file returns the total size of regions that the
action of the scheme has tried to be applied in bytes.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/nr_applied +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Reading this file returns the number of regions that the action
of the scheme has successfully applied.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/sz_applied +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Reading this file returns the total size of regions that the
action of the scheme has successfully applied in bytes.+What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/stats/qt_exceeds +Date: Feb 2022 +Contact: SeongJae Park sj@kernel.org +Description: Reading this file returns the number of the exceed events of
the scheme's quotas.
Yes, this looks much better, thanks. But you might want to change the month as I doubt this will be merged in the next few days :)
thanks,
greg k-h