Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
tjh.dev
kernel
os
linux
1/* SPDX-License-Identifier: GPL-2.0-or-later */
2/*
3 * Stack depot - a stack trace storage that avoids duplication.
4 *
5 * Stack depot is intended to be used by subsystems that need to store and
6 * later retrieve many potentially duplicated stack traces without wasting
7 * memory.
8 *
9 * For example, KASAN needs to save allocation and free stack traces for each
10 * object. Storing two stack traces per object requires a lot of memory (e.g.
11 * SLUB_DEBUG needs 256 bytes per object for that). Since allocation and free
12 * stack traces often repeat, using stack depot allows to save about 100x space.
13 *
14 * Author: Alexander Potapenko <glider@google.com>
15 * Copyright (C) 2016 Google, Inc.
16 *
17 * Based on the code by Dmitry Chernenkov.
18 */
19
20#ifndef _LINUX_STACKDEPOT_H
21#define _LINUX_STACKDEPOT_H
22
23#include <linux/gfp.h>
24
25typedef u32 depot_stack_handle_t;
26
27/*
28 * Number of bits in the handle that stack depot doesn't use. Users may store
29 * information in them via stack_depot_set/get_extra_bits.
30 */
31#define STACK_DEPOT_EXTRA_BITS 5
32
33typedef u32 depot_flags_t;
34
35/*
36 * Flags that can be passed to stack_depot_save_flags(); see the comment next
37 * to its declaration for more details.
38 */
39#define STACK_DEPOT_FLAG_CAN_ALLOC ((depot_flags_t)0x0001)
40#define STACK_DEPOT_FLAG_GET ((depot_flags_t)0x0002)
41
42#define STACK_DEPOT_FLAGS_NUM 2
43#define STACK_DEPOT_FLAGS_MASK ((depot_flags_t)((1 << STACK_DEPOT_FLAGS_NUM) - 1))
44
45/*
46 * Using stack depot requires its initialization, which can be done in 3 ways:
47 *
48 * 1. Selecting CONFIG_STACKDEPOT_ALWAYS_INIT. This option is suitable in
49 * scenarios where it's known at compile time that stack depot will be used.
50 * Enabling this config makes the kernel initialize stack depot in mm_init().
51 *
52 * 2. Calling stack_depot_request_early_init() during early boot, before
53 * stack_depot_early_init() in mm_init() completes. For example, this can
54 * be done when evaluating kernel boot parameters.
55 *
56 * 3. Calling stack_depot_init(). Possible after boot is complete. This option
57 * is recommended for modules initialized later in the boot process, after
58 * mm_init() completes.
59 *
60 * stack_depot_init() and stack_depot_request_early_init() can be called
61 * regardless of whether CONFIG_STACKDEPOT is enabled and are no-op when this
62 * config is disabled. The save/fetch/print stack depot functions can only be
63 * called from the code that makes sure CONFIG_STACKDEPOT is enabled _and_
64 * initializes stack depot via one of the ways listed above.
65 */
66#ifdef CONFIG_STACKDEPOT
67int stack_depot_init(void);
68
69void __init stack_depot_request_early_init(void);
70
71/* Must be only called from mm_init(). */
72int __init stack_depot_early_init(void);
73#else
74static inline int stack_depot_init(void) { return 0; }
75
76static inline void stack_depot_request_early_init(void) { }
77
78static inline int stack_depot_early_init(void) { return 0; }
79#endif
80
81/**
82 * stack_depot_save_flags - Save a stack trace to stack depot
83 *
84 * @entries: Pointer to the stack trace
85 * @nr_entries: Number of frames in the stack
86 * @alloc_flags: Allocation GFP flags
87 * @depot_flags: Stack depot flags
88 *
89 * Saves a stack trace from @entries array of size @nr_entries.
90 *
91 * If STACK_DEPOT_FLAG_CAN_ALLOC is set in @depot_flags, stack depot can
92 * replenish the stack pools in case no space is left (allocates using GFP
93 * flags of @alloc_flags). Otherwise, stack depot avoids any allocations and
94 * fails if no space is left to store the stack trace.
95 *
96 * If STACK_DEPOT_FLAG_GET is set in @depot_flags, stack depot will increment
97 * the refcount on the saved stack trace if it already exists in stack depot.
98 * Users of this flag must also call stack_depot_put() when keeping the stack
99 * trace is no longer required to avoid overflowing the refcount.
100 *
101 * If the provided stack trace comes from the interrupt context, only the part
102 * up to the interrupt entry is saved.
103 *
104 * Context: Any context, but setting STACK_DEPOT_FLAG_CAN_ALLOC is required if
105 * alloc_pages() cannot be used from the current context. Currently
106 * this is the case for contexts where neither %GFP_ATOMIC nor
107 * %GFP_NOWAIT can be used (NMI, raw_spin_lock).
108 *
109 * Return: Handle of the stack struct stored in depot, 0 on failure
110 */
111depot_stack_handle_t stack_depot_save_flags(unsigned long *entries,
112 unsigned int nr_entries,
113 gfp_t gfp_flags,
114 depot_flags_t depot_flags);
115
116/**
117 * stack_depot_save - Save a stack trace to stack depot
118 *
119 * @entries: Pointer to the stack trace
120 * @nr_entries: Number of frames in the stack
121 * @alloc_flags: Allocation GFP flags
122 *
123 * Does not increment the refcount on the saved stack trace; see
124 * stack_depot_save_flags() for more details.
125 *
126 * Context: Contexts where allocations via alloc_pages() are allowed;
127 * see stack_depot_save_flags() for more details.
128 *
129 * Return: Handle of the stack trace stored in depot, 0 on failure
130 */
131depot_stack_handle_t stack_depot_save(unsigned long *entries,
132 unsigned int nr_entries, gfp_t gfp_flags);
133
134/**
135 * stack_depot_fetch - Fetch a stack trace from stack depot
136 *
137 * @handle: Stack depot handle returned from stack_depot_save()
138 * @entries: Pointer to store the address of the stack trace
139 *
140 * Return: Number of frames for the fetched stack
141 */
142unsigned int stack_depot_fetch(depot_stack_handle_t handle,
143 unsigned long **entries);
144
145/**
146 * stack_depot_print - Print a stack trace from stack depot
147 *
148 * @stack: Stack depot handle returned from stack_depot_save()
149 */
150void stack_depot_print(depot_stack_handle_t stack);
151
152/**
153 * stack_depot_snprint - Print a stack trace from stack depot into a buffer
154 *
155 * @handle: Stack depot handle returned from stack_depot_save()
156 * @buf: Pointer to the print buffer
157 * @size: Size of the print buffer
158 * @spaces: Number of leading spaces to print
159 *
160 * Return: Number of bytes printed
161 */
162int stack_depot_snprint(depot_stack_handle_t handle, char *buf, size_t size,
163 int spaces);
164
165/**
166 * stack_depot_put - Drop a reference to a stack trace from stack depot
167 *
168 * @handle: Stack depot handle returned from stack_depot_save()
169 *
170 * The stack trace is evicted from stack depot once all references to it have
171 * been dropped (once the number of stack_depot_evict() calls matches the
172 * number of stack_depot_save_flags() calls with STACK_DEPOT_FLAG_GET set for
173 * this stack trace).
174 */
175void stack_depot_put(depot_stack_handle_t handle);
176
177/**
178 * stack_depot_set_extra_bits - Set extra bits in a stack depot handle
179 *
180 * @handle: Stack depot handle returned from stack_depot_save()
181 * @extra_bits: Value to set the extra bits
182 *
183 * Return: Stack depot handle with extra bits set
184 *
185 * Stack depot handles have a few unused bits, which can be used for storing
186 * user-specific information. These bits are transparent to the stack depot.
187 */
188depot_stack_handle_t __must_check stack_depot_set_extra_bits(
189 depot_stack_handle_t handle, unsigned int extra_bits);
190
191/**
192 * stack_depot_get_extra_bits - Retrieve extra bits from a stack depot handle
193 *
194 * @handle: Stack depot handle with extra bits saved
195 *
196 * Return: Extra bits retrieved from the stack depot handle
197 */
198unsigned int stack_depot_get_extra_bits(depot_stack_handle_t handle);
199
200#endif