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