1 /* SPDX-License-Identifier: GPL-2.0-or-later * 1
2 /*
3 * Stack depot - a stack trace storage that av
4 *
5 * Stack depot is intended to be used by subsy
6 * later retrieve many potentially duplicated
7 * memory.
8 *
9 * For example, KASAN needs to save allocation
10 * object. Storing two stack traces per object
11 * SLUB_DEBUG needs 256 bytes per object for t
12 * stack traces often repeat, using stack depo
13 *
14 * Author: Alexander Potapenko <glider@google.
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
25 typedef u32 depot_stack_handle_t;
26
27 /*
28 * Number of bits in the handle that stack dep
29 * information in them via stack_depot_set/get
30 */
31 #define STACK_DEPOT_EXTRA_BITS 5
32
33 #define DEPOT_HANDLE_BITS (sizeof(depot_stack_
34
35 #define DEPOT_POOL_ORDER 2 /* Pool size order,
36 #define DEPOT_POOL_SIZE (1LL << (PAGE_SHIFT +
37 #define DEPOT_STACK_ALIGN 4
38 #define DEPOT_OFFSET_BITS (DEPOT_POOL_ORDER +
39 #define DEPOT_POOL_INDEX_BITS (DEPOT_HANDLE_BI
40 STACK_DEPOT_EXT
41
42 #ifdef CONFIG_STACKDEPOT
43 /* Compact structure that stores a reference t
44 union handle_parts {
45 depot_stack_handle_t handle;
46 struct {
47 u32 pool_index_plus_1 : DEPO
48 u32 offset : DEPO
49 u32 extra : STAC
50 };
51 };
52
53 struct stack_record {
54 struct list_head hash_list; /* Lin
55 u32 hash; /* Has
56 u32 size; /* Num
57 union handle_parts handle; /* Con
58 refcount_t count;
59 union {
60 unsigned long entries[CONFIG_S
61 struct {
62 /*
63 * An important invari
64 * only place a stack
65 * refcount is zero. B
66 * refcount are never
67 * union @entries and
68 * Conversely, as soon
69 * and its refcount be
70 * be accessed until b
71 */
72 struct list_head free_
73 unsigned long rcu_stat
74 };
75 };
76 };
77 #endif
78
79 typedef u32 depot_flags_t;
80
81 /*
82 * Flags that can be passed to stack_depot_sav
83 * to its declaration for more details.
84 */
85 #define STACK_DEPOT_FLAG_CAN_ALLOC ((depo
86 #define STACK_DEPOT_FLAG_GET ((depo
87
88 #define STACK_DEPOT_FLAGS_NUM 2
89 #define STACK_DEPOT_FLAGS_MASK ((depot_flags_
90
91 /*
92 * Using stack depot requires its initializati
93 *
94 * 1. Selecting CONFIG_STACKDEPOT_ALWAYS_INIT.
95 * scenarios where it's known at compile ti
96 * Enabling this config makes the kernel in
97 *
98 * 2. Calling stack_depot_request_early_init()
99 * stack_depot_early_init() in mm_init() co
100 * be done when evaluating kernel boot para
101 *
102 * 3. Calling stack_depot_init(). Possible aft
103 * is recommended for modules initialized l
104 * mm_init() completes.
105 *
106 * stack_depot_init() and stack_depot_request_
107 * regardless of whether CONFIG_STACKDEPOT is
108 * config is disabled. The save/fetch/print st
109 * called from the code that makes sure CONFIG
110 * initializes stack depot via one of the ways
111 */
112 #ifdef CONFIG_STACKDEPOT
113 int stack_depot_init(void);
114
115 void __init stack_depot_request_early_init(voi
116
117 /* Must be only called from mm_init(). */
118 int __init stack_depot_early_init(void);
119 #else
120 static inline int stack_depot_init(void) { ret
121
122 static inline void stack_depot_request_early_i
123
124 static inline int stack_depot_early_init(void)
125 #endif
126
127 /**
128 * stack_depot_save_flags - Save a stack trace
129 *
130 * @entries: Pointer to the stack t
131 * @nr_entries: Number of frames in th
132 * @alloc_flags: Allocation GFP flags
133 * @depot_flags: Stack depot flags
134 *
135 * Saves a stack trace from @entries array of
136 *
137 * If STACK_DEPOT_FLAG_CAN_ALLOC is set in @de
138 * replenish the stack pools in case no space
139 * flags of @alloc_flags). Otherwise, stack de
140 * fails if no space is left to store the stac
141 *
142 * If STACK_DEPOT_FLAG_GET is set in @depot_fl
143 * the refcount on the saved stack trace if it
144 * Users of this flag must also call stack_dep
145 * trace is no longer required to avoid overfl
146 *
147 * If the provided stack trace comes from the
148 * up to the interrupt entry is saved.
149 *
150 * Context: Any context, but setting STACK_DEP
151 * alloc_pages() cannot be used from
152 * this is the case for contexts wher
153 * %GFP_NOWAIT can be used (NMI, raw_
154 *
155 * Return: Handle of the stack struct stored i
156 */
157 depot_stack_handle_t stack_depot_save_flags(un
158 un
159 gf
160 de
161
162 /**
163 * stack_depot_save - Save a stack trace to st
164 *
165 * @entries: Pointer to the stack t
166 * @nr_entries: Number of frames in th
167 * @alloc_flags: Allocation GFP flags
168 *
169 * Does not increment the refcount on the save
170 * stack_depot_save_flags() for more details.
171 *
172 * Context: Contexts where allocations via all
173 * see stack_depot_save_flags() for m
174 *
175 * Return: Handle of the stack trace stored in
176 */
177 depot_stack_handle_t stack_depot_save(unsigned
178 unsigned
179
180 /**
181 * __stack_depot_get_stack_record - Get a poin
182 *
183 * @handle: Stack depot handle
184 *
185 * This function is only for internal purposes
186 *
187 * Return: Returns a pointer to a stack_record
188 */
189 struct stack_record *__stack_depot_get_stack_r
190
191 /**
192 * stack_depot_fetch - Fetch a stack trace fro
193 *
194 * @handle: Stack depot handle returned fr
195 * @entries: Pointer to store the address o
196 *
197 * Return: Number of frames for the fetched st
198 */
199 unsigned int stack_depot_fetch(depot_stack_han
200 unsigned long *
201
202 /**
203 * stack_depot_print - Print a stack trace fro
204 *
205 * @stack: Stack depot handle returned fr
206 */
207 void stack_depot_print(depot_stack_handle_t st
208
209 /**
210 * stack_depot_snprint - Print a stack trace f
211 *
212 * @handle: Stack depot handle returned fr
213 * @buf: Pointer to the print buffer
214 * @size: Size of the print buffer
215 * @spaces: Number of leading spaces to pr
216 *
217 * Return: Number of bytes printed
218 */
219 int stack_depot_snprint(depot_stack_handle_t h
220 int spaces);
221
222 /**
223 * stack_depot_put - Drop a reference to a sta
224 *
225 * @handle: Stack depot handle returned fr
226 *
227 * The stack trace is evicted from stack depot
228 * been dropped (once the number of stack_depo
229 * number of stack_depot_save_flags() calls wi
230 * this stack trace).
231 */
232 void stack_depot_put(depot_stack_handle_t hand
233
234 /**
235 * stack_depot_set_extra_bits - Set extra bits
236 *
237 * @handle: Stack depot handle returned fr
238 * @extra_bits: Value to set the extra bits
239 *
240 * Return: Stack depot handle with extra bits
241 *
242 * Stack depot handles have a few unused bits,
243 * user-specific information. These bits are t
244 */
245 depot_stack_handle_t __must_check stack_depot_
246 depot_stack_handle_t h
247
248 /**
249 * stack_depot_get_extra_bits - Retrieve extra
250 *
251 * @handle: Stack depot handle with extra
252 *
253 * Return: Extra bits retrieved from the stack
254 */
255 unsigned int stack_depot_get_extra_bits(depot_
256
257 #endif
258
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.