[RFC PATCH v1 0/4] mm/damon: Introduce a huge page collapsing mechanism using auto tuning

[RFC PATCH v1 0/4] mm/damon: Introduce a huge page collapsing mechanism using auto tuning

[gutierrez.asier]

From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>

Overview
================

This patch set introduces a new autotuning which allows to collapse
hot regions into hugepages.

Motivation
================

Since TLB is a bottleneck for many systems, a way to optimize TLB
misses (or hits) is to use huge pages. Unfortunately, using "always"
in THP leads to memory fragmentation and memory waste. For this reason,
most application guides and system administrators suggest to disable THP.

Solution
================

A new autotuning quota goal[1], damos_get_used_hugepage_mem_bp, is
introduced, which checks the huge page consumption to total anonymous
memory consumption. This new quota mechanism reuses current autotuning
architecture.

A new module is introduced to demonstrate the use of huge pages
collapse autotuning. The module launches a kdamond thread for a 
certain task provided by the user through monitored_pid module argument.

This module also has a user autotuning knob which allows the user to
adjust the aggressiveness of page collapsing.

Benchmarks
================
In progress, will add them in the next RFC series.

TODO
================

- Since DAMOS_COLLAPSE is not in upstream and this is just a
  RFC, I have used DAMOS_HUGEPAGE instead. This will change
  to DAMOS_COLLAPSE in future series.

Patches Sequence
================
Patch 1 -> damon_modules_new_vaddr_ctx_target
Patch 2 -> Introduce DAMOS_QUOTA_HUGEPAGE and autotuning
Patch 3 -> Module that demonstrates how to use DAMOS_QUOTA_HUGEPAGE
           and the new VADDR ctx creation
Patch 4 -> Documentation

[1] https://lore.kernel.org/e67f05ad-dbb9-45e6-ba30-b167a99ac67d@huawei-partners.com

 .../admin-guide/mm/damon/hugepage.rst (new)   | 258 +++++++++++++
 Documentation/admin-guide/mm/damon/index.rst  |   1 +
 include/linux/damon.h                         |   1 +
 mm/damon/Kconfig                              |   7 +
 mm/damon/Makefile                             |   1 +
 mm/damon/core.c                               |  15 +
 mm/damon/hugepage.c (new)                     | 341 ++++++++++++++++++
 mm/damon/modules-common.c                     |  33 +-
 mm/damon/modules-common.h                     |   3 +
 9 files changed, 652 insertions(+), 8 deletions(-)
 create mode 100644 Documentation/admin-guide/mm/damon/hugepage.rst
 create mode 100644 mm/damon/hugepage.c

-- 
2.43.0

[RFC PATCH v1 1/4] mm/damon: Generalize ctx_target creation for damon_ops_id and add vaddr support

[gutierrez.asier]

From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>

This patch adds a new function damon_modules_new_vaddr_ctx_target.
Since ctx_target creation for vaddr and  paddr is almost identical,
the logic is extracted to a new function,
damon_modules_new_ctx_target, and vaddr and paddr functions are
left just as interfaces.

This change was suggested earlier1 and it is needed to allow
developers to create DAMON modules that use DAMON_OPS_VADDR targets.

Signed-off-by: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
Suggested-by: SeongJae Park <sj@kernel.org>
---
 mm/damon/modules-common.c | 33 +++++++++++++++++++++++++--------
 mm/damon/modules-common.h |  3 +++
 2 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/mm/damon/modules-common.c b/mm/damon/modules-common.c
index 86d58f8c4f63..35a4a89b6caa 100644
--- a/mm/damon/modules-common.c
+++ b/mm/damon/modules-common.c
@@ -9,13 +9,8 @@
 
 #include "modules-common.h"
 
