unwind_user: Add user space unwinding API with frame pointer support

Introduce a generic API for unwinding user stacks.

In order to expand user space unwinding to be able to handle more complex
scenarios, such as deferred unwinding and reading user space information,
create a generic interface that all architectures can use that support the
various unwinding methods.

This is an alternative method for handling user space stack traces from
the simple stack_trace_save_user() API. This does not replace that
interface, but this interface will be used to expand the functionality of
user space stack walking.

None of the structures introduced will be exposed to user space tooling.

Support for frame pointer unwinding is added. For an architecture to
support frame pointer unwinding it needs to enable
CONFIG_HAVE_UNWIND_USER_FP and define ARCH_INIT_USER_FP_FRAME.

By encoding the frame offsets in struct unwind_user_frame, much of this
code can also be reused for future unwinder implementations like sframe.

Cc: Masami Hiramatsu <mhiramat@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Ingo Molnar <mingo@kernel.org>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Arnaldo Carvalho de Melo <acme@kernel.org>
Cc: Namhyung Kim <namhyung@kernel.org>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Andrii Nakryiko <andrii@kernel.org>
Cc: Indu Bhagat <indu.bhagat@oracle.com>
Cc: "Jose E. Marchesi" <jemarch@gnu.org>
Cc: Beau Belgrave <beaub@linux.microsoft.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Florian Weimer <fweimer@redhat.com>
Cc: Sam James <sam@gentoo.org>
Link: https://lore.kernel.org/20250729182404.975790139@kernel.org
Reviewed-by: Jens Remus <jremus@linux.ibm.com>
Signed-off-by: Josh Poimboeuf <jpoimboe@kernel.org>
Co-developed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Link: https://lore.kernel.org/all/20250710164301.3094-2-mathieu.desnoyers@efficios.com/
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Co-developed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>

diff --git a/MAINTAINERS b/MAINTAINERS
index fad6cb025a1918beec113b576cf28b76151745ef..370d780fd5f8361a50cb7ebf226c64faa02612d4 100644 (file)
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -25928,6 +25928,14 @@ F:     Documentation/driver-api/uio-howto.rst
 F:     drivers/uio/
 F:     include/linux/uio_driver.h
 
+USERSPACE STACK UNWINDING
+M:     Josh Poimboeuf <jpoimboe@kernel.org>
+M:     Steven Rostedt <rostedt@goodmis.org>
+S:     Maintained
+F:     include/linux/unwind*.h
+F:     kernel/unwind/
+
+
 UTIL-LINUX PACKAGE
 M:     Karel Zak <kzak@redhat.com>
 L:     util-linux@vger.kernel.org

diff --git a/arch/Kconfig b/arch/Kconfig
index a3308a220f86413085cdd101611b689078b998be..8e3fd723bd748c61ee8be402c4cda2c79c24b91b 100644 (file)
--- a/arch/Kconfig
+++ b/arch/Kconfig
@@ -435,6 +435,13 @@ config HAVE_HARDLOCKUP_DETECTOR_ARCH
          It uses the same command line parameters, and sysctl interface,
          as the generic hardlockup detectors.
 
+config UNWIND_USER
+       bool
+
+config HAVE_UNWIND_USER_FP
+       bool
+       select UNWIND_USER
+
 config HAVE_PERF_REGS
        bool
        help

diff --git a/include/asm-generic/Kbuild b/include/asm-generic/Kbuild
index 8675b7b4ad23ed8485ecb58f0a4a3e7750c6e0a8..295c94a3ccc1c23c71a705cdea96445a5ad2ba5f 100644 (file)
--- a/include/asm-generic/Kbuild
+++ b/include/asm-generic/Kbuild
@@ -59,6 +59,7 @@ mandatory-y += tlbflush.h
 mandatory-y += topology.h
 mandatory-y += trace_clock.h
 mandatory-y += uaccess.h
