1 | /* SPDX-License-Identifier: GPL-2.0 */ |
2 | /* |
3 | * Kernel Electric-Fence (KFENCE). Public interface for allocator and fault |
4 | * handler integration. For more info see Documentation/dev-tools/kfence.rst. |
5 | * |
6 | * Copyright (C) 2020, Google LLC. |
7 | */ |
8 | |
9 | #ifndef _LINUX_KFENCE_H |
10 | #define _LINUX_KFENCE_H |
11 | |
12 | #include <linux/mm.h> |
13 | #include <linux/types.h> |
14 | |
15 | #ifdef CONFIG_KFENCE |
16 | |
17 | #include <linux/atomic.h> |
18 | #include <linux/static_key.h> |
19 | |
20 | extern unsigned long kfence_sample_interval; |
21 | |
22 | /* |
23 | * We allocate an even number of pages, as it simplifies calculations to map |
24 | * address to metadata indices; effectively, the very first page serves as an |
25 | * extended guard page, but otherwise has no special purpose. |
26 | */ |
27 | #define KFENCE_POOL_SIZE ((CONFIG_KFENCE_NUM_OBJECTS + 1) * 2 * PAGE_SIZE) |
28 | extern char *__kfence_pool; |
29 | |
30 | DECLARE_STATIC_KEY_FALSE(kfence_allocation_key); |
31 | extern atomic_t kfence_allocation_gate; |
32 | |
33 | /** |
34 | * is_kfence_address() - check if an address belongs to KFENCE pool |
35 | * @addr: address to check |
36 | * |
37 | * Return: true or false depending on whether the address is within the KFENCE |
38 | * object range. |
39 | * |
40 | * KFENCE objects live in a separate page range and are not to be intermixed |
41 | * with regular heap objects (e.g. KFENCE objects must never be added to the |
42 | * allocator freelists). Failing to do so may and will result in heap |
43 | * corruptions, therefore is_kfence_address() must be used to check whether |
44 | * an object requires specific handling. |
45 | * |
46 | * Note: This function may be used in fast-paths, and is performance critical. |
47 | * Future changes should take this into account; for instance, we want to avoid |
48 | * introducing another load and therefore need to keep KFENCE_POOL_SIZE a |
49 | * constant (until immediate patching support is added to the kernel). |
50 | */ |
51 | static __always_inline bool is_kfence_address(const void *addr) |
52 | { |
53 | /* |
54 | * The __kfence_pool != NULL check is required to deal with the case |
55 | * where __kfence_pool == NULL && addr < KFENCE_POOL_SIZE. Keep it in |
56 | * the slow-path after the range-check! |
57 | */ |
58 | return unlikely((unsigned long)((char *)addr - __kfence_pool) < KFENCE_POOL_SIZE && __kfence_pool); |
59 | } |
60 | |
61 | /** |
62 | * kfence_alloc_pool_and_metadata() - allocate the KFENCE pool and KFENCE |
63 | * metadata via memblock |
64 | */ |
65 | void __init kfence_alloc_pool_and_metadata(void); |
66 | |
67 | /** |
68 | * kfence_init() - perform KFENCE initialization at boot time |
69 | * |
70 | * Requires that kfence_alloc_pool_and_metadata() was called before. This sets |
71 | * up the allocation gate timer, and requires that workqueues are available. |
72 | */ |
73 | void __init kfence_init(void); |
74 | |
75 | /** |
76 | * kfence_shutdown_cache() - handle shutdown_cache() for KFENCE objects |
77 | * @s: cache being shut down |
78 | * |
79 | * Before shutting down a cache, one must ensure there are no remaining objects |
80 | * allocated from it. Because KFENCE objects are not referenced from the cache |
81 | * directly, we need to check them here. |
82 | * |
83 | * Note that shutdown_cache() is internal to SL*B, and kmem_cache_destroy() does |
84 | * not return if allocated objects still exist: it prints an error message and |
85 | * simply aborts destruction of a cache, leaking memory. |
86 | * |
87 | * If the only such objects are KFENCE objects, we will not leak the entire |
88 | * cache, but instead try to provide more useful debug info by making allocated |
89 | * objects "zombie allocations". Objects may then still be used or freed (which |
90 | * is handled gracefully), but usage will result in showing KFENCE error reports |
91 | * which include stack traces to the user of the object, the original allocation |
92 | * site, and caller to shutdown_cache(). |
93 | */ |
94 | void kfence_shutdown_cache(struct kmem_cache *s); |
95 | |
96 | /* |
97 | * Allocate a KFENCE object. Allocators must not call this function directly, |
98 | * use kfence_alloc() instead. |
99 | */ |
100 | void *__kfence_alloc(struct kmem_cache *s, size_t size, gfp_t flags); |
101 | |
102 | /** |
103 | * kfence_alloc() - allocate a KFENCE object with a low probability |
104 | * @s: struct kmem_cache with object requirements |
105 | * @size: exact size of the object to allocate (can be less than @s->size |
106 | * e.g. for kmalloc caches) |
107 | * @flags: GFP flags |
108 | * |
109 | * Return: |
110 | * * NULL - must proceed with allocating as usual, |
111 | * * non-NULL - pointer to a KFENCE object. |
112 | * |
113 | * kfence_alloc() should be inserted into the heap allocation fast path, |
114 | * allowing it to transparently return KFENCE-allocated objects with a low |
115 | * probability using a static branch (the probability is controlled by the |
116 | * kfence.sample_interval boot parameter). |
117 | */ |
118 | static __always_inline void *kfence_alloc(struct kmem_cache *s, size_t size, gfp_t flags) |
119 | { |
120 | #if defined(CONFIG_KFENCE_STATIC_KEYS) || CONFIG_KFENCE_SAMPLE_INTERVAL == 0 |
121 | if (!static_branch_unlikely(&kfence_allocation_key)) |
122 | return NULL; |
123 | #else |
124 | if (!static_branch_likely(&kfence_allocation_key)) |
125 | return NULL; |
126 | #endif |
127 | if (likely(atomic_read(&kfence_allocation_gate))) |
128 | return NULL; |
129 | return __kfence_alloc(s, size, flags); |
130 | } |
131 | |
132 | /** |
133 | * kfence_ksize() - get actual amount of memory allocated for a KFENCE object |
134 | * @addr: pointer to a heap object |
135 | * |
136 | * Return: |
137 | * * 0 - not a KFENCE object, must call __ksize() instead, |
138 | * * non-0 - this many bytes can be accessed without causing a memory error. |
139 | * |
140 | * kfence_ksize() returns the number of bytes requested for a KFENCE object at |
141 | * allocation time. This number may be less than the object size of the |
142 | * corresponding struct kmem_cache. |
143 | */ |
144 | size_t kfence_ksize(const void *addr); |
145 | |
146 | /** |
147 | * kfence_object_start() - find the beginning of a KFENCE object |
148 | * @addr: address within a KFENCE-allocated object |
149 | * |
150 | * Return: address of the beginning of the object. |
151 | * |
152 | * SL[AU]B-allocated objects are laid out within a page one by one, so it is |
153 | * easy to calculate the beginning of an object given a pointer inside it and |
154 | * the object size. The same is not true for KFENCE, which places a single |
155 | * object at either end of the page. This helper function is used to find the |
156 | * beginning of a KFENCE-allocated object. |
157 | */ |
158 | void *kfence_object_start(const void *addr); |
159 | |
160 | /** |
161 | * __kfence_free() - release a KFENCE heap object to KFENCE pool |
162 | * @addr: object to be freed |
163 | * |
164 | * Requires: is_kfence_address(addr) |
165 | * |
166 | * Release a KFENCE object and mark it as freed. |
167 | */ |
168 | void __kfence_free(void *addr); |
169 | |
170 | /** |
171 | * kfence_free() - try to release an arbitrary heap object to KFENCE pool |
172 | * @addr: object to be freed |
173 | * |
174 | * Return: |
175 | * * false - object doesn't belong to KFENCE pool and was ignored, |
176 | * * true - object was released to KFENCE pool. |
177 | * |
178 | * Release a KFENCE object and mark it as freed. May be called on any object, |
179 | * even non-KFENCE objects, to simplify integration of the hooks into the |
180 | * allocator's free codepath. The allocator must check the return value to |
181 | * determine if it was a KFENCE object or not. |
182 | */ |
183 | static __always_inline __must_check bool kfence_free(void *addr) |
184 | { |
185 | if (!is_kfence_address(addr)) |
186 | return false; |
187 | __kfence_free(addr); |
188 | return true; |
189 | } |
190 | |
191 | /** |
192 | * kfence_handle_page_fault() - perform page fault handling for KFENCE pages |
193 | * @addr: faulting address |
194 | * @is_write: is access a write |
195 | * @regs: current struct pt_regs (can be NULL, but shows full stack trace) |
196 | * |
197 | * Return: |
198 | * * false - address outside KFENCE pool, |
199 | * * true - page fault handled by KFENCE, no additional handling required. |
200 | * |
201 | * A page fault inside KFENCE pool indicates a memory error, such as an |
202 | * out-of-bounds access, a use-after-free or an invalid memory access. In these |
203 | * cases KFENCE prints an error message and marks the offending page as |
204 | * present, so that the kernel can proceed. |
205 | */ |
206 | bool __must_check kfence_handle_page_fault(unsigned long addr, bool is_write, struct pt_regs *regs); |
207 | |
208 | #ifdef CONFIG_PRINTK |
209 | struct kmem_obj_info; |
210 | /** |
211 | * __kfence_obj_info() - fill kmem_obj_info struct |
212 | * @kpp: kmem_obj_info to be filled |
213 | * @object: the object |
214 | * |
215 | * Return: |
216 | * * false - not a KFENCE object |
217 | * * true - a KFENCE object, filled @kpp |
218 | * |
219 | * Copies information to @kpp for KFENCE objects. |
220 | */ |
221 | bool __kfence_obj_info(struct kmem_obj_info *kpp, void *object, struct slab *slab); |
222 | #endif |
223 | |
224 | #else /* CONFIG_KFENCE */ |
225 | |
226 | static inline bool is_kfence_address(const void *addr) { return false; } |
227 | static inline void kfence_alloc_pool_and_metadata(void) { } |
228 | static inline void kfence_init(void) { } |
229 | static inline void kfence_shutdown_cache(struct kmem_cache *s) { } |
230 | static inline void *kfence_alloc(struct kmem_cache *s, size_t size, gfp_t flags) { return NULL; } |
231 | static inline size_t kfence_ksize(const void *addr) { return 0; } |
232 | static inline void *kfence_object_start(const void *addr) { return NULL; } |
233 | static inline void __kfence_free(void *addr) { } |
234 | static inline bool __must_check kfence_free(void *addr) { return false; } |
235 | static inline bool __must_check kfence_handle_page_fault(unsigned long addr, bool is_write, |
236 | struct pt_regs *regs) |
237 | { |
238 | return false; |
239 | } |
240 | |
241 | #ifdef CONFIG_PRINTK |
242 | struct kmem_obj_info; |
243 | static inline bool __kfence_obj_info(struct kmem_obj_info *kpp, void *object, struct slab *slab) |
244 | { |
245 | return false; |
246 | } |
247 | #endif |
248 | |
249 | #endif |
250 | |
251 | #endif /* _LINUX_KFENCE_H */ |
252 | |