[RFC PATCH 0/7] mm/damon: introduce damos quota goal target metric complement flag

[SJ Park]

Aim-oriented DAMOS quota auto-tuning assumes the aggressiveness of the
scheme (quota) and the quota goal metric are directly proportional.
Depending on the scheme setup and usage, keeping the relationship can be
challenging.

For example, let's suppose a memory tiering approach for higher upper
tier utilization. One common idea for that (TPP) is utilizing two
schemes, one for promotion and the other one for demotion. The
promotion scheme migrates hot pages from lower tier to upper tier,
aiming for high utilization of the upper tier. The demotion scheme
migrates cold pages from upper tier to lower tier, aiming for head room
free memory of the upper tier. Both schemes and their goals are in
direct proportion. However, for this kind of use case, we need to
implement two different goal metrics (per-node memory utilization and
free memory ratio) while essentially the free memory ratio is just a
complemented value of the utilization.

To avoid adding too many new metrics, we are adding metrics that turn
out to be really needed for each found use case. For example,
some_mem_psi_us, node_eligible_mem_bp and hugepage_mem_bp don't have
their complemented value version. But it is not really difficult to
expect use cases that their complemented version can be useful. For
example, hugepage_mem_bp use case may need a way to reduce the hugepage
ratio. That would require a complemented version of hugepage_mem_bp.
Adding a new metric for each of such use cases could make the number of
metrics unnecessarily high, and discourage flexible usages of DAMOS.

Add a new flag, quota goal complement, to allow flexible tuning goal
setup without unnecessarily increasing the number of metrics. The flag
specifies whether to use the complemented value of the given goal metric
for the tuning. For example, if the complement flag is set, the upper
tier memory utilization ratio metric works the same as the free memory
ratio metric for the tier.

SJ Park (7):
mm/damon/core: introduce damos_quota_goal->complement
mm/damon: add complement argument to damos_new_quota_goal()
mm/damon/sysfs-schemes: support quota goal complement flag
mm/damon/tests/core-kunit: test quota_goal->complement commit
Docs/mm/damon/design: document damos quota goal complement flag
Docs/admin-guide/mm/damon/usage: update for quota goal complement file
Docs/ABI/damon: update for quota goal metric complement sysfs file

.../ABI/testing/sysfs-kernel-mm-damon | 6 ++++
Documentation/admin-guide/mm/damon/usage.rst | 13 ++++----
Documentation/mm/damon/design.rst | 13 +++++---
include/linux/damon.h | 4 ++-
mm/damon/core.c | 21 +++++++++++--
mm/damon/lru_sort.c | 5 ++--
mm/damon/reclaim.c | 5 ++--
mm/damon/sysfs-schemes.c | 30 +++++++++++++++++++
mm/damon/tests/core-kunit.h | 4 ++-
samples/damon/mtier.c | 2 +-
10 files changed, 83 insertions(+), 20 deletions(-)


base-commit: 93d2baf86ca2a321306c5ea2f07e3d936cc4e6fa
--
2.47.3

[SJ Park]

Extend existing DAMOS quota goal commit unit test to test the complement
flag. Set the source complement flag and confirm the destination is
updated to the given input.

Signed-off-by: SJ Park <s...@kernel.org>
---
mm/damon/tests/core-kunit.h | 2 ++
1 file changed, 2 insertions(+)