+mandatory-y += unwind_user.h
 mandatory-y += vermagic.h
 mandatory-y += vga.h
 mandatory-y += video.h

diff --git a/include/asm-generic/unwind_user.h b/include/asm-generic/unwind_user.h
new file mode 100644 (file)
index 0000000..b8882b9
--- /dev/null
+++ b/include/asm-generic/unwind_user.h
@@ -0,0 +1,5 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+#ifndef _ASM_GENERIC_UNWIND_USER_H
+#define _ASM_GENERIC_UNWIND_USER_H
+
+#endif /* _ASM_GENERIC_UNWIND_USER_H */

diff --git a/include/linux/unwind_user.h b/include/linux/unwind_user.h
new file mode 100644 (file)
index 0000000..7f72825
--- /dev/null
+++ b/include/linux/unwind_user.h
@@ -0,0 +1,14 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+#ifndef _LINUX_UNWIND_USER_H
+#define _LINUX_UNWIND_USER_H
+
+#include <linux/unwind_user_types.h>
+#include <asm/unwind_user.h>
+
+#ifndef ARCH_INIT_USER_FP_FRAME
+ #define ARCH_INIT_USER_FP_FRAME
+#endif
+
+int unwind_user(struct unwind_stacktrace *trace, unsigned int max_entries);
+
+#endif /* _LINUX_UNWIND_USER_H */

diff --git a/include/linux/unwind_user_types.h b/include/linux/unwind_user_types.h
new file mode 100644 (file)
index 0000000..a449f15
--- /dev/null
+++ b/include/linux/unwind_user_types.h
@@ -0,0 +1,44 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+#ifndef _LINUX_UNWIND_USER_TYPES_H
+#define _LINUX_UNWIND_USER_TYPES_H
+
+#include <linux/types.h>
+
+/*
+ * Unwind types, listed in priority order: lower numbers are attempted first if
+ * available.
+ */
+enum unwind_user_type_bits {
+       UNWIND_USER_TYPE_FP_BIT =               0,
+
+       NR_UNWIND_USER_TYPE_BITS,
+};
+
+enum unwind_user_type {
+       /* Type "none" for the start of stack walk iteration. */
+       UNWIND_USER_TYPE_NONE =                 0,
+       UNWIND_USER_TYPE_FP =                   BIT(UNWIND_USER_TYPE_FP_BIT),
+};
+
+struct unwind_stacktrace {
+       unsigned int    nr;
+       unsigned long   *entries;
+};
+
+struct unwind_user_frame {
+       s32 cfa_off;
+       s32 ra_off;
+       s32 fp_off;
+       bool use_fp;
+};
+
+struct unwind_user_state {
+       unsigned long                           ip;
+       unsigned long                           sp;
+       unsigned long                           fp;
+       enum unwind_user_type                   current_type;
+       unsigned int                            available_types;
+       bool                                    done;
+};
+
+#endif /* _LINUX_UNWIND_USER_TYPES_H */

diff --git a/kernel/Makefile b/kernel/Makefile
index 32e80dd626af07d0c43290e3f5c64af5bff07b51..5411860502514a934d77bd8cbfc32a7a125cc375 100644 (file)
--- a/kernel/Makefile
+++ b/kernel/Makefile
@@ -55,6 +55,7 @@ obj-y += rcu/
 obj-y += livepatch/
 obj-y += dma/
 obj-y += entry/
+obj-y += unwind/
 obj-$(CONFIG_MODULES) += module/
 
 obj-$(CONFIG_KCMP) += kcmp.o

diff --git a/kernel/unwind/Makefile b/kernel/unwind/Makefile
new file mode 100644 (file)
index 0000000..349ce36
--- /dev/null
+++ b/kernel/unwind/Makefile
@@ -0,0 +1 @@
+ obj-$(CONFIG_UNWIND_USER) += user.o

