Skip to contentSkip to conversation

mm/damon/sysfs: document filters/ directory as deprecated

PATCH Applied SeongJae Park 2 participants 5 messages Apr 29 – Apr 30

Subsystems (4)
lore
Share & tools
lore

SeongJae Park

author maintainer
#0 lore raw

cover mm/damon/sysfs: document filters/ directory as deprecated

Commit ab71d2d30121 ("mm/damon/sysfs-schemes: let damon_sysfs_scheme_set_filters() be used for different named directories") introduced alternatives of 'filters' directory, namely core_filters/ and 'ops_filters/ directories. Now the alternatives are well stabilized and ready for all users. All filters/ directory use cases are expected to be able to be migrated to the alternatives. An LTS kernel having the alternatives, namely 6.18.y, is also released. Existence of filters/ directory is only confusing.

It would be better not immediately removing the directory, though. There could be users that need time before migrating to the alternatives. There might be unexpected use cases that the alternatives cannot support. Doing the deprecation step by step across multiple years like DAMON debugfs deprecation would be safer. Start the deprecation changes by announcing the deprecation on the documents.

Every year, one more action for completely removing the directory will be followed, like DAMON debugfs deprecation did. Following yearly actions are currently expected. In 2027, deprecation warning kernel messages will be printed once, for use of filters/ directory. In 2028, filters/ directory will be renamed to filters_DEPRECATED/. In 2029, filters_DEPRECATED/ directory will be removed.

Changes from RFC
- rfc: https://lore.kernel.org/[email protected]
- Wordsmith deprecation notice.
- Rebase to latest mm-new.

SeongJae Park (2):
Docs/admin-guide/mm/damon/usage: mark scheme filters sysfs dir as
deprecated
Docs/ABI/damon: mark schemes/<S>/filters/ deprecated

 .../ABI/testing/sysfs-kernel-mm-damon         | 62 ++++++++++---------
 Documentation/admin-guide/mm/damon/usage.rst  |  8 +--
 2 files changed, 38 insertions(+), 32 deletions(-)

base-commit: 97bd4e9ac10095f9b55f4a38d5d0757bc2a287fa

Signature · 1 line
2.47.3
author maintainer
#1 lore raw

PATCH 1/2 Docs/admin-guide/mm/damon/usage: mark scheme filters sysfs dir as deprecated

The alternatives of 'filters/' directory, namely 'core_filters/' and 'ops_filters/', can fully support all the features 'filters/' directory
can do, and provide better user experience. Having 'filters/'
directory is only confusing to users. Announce it as deprecated on the usage document.

---
 Documentation/admin-guide/mm/damon/usage.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/admin-guide/mm/damon/usage.rst +4 -4
index d5548e460857c..11c75a598393c 100644
@@ -485,10 +485,10 @@ directory can be used for installing filters regardless of their handled
 layers.  Filters that requested by ``core_filters`` and ``ops_filters`` will be
 installed before those of ``filters``.  All three directories have same files.
 
-Use of ``filters`` directory can make expecting evaluation orders of given
-filters with the files under directory bit confusing.  Users are hence
-recommended to use ``core_filters`` and ``ops_filters`` directories.  The
-``filters`` directory could be deprecated in future.
+Use of ``filters`` directory can make filters evaluation orders confusing to
+expect.  For this reason, ``filters`` directory is deprecated.  It is still
+functioning, but is scheduled for removal in the near future.  Users should use
+``core_filters`` and ``ops_filters`` directories instead.
 
 In the beginning, the directory has only one file, ``nr_filters``.  Writing a
 number (``N``) to the file creates the number of child directories named ``0``
Signature · 1 line
2.47.3
author maintainer
#2 lore raw

PATCH 2/2 Docs/ABI/damon: mark schemes/<S>/filters/ deprecated

In reply to SeongJae Park

Now the 'filters/' directory is deprecated. Update ABI document to also announce the fact. Also update the descriptions of the files to be based on 'core_filter/' directory, to make the old descriptions ready to be removed when the time arrives.

---
 .../ABI/testing/sysfs-kernel-mm-damon         | 62 ++++++++++---------
 1 file changed, 34 insertions(+), 28 deletions(-)
Documentation/ABI/testing/sysfs-kernel-mm-damon +34 -28
index 971c22e34e722..ee29d4e204ffa 100644
@@ -396,15 +396,20 @@ Contact:	SeongJae Park <[email protected]>
 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>/filters/nr_filters
-Date:		Dec 2022
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters
+Date:		Feb 2025
+Contact:	SeongJae Park <[email protected]>
+Description:	Directory for DAMON core layer-handled DAMOS filters.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/nr_filters
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	Writing a number 'N' to this file creates the number of
 		directories for setting filters of the scheme named '0' to