diff --git a/mm/damon/tests/core-kunit.h b/mm/damon/tests/core-kunit.h
index e8290a2c6f343..a2504e96954f7 100644
--- a/mm/damon/tests/core-kunit.h
+++ b/mm/damon/tests/core-kunit.h
@@ -819,6 +819,7 @@ static void damos_test_commit_quota_goal_for(struct kunit *test,
damos_commit_quota_goal(dst, src);

KUNIT_EXPECT_EQ(test, dst->metric, src->metric);
+ KUNIT_EXPECT_EQ(test, dst->complement, src->complement);
KUNIT_EXPECT_EQ(test, dst->target_value, src->target_value);
if (src->metric == DAMOS_QUOTA_USER_INPUT)
KUNIT_EXPECT_EQ(test, dst->current_value, src->current_value);
@@ -862,6 +863,7 @@ static void damos_test_commit_quota_goal(struct kunit *test)
damos_test_commit_quota_goal_for(test, &dst,
&(struct damos_quota_goal){
.metric = DAMOS_QUOTA_USER_INPUT,
+ .complement = true,
.target_value = 789,
.current_value = 12});
damos_test_commit_quota_goal_for(test, &dst,
--
2.47.3

[SJ Park]

Changes from RFC
- RFC: https://lore.kernel.org/202609181428...@kernel.org
- Avoid quota goal value underflow.
- Fix usage doc for number of files in each goal directory.
- Rebase to the latest mm-new.

SJ Park (7):
mm/damon/core: introduce damos_quota_goal->complement
mm/damon: add complement argument to damos_new_quota_goal()
mm/damon/sysfs-schemes: support quota goal complement flag
mm/damon/tests/core-kunit: test quota_goal->complement commit
Docs/mm/damon/design: document damos quota goal complement flag
Docs/admin-guide/mm/damon/usage: update for quota goal complement file
Docs/ABI/damon: update for quota goal metric complement sysfs file

.../ABI/testing/sysfs-kernel-mm-damon | 6 ++++

Documentation/admin-guide/mm/damon/usage.rst | 15 +++++-----

Documentation/mm/damon/design.rst | 13 +++++---
include/linux/damon.h | 4 ++-

mm/damon/core.c | 25 ++++++++++++++--

mm/damon/lru_sort.c | 5 ++--
mm/damon/reclaim.c | 5 ++--
mm/damon/sysfs-schemes.c | 30 +++++++++++++++++++
mm/damon/tests/core-kunit.h | 4 ++-
samples/damon/mtier.c | 2 +-

10 files changed, 88 insertions(+), 21 deletions(-)


base-commit: 026f1215e57024b54116f6388ca96c64ff84f44d
--
2.47.3

[SJ Park]

[SJ Park]

Changes from RFC v2
- RFC v2: https://lore.kernel.org/202609190113...@kernel.org
- Avoid quota goal value underflow for some_mem_psi.
- Handle complement flag for psi goal with unset last_psi_total.
- Pass complement argument to damos_new_quota_goal() from core and
core-kunit.
- Explicitly document no-op complement behavior for user_input.

Changes from RFC
- RFC: https://lore.kernel.org/202609181428...@kernel.org
- Avoid quota goal value underflow.
- Fix usage doc for number of files in each goal directory.
- Rebase to the latest mm-new.

SJ Park (7):
mm/damon/core: introduce damos_quota_goal->complement

mm/damon/core: add complement argument to damos_new_quota_goal()

mm/damon/sysfs-schemes: support quota goal complement flag
mm/damon/tests/core-kunit: test quota_goal->complement commit
Docs/mm/damon/design: document damos quota goal complement flag
Docs/admin-guide/mm/damon/usage: update for quota goal complement file
Docs/ABI/damon: update for quota goal metric complement sysfs file

.../ABI/testing/sysfs-kernel-mm-damon | 6 ++++
Documentation/admin-guide/mm/damon/usage.rst | 15 +++++----

Documentation/mm/damon/design.rst | 15 ++++++---
include/linux/damon.h | 4 ++-
mm/damon/core.c | 33 ++++++++++++++++---
mm/damon/lru_sort.c | 5 +--
mm/damon/reclaim.c | 5 +--
mm/damon/sysfs-schemes.c | 30 +++++++++++++++++
mm/damon/tests/core-kunit.h | 3 ++
samples/damon/mtier.c | 2 +-
10 files changed, 97 insertions(+), 21 deletions(-)


base-commit: 976311048bbb3a9e455552281fb9927fe6e8f091
--
2.47.3

[SJ Park]

Extend existing DAMOS quota goal commit unit test to test the complement
flag. Set the source complement flag and confirm the destination is
updated to the given input.

Signed-off-by: SJ Park <s...@kernel.org>
---
mm/damon/tests/core-kunit.h | 2 ++
1 file changed, 2 insertions(+)

diff --git a/mm/damon/tests/core-kunit.h b/mm/damon/tests/core-kunit.h

index 72dfb9c595a4..ce15e693bc0e 100644

[SJ Park]

Patches Sequence
================

Patch 1 introduces the quota goal complement flag API and implements its
behavior. Patch 2 updates damos_new_quota_goal() to receive the flag.
Patch 3 update DAMON sysfs interface to support the complement flag.
Patches 4 and 5 extend existing kunit and kselftest to cover the new
flag. Patches 6-8 update design, usage and ABI documents for the new
feature.

Note: Below is additional information that is not intended to be added
to the final commit message.

Test
====

I tested this feature using the latest version of DAMON user-space tool,
damo [1], as below.

On an idle system having 10 GiB single node memory (node id 0), fill up
80% of memory with page cache.

$ dd if=/dev/zero of=foo bs=1M count=$((1024*8))

Run DAMOS with pageout action for 80% of free memory, but using
node_mem_used_bp metric like below.

$ sudo ./damo start --damos_action pageout \
--damos_quota_space 100M --damos_quota_interval 1s \
--damos_quota_fail_charge_ratio 1 4096 \
--damos_quota_goal_tuner temporal \
--damos_quota_goal node_mem_used_bp 20% 0

Because the system has more than 20% node 0 memory utilization, DAMOS
does nothing, as expected.

Run DAMOS with pageout action for 80% of free memory, using
node_mem_used_bp metrics with complement flag like below.

$ sudo ./damo start --damos_action pageout \
--damos_quota_space 100M --damos_quota_interval 1s \
--damos_quota_fail_charge_ratio 1 4096 \
--damos_quota_goal_tuner temporal \
--damos_quota_goal node_mem_used_bp 80% complement 0

Because the complement flag is given, it is effectively the same as
node_mem_freepbp metrics with a target of 80%. DAMOS reclaims the page
cache ~100 MiB per second, until the free memory ratio (complemented
memory utilization ratio) reaches the goal, 80%.

Changes from RFC v4
- RFC v4: https://lore.kernel.org/202609271205...@kernel.org
- Fix a typo in test code (s/complementfalse/complement/).
- Extend sysfs.sh DAMON selftest for complement flag sysfs file.
Changes from RFC v3
- RFC v3: https://lore.kernel.org/202609231014...@kernel.org

- Rebase to the latest mm-new.

- Add tests done to the cover letter.

Changes from RFC v2
- RFC v2: https://lore.kernel.org/202609190113...@kernel.org
- Avoid quota goal value underflow for some_mem_psi.
- Handle complement flag for psi goal with unset last_psi_total.
- Pass complement argument to damos_new_quota_goal() from core and
core-kunit.
- Explicitly document no-op complement behavior for user_input.
Changes from RFC
- RFC: https://lore.kernel.org/202609181428...@kernel.org
- Avoid quota goal value underflow.
- Fix usage doc for number of files in each goal directory.
- Rebase to the latest mm-new.

[1] https://github.com/damonitor/damo

SJ Park (8):

mm/damon/core: introduce damos_quota_goal->complement
mm/damon/core: add complement argument to damos_new_quota_goal()
mm/damon/sysfs-schemes: support quota goal complement flag
mm/damon/tests/core-kunit: test quota_goal->complement commit

selftests/damon/sysfs.sh: test quota goal complement flag file

Docs/mm/damon/design: document damos quota goal complement flag
Docs/admin-guide/mm/damon/usage: update for quota goal complement file
Docs/ABI/damon: update for quota goal metric complement sysfs file

.../ABI/testing/sysfs-kernel-mm-damon | 6 ++++
Documentation/admin-guide/mm/damon/usage.rst | 15 +++++----
Documentation/mm/damon/design.rst | 15 ++++++---
include/linux/damon.h | 4 ++-
mm/damon/core.c | 33 ++++++++++++++++---
mm/damon/lru_sort.c | 5 +--
mm/damon/reclaim.c | 5 +--
mm/damon/sysfs-schemes.c | 30 +++++++++++++++++
mm/damon/tests/core-kunit.h | 3 ++
samples/damon/mtier.c | 2 +-

tools/testing/selftests/damon/sysfs.sh | 3 ++
11 files changed, 100 insertions(+), 21 deletions(-)


base-commit: f3528689602b1d578d582cb060e89fa25516fd67
--
2.47.3

[SJ Park]

Extend existing DAMOS quota goal commit unit test to test the complement
flag. Set the source complement flag and confirm the destination is
updated to the given input.

Signed-off-by: SJ Park <s...@kernel.org>
---
mm/damon/tests/core-kunit.h | 2 ++
1 file changed, 2 insertions(+)

diff --git a/mm/damon/tests/core-kunit.h b/mm/damon/tests/core-kunit.h

index 945037fe4be9..251b300eaa50 100644

[SJ Park]

Changes from RFC v5
- RFC v5: https://lore.kernel.org/202609280933...@kernel.org
- Rebase to latest mm-new.
- Drop RFC tag.

mm/damon/tests/core-kunit.h | 5 ++-

samples/damon/mtier.c | 2 +-
tools/testing/selftests/damon/sysfs.sh | 3 ++

11 files changed, 101 insertions(+), 22 deletions(-)


base-commit: af86bf5500fcc53d591e1000e6e08dec1227fb06
--
2.47.3

[SJ Park]

Extend existing DAMOS quota goal commit unit test to test the complement
flag. Set the source complement flag and confirm the destination is
updated to the given input.

Signed-off-by: SJ Park <s...@kernel.org>
---
mm/damon/tests/core-kunit.h | 2 ++
1 file changed, 2 insertions(+)

diff --git a/mm/damon/tests/core-kunit.h b/mm/damon/tests/core-kunit.h

index 5a924edb171f..ef146ca2ae8a 100644
--- a/mm/damon/tests/core-kunit.h
+++ b/mm/damon/tests/core-kunit.h
@@ -861,6 +861,7 @@ static void damos_test_commit_quota_goal_for(struct kunit *test,

damos_commit_quota_goal(dst, src);

KUNIT_EXPECT_EQ(test, dst->metric, src->metric);
+ KUNIT_EXPECT_EQ(test, dst->complement, src->complement);
KUNIT_EXPECT_EQ(test, dst->target_value, src->target_value);
if (src->metric == DAMOS_QUOTA_USER_INPUT)
KUNIT_EXPECT_EQ(test, dst->current_value, src->current_value);

@@ -904,6 +905,7 @@ static void damos_test_commit_quota_goal(struct kunit *test)

[SJ Park]

On Tue, 29 Sep 2026 01:01:03 -0700 SJ Park <s...@kernel.org> wrote:
[...]

> Add a new flag, quota goal complement, to allow flexible tuning goal
> setup without unnecessarily increasing the number of metrics. The flag
> specifies whether to use the complemented value of the given goal metric
> for the tuning. For example, if the complement flag is set, the upper
> tier memory utilization ratio metric works the same as the free memory
> ratio metric for the tier.

Sashiko found no blocker for this series. Sashiko sends its findings to damon@
mailing list [1], and I reply those if anything needs to be clarified. Please
refer to those for details.

[1] https://lore.kernel.org/damon/


Thanks,
SJ

[...]