-/*
- * Allocate, set, and return a DAMON context for the physical address space.
- * @ctxp:	Pointer to save the point to the newly created context
- * @targetp:	Pointer to save the point to the newly created target
- */
-int damon_modules_new_paddr_ctx_target(struct damon_ctx **ctxp,
-		struct damon_target **targetp)
+static int _damon_modules_new_ctx_target(struct damon_ctx **ctxp,
+		struct damon_target **targetp, enum damon_ops_id id)
 {
 	struct damon_ctx *ctx;
 	struct damon_target *target;
@@ -24,7 +19,7 @@ int damon_modules_new_paddr_ctx_target(struct damon_ctx **ctxp,
 	if (!ctx)
 		return -ENOMEM;
 
-	if (damon_select_ops(ctx, DAMON_OPS_PADDR)) {
+	if (damon_select_ops(ctx, id)) {
 		damon_destroy_ctx(ctx);
 		return -EINVAL;
 	}
@@ -40,3 +35,25 @@ int damon_modules_new_paddr_ctx_target(struct damon_ctx **ctxp,
 	*targetp = target;
 	return 0;
 }
+
+/*
+ * Allocate, set, and return a DAMON context for the physical address space.
+ * @ctxp:	Pointer to save the point to the newly created context
+ * @targetp:	Pointer to save the point to the newly created target
+ */
+int damon_modules_new_paddr_ctx_target(struct damon_ctx **ctxp,
+		struct damon_target **targetp)
+{
+	return _damon_modules_new_ctx_target(ctxp, targetp, DAMON_OPS_PADDR);
+}
+
+/*
+ * Allocate, set, and return a DAMON context for the virtual address space.
+ * @ctxp:	Pointer to save the point to the newly created context
+ * @targetp:	Pointer to save the point to the newly created target
+ */
+int damon_modules_new_vaddr_ctx_target(struct damon_ctx **ctxp,
+		struct damon_target **targetp)
+{
+	return _damon_modules_new_ctx_target(ctxp, targetp, DAMON_OPS_VADDR);
+}
diff --git a/mm/damon/modules-common.h b/mm/damon/modules-common.h
index f103ad556368..324b9cb4957e 100644
--- a/mm/damon/modules-common.h
+++ b/mm/damon/modules-common.h
@@ -47,3 +47,6 @@
 
 int damon_modules_new_paddr_ctx_target(struct damon_ctx **ctxp,
 		struct damon_target **targetp);
+
+int damon_modules_new_vaddr_ctx_target(struct damon_ctx **ctxp,
+		struct damon_target **targetp);
-- 
2.43.0

[RFC PATCH v1 2/4] mm/damon: Introduce DAMOS_QUOTA_HUGEPAGE auto tuning

[gutierrez.asier]

From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>

Introduce DAMOS_QUOTA_HUGEPAGE auto tuning Add a new DAMOS quota goal
metric to measure the amount of huge page consumption to total anonymous
memory consumption ratio.

Signed-off-by: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
---
 include/linux/damon.h |  1 +
 mm/damon/core.c       | 15 +++++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/include/linux/damon.h b/include/linux/damon.h
index f2cdb7c3f5e6..97201e9fa407 100644
--- a/include/linux/damon.h
+++ b/include/linux/damon.h
@@ -172,6 +172,7 @@ enum damos_quota_goal_metric {
 	DAMOS_QUOTA_NODE_MEMCG_FREE_BP,
 	DAMOS_QUOTA_ACTIVE_MEM_BP,
 	DAMOS_QUOTA_INACTIVE_MEM_BP,
+	DAMOS_QUOTA_HUGEPAGE,
 	NR_DAMOS_QUOTA_GOAL_METRICS,
 };
 
diff --git a/mm/damon/core.c b/mm/damon/core.c
index 3dbbbfdeff71..06547e590ff2 100644
--- a/mm/damon/core.c
+++ b/mm/damon/core.c
@@ -2319,6 +2319,18 @@ static unsigned int damos_get_in_active_mem_bp(bool active_ratio)
 	return mult_frac(inactive, 10000, total);
 }
 
+/*
+ * Returns anon hugepage memory to total anon memory use ratio.
+ */
+static unsigned int damos_get_used_hugepage_mem_bp(void)
+{
+	unsigned long used_hugepages, total_used;
+ 
+	used_hugepages = global_node_page_state(NR_ANON_THPS);
+	total_used = global_node_page_state(NR_ANON_MAPPED);
+	return mult_frac(used_hugepages, 10000, total_used);
+}
+ 
 static void damos_set_quota_goal_current_value(struct damos_quota_goal *goal)
 {
 	u64 now_psi_total;
@@ -2345,6 +2357,9 @@ static void damos_set_quota_goal_current_value(struct damos_quota_goal *goal)
 		goal->current_value = damos_get_in_active_mem_bp(
 				goal->metric == DAMOS_QUOTA_ACTIVE_MEM_BP);
 		break;
+	case DAMOS_QUOTA_HUGEPAGE:
+		goal->current_value = damos_get_used_hugepage_mem_bp();
+		break;
 	default:
 		break;
 	}
-- 
2.43.0

[RFC PATCH v1 3/4] mm/damon: introduce DAMON_HUGEPAGE for hot region hugepage collapsing

[gutierrez.asier]

From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>

This patch introduces a new DAMON module (DAMON_HUGEPAGE)
which collapses hot regions into huge pages.

DAMON_HUGEPAGE operates in the virtual memory space, for a
specific task. The user is expected to supply the PID of
the task that is going to be monitored through the
monitored_pid module variable.

DAMON_HUGEPAGE uses the hugepage auto-tune mechanism to
increase or decrease the aggressiveness of page collapsing.
User autotuning is also available for additional tuning
aggressiveness control.

The module also includes changes to the DAMON compilation,
so that the module can be enabled or disabled.

Signed-off-by: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
---
 mm/damon/Kconfig          |   7 +
 mm/damon/Makefile         |   1 +
 mm/damon/hugepage.c (new) | 341 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 349 insertions(+)

diff --git a/mm/damon/Kconfig b/mm/damon/Kconfig
index 34631a44cdec..b615407cc13f 100644
--- a/mm/damon/Kconfig
+++ b/mm/damon/Kconfig
@@ -121,4 +121,11 @@ config DAMON_STAT_ENABLED_DEFAULT
 	  Whether to enable DAMON_STAT by default.  Users can disable it in
 	  boot or runtime using its 'enabled' parameter.
 
+config DAMON_HUGEPAGE
+	bool "Build DAMON-based collapse of hot regions (DAMON_HUGEPAGES)"
+	depends on DAMON_VADDR
+	help
+	 Collapse hot region into huge pages. Hot regions are determined by
+	 DAMON-based sampling
+
 endmenu
diff --git a/mm/damon/Makefile b/mm/damon/Makefile
index d8d6bf5f8bff..7cb55cc483f9 100644
--- a/mm/damon/Makefile
+++ b/mm/damon/Makefile
@@ -7,3 +7,4 @@ obj-$(CONFIG_DAMON_SYSFS)	+= sysfs-common.o sysfs-schemes.o sysfs.o
 obj-$(CONFIG_DAMON_RECLAIM)	+= modules-common.o reclaim.o
 obj-$(CONFIG_DAMON_LRU_SORT)	+= modules-common.o lru_sort.o
 obj-$(CONFIG_DAMON_STAT)	+= modules-common.o stat.o
+obj-$(CONFIG_DAMON_HUGEPAGE)	+= modules-common.o hugepage.o
diff --git a/mm/damon/hugepage.c b/mm/damon/hugepage.c
new file mode 100644
index 000000000000..02729736dc56
--- /dev/null
+++ b/mm/damon/hugepage.c
@@ -0,0 +1,341 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * Copyright (C) 2026 HUAWEI, Inc.
+ *             https://www.huawei.com
+ *
+ * Author: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
+ */
+
+#define pr_fmt(fmt) "damon-hugepage: " fmt
+
+#include <linux/damon.h>
+#include <linux/kstrtox.h>
+#include <linux/module.h>
+
+#include "modules-common.h"
+
+#ifdef MODULE_PARAM_PREFIX
+#undef MODULE_PARAM_PREFIX
+#endif
+#define MODULE_PARAM_PREFIX "damon_hugepage."
+
+/*
+ * Enable or disable DAMON_HUGEPAGE.
+ *
+ * You can enable DAMON_HUGEPAGE by setting the value of this parameter
+ * as ``Y``. Setting it as ``N`` disables DAMON_HUGEPAGE.
+ */
+static bool enabled __read_mostly;
+
+/*
+ * Make DAMON_HUGEPAGE reads the input parameters again, except ``enabled``.
+ *
+ * Input parameters that updated while DAMON_HUGEPAGE is running are not applied
+ * by default.  Once this parameter is set as ``Y``, DAMON_HUGEPAGE reads values
+ * of parametrs except ``enabled`` again.  Once the re-reading is done, this
+ * parameter is set as ``N``.  If invalid parameters are found while the
+ * re-reading, DAMON_HUGEPAGE will be disabled.
+ */
+static bool commit_inputs __read_mostly;
+module_param(commit_inputs, bool, 0600);
+
+/*
+ * Scale factor for DAMON_HUGEPAGE to ops address conversion.
+ *
+ * This parameter must not be set to 0.
+ */
+static unsigned long addr_unit __read_mostly = 1;
+
+static long monitored_pid;
+module_param(monitored_pid, ulong, 0600);
+
+/*
+ * Time threshold for hot memory regions identification in microseconds.
+ *
+ * If a memory region has been accessed for this or longer time,
+ * DAMON_HUGEPAGE identifies the region as hot, and collapse it into a huge
+ * page.  100 microseconds by default.
+ */
+static unsigned long min_age __read_mostly = 100000;
+module_param(min_age, ulong, 0600);
+
+static struct damos_quota damon_hugepage_quota = {
+	/* use up to 10 ms time, collapse up to 128 MiB per 1 sec by default */
+	.ms = 10,
+	.sz = 128 * 1024 * 1024,
+	.reset_interval = 1000,
+	.weight_sz = 0,
+	.weight_nr_accesses = 1,
+	.weight_age = 1
+};
+DEFINE_DAMON_MODULES_DAMOS_QUOTAS(damon_hugepage_quota);
+
+
+/*
+ * Desired ratio of huge pages use vs total anonymous memory usage.
+ *
+ * While keeping the caps that set by other quotas, DAMON_HUGEPAGE automatically
+ * increases and decreases the effective level of the quota to achieve the
+ * desired ratio.
+ *
+ * 100 bp by default.
+ */
+static unsigned long quota_percentage_hugepage __read_mostly = 100;
+module_param(quota_percentage_hugepage, ulong, 0600);
+
+/*
+ * User-specifiable feedback for auto-tuning of the effective quota.
+ *
+ * While keeping the caps that set by other quotas, DAMON_HUGEPAGE automatically
+ * increases and decreases the effective level of the quota aiming receiving this
+ * feedback of value ``10,000`` from the user.  DAMON_HUGEPAGE assumes the feedback
+ * value and the quota are positively proportional.  Value zero means disabling
+ * this auto-tuning feature.
+ *
+ * Disabled by default.
+ *
+ */
+static unsigned long quota_autotune_feedback __read_mostly;
+module_param(quota_autotune_feedback, ulong, 0600);
+
+/*
+ * PID of the DAMON thread
+ *
+ * If DAMON_HUGEPAGE is enabled, this becomes the PID of the worker thread.
+ * Else, -1.
+ */
+static int kdamond_pid __read_mostly = -1;
+module_param(kdamond_pid, int, 0400);
+
+static struct damos_stat damon_hugepage_stat;
+DEFINE_DAMON_MODULES_DAMOS_STATS_PARAMS(damon_hugepage_stat,
+		hugepage_tried_regions, hugepage_regions, quota_exceeds);
+
+static struct damon_attrs damon_hugepage_mon_attrs = {
+	.sample_interval = 5 * USEC_PER_MSEC,
+	.aggr_interval = 100 * USEC_PER_MSEC,
+	.ops_update_interval = 60 * USEC_PER_MSEC * MSEC_PER_SEC,
+	.min_nr_regions = 10,
+	.max_nr_regions = 1000,
+};
+DEFINE_DAMON_MODULES_MON_ATTRS_PARAMS(damon_hugepage_mon_attrs);
+
+static struct damon_ctx *ctx;
+static struct damon_target *target;
+
+static struct damos *damon_hugepage_new_scheme(void)
+{
+	struct damos_access_pattern pattern = {
+		/* Find regions having PMD_SIZE or larger size */
+		.min_sz_region = PMD_SIZE,
+		.max_sz_region = ULONG_MAX,
+		.min_nr_accesses = 0,
+		.max_nr_accesses = UINT_MAX,
+		.min_age_region = min_age /
+			damon_hugepage_mon_attrs.aggr_interval,
+		.max_age_region = UINT_MAX,
+	};
+
+	return damon_new_scheme(
+		&pattern,
+		/* synchrounous partial collapse as soon as found */
+		DAMOS_HUGEPAGE, 0,
+		/* under the quota. */
+		&damon_hugepage_quota,
+		&(struct damos_watermarks){}, NUMA_NO_NODE);
+}
+
+static int damon_hugepage_apply_parameters(void)
+{
+	struct damon_ctx *param_ctx;
+	struct damon_target *param_target;
+	struct damos *scheme;
+	struct damos_quota_goal *goal;
+	struct pid *spid;
+	int err;
+
+	err = damon_modules_new_vaddr_ctx_target(&param_ctx, &param_target);
+	if (err)
+		return err;
+
+	param_ctx->addr_unit = addr_unit;
+	param_ctx->min_region_sz = max(DAMON_MIN_REGION_SZ / addr_unit, 1);
+
+	spid = find_get_pid(monitored_pid);
+	if (!spid)
+		goto out;
+
+	param_target->pid = spid;
+
+	if (!damon_hugepage_mon_attrs.aggr_interval) {
+		err = -EINVAL;
+		goto out;
+	}
+
+	err = damon_set_attrs(param_ctx, &damon_hugepage_mon_attrs);
+	if (err)
+		goto out;
+
+	err = -ENOMEM;
+	scheme = damon_hugepage_new_scheme();
+	if (!scheme)
+		goto out;
+	damon_set_schemes(param_ctx, &scheme, 1);
+
+	goal = damos_new_quota_goal(DAMOS_QUOTA_HUGEPAGE, quota_percentage_hugepage);
+	if (!goal)
+		goto out;
+	damos_add_quota_goal(&scheme->quota, goal);
+
+	if (quota_autotune_feedback) {
+		goal = damos_new_quota_goal(DAMOS_QUOTA_USER_INPUT, 10000);
+		if (!goal)
+			goto out;
+		goal->current_value = quota_autotune_feedback;
+		damos_add_quota_goal(&scheme->quota, goal);
+	}
+
+	err = damon_commit_ctx(ctx, param_ctx);
+out:
+	damon_destroy_ctx(param_ctx);
+	return err;
+}
+
+static int damon_hugepage_handle_commit_inputs(void)
+{
+	int err;
+
+	if (!commit_inputs)
+		return 0;
+
+	err = damon_hugepage_apply_parameters();
+	commit_inputs = false;
+	return err;
+}
+
+static int damon_hugepage_damon_call_fn(void *arg)
+{
+	struct damon_ctx *c = arg;
+	struct damos *s;
+
+	/* update the stats parameter */
+	damon_for_each_scheme(s, c)
+		damon_hugepage_stat = s->stat;
+
+	return damon_hugepage_handle_commit_inputs();
+}
+
+static struct damon_call_control call_control = {
+	.fn = damon_hugepage_damon_call_fn,
+	.repeat = true,
+};
+
+static int damon_hugepage_turn(bool on)
+{
+	int err;
+
+	if (!on) {
+		err = damon_stop(&ctx, 1);
+		if (!err)
+			kdamond_pid = -1;
+		return err;
+	}
+
+	err = damon_hugepage_apply_parameters();
+	if (err)
+		return err;
+
+	err = damon_start(&ctx, 1, true);
+	if (err)
+		return err;
+	kdamond_pid = damon_kdamond_pid(ctx);
+	if (kdamond_pid < 0)
+		return kdamond_pid;
+	return damon_call(ctx, &call_control);
+}
+
+static int damon_hugepage_addr_unit_store(const char *val,
+		const struct kernel_param *kp)
+{
+	unsigned long input_addr_unit;
+	int err = kstrtoul(val, 0, &input_addr_unit);
+
+	if (err)
+		return err;
+	if (!input_addr_unit)
+		return -EINVAL;
+
+	addr_unit = input_addr_unit;
+	return 0;
+}
+
+static const struct kernel_param_ops addr_unit_param_ops = {
+	.set = damon_hugepage_addr_unit_store,
+	.get = param_get_ulong,
+};
+
+module_param_cb(addr_unit, &addr_unit_param_ops, &addr_unit, 0600);
+MODULE_PARM_DESC(addr_unit,
+	"Scale factor for DAMON_HUGEPAGE to ops address conversion (default: 1)");
+
+static int damon_hugepage_enabled_store(const char *val,
+				const struct kernel_param *kp)
+{
+	bool is_enabled = enabled;
+	bool enable;
+	int err;
+
+	err = kstrtobool(val, &enable);
+	if (err)
+		return err;
+
+	if (is_enabled == enable)
+		return 0;
+
+	/* Called before init function.  The function will handle this. */
+	if (!damon_initialized())
+		goto set_param_out;
+
+	err = damon_hugepage_turn(enable);
+	if (err)
+		return err;
+
+set_param_out:
+	enabled = enable;
+	return err;
+}
+
+static const struct kernel_param_ops enabled_param_ops = {
+	.set = damon_hugepage_enabled_store,
+	.get = param_get_bool,
+};
+
+module_param_cb(enabled, &enabled_param_ops, &enabled, 0600);
+MODULE_PARM_DESC(enabled,
+	"Enable or disable DAMON_HUGEPAGES (default: disabled)");
+
+static int __init damon_hugepage_init(void)
+{
+	int err;
+
+	if (!damon_initialized()) {
+		err = -ENOMEM;
+		goto out;
+	}
+	err = damon_modules_new_vaddr_ctx_target(&ctx, &target);
+	if (err)
+		goto out;
+
+	call_control.data = ctx;
+
+	/* 'enabled' has set before this function, probably via command line */
+	if (enabled)
+		err = damon_hugepage_turn(true);
+
+out:
+	if (err && enabled)
+		enabled = false;
+	return err;
+}
+
+module_init(damon_hugepage_init);
-- 
2.43.0

[RFC PATCH v1 4/4] Documentation/admin-guide/mm/damon: add DAMON-based Hugepage Management documentation

[gutierrez.asier]

From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>

Add documentation for the DAMON-based Hugepage Management (DAMON_HUGEPAGE)
feature, which automatically manages huge pages by identifying cold memory
regions and collapsing them back to regular pages. The documentation covers
the module's features, operation, and all available module parameters.

Signed-off-by: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
---
 .../admin-guide/mm/damon/hugepage.rst (new)   | 258 ++++++++++++++++++
 Documentation/admin-guide/mm/damon/index.rst  |   1 +
 2 files changed, 259 insertions(+)

diff --git a/Documentation/admin-guide/mm/damon/hugepage.rst b/Documentation/admin-guide/mm/damon/hugepage.rst
new file mode 100644
index 000000000000..ee50cfa79281
--- /dev/null
+++ b/Documentation/admin-guide/mm/damon/hugepage.rst
@@ -0,0 +1,258 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+DAMON-based huge page collapsing
+=======================
+
+DAMON-based huge page collapsing (DAMON_HUGEPAGE) is a static kernel module
+that aimed to collapse hot regions into huge pages.
+
+Where Proactive huge page collapsing is Required?
+========================================
+
+The amount of available memory grows faster than the amount of TLB entries.
+This leads to higher amount of TLB misses and excesive cycle wastes. Huge
+pages are meant to solve this problem. However, huge pages usually lead to
+memory fragmentation and memory waste.
+
+Collapsing selectively hot regions in a specific process can avoid big
+memory fragmentation, while increasing TLB performance.
+
+DAMON_HUGEPAGE solves this by:
+
+- Identifying hot regions that have been accessed for a configured time
+- Automatically collapsing the regions into huge pages back
+- Auto tune the huge page usage ratio to meet desired targets
+- Controlling the collapse rate with configurable quotas to avoid performance
+  degradation
+
+
+How It Works?
+=============
+
+DAMON_HUGEPAGE uses kdamond to identify anonymous memory regions that are:
+
+1. Large enough to be backed by huge pages (``PMD_SIZE`` or larger)
+2. Have been accessed for a configured time period
+
+Once identified, DAMON_HUGEPAGE triggers synchronous partial collapse of those
+regions. The collapse operation is controlled by quotas to limit the impact on
+system performance.
+
+The module also supports automatic tuning of the collapse rate to achieve a
+desired huge page usage ratio. Administrators can configure a target percentage
+of huge page usage vs total anonymous memory usage.
+
+Additionally, the module accepts manual feedback from system administrators to
+adjust the effective quota level based on observed system behavior.
+
+Interface: Module Parameters
+============================
+
+To use this feature, you should first ensure your system is running on a kernel
+that is built with ``CONFIG_DAMON_HUGEPAGE=y``.
+
+To let sysadmins enable or disable it and tune for the given system,
+DAMON_HUGEPAGE utilizes module parameters.  That is, you can put
+``damon_hugepage.<parameter>=<value>`` on the kernel boot command line or write
+proper values to ``/sys/module/damon_hugepage/parameters/<parameter>`` files.
+
+Below are the description of each parameter.
+
+enabled
+-------
+
+Enable or disable DAMON_HUGEPAGE.
+
+You can enable DAMON_HUGEPAGE by setting the value of this parameter as ``Y``.
+Setting it as ``N`` disables DAMON_HUGEPAGE.  Note that DAMON_HUGEPAGE could do
+no real monitoring and collapse due to the activation condition.
+
+commit_inputs
+-------------
+
+Make DAMON_HUGEPAGE reads the input parameters again, except ``enabled``.
+
+Input parameters that updated while DAMON_HUGEPAGE is running are not applied
+by default.  Once this parameter is set as ``Y``, DAMON_HUGEPAGE reads values
+of parametrs except ``enabled`` again.  Once the re-reading is done, this
+parameter is set as ``N``.  If invalid parameters are found while the
+re-reading, DAMON_HUGEPAGE will be disabled.
+
+Once ``Y`` is written to this parameter, the user must not write to any
+parameters until reading ``commit_inputs`` again returns ``N``.  If users
+violate this rule, the kernel may exhibit undefined behavior.
+
+min_age
+-------
+
+Time threshold for hot memory regions identification in microseconds.
+
+100 milliseconds by default.
+
+quota_ms
+--------
+
+Limit of time for the collapse in milliseconds.
+
+DAMON_HUGEPAGE tries to use only up to this time within a time window
+(quota_reset_interval_ms) for trying collapse hot pages.  This can be
+used for limiting CPU consumption of DAMON_HUGEPAGE.  If the value is zero, the
+limit is disabled.
+
+10 ms by default.
+
+quota_reset_interval_ms
+-----------------------
+
+The time/size quota charge reset interval in milliseconds.
+
+The charget reset interval for the quota of time (quota_ms) and size
+(quota_sz).  That is, DAMON_HUGEPAGE does not try collapsing for more than
+quota_ms milliseconds or quota_sz bytes within quota_reset_interval_ms
+milliseconds.
+
+1 second by default.
+
+quota_autotune_feedback
+-----------------------
+
+User-specifiable feedback for auto-tuning of the effective quota.
+
+While keeping the caps that set by other quotas, DAMON_HUGEPAGE automatically
+increases and decreases the effective level of the quota aiming receiving this
+feedback of value ``10,000`` from the user.  DAMON_HUGEPAGE assumes the feedback
+value and the quota are positively proportional.  Value zero means disabling
+this auto-tuning feature.
+
+Disabled by default.
+
+monitored_pid
+----------------
+
+PID of the task that is going to be monitored for hot regions.
+
+quota_percentage_hugepage
+----------------
+
+Huge page consumption to total memory anonymous memory consumption ratio goal
+in bp ``(10,000)``. DAMON_HUGEPAGE automatically increases and decreases page
+collapse aggressiveness in order to achieve the given value.
+
+sample_interval
+---------------
+
+Sampling interval for the monitoring in microseconds.
+
+The sampling interval of DAMON for the cold memory monitoring.  Please refer to
+the DAMON documentation (:doc:`usage`) for more detail.
+
+aggr_interval
+-------------
+
+Aggregation interval for the monitoring in microseconds.
+
+The aggregation interval of DAMON for the cold memory monitoring.  Please
+refer to the DAMON documentation (:doc:`usage`) for more detail.
+
+min_nr_regions
+--------------
+
+Minimum number of monitoring regions.
+
+The minimal number of monitoring regions of DAMON for the cold memory
+monitoring.  This can be used to set lower-bound of the monitoring quality.
+But, setting this too high could result in increased monitoring overhead.
+Please refer to the DAMON documentation (:doc:`usage`) for more detail.
+
+Note that this must be 3 or higher. Please refer to the :ref:`Monitoring
+<damon_design_monitoring>` section of the design document for the rationale
+behind this lower bound.
+
+max_nr_regions
+--------------
+
+Maximum number of monitoring regions.
+
+The maximum number of monitoring regions of DAMON for the cold memory
+monitoring.  This can be used to set upper-bound of the monitoring overhead.
+However, setting this too low could result in bad monitoring quality.  Please
+refer to the DAMON documentation (:doc:`usage`) for more detail.
+
+addr_unit
+---------
+
+A scale factor for memory addresses and bytes.
+
+This parameter is for setting and getting the :ref:`address unit
+<damon_design_addr_unit>` parameter of the DAMON instance for DAMON_HUGEPAGE.
+
+``monitor_region_start`` and ``monitor_region_end`` should be provided in this
+unit.  For example, let's suppose ``addr_unit``, ``monitor_region_start`` and
+``monitor_region_end`` are set as ``1024``, ``0`` and ``10``, respectively.
+Then DAMON_HUGEPAGE will work for 10 KiB length of physical address range that
+starts from address zero (``[0 * 1024, 10 * 1024)`` in bytes).
+
+``bytes_hugepage_tried_regions`` and ``bytes_hugepage_regions`` are also in
+this unit.  For example, let's suppose values of ``addr_unit``,
+``bytes_hugepage_tried_regions`` and ``bytes_hugepage_regions`` are
+``1048576``, ``42``, and ``32``, respectively.  Then it means DAMON_HUGEPAGE
+tried to collapse 42 MiB memory and successfully collapse 32 MiB memory in
+total.
+
+If unsure, use only the default value (``1``) and forget about this.
+
+
+kdamond_pid
+-----------
+
+PID of the DAMON thread.
+
+If DAMON_HUGEPAGE is enabled, this becomes the PID of the worker thread.  Else,
+-1.
+
+nr_hugepage_tried_regions
+------------------------
+
+Number of memory regions that tried to be collapsed by DAMON_HUGEPAGE.
+
+bytes_hugepage_tried_regions
+---------------------------
+
+Total bytes of memory regions that tried to be collapsed by DAMON_HUGEPAGE.
+
+nr_hugepage_regions
+--------------------
+
+Number of memory regions that successfully be collapsed by DAMON_HUGEPAGE.
+
+bytes_hugepage_regions
+-----------------------
+
+Total bytes of memory regions that successfully be collapsed by DAMON_HUGEPAGE.
+
+nr_quota_exceeds
+----------------
+
+Number of times that the time/space quota limits have exceeded.
+
+Example
+=======
+
+Below runtime example commands make DAMON_HUGEPAGE to find memory regions of 
+the task with PID 1234 that have been accessed in the last 100 millseconds or
+more and pages out. The pagecollapsing is limited to be done only up to 1 GiB
+per second to avoid DAMON_HUGEPAGE consuming too much CPU time for the collapse
+operation. ::
+
+    # cd /sys/module/damon_hugepage/parameters
+    # echo 100000 > min_age
+    # echo $((1 * 1024 * 1024 * 1024)) > quota_sz
+    # echo 1000 > quota_reset_interval_ms
+    # echo 1234 > monitored_pid
+    # echo Y > enabled
+
+Note that this module (damon_hugepage) cannot run simultaneously with other
+DAMON-based special-purpose modules.  Refer to :ref:`DAMON design special
+purpose modules exclusivity <damon_design_special_purpose_modules_exclusivity>`
+for more details.
diff --git a/Documentation/admin-guide/mm/damon/index.rst b/Documentation/admin-guide/mm/damon/index.rst
index 3ce3164480c7..6f2cad21a2da 100644
--- a/Documentation/admin-guide/mm/damon/index.rst
+++ b/Documentation/admin-guide/mm/damon/index.rst
@@ -15,3 +15,4 @@ access monitoring and access-aware system operations.
    reclaim
    lru_sort
    stat
+   hugepage
-- 
2.43.0

Re: [RFC PATCH v1 0/4] mm/damon: Introduce a huge page collapsing mechanism using auto tuning

[SeongJae Park]

Hello Asier,

On Thu, 30 Apr 2026 13:41:35 +0000 <gutierrez.asier@huawei-partners.com> wrote:

> From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
> 
> Overview
> ================

Let's align the length of underline with the text.

> 
> This patch set introduces a new autotuning which allows to collapse
> hot regions into hugepages.
> 
> Motivation
> ================
> 
> Since TLB is a bottleneck for many systems, a way to optimize TLB
> misses (or hits) is to use huge pages. Unfortunately, using "always"
> in THP leads to memory fragmentation and memory waste. For this reason,
> most application guides and system administrators suggest to disable THP.

I think the motivation should further explain why existing DAMOS features
(access pattern-based targetting and quota auto-tuning with existing quota
goals) are insufficient.  If that makes the text too long, I think the
explanation for well-known THP benefit and problems can be reduced or skipped.

> 
> Solution
> ================
> 
> A new autotuning quota goal[1], damos_get_used_hugepage_mem_bp, is
> introduced, which checks the huge page consumption to total anonymous
> memory consumption. This new quota mechanism reuses current autotuning
> architecture.

The idea makes sense to me.

The name sounds bit redundant, though.  How about DAMOS_QUOTA_HUGEPAGE_BP for
the enum, and hugeapge_bp for sysfs input?

> 
> A new module is introduced to demonstrate the use of huge pages
> collapse autotuning. The module launches a kdamond thread for a 
> certain task provided by the user through monitored_pid module argument.

If it is only for demonstration, I think it is more fit to be a sample module
(placed under samples/damon/).

> 
> This module also has a user autotuning knob which allows the user to
> adjust the aggressiveness of page collapsing.
> 
> Benchmarks
> ================
> In progress, will add them in the next RFC series.

Looking forward to!

I may request not that much test results for the quota goal.  If the module is
not just a sample but for a real world use case, I may hope somewhat reasonable
test resulsts.

> 
> TODO
> ================
> 
> - Since DAMOS_COLLAPSE is not in upstream and this is just a
>   RFC, I have used DAMOS_HUGEPAGE instead. This will change
>   to DAMOS_COLLAPSE in future series.

It is now in mm-new and it is recommended to use it as a baseline for DAMON
patches.  So please feel free to use DAMOS_COLLAPSE from the next version,
unless there is a reason to worry if DAMOS_COLLAPSE will be dropped from
mm-new.

> 
> Patches Sequence
> ================
> Patch 1 -> damon_modules_new_vaddr_ctx_target
> Patch 2 -> Introduce DAMOS_QUOTA_HUGEPAGE and autotuning
> Patch 3 -> Module that demonstrates how to use DAMOS_QUOTA_HUGEPAGE
>            and the new VADDR ctx creation
> Patch 4 -> Documentation
> 
> [1] https://lore.kernel.org/e67f05ad-dbb9-45e6-ba30-b167a99ac67d@huawei-partners.com

Adding more context about what this link is would be nice.  I can find the link
marker from the above text, but I was unable to expect what this is without
opening the link.


Thanks,
SJ

[...]

Re: [RFC PATCH v1 2/4] mm/damon: Introduce DAMOS_QUOTA_HUGEPAGE auto tuning

[SeongJae Park]

On Thu, 30 Apr 2026 13:41:37 +0000 <gutierrez.asier@huawei-partners.com> wrote:

> From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
> 
> Introduce DAMOS_QUOTA_HUGEPAGE auto tuning

You forgot the sentence ending period.

Also, the cover letter was calling it in a different name.  Let's match those.
Also, as I suggested on the reply to the cover letter of this series, too, I'd
prefer having the unit for the ratio on the name, like other goals, e.g.,
DAMOS_QUOTA_HUGEPAGE_BP.

> Add a new DAMOS quota goal
> metric to measure the amount of huge page consumption to total anonymous
> memory consumption ratio.

Why only anonymous memory?

> 
> Signed-off-by: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
> ---
>  include/linux/damon.h |  1 +
>  mm/damon/core.c       | 15 +++++++++++++++
>  2 files changed, 16 insertions(+)
> 
> diff --git a/include/linux/damon.h b/include/linux/damon.h
> index f2cdb7c3f5e6..97201e9fa407 100644
> --- a/include/linux/damon.h
> +++ b/include/linux/damon.h
> @@ -172,6 +172,7 @@ enum damos_quota_goal_metric {
>  	DAMOS_QUOTA_NODE_MEMCG_FREE_BP,
>  	DAMOS_QUOTA_ACTIVE_MEM_BP,
>  	DAMOS_QUOTA_INACTIVE_MEM_BP,
> +	DAMOS_QUOTA_HUGEPAGE,
>  	NR_DAMOS_QUOTA_GOAL_METRICS,
>  };
>  
> diff --git a/mm/damon/core.c b/mm/damon/core.c
> index 3dbbbfdeff71..06547e590ff2 100644
> --- a/mm/damon/core.c
> +++ b/mm/damon/core.c
> @@ -2319,6 +2319,18 @@ static unsigned int damos_get_in_active_mem_bp(bool active_ratio)
>  	return mult_frac(inactive, 10000, total);
>  }
>  
> +/*
> + * Returns anon hugepage memory to total anon memory use ratio.
> + */
> +static unsigned int damos_get_used_hugepage_mem_bp(void)

Name sounds bit long.  What about damos_get_hugepage_bp() ?

> +{
> +	unsigned long used_hugepages, total_used;
> + 
> +	used_hugepages = global_node_page_state(NR_ANON_THPS);
> +	total_used = global_node_page_state(NR_ANON_MAPPED);
> +	return mult_frac(used_hugepages, 10000, total_used);
> +}
> + 
>  static void damos_set_quota_goal_current_value(struct damos_quota_goal *goal)
>  {
>  	u64 now_psi_total;
> @@ -2345,6 +2357,9 @@ static void damos_set_quota_goal_current_value(struct damos_quota_goal *goal)
>  		goal->current_value = damos_get_in_active_mem_bp(
>  				goal->metric == DAMOS_QUOTA_ACTIVE_MEM_BP);
>  		break;
> +	case DAMOS_QUOTA_HUGEPAGE:
> +		goal->current_value = damos_get_used_hugepage_mem_bp();
> +		break;
>  	default:
>  		break;
>  	}
> -- 
> 2.43.0


Thanks,
SJ

[...]

Re: [RFC PATCH v1 3/4] mm/damon: introduce DAMON_HUGEPAGE for hot region hugepage collapsing

[SeongJae Park]

On Thu, 30 Apr 2026 13:41:38 +0000 <gutierrez.asier@huawei-partners.com> wrote:

> From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
> 
> This patch introduces a new DAMON module (DAMON_HUGEPAGE)
> which collapses hot regions into huge pages.
> 
> DAMON_HUGEPAGE operates in the virtual memory space, for a
> specific task.

The new quota goal is for global memory, isn't it?  Why use global memory goal
for virtual address based scheme?

I understand it makes sense to monitor virtual address space for collapsing.
If we have to do collapsing, should we modify the quota goal to work for only
given task's virtual address space?

Also, what about split?  Should we also split huge pages into regular pages if
it is cold?  Maybe that could work on physical address space, and use the
proposed quota goal as is?

> The user is expected to supply the PID of
> the task that is going to be monitored through the
> monitored_pid module variable.
> 
> DAMON_HUGEPAGE uses the hugepage auto-tune mechanism to
> increase or decrease the aggressiveness of page collapsing.
> User autotuning is also available for additional tuning
> aggressiveness control.
> 
> The module also includes changes to the DAMON compilation,
> so that the module can be enabled or disabled.
> 
> Signed-off-by: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
> ---
>  mm/damon/Kconfig          |   7 +
>  mm/damon/Makefile         |   1 +
>  mm/damon/hugepage.c (new) | 341 ++++++++++++++++++++++++++++++++++++++

The cover letter was saying this module is for demonstrating the usage of the
new goal type, but this is not a sample module.  Let's make sure what is the
purpose of this module, and decide where to put it based on that.

I will skip detailed code review until the above high level question is
answered, as depending on the conclusion the code may be changed a lot.


Thanks,
SJ

[...]

Re: [RFC PATCH v1 4/4] Documentation/admin-guide/mm/damon: add DAMON-based Hugepage Management documentation

[SeongJae Park]

On Thu, 30 Apr 2026 13:41:39 +0000 <gutierrez.asier@huawei-partners.com> wrote:

> From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
> 
> Add documentation for the DAMON-based Hugepage Management (DAMON_HUGEPAGE)
> feature, which automatically manages huge pages by identifying cold memory
> regions and collapsing them back to regular pages. The documentation covers
> the module's features, operation, and all available module parameters.
> 
> Signed-off-by: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
> ---
>  .../admin-guide/mm/damon/hugepage.rst (new)   | 258 ++++++++++++++++++
>  Documentation/admin-guide/mm/damon/index.rst  |   1 +

I will review this after the discussion about whether it should be a sample
module or real world usage module is concluded, as this could be changed a lot
depending on the conclusion.


Thanks,
SJ

[...]

Re: [RFC PATCH v1 0/4] mm/damon: Introduce a huge page collapsing mechanism using auto tuning

[Gutierrez Asier]

On 5/1/2026 3:41 AM, SeongJae Park wrote:
> Hello Asier,
Hi, sorry for the delayed answer.
> 
> On Thu, 30 Apr 2026 13:41:35 +0000 <gutierrez.asier@huawei-partners.com> wrote:
> 
>> From: Asier Gutierrez <gutierrez.asier@huawei-partners.com>
>>
>> Overview
>> ================
> 
> Let's align the length of underline with the text.
> 
>>
>> This patch set introduces a new autotuning which allows to collapse
>> hot regions into hugepages.
>>
>> Motivation
>> ================
>>
>> Since TLB is a bottleneck for many systems, a way to optimize TLB
>> misses (or hits) is to use huge pages. Unfortunately, using "always"
>> in THP leads to memory fragmentation and memory waste. For this reason,
>> most application guides and system administrators suggest to disable THP.
> 
> I think the motivation should further explain why existing DAMOS features
> (access pattern-based targetting and quota auto-tuning with existing quota
> goals) are insufficient.  If that makes the text too long, I think the
> explanation for well-known THP benefit and problems can be reduced or skipped.
OK, I will elaborate it in further series.
> 
>>
>> Solution
>> ================
>>
>> A new autotuning quota goal[1], damos_get_used_hugepage_mem_bp, is
>> introduced, which checks the huge page consumption to total anonymous
>> memory consumption. This new quota mechanism reuses current autotuning
>> architecture.
> 
> The idea makes sense to me.
> 
> The name sounds bit redundant, though.  How about DAMOS_QUOTA_HUGEPAGE_BP for
> the enum, and hugeapge_bp for sysfs input?
Agree. In fact, DAMOS_QUOTA_HUGEPAGE_BP would make sense to keep it
consistent with the quota naming.
> 
>>
>> A new module is introduced to demonstrate the use of huge pages
>> collapse autotuning. The module launches a kdamond thread for a 
>> certain task provided by the user through monitored_pid module argument.
> 
> If it is only for demonstration, I think it is more fit to be a sample module
> (placed under samples/damon/).
We are testing this in a bare metal MySQL server. Maybe the description
was not the most accurate.
>>
>> This module also has a user autotuning knob which allows the user to
>> adjust the aggressiveness of page collapsing.
>>
>> Benchmarks
>> ================
>> In progress, will add them in the next RFC series.
> 
> Looking forward to!
> 
> I may request not that much test results for the quota goal.  If the module is
> not just a sample but for a real world use case, I may hope somewhat reasonable
> test resulsts.
OK, will do it.
>>
>> TODO
>> ================
>>
>> - Since DAMOS_COLLAPSE is not in upstream and this is just a
>>   RFC, I have used DAMOS_HUGEPAGE instead. This will change
>>   to DAMOS_COLLAPSE in future series.
> 
> It is now in mm-new and it is recommended to use it as a baseline for DAMON
> patches.  So please feel free to use DAMOS_COLLAPSE from the next version,
> unless there is a reason to worry if DAMOS_COLLAPSE will be dropped from
> mm-new.
Thanks.
>>
>> Patches Sequence
>> ================
>> Patch 1 -> damon_modules_new_vaddr_ctx_target
>> Patch 2 -> Introduce DAMOS_QUOTA_HUGEPAGE and autotuning
>> Patch 3 -> Module that demonstrates how to use DAMOS_QUOTA_HUGEPAGE
>>            and the new VADDR ctx creation
>> Patch 4 -> Documentation
>>
>> [1] https://lore.kernel.org/e67f05ad-dbb9-45e6-ba30-b167a99ac67d@huawei-partners.com
> 
> Adding more context about what this link is would be nice.  I can find the link
> marker from the above text, but I was unable to expect what this is without
> opening the link.
> 
> 
> Thanks,
> SJ
> 
> [...]
> 

-- 
Asier Gutierrez
Huawei

Re: [RFC PATCH v1 0/4] mm/damon: Introduce a huge page collapsing mechanism using auto tuning

[SeongJae Park]

On Mon, 4 May 2026 16:52:01 +0300 Gutierrez Asier <gutierrez.asier@huawei-partners.com> wrote:

> On 5/1/2026 3:41 AM, SeongJae Park wrote:
> > Hello Asier,
> Hi, sorry for the delayed answer.

No worry, no rush.  Take your time :)

> > 
> > On Thu, 30 Apr 2026 13:41:35 +0000 <gutierrez.asier@huawei-partners.com> wrote:
[...]
> >> A new module is introduced to demonstrate the use of huge pages
> >> collapse autotuning. The module launches a kdamond thread for a 
> >> certain task provided by the user through monitored_pid module argument.
> > 
> > If it is only for demonstration, I think it is more fit to be a sample module
> > (placed under samples/damon/).
> We are testing this in a bare metal MySQL server. Maybe the description
> was not the most accurate.

Do you mean it is not only for demonstration but a real world use case and
therefore better not to be a sample module?

> >>
> >> This module also has a user autotuning knob which allows the user to
> >> adjust the aggressiveness of page collapsing.
> >>
> >> Benchmarks
> >> ================
> >> In progress, will add them in the next RFC series.
> > 
> > Looking forward to!
> > 
> > I may request not that much test results for the quota goal.  If the module is
> > not just a sample but for a real world use case, I may hope somewhat reasonable
> > test resulsts.
> OK, will do it.

Thank you for kindly and flexibly accepting my humble suggestions :)


Thanks,
SJ

[...]