-		'N-1' under the filters/ directory.
+		'N-1' under the core_filters/ directory.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/type
-Date:		Dec 2022
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/type
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	Writing to and reading from this file sets and gets the type of
 		the memory of the interest.  'anon' for anonymous pages,
@@ -412,77 +417,78 @@ Description:	Writing to and reading from this file sets and gets the type of
 		'addr' for address range (an open-ended interval), or 'target'
 		for DAMON monitoring target can be written and read.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/memcg_path
-Date:		Dec 2022
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/memcg_path
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	If 'memcg' is written to the 'type' file, writing to and
 		reading from this file sets and gets the path to the memory
 		cgroup of the interest.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_start
-Date:		Jul 2023
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/addr_start
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	If 'addr' is written to the 'type' file, writing to or reading
 		from this file sets or gets the start address of the address
 		range for the filter.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/addr_end
-Date:		Jul 2023
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/addr_end
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	If 'addr' is written to the 'type' file, writing to or reading
 		from this file sets or gets the end address of the address
 		range for the filter.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/min
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/min
 Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	If 'hugepage_size' is written to the 'type' file, writing to
 		or reading from this file sets or gets the minimum size of the
 		hugepage for the filter.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/max
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/max
 Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	If 'hugepage_size' is written to the 'type' file, writing to
 		or reading from this file sets or gets the maximum size of the
 		hugepage for the filter.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/target_idx
-Date:		Dec 2022
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/target_idx
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	If 'target' is written to the 'type' file, writing to or
 		reading from this file sets or gets the index of the DAMON
 		monitoring target of the interest.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/matching
-Date:		Dec 2022
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/matching
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	Writing 'Y' or 'N' to this file sets whether the filter is for
 		the memory of the 'type', or all except the 'type'.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters/<F>/allow
-Date:		Jan 2025
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/<F>/allow
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	Writing 'Y' or 'N' to this file sets whether to allow or reject
 		applying the scheme's action to the memory that satisfies the
 		'type' and the 'matching' of the directory.
 
-What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters
-Date:		Feb 2025
-Contact:	SeongJae Park <[email protected]>
-Description:	Directory for DAMON core layer-handled DAMOS filters.  Files
-		under this directory works same to those of
-		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
-		directory.
-
 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/ops_filters
 Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	Directory for DAMON operations set layer-handled DAMOS filters.
 		Files under this directory works same to those of
-		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
+		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters
 		directory.
 
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
+Date:		Dec 2022
+Contact:	SeongJae Park <[email protected]>
+Description:	Directory for DAMOS filters.  Files under this directory works
+		same to those of
+		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/{core,ops}_filters
+		directory.  This is deprecated.  Use the core_filters and
+		ops_filters instead.
+
 What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/dests/nr_dests
 Date:		Jul 2025
 Contact:	SeongJae Park <[email protected]>
Signature · 1 line
2.47.3
#3 lore raw

Re: [PATCH 2/2] Docs/ABI/damon: mark schemes/<S>/filters/ deprecated

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [Low] Missing `What:` entries for files under the deprecated `filters/` and newly added `ops_filters/`…

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Missing What: entries for files under the deprecated filters/ and newly added ops_filters/ directories. --

commit d4b50ba450c215da3baec9d7d831c83147cf209c
Author: SeongJae Park <[email protected]>

Docs/ABI/damon: mark schemes/<S>/filters/ deprecated

This commit deprecates the filters/ directory in the DAMON sysfs interface and updates the ABI documentation to use the new core_filters/ path. It also adds documentation for the ops_filters/ and filters/ directories, noting they work the same as core_filters/.

Quoted 22 lines
Documentation/ABI/testing/sysfs-kernel-mm-damon +8 -3
index 2424237ebb10..b61a34b9b185 100644
@@ -377,15 +377,20 @@ Contact:	SeongJae Park <[email protected]>
 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>/filters/nr_filters
-Date:		Dec 2022
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters
+Date:		Feb 2025
+Contact:	SeongJae Park <[email protected]>
+Description:	Directory for DAMON core layer-handled DAMOS filters.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/nr_filters
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	Writing a number 'N' to this file creates the number of
 		directories for setting filters of the scheme named '0' to
-		'N-1' under the filters/ directory.
+		'N-1' under the core_filters/ directory.

[ ... ]

Quoted 7 lines

What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/ops_filters
Date: Feb 2025
Contact: SeongJae Park <[email protected]>
Description: Directory for DAMON operations set layer-handled DAMOS filters.

