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  */
is_kfence_address(const void * addr)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  */
kfence_alloc(struct kmem_cache * s,size_t size,gfp_t flags)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) > 0))
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  */
kfence_free(void * addr)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 #define kfence_sample_interval	(0)
227 
is_kfence_address(const void * addr)228 static inline bool is_kfence_address(const void *addr) { return false; }
kfence_alloc_pool_and_metadata(void)229 static inline void kfence_alloc_pool_and_metadata(void) { }
kfence_init(void)230 static inline void kfence_init(void) { }
kfence_shutdown_cache(struct kmem_cache * s)231 static inline void kfence_shutdown_cache(struct kmem_cache *s) { }
kfence_alloc(struct kmem_cache * s,size_t size,gfp_t flags)232 static inline void *kfence_alloc(struct kmem_cache *s, size_t size, gfp_t flags) { return NULL; }
kfence_ksize(const void * addr)233 static inline size_t kfence_ksize(const void *addr) { return 0; }
kfence_object_start(const void * addr)234 static inline void *kfence_object_start(const void *addr) { return NULL; }
__kfence_free(void * addr)235 static inline void __kfence_free(void *addr) { }
kfence_free(void * addr)236 static inline bool __must_check kfence_free(void *addr) { return false; }
kfence_handle_page_fault(unsigned long addr,bool is_write,struct pt_regs * regs)237 static inline bool __must_check kfence_handle_page_fault(unsigned long addr, bool is_write,
238 							 struct pt_regs *regs)
239 {
240 	return false;
241 }
242 
243 #ifdef CONFIG_PRINTK
244 struct kmem_obj_info;
__kfence_obj_info(struct kmem_obj_info * kpp,void * object,struct slab * slab)245 static inline bool __kfence_obj_info(struct kmem_obj_info *kpp, void *object, struct slab *slab)
246 {
247 	return false;
248 }
249 #endif
250 
251 #endif
252 
253 #endif /* _LINUX_KFENCE_H */
254