Skip to contentSkip to conversation

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

RFC PATCH In review SeongJae Park 2 participants 5 messages Apr 21

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.

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  |  7 ++-
 2 files changed, 38 insertions(+), 31 deletions(-)

base-commit: 68f9cad2eca9a05a70ec47a90f2ae97aa2363a9c

Signature · 1 line
2.47.3
author maintainer
#1 lore raw

RFC 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 | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/admin-guide/mm/damon/usage.rst +4 -3
index d5548e460857c..918c14a8e852b 100644
@@ -486,9 +486,10 @@ 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.
+filters with the files under directory bit confusing.  For the reason,
+``filters`` directory is deprecated.  It is still functioning, but it will be
+broken and eventually removed in 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
#4 lore raw

RFC 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
#2 lore raw

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

In reply to SeongJae Park
Sashiko AI review found 1 potential issue(s): - [Low] Poor grammar and inappropriate terminology in the deprecation notice. --

Sashiko AI review found 1 potential issue(s):
- [Low] Poor grammar and inappropriate terminology in the deprecation notice. --

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

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

This commit updates the DAMON usage documentation to formally mark the sysfs 'filters/' directory as deprecated. It recommends users migrate to the 'core_filters/' and 'ops_filters/' directories instead.

Quoted 4 lines
Documentation/admin-guide/mm/damon/usage.rst +0 -0
index 534e1199cf091..4c222e956b100 100644

[ ... ]

Documentation/admin-guide/mm/damon/usage.rst layers. Filters that requested by ``core_filters`` and ``ops_filters`` will be · line 492

Quoted 8 lines

Use of ``filters`` directory can make expecting evaluation orders of given

Documentation/admin-guide/mm/damon/usage.rst +4 -3
-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.
+filters with the files under directory bit confusing.  For the reason,
+``filters`` directory is deprecated.  It is still functioning, but it will be
+broken and eventually removed in near future.  Users should use
+``core_filters`` and ``ops_filters`` directories instead.

This isn't a bug, but could the phrasing here be smoothed out a bit? There are a few awkward phrases like "make expecting evaluation orders" and "with the files under directory bit confusing".

Also, stating that a sysfs interface "will be broken" is generally avoided in kernel documentation. The standard convention is to say that an interface is "deprecated and scheduled for removal" to avoid implying that userspace will be intentionally broken.

Would a rewrite like this work better?

"Using the ``filters`` directory can make the evaluation order of filters confusing. For this reason, the ``filters`` directory is deprecated. It continues to function for now, but is scheduled for removal in the near future."

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

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

Quoted 36 lines · On Tue, 21 Apr 2026 05:04:13 +0000 [email protected] wrote:

Sashiko AI review found 1 potential issue(s):
- [Low] Poor grammar and inappropriate terminology in the deprecation notice. --

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

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

This commit updates the DAMON usage documentation to formally mark the sysfs 'filters/' directory as deprecated. It recommends users migrate to the 'core_filters/' and 'ops_filters/' directories instead.

Quoted 4 lines
Documentation/admin-guide/mm/damon/usage.rst +0 -0
index 534e1199cf091..4c222e956b100 100644

[ ... ]

Documentation/admin-guide/mm/damon/usage.rst layers. Filters that requested by ``core_filters`` and ``ops_filters`` will be · line 492

Quoted 8 lines

Use of ``filters`` directory can make expecting evaluation orders of given

Documentation/admin-guide/mm/damon/usage.rst +4 -3
-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.
+filters with the files under directory bit confusing.  For the reason,
+``filters`` directory is deprecated.  It is still functioning, but it will be
+broken and eventually removed in near future.  Users should use
+``core_filters`` and ``ops_filters`` directories instead.

This isn't a bug, but could the phrasing here be smoothed out a bit? There are a few awkward phrases like "make expecting evaluation orders" and "with the files under directory bit confusing".

Also, stating that a sysfs interface "will be broken" is generally avoided in kernel documentation. The standard convention is to say that an interface is "deprecated and scheduled for removal" to avoid implying that userspace will be intentionally broken.

Quoted 6 lines

Would a rewrite like this work better?

"Using the ``filters`` directory can make the evaluation order of filters confusing. For this reason, the ``filters`` directory is deprecated. It continues to function for now, but is scheduled for removal in the near future."

Nice suggestion. I will apply that suggestion.

Thanks,
SJ

[...]