Documentation/ABI/testing/sysfs-kernel-mm-damon +1 -1
 		Files under this directory works same to those of
-		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
+		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters

Documentation/ABI/testing/sysfs-kernel-mm-damon Description: Writing to and reading from this file sets and gets the type of · line 490

Quoted 10 lines
Documentation/ABI/testing/sysfs-kernel-mm-damon +8 -0
 		directory.
 
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
+Date:		Dec 2022
+Contact:	SeongJae Park <[email protected]>
+Description:	Directory for DAMOS filters.  Files under this directory works
+		same to those of
+		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/{core,ops}_filters
+		directory.  This is deprecated.  Use the core_filters and
+		ops_filters instead.

Will automated ABI parsing tools like scripts/get_abi.pl be able to find the documentation for the individual files under the ops_filters/ and deprecated filters/ directories?

Since the What: lines earlier in the patch were renamed from filters/ to core_filters/, the old sysfs attributes and the new ops_filters/ attributes are no longer explicitly listed. These tools rely strictly on explicit What:
entries and ignore textual cross-references.

Should multiple What: lines be stacked above the shared descriptions so that the core_filters/, ops_filters/, and filters/ attributes are all correctly parsed?

Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=2
author maintainer
#4 lore raw

Re: [PATCH 2/2] Docs/ABI/damon: mark schemes/<S>/filters/ deprecated

Quoted 48 lines · On Wed, 29 Apr 2026 19:38:54 +0000 [email protected] wrote:

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] Missing What: entries for files under the deprecated filters/ and newly added ops_filters/ directories. --

commit d4b50ba450c215da3baec9d7d831c83147cf209c
Author: SeongJae Park <[email protected]>

Docs/ABI/damon: mark schemes/<S>/filters/ deprecated

This commit deprecates the filters/ directory in the DAMON sysfs interface and updates the ABI documentation to use the new core_filters/ path. It also adds documentation for the ops_filters/ and filters/ directories, noting they work the same as core_filters/.

Quoted 22 lines
Documentation/ABI/testing/sysfs-kernel-mm-damon +8 -3
index 2424237ebb10..b61a34b9b185 100644
@@ -377,15 +377,20 @@ Contact:	SeongJae Park <[email protected]>
 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>/filters/nr_filters
-Date:		Dec 2022
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters
+Date:		Feb 2025
+Contact:	SeongJae Park <[email protected]>
+Description:	Directory for DAMON core layer-handled DAMOS filters.
+
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters/nr_filters
+Date:		Feb 2025
 Contact:	SeongJae Park <[email protected]>
 Description:	Writing a number 'N' to this file creates the number of
 		directories for setting filters of the scheme named '0' to
-		'N-1' under the filters/ directory.
+		'N-1' under the core_filters/ directory.

[ ... ]

Quoted 9 lines

What: /sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/ops_filters
Date: Feb 2025
Contact: SeongJae Park <[email protected]>
Description: Directory for DAMON operations set layer-handled DAMOS filters.

Documentation/ABI/testing/sysfs-kernel-mm-damon +1 -1
 		Files under this directory works same to those of
-		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
+		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/core_filters
 		directory.
Quoted 12 lines

Documentation/ABI/testing/sysfs-kernel-mm-damon Description: Writing to and reading from this file sets and gets the type of · line 490

Quoted 8 lines
Documentation/ABI/testing/sysfs-kernel-mm-damon +8 -0
+What:		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/filters
+Date:		Dec 2022
+Contact:	SeongJae Park <[email protected]>
+Description:	Directory for DAMOS filters.  Files under this directory works
+		same to those of
+		/sys/kernel/mm/damon/admin/kdamonds/<K>/contexts/<C>/schemes/<S>/{core,ops}_filters
+		directory.  This is deprecated.  Use the core_filters and
+		ops_filters instead.

Will automated ABI parsing tools like scripts/get_abi.pl be able to find the documentation for the individual files under the ops_filters/ and deprecated filters/ directories?

Seems now the script is renamed to tools/docs/get_abi.py. And I'm not very faimilar with the script, but I confirmed at least 'get_abi.py validate' is not complaining anything about DAMON.

And this part was anyway like this before this patch.

Quoted 9 lines

Since the What: lines earlier in the patch were renamed from filters/ to core_filters/, the old sysfs attributes and the new ops_filters/ attributes are no longer explicitly listed. These tools rely strictly on explicit What:
entries and ignore textual cross-references.

Should multiple What: lines be stacked above the shared descriptions so that the core_filters/, ops_filters/, and filters/ attributes are all correctly parsed?

So I will revisit if some people start complaining.

Thanks,
SJ

[...]