diff --git a/kernel/unwind/user.c b/kernel/unwind/user.c
new file mode 100644 (file)
index 0000000..97a8415
--- /dev/null
+++ b/kernel/unwind/user.c
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+* Generic interfaces for unwinding user space
+*/
+#include <linux/kernel.h>
+#include <linux/sched.h>
+#include <linux/sched/task_stack.h>
+#include <linux/unwind_user.h>
+#include <linux/uaccess.h>
+
+static const struct unwind_user_frame fp_frame = {
+       ARCH_INIT_USER_FP_FRAME
+};
+
+#define for_each_user_frame(state) \
+       for (unwind_user_start(state); !(state)->done; unwind_user_next(state))
+
+static int unwind_user_next_fp(struct unwind_user_state *state)
+{
+       const struct unwind_user_frame *frame = &fp_frame;
+       unsigned long cfa, fp, ra;
+       unsigned int shift;
+
+       if (frame->use_fp) {
+               if (state->fp < state->sp)
+                       return -EINVAL;
+               cfa = state->fp;
+       } else {
+               cfa = state->sp;
+       }
+
+       /* Get the Canonical Frame Address (CFA) */
+       cfa += frame->cfa_off;
+
+       /* stack going in wrong direction? */
+       if (cfa <= state->sp)
+               return -EINVAL;
+
+       /* Make sure that the address is word aligned */
+       shift = sizeof(long) == 4 ? 2 : 3;
+       if (cfa & ((1 << shift) - 1))
+               return -EINVAL;
+
+       /* Find the Return Address (RA) */
+       if (get_user(ra, (unsigned long *)(cfa + frame->ra_off)))
+               return -EINVAL;
+
+       if (frame->fp_off && get_user(fp, (unsigned long __user *)(cfa + frame->fp_off)))
+               return -EINVAL;
+
+       state->ip = ra;
+       state->sp = cfa;
+       if (frame->fp_off)
+               state->fp = fp;
+       return 0;
+}
+
+static int unwind_user_next(struct unwind_user_state *state)
+{
+       unsigned long iter_mask = state->available_types;
+       unsigned int bit;
+
+       if (state->done)
+               return -EINVAL;
+
+       for_each_set_bit(bit, &iter_mask, NR_UNWIND_USER_TYPE_BITS) {
+               enum unwind_user_type type = BIT(bit);
+
+               state->current_type = type;
+               switch (type) {
+               case UNWIND_USER_TYPE_FP:
+                       if (!unwind_user_next_fp(state))
+                               return 0;
+                       continue;
+               default:
+                       WARN_ONCE(1, "Undefined unwind bit %d", bit);
+                       break;
+               }
+               break;
+       }
+
+       /* No successful unwind method. */
+       state->current_type = UNWIND_USER_TYPE_NONE;
+       state->done = true;
+       return -EINVAL;
+}
+
+static int unwind_user_start(struct unwind_user_state *state)
+{
+       struct pt_regs *regs = task_pt_regs(current);
+
+       memset(state, 0, sizeof(*state));
+
+       if ((current->flags & PF_KTHREAD) || !user_mode(regs)) {
+               state->done = true;
+               return -EINVAL;
+       }
+
+       if (IS_ENABLED(CONFIG_HAVE_UNWIND_USER_FP))
+               state->available_types |= UNWIND_USER_TYPE_FP;
+
+       state->ip = instruction_pointer(regs);
+       state->sp = user_stack_pointer(regs);
+       state->fp = frame_pointer(regs);
+
+       return 0;
+}
+
+int unwind_user(struct unwind_stacktrace *trace, unsigned int max_entries)
+{
+       struct unwind_user_state state;
+
+       trace->nr = 0;
+
+       if (!max_entries)
+               return -EINVAL;
+
+       if (current->flags & PF_KTHREAD)
+               return 0;
+
+       for_each_user_frame(&state) {
+               trace->entries[trace->nr++] = state.ip;
+               if (trace->nr >= max_entries)
+                       break;
+       }
+
+       return 0;
+}