Provide two debug helpers:
- ksw_watch_show(): print the current watch target address and length.
- ksw_watch_fire(): intentionally trigger the watchpoint immediately
by writing to the watched address, useful for testing HWBP behavior.
Signed-off-by: Jinchao Wang <wangjinchao600@gmail.com>
---
mm/kstackwatch/kstackwatch.h | 2 ++
mm/kstackwatch/watch.c | 34 ++++++++++++++++++++++++++++++++++
2 files changed, 36 insertions(+)
diff --git a/mm/kstackwatch/kstackwatch.h b/mm/kstackwatch/kstackwatch.h
index 4045890e5652..528001534047 100644
--- a/mm/kstackwatch/kstackwatch.h
+++ b/mm/kstackwatch/kstackwatch.h
@@ -52,5 +52,7 @@ void ksw_watch_exit(void);
int ksw_watch_get(struct ksw_watchpoint **out_wp);
int ksw_watch_on(struct ksw_watchpoint *wp, ulong watch_addr, u16 watch_len);
int ksw_watch_off(struct ksw_watchpoint *wp);
+void ksw_watch_show(void);
+void ksw_watch_fire(void);
#endif /* _KSTACKWATCH_H */
diff --git a/mm/kstackwatch/watch.c b/mm/kstackwatch/watch.c
index f32b1e46168c..9837d6873d92 100644
--- a/mm/kstackwatch/watch.c
+++ b/mm/kstackwatch/watch.c
@@ -269,3 +269,37 @@ void ksw_watch_exit(void)
{
ksw_watch_free();
}
+
+/* self debug function */
+void ksw_watch_show(void)
+{
+ struct ksw_watchpoint *wp = current->ksw_ctx.wp;
+
+ if (!wp) {
+ pr_info("nothing to show\n");
+ return;
+ }
+
+ pr_info("watch target bp_addr: 0x%llx len:%llu\n", wp->attr.bp_addr,
+ wp->attr.bp_len);
+}
+EXPORT_SYMBOL_GPL(ksw_watch_show);
+
+/* self debug function */
+void ksw_watch_fire(void)
+{
+ struct ksw_watchpoint *wp;
+ char *ptr;
+
+ wp = current->ksw_ctx.wp;
+
+ if (!wp) {
+ pr_info("nothing to fire\n");
+ return;
+ }
+
+ ptr = (char *)wp->attr.bp_addr;
+ pr_warn("watch triggered immediately\n");
+ *ptr = 0x42; // This should trigger immediately for any bp_len
+}
+EXPORT_SYMBOL_GPL(ksw_watch_fire);
--
2.43.0Introduce a separate test module to validate functionality in controlled
scenarios.
The module provides a proc interface (/proc/kstackwatch_test) that allows
triggering specific test cases via simple commands:
echo test0 > /proc/kstackwatch_test
Test module is built with optimizations disabled to ensure predictable
behavior.
Signed-off-by: Jinchao Wang <wangjinchao600@gmail.com>
---
mm/Kconfig.debug | 10 ++++
mm/kstackwatch/Makefile | 6 ++
mm/kstackwatch/test.c | 122 ++++++++++++++++++++++++++++++++++++++++
3 files changed, 138 insertions(+)
create mode 100644 mm/kstackwatch/test.c
diff --git a/mm/Kconfig.debug b/mm/Kconfig.debug
index 89be351c0be5..291dd8a78b98 100644
--- a/mm/Kconfig.debug
+++ b/mm/Kconfig.debug
@@ -317,3 +317,13 @@ config KSTACK_WATCH
A lightweight real-time debugging tool to detect stack corrupting.
If unsure, say N.
+
+config KSTACK_WATCH_TEST
+ tristate "KStackWatch Test Module"
+ depends on KSTACK_WATCH
+ help
+ This module provides controlled stack corruption scenarios to verify
+ the functionality of KStackWatch. It is useful for development and
+ validation of KStackWatch mechanism.
+
+ If unsure, say N.
diff --git a/mm/kstackwatch/Makefile b/mm/kstackwatch/Makefile
index 84a46cb9a766..d007b8dcd1c6 100644
--- a/mm/kstackwatch/Makefile
+++ b/mm/kstackwatch/Makefile
@@ -1,2 +1,8 @@
obj-$(CONFIG_KSTACK_WATCH) += kstackwatch.o
kstackwatch-y := kernel.o stack.o watch.o
+
+obj-$(CONFIG_KSTACK_WATCH_TEST) += kstackwatch_test.o
+kstackwatch_test-y := test.o
+CFLAGS_test.o := -fno-inline \
+ -fno-optimize-sibling-calls \
+ -fno-pic -fno-pie -O0 -Og
diff --git a/mm/kstackwatch/test.c b/mm/kstackwatch/test.c
new file mode 100644
index 000000000000..1ed98931cc51
--- /dev/null
+++ b/mm/kstackwatch/test.c
@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: GPL-2.0
+#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
+
+#include <linux/delay.h>
+#include <linux/kthread.h>
+#include <linux/list.h>
+#include <linux/module.h>
+#include <linux/prandom.h>
+#include <linux/printk.h>
+#include <linux/proc_fs.h>
+#include <linux/random.h>
+#include <linux/spinlock.h>
+#include <linux/string.h>
+#include <linux/uaccess.h>
+
+#include "kstackwatch.h"
+
+static struct proc_dir_entry *test_proc;
+
+#define BUFFER_SIZE 16
+#define MAX_DEPTH 6
+
+struct work_node {
+ ulong *ptr;
+ struct completion done;
+ struct list_head list;
+};
+
+static DECLARE_COMPLETION(work_res);
+static DEFINE_MUTEX(work_mutex);
+static LIST_HEAD(work_list);
+
+static void test_watch_fire(void)
+{
+ u64 buffer[BUFFER_SIZE] = { 0 };
+
+ pr_info("entry of %s\n", __func__);
+ ksw_watch_show();
+ ksw_watch_fire();
+ pr_info("buf[0]:%lld\n", buffer[0]);
+
+ barrier_data(buffer);
+ pr_info("exit of %s\n", __func__);
+}
+
+
+static ssize_t test_proc_write(struct file *file, const char __user *buffer,
+ size_t count, loff_t *pos)
+{
+ char cmd[256];
+ int test_num;
+
+ if (count >= sizeof(cmd))
+ return -EINVAL;
+
+ if (copy_from_user(cmd, buffer, count))
+ return -EFAULT;
+
+ cmd[count] = '\0';
+ strim(cmd);
+
+ pr_info("received command: %s\n", cmd);
+
+ if (sscanf(cmd, "test%d", &test_num) == 1) {
+ switch (test_num) {
+ case 0:
+ test_watch_fire();
+ break;
+ default:
+ pr_err("Unknown test number %d\n", test_num);
+ return -EINVAL;
+ }
+ } else {
+ pr_err("invalid command format. Use 'testN'.\n");
+ return -EINVAL;
+ }
+
+ return count;
+}
+
+static ssize_t test_proc_read(struct file *file, char __user *buffer,
+ size_t count, loff_t *pos)
+{
+ static const char usage[] = "KStackWatch Simplified Test Module\n"
+ "============ usage ==============\n"
+ "Usage:\n"
+ "echo test{i} > /proc/kstackwatch_test\n"
+ " test0 - test watch fire\n";
+
+ return simple_read_from_buffer(buffer, count, pos, usage,
+ strlen(usage));
+}
+
+static const struct proc_ops test_proc_ops = {
+ .proc_read = test_proc_read,
+ .proc_write = test_proc_write,
+};
+
+static int __init kstackwatch_test_init(void)
+{
+ test_proc = proc_create("kstackwatch_test", 0600, NULL, &test_proc_ops);
+ if (!test_proc) {
+ pr_err("Failed to create proc entry\n");
+ return -ENOMEM;
+ }
+ pr_info("module loaded\n");
+ return 0;
+}
+
+static void __exit kstackwatch_test_exit(void)
+{
+ if (test_proc)
+ remove_proc_entry("kstackwatch_test", NULL);
+ pr_info("module unloaded\n");
+}
+
+module_init(kstackwatch_test_init);
+module_exit(kstackwatch_test_exit);
+
+MODULE_AUTHOR("Jinchao Wang");
+MODULE_DESCRIPTION("Simple KStackWatch Test Module");
+MODULE_LICENSE("GPL");
--
2.43.0Extend the test module with a new test case (test1) that intentionally
overflows a local u64 buffer to corrupt the stack canary.
Signed-off-by: Jinchao Wang <wangjinchao600@gmail.com>
---
mm/kstackwatch/test.c | 20 +++++++++++++++++++-
1 file changed, 19 insertions(+), 1 deletion(-)
diff --git a/mm/kstackwatch/test.c b/mm/kstackwatch/test.c
index 1ed98931cc51..740e3c11b3ef 100644
--- a/mm/kstackwatch/test.c
+++ b/mm/kstackwatch/test.c
@@ -43,6 +43,20 @@ static void test_watch_fire(void)
pr_info("exit of %s\n", __func__);
}
+static void test_canary_overflow(void)
+{
+ u64 buffer[BUFFER_SIZE];
+
+ pr_info("entry of %s\n", __func__);
+
+ /* intentionally overflow */
+ for (int i = BUFFER_SIZE; i < BUFFER_SIZE + 10; i++)
+ buffer[i] = 0xdeadbeefdeadbeef;
+ barrier_data(buffer);
+
+ pr_info("exit of %s\n", __func__);
+}
+
static ssize_t test_proc_write(struct file *file, const char __user *buffer,
size_t count, loff_t *pos)
@@ -66,6 +80,9 @@ static ssize_t test_proc_write(struct file *file, const char __user *buffer,
case 0:
test_watch_fire();
break;
+ case 1:
+ test_canary_overflow();
+ break;
default:
pr_err("Unknown test number %d\n", test_num);
return -EINVAL;
@@ -85,7 +102,8 @@ static ssize_t test_proc_read(struct file *file, char __user *buffer,
"============ usage ==============\n"
"Usage:\n"
"echo test{i} > /proc/kstackwatch_test\n"
- " test0 - test watch fire\n";
+ " test0 - test watch fire\n"
+ " test1 - test canary overflow\n";
return simple_read_from_buffer(buffer, count, pos, usage,
strlen(usage));
--
2.43.0Introduce a test that performs stack writes in recursive calls to exercise
stack watch at a specific recursion depth.
Signed-off-by: Jinchao Wang <wangjinchao600@gmail.com>
---
mm/kstackwatch/test.c | 20 +++++++++++++++++++-
1 file changed, 19 insertions(+), 1 deletion(-)
diff --git a/mm/kstackwatch/test.c b/mm/kstackwatch/test.c
index 740e3c11b3ef..08e3d37c4c04 100644
--- a/mm/kstackwatch/test.c
+++ b/mm/kstackwatch/test.c
@@ -57,6 +57,20 @@ static void test_canary_overflow(void)
pr_info("exit of %s\n", __func__);
}
+static void test_recursive_depth(int depth)
+{
+ u64 buffer[BUFFER_SIZE];
+
+ pr_info("entry of %s depth:%d\n", __func__, depth);
+
+ if (depth < MAX_DEPTH)
+ test_recursive_depth(depth + 1);
+
+ buffer[0] = depth;
+ barrier_data(buffer);
+
+ pr_info("exit of %s depth:%d\n", __func__, depth);
+}
static ssize_t test_proc_write(struct file *file, const char __user *buffer,
size_t count, loff_t *pos)
@@ -83,6 +97,9 @@ static ssize_t test_proc_write(struct file *file, const char __user *buffer,
case 1:
test_canary_overflow();
break;
+ case 2:
+ test_recursive_depth(0);
+ break;
default:
pr_err("Unknown test number %d\n", test_num);
return -EINVAL;
@@ -103,7 +120,8 @@ static ssize_t test_proc_read(struct file *file, char __user *buffer,
"Usage:\n"
"echo test{i} > /proc/kstackwatch_test\n"
" test0 - test watch fire\n"
- " test1 - test canary overflow\n";
+ " test1 - test canary overflow\n"
+ " test2 - test recursive func\n";
return simple_read_from_buffer(buffer, count, pos, usage,
strlen(usage));
--
2.43.0These tests share a common structure and are grouped together.
- buggy():
exposes the stack address to corrupting(); may omit waiting
- corrupting():
reads the exposed pointer and modifies memory;
if buggy() omits waiting, victim()'s buffer is corrupted
- victim():
initializes a local buffer and later verifies it;
reports an error if the buffer was unexpectedly modified
buggy() and victim() run in worker() thread, with similar stack frame sizes
to simplify testing. By adjusting fence_size in corrupting(), the test can
trigger either silent corruption or overflow across threads.
- Test 3: one worker, 20 loops, silent corruption
- Test 4: 20 workers, one loop each, silent corruption
- Test 5: one worker, one loop, overflow corruption
Test 4 also exercises multiple watchpoint instances.
Signed-off-by: Jinchao Wang <wangjinchao600@gmail.com>
---
mm/kstackwatch/test.c | 178 +++++++++++++++++++++++++++++++++++++++++-
1 file changed, 176 insertions(+), 2 deletions(-)
diff --git a/mm/kstackwatch/test.c b/mm/kstackwatch/test.c
index 08e3d37c4c04..859122bbbdeb 100644
--- a/mm/kstackwatch/test.c
+++ b/mm/kstackwatch/test.c
@@ -17,11 +17,12 @@
static struct proc_dir_entry *test_proc;
-#define BUFFER_SIZE 16
+#define BUFFER_SIZE 32
#define MAX_DEPTH 6
struct work_node {
ulong *ptr;
+ u64 start_ns;
struct completion done;
struct list_head list;
};
@@ -30,6 +31,9 @@ static DECLARE_COMPLETION(work_res);
static DEFINE_MUTEX(work_mutex);
static LIST_HEAD(work_list);
+static int global_fence_size;
+static int global_loop_count;
+
static void test_watch_fire(void)
{
u64 buffer[BUFFER_SIZE] = { 0 };
@@ -72,6 +76,164 @@ static void test_recursive_depth(int depth)
pr_info("exit of %s depth:%d\n", __func__, depth);
}
+static struct work_node *test_mthread_buggy(int thread_id, int seq_id)
+{
+ ulong buf[BUFFER_SIZE];
+ struct work_node *node;
+ bool trigger;
+
+ node = kmalloc(sizeof(*node), GFP_KERNEL);
+ if (!node)
+ return NULL;
+
+ init_completion(&node->done);
+ node->ptr = buf;
+ node->start_ns = ktime_get_ns();
+ mutex_lock(&work_mutex);
+ list_add(&node->list, &work_list);
+ mutex_unlock(&work_mutex);
+ complete(&work_res);
+
+ trigger = (get_random_u32() % 100) < 10;
+ if (trigger)
+ return node; /* let the caller handle cleanup */
+
+ wait_for_completion(&node->done);
+ kfree(node);
+ return NULL;
+}
+
+#define CORRUPTING_MINIOR_WAIT_NS (100000)
+#define VICTIM_MINIOR_WAIT_NS (300000)
+
+static inline void silent_wait_us(u64 start_ns, u64 min_wait_us)
+{
+ u64 diff_ns, remain_us;
+
+ diff_ns = ktime_get_ns() - start_ns;
+ if (diff_ns < min_wait_us * 1000ULL) {
+ remain_us = min_wait_us - (diff_ns >> 10);
+ usleep_range(remain_us, remain_us + 200);
+ }
+}
+
+static void test_mthread_victim(int thread_id, int seq_id, u64 start_ns)
+{
+ ulong buf[BUFFER_SIZE];
+
+ for (int j = 0; j < BUFFER_SIZE; j++)
+ buf[j] = 0xdeadbeef + seq_id;
+ if (start_ns)
+ silent_wait_us(start_ns, VICTIM_MINIOR_WAIT_NS);
+
+ for (int j = 0; j < BUFFER_SIZE; j++) {
+ if (buf[j] != (0xdeadbeef + seq_id)) {
+ pr_warn("victim[%d][%d]: unhappy buf[%d]=0x%lx\n",
+ thread_id, seq_id, j, buf[j]);
+ return;
+ }
+ }
+
+ pr_info("victim[%d][%d]: happy\n", thread_id, seq_id);
+}
+
+static int test_mthread_corrupting(void *data)
+{
+ struct work_node *node;
+ int fence_size;
+
+ while (!kthread_should_stop()) {
+ if (!wait_for_completion_timeout(&work_res, HZ))
+ continue;
+ while (true) {
+ mutex_lock(&work_mutex);
+ node = list_first_entry_or_null(&work_list,
+ struct work_node, list);
+ if (node)
+ list_del(&node->list);
+ mutex_unlock(&work_mutex);
+
+ if (!node)
+ break; /* no more nodes, exit inner loop */
+ silent_wait_us(node->start_ns,
+ CORRUPTING_MINIOR_WAIT_NS);
+
+ fence_size = READ_ONCE(global_fence_size);
+ for (int i = fence_size; i < BUFFER_SIZE - fence_size;
+ i++)
+ node->ptr[i] = 0xabcdabcd;
+
+ complete(&node->done);
+ }
+ }
+
+ return 0;
+}
+
+static int test_mthread_worker(void *data)
+{
+ int thread_id = (long)data;
+ int loop_count;
+ struct work_node *node;
+
+ loop_count = READ_ONCE(global_loop_count);
+
+ for (int i = 0; i < loop_count; i++) {
+ node = test_mthread_buggy(thread_id, i);
+
+ if (node)
+ test_mthread_victim(thread_id, i, node->start_ns);
+ else
+ test_mthread_victim(thread_id, i, 0);
+ if (node) {
+ wait_for_completion(&node->done);
+ kfree(node);
+ }
+ }
+ return 0;
+}
+
+static void test_mthread_case(int num_workers, int loop_count, int fence_size)
+{
+ static struct task_struct *corrupting;
+ static struct task_struct **workers;
+
+ WRITE_ONCE(global_loop_count, loop_count);
+ WRITE_ONCE(global_fence_size, fence_size);
+
+ init_completion(&work_res);
+ workers = kmalloc_array(num_workers, sizeof(void *), GFP_KERNEL);
+ memset(workers, 0, sizeof(struct task_struct *) * num_workers);
+
+ corrupting = kthread_run(test_mthread_corrupting, NULL, "corrupting");
+ if (IS_ERR(corrupting)) {
+ pr_err("failed to create corrupting thread\n");
+ return;
+ }
+
+ for (ulong i = 0; i < num_workers; i++) {
+ workers[i] = kthread_run(test_mthread_worker, (void *)i,
+ "worker_%ld", i);
+ if (IS_ERR(workers[i])) {
+ pr_err("failto create worker thread %ld", i);
+ workers[i] = NULL;
+ }
+ }
+
+ for (ulong i = 0; i < num_workers; i++) {
+ if (workers[i] && workers[i]->__state != TASK_DEAD) {
+ usleep_range(1000, 2000);
+ i--;
+ }
+ }
+ kfree(workers);
+
+ if (corrupting && !IS_ERR(corrupting)) {
+ kthread_stop(corrupting);
+ corrupting = NULL;
+ }
+}
+
static ssize_t test_proc_write(struct file *file, const char __user *buffer,
size_t count, loff_t *pos)
{
@@ -100,6 +262,15 @@ static ssize_t test_proc_write(struct file *file, const char __user *buffer,
case 2:
test_recursive_depth(0);
break;
+ case 3:
+ test_mthread_case(1, 20, BUFFER_SIZE / 4);
+ break;
+ case 4:
+ test_mthread_case(20, 1, BUFFER_SIZE / 4);
+ break;
+ case 5:
+ test_mthread_case(1, 1, -3);
+ break;
default:
pr_err("Unknown test number %d\n", test_num);
return -EINVAL;
@@ -121,7 +292,10 @@ static ssize_t test_proc_read(struct file *file, char __user *buffer,
"echo test{i} > /proc/kstackwatch_test\n"
" test0 - test watch fire\n"
" test1 - test canary overflow\n"
- " test2 - test recursive func\n";
+ " test2 - test recursive func\n"
+ " test3 - test silent corruption\n"
+ " test4 - test multiple silent corruption\n"
+ " test5 - test prologue corruption\n";
return simple_read_from_buffer(buffer, count, pos, usage,
strlen(usage));
--
2.43.0Provide a shell script to trigger test cases.
Signed-off-by: Jinchao Wang <wangjinchao600@gmail.com>
---
tools/kstackwatch/kstackwatch_test.sh | 52 +++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
create mode 100755 tools/kstackwatch/kstackwatch_test.sh
diff --git a/tools/kstackwatch/kstackwatch_test.sh b/tools/kstackwatch/kstackwatch_test.sh
new file mode 100755
index 000000000000..aede35dcb8b6
--- /dev/null
+++ b/tools/kstackwatch/kstackwatch_test.sh
@@ -0,0 +1,52 @@
+#!/bin/bash
+# SPDX-License-Identifier: GPL-2.0
+
+echo "IMPORTANT: Before running, make sure you have updated the config values!"
+
+usage() {
+ echo "Usage: $0 [0-5]"
+ echo " 0 - test watch fire"
+ echo " 1 - test canary overflow"
+ echo " 2 - test recursive depth"
+ echo " 3 - test silent corruption"
+ echo " 4 - test multi-threaded silent corruption"
+ echo " 5 - test multi-threaded overflow"
+}
+
+run_test() {
+ local test_num=$1
+ case "$test_num" in
+ 0) echo fn=test_watch_fire fo=0x29 wl=8 >/proc/kstackwatch
+ echo test0 > /proc/kstackwatch_test
+ ;;
+ 1) echo fn=test_canary_overflow fo=0x14 >/proc/kstackwatch
+ echo test1 >/proc/kstackwatch_test
+ ;;
+ 2) echo fn=test_recursive_depth fo=0x2f dp=3 wl=8 so=0 >/proc/kstackwatch
+ echo test2 >/proc/kstackwatch_test
+ ;;
+ 3) echo fn=test_mthread_victim fo=0x4c so=64 wl=8 >/proc/kstackwatch
+ echo test3 >/proc/kstackwatch_test
+ ;;
+ 4) echo fn=test_mthread_victim fo=0x4c so=64 wl=8 >/proc/kstackwatch
+ echo test4 >/proc/kstackwatch_test
+ ;;
+ 5) echo fn=test_mthread_buggy fo=0x16 so=0x100 wl=8 >/proc/kstackwatch
+ echo test5 >/proc/kstackwatch_test
+ ;;
+ *) usage
+ exit 1 ;;
+ esac
+ # Reset watch after test
+ echo >/proc/kstackwatch
+}
+
+# Check root and module
+[ "$EUID" -ne 0 ] && echo "Run as root" && exit 1
+for f in /proc/kstackwatch /proc/kstackwatch_test; do
+ [ ! -f "$f" ] && echo "$f not found" && exit 1
+done
+
+# Run
+[ -z "$1" ] && { usage; exit 0; }
+run_test "$1"
--
2.43.0Add documentation for KStackWatch under Documentation/.
It provides an overview, main features, usage details, configuration
parameters, and example scenarios with test cases. The document also
explains how to locate function offsets and interpret logs.
Signed-off-by: Jinchao Wang <wangjinchao600@gmail.com>
---
Documentation/dev-tools/index.rst | 1 +
Documentation/dev-tools/kstackwatch.rst | 316 ++++++++++++++++++++++++
2 files changed, 317 insertions(+)
create mode 100644 Documentation/dev-tools/kstackwatch.rst
diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
index 65c54b27a60b..45eb828d9d65 100644
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -31,6 +31,7 @@ Documentation/process/debugging/index.rst
kcsan
kfence
kselftest
+ kstackwatch
kunit/index
ktap
checkuapi
diff --git a/Documentation/dev-tools/kstackwatch.rst b/Documentation/dev-tools/kstackwatch.rst
new file mode 100644
index 000000000000..7a9e018ddccb
--- /dev/null
+++ b/Documentation/dev-tools/kstackwatch.rst
@@ -0,0 +1,316 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+KStackWatch: Kernel Stack Watch
+=================================
+
+Overview
+========
+
+KStackWatch is a lightweight debugging tool designed to detect kernel stack
+corruption in real time. It installs a hardware breakpoint (watchpoint)
+at a function's specified offset using *kprobe.post_handler* and
+removes it in *fprobe.exit_handler*. This covers the full execution
+window and reports corruption immediately with time, location, and
+call stack.
+
+Main features:
+
+* Immediate and precise detection
+* Supports concurrent calls to the watched function
+* Lockless design, usable in any context
+* Depth filter for recursive calls
+* Minimal impact on reproducibility
+* Flexible procfs configuration with key=val syntax
+
+Usage
+=====
+
+KStackWatch is configured through */proc/kstackwatch* using a key=value
+format. Both long and short forms are supported. Writing an empty string
+disables the watch.
+
+.. code-block:: bash
+
+ # long form
+ echo func_name=? func_offset=? ... > /proc/kstackwatch
+
+ # short form
+ echo fn=? fo=? ... > /proc/kstackwatch
+
+ # disable
+ echo > /proc/kstackwatch
+
+The function name and the instruction offset where the watchpoint should
+be placed must be known. This information can be obtained from
+*objdump* or other tools.
+
+Required parameters
+--------------------
+
++--------------+--------+-----------------------------------------+
+| Parameter | Short | Description |
++==============+========+=========================================+
+| func_name | fn | Name of the target function |
++--------------+--------+-----------------------------------------+
+| func_offset | fo | Instruction pointer offset |
++--------------+--------+-----------------------------------------+
+
+Optional parameters
+--------------------
+
+Default 0 and can be omitted.
+Both decimal and hexadecimal are supported.
+
++--------------+--------+------------------------------------------------+
+| Parameter | Short | Description |
++==============+========+================================================+
+| depth | dp | Recursion depth filter |
++--------------+--------+------------------------------------------------+
+| max_watch | mw | Maximum number of concurrent watchpoints |
+| | | (default 0, capped by available hardware |
+| | | breakpoints) |
++--------------+--------+------------------------------------------------+
+| sp_offset | so | Watching addr offset from stack pointer |
++--------------+--------+------------------------------------------------+
+| watch_len | wl | Watch length in bytes (1, 2, 4, 8, or 0), |
+| | | 0 means automatically watch the stack canary |
+| | | and ignore the ``sp_offset`` parameter |
++--------------+--------+------------------------------------------------+
+
+Workflow Example
+================
+
+Silent corruption
+-----------------
+
+Consider *test3* in *kstackwatch_test.sh*. Run it directly:
+
+.. code-block:: bash
+
+ echo test3 >/proc/kstackwatch_test
+
+Sometimes, *test_mthread_victim()* may report as unhappy:
+
+.. code-block:: bash
+
+ [ 7.807082] kstackwatch_test: victim[0][11]: unhappy buf[8]=0xabcdabcd
+
+Its source code is:
+
+.. code-block:: c
+
+ static void test_mthread_victim(int thread_id, int seq_id, u64 start_ns)
+ {
+ ulong buf[BUFFER_SIZE];
+
+ for (int j = 0; j < BUFFER_SIZE; j++)
+ buf[j] = 0xdeadbeef + seq_id;
+
+ if (start_ns)
+ silent_wait_us(start_ns, VICTIM_MINIOR_WAIT_NS);
+
+ for (int j = 0; j < BUFFER_SIZE; j++) {
+ if (buf[j] != (0xdeadbeef + seq_id)) {
+ pr_warn("victim[%d][%d]: unhappy buf[%d]=0x%lx\n",
+ thread_id, seq_id, j, buf[j]);
+ return;
+ }
+ }
+
+ pr_info("victim[%d][%d]: happy\n", thread_id, seq_id);
+ }
+
+From the source code, the report indicates buf[8] was unexpectedly modified,
+a case of silent corruption.
+
+Configuration
+-------------
+
+Since buf[8] is the corrupted variable, the following configuration shows
+how to use KStackWatch to detect its corruption.
+
+func_name
+~~~~~~~~~~~
+
+As seen, buf[8] is initialized and modified in *test_mthread_victim*(),
+which sets *func_name*.
+
+func_offset & sp_offset
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The watchpoint should be set after the assignment and as close as
+possible, which sets *func_offset*.
+
+The watchpoint should be set to watch buf[8], which sets *sp_offset*.
+
+Use the objdump output to disassemble the function:
+
+.. code-block:: bash
+
+ objdump -S --disassemble=test_mthread_victim vmlinux
+
+A shortened output is:
+
+.. code-block:: text
+
+ static void test_mthread_victim(int thread_id, int seq_id, u64 start_ns)
+ {
+ ffffffff815cb4e0: e8 5b 9b ca ff call ffffffff81275040 <__fentry__>
+ ffffffff815cb4e5: 55 push %rbp
+ ffffffff815cb4e6: 53 push %rbx
+ ffffffff815cb4e7: 48 81 ec 08 01 00 00 sub $0x108,%rsp
+ ffffffff815cb4ee: 89 fd mov %edi,%ebp
+ ffffffff815cb4f0: 89 f3 mov %esi,%ebx
+ ffffffff815cb4f2: 49 89 d0 mov %rdx,%r8
+ ffffffff815cb4f5: 65 48 8b 05 0b cb 80 mov %gs:0x280cb0b(%rip),%rax # ffffffff83dd8008 <__stack_chk_guard>
+ ffffffff815cb4fc: 02
+ ffffffff815cb4fd: 48 89 84 24 00 01 00 mov %rax,0x100(%rsp)
+ ffffffff815cb504: 00
+ ffffffff815cb505: 31 c0 xor %eax,%eax
+ ulong buf[BUFFER_SIZE];
+ ffffffff815cb507: 48 89 e2 mov %rsp,%rdx
+ ffffffff815cb50a: b9 20 00 00 00 mov $0x20,%ecx
+ ffffffff815cb50f: 48 89 d7 mov %rdx,%rdi
+ ffffffff815cb512: f3 48 ab rep stos %rax,%es:(%rdi)
+
+ for (int j = 0; j < BUFFER_SIZE; j++)
+ ffffffff815cb515: eb 10 jmp ffffffff815cb527 <test_mthread_victim+0x47>
+ buf[j] = 0xdeadbeef + seq_id;
+ ffffffff815cb517: 8d 93 ef be ad de lea -0x21524111(%rbx),%edx
+ ffffffff815cb51d: 48 63 c8 movslq %eax,%rcx
+ ffffffff815cb520: 48 89 14 cc mov %rdx,(%rsp,%rcx,8)
+ ffffffff815cb524: 83 c0 01 add $0x1,%eax
+ ffffffff815cb527: 83 f8 1f cmp $0x1f,%eax
+ ffffffff815cb52a: 7e eb jle ffffffff815cb517 <test_mthread_victim+0x37>
+ if (start_ns)
+ ffffffff815cb52c: 4d 85 c0 test %r8,%r8
+ ffffffff815cb52f: 75 21 jne ffffffff815cb552 <test_mthread_victim+0x72>
+ silent_wait_us(start_ns, VICTIM_MINIOR_WAIT_NS);
+ ...
+ ffffffff815cb571: 48 8b 84 24 00 01 00 mov 0x100(%rsp),%rax
+ ffffffff815cb579: 65 48 2b 05 87 ca 80 sub %gs:0x280ca87(%rip),%rax # ffffffff83dd8008 <__stack_chk_guard>
+ ...
+ ffffffff815cb5a1: eb ce jmp ffffffff815cb571 <test_mthread_victim+0x91>
+ }
+ ffffffff815cb5a3: e8 d8 86 f1 00 call ffffffff824e3c80 <__stack_chk_fail>
+
+
+func_offset
+^^^^^^^^^^^
+
+The function begins at ffffffff815cb4e0. The *buf* array is initialized in a loop.
+The instruction storing values into the array is at ffffffff815cb520, and the
+first instruction after the loop is at ffffffff815cb52c.
+
+Because KStackWatch uses *kprobe.post_handler*, the watchpoint can be
+set right after ffffffff815cb520. However, this may cause false positives
+because the watchpoint is active before buf[8] is fully assigned.
+
+An alternative is to place the watchpoint at ffffffff815cb52c, right
+after the loop. This avoids false positives but leaves a small window
+for false negatives.
+
+In this document, ffffffff815cb52c is chosen for cleaner logs. If false
+negatives are suspected, repeat the test to catch the corruption.
+
+The required offset is calculated from the function start:
+
+*func_offset* is 0x4c (ffffffff815cb52c - ffffffff815cb4e0).
+
+sp_offset
+^^^^^^^^^^^
+
+From the disassembly, the buf array is at the top of the stack,
+meaning buf == rsp. Therefore, buf[8] sits at rsp + 8 * sizeof(ulong) =
+rsp + 64. Thus, *sp_offset* is 64.
+
+Other parameters
+~~~~~~~~~~~~~~~~~~
+
+* *depth* is 0, as test_mthread_victim is not recursive
+* *max_watch* is 0 to use all available hwbps
+* *watch_len* is 8, the size of a ulong on x86_64
+
+Parameters with a value of 0 can be omitted as defaults.
+
+Configure the watch:
+
+.. code-block:: bash
+
+ echo "fn=test_mthread_victim fo=0x4c so=64 wl=8" > /proc/kstackwatch
+
+Now rerun the test:
+
+.. code-block:: bash
+
+ echo test3 >/proc/kstackwatch_test
+
+The dmesg log shows:
+
+.. code-block:: text
+
+ [ 7.607074] kstackwatch: ========== KStackWatch: Caught stack corruption =======
+ [ 7.607077] kstackwatch: config fn=test_mthread_victim fo=0x4c so=64 wl=8
+ [ 7.607080] CPU: 2 UID: 0 PID: 347 Comm: corrupting Not tainted 6.17.0-rc7-00022-g90270f3db80a-dirty #509 PREEMPT(voluntary)
+ [ 7.607083] Call Trace:
+ [ 7.607084] <#DB>
+ [ 7.607085] dump_stack_lvl+0x66/0xa0
+ [ 7.607091] ksw_watch_handler.part.0+0x2b/0x60
+ [ 7.607094] ksw_watch_handler+0xba/0xd0
+ [ 7.607095] ? test_mthread_corrupting+0x48/0xd0
+ [ 7.607097] ? kthread+0x10d/0x210
+ [ 7.607099] ? ret_from_fork+0x187/0x1e0
+ [ 7.607102] ? ret_from_fork_asm+0x1a/0x30
+ [ 7.607105] __perf_event_overflow+0x154/0x570
+ [ 7.607108] perf_bp_event+0xb4/0xc0
+ [ 7.607112] ? look_up_lock_class+0x59/0x150
+ [ 7.607115] hw_breakpoint_exceptions_notify+0xf7/0x110
+ [ 7.607117] notifier_call_chain+0x44/0x110
+ [ 7.607119] atomic_notifier_call_chain+0x5f/0x110
+ [ 7.607121] notify_die+0x4c/0xb0
+ [ 7.607123] exc_debug_kernel+0xaf/0x170
+ [ 7.607126] asm_exc_debug+0x1e/0x40
+ [ 7.607127] RIP: 0010:test_mthread_corrupting+0x48/0xd0
+ [ 7.607129] Code: c7 80 0a 24 83 e8 48 f1 f1 00 48 85 c0 74 dd eb 30 bb 00 00 00 00 eb 59 48 63 c2 48 c1 e0 03 48 03 03 be cd ab cd ab 48 89 30 <83> c2 01 b8 20 00 00 00 29 c8 39 d0 7f e0 48 8d 7b 10 e8 d1 86 d4
+ [ 7.607130] RSP: 0018:ffffc90000acfee0 EFLAGS: 00000286
+ [ 7.607132] RAX: ffffc90000a13de8 RBX: ffff888102d57580 RCX: 0000000000000008
+ [ 7.607132] RDX: 0000000000000008 RSI: 00000000abcdabcd RDI: ffffc90000acfe00
+ [ 7.607133] RBP: ffff8881085bc800 R08: 0000000000000001 R09: 0000000000000000
+ [ 7.607133] R10: 0000000000000001 R11: 0000000000000000 R12: ffff888105398000
+ [ 7.607134] R13: ffff8881085bc800 R14: ffffffff815cb660 R15: 0000000000000000
+ [ 7.607134] ? __pfx_test_mthread_corrupting+0x10/0x10
+ [ 7.607137] </#DB>
+ [ 7.607138] <TASK>
+ [ 7.607138] kthread+0x10d/0x210
+ [ 7.607140] ? __pfx_kthread+0x10/0x10
+ [ 7.607141] ret_from_fork+0x187/0x1e0
+ [ 7.607143] ? __pfx_kthread+0x10/0x10
+ [ 7.607144] ret_from_fork_asm+0x1a/0x30
+ [ 7.607147] </TASK>
+ [ 7.607147] kstackwatch: =================== KStackWatch End ===================
+ [ 7.807082] kstackwatch_test: victim[0][11]: unhappy buf[8]=0xabcdabcd
+
+The line ``RIP: 0010:test_mthread_corrupting+0x48/0xd0`` shows the exact
+location where the corruption occurred. Now that the ``corrupting()`` function has
+been identified, it is straightforward to trace back to ``buggy()`` and fix the bug.
+
+
+More usage examples and corruption scenarios are provided in
+``kstackwatch_test.sh`` and ``mm/kstackwatch/test.c``.
+
+Limitations
+===========
+
+* Limited by available hardware breakpoints
+* Only one function can be watched at a time
+* Canary search limited to 128 * sizeof(ulong) from the current stack
+ pointer. This is sufficient for most cases, but has three limitations:
+
+ - If the stack frame is larger, the search may fail.
+ - If the function does not have a canary, the search may fail.
+ - If stack memory occasionally contains the same value as the canary,
+ it may be incorrectly matched.
+
+ In these cases, the user can provide the canary location using
+ ``sp_offset``, or treat any memory in the function prologue
+ as the canary.
--
2.43.0Add a maintainer entry for Kernel Stack Watch.
Signed-off-by: Jinchao Wang <wangjinchao600@gmail.com>
---
MAINTAINERS | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 520fb4e379a3..3d4811ff3631 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13362,6 +13362,14 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git
F: Documentation/dev-tools/kselftest*
F: tools/testing/selftests/
+KERNEL STACK WATCH
+M: Jinchao Wang <wangjinchao600@gmail.com>
+S: Maintained
+F: Documentation/dev-tools/kstackwatch.rst
+F: include/linux/kstackwatch_types.h
+F: mm/kstackwatch/
+F: tools/kstackwatch/
+
KERNEL SMB3 SERVER (KSMBD)
M: Namjae Jeon <linkinjeon@kernel.org>
M: Namjae Jeon <linkinjeon@samba.org>
--
2.43.0© 2016 - 2025 Red Hat, Inc.