kfence.h

  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
 20extern 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)
 28extern char *__kfence_pool;
 29
 30DECLARE_STATIC_KEY_FALSE(kfence_allocation_key);
 31extern 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 */
 51static __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 */
 65void __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 */
 73void __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 */
 94void 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 */
100void *__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 */
118static __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 */
144size_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 */
158void *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 */
168void __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 */
183static __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 */
206bool __must_check kfence_handle_page_fault(unsigned long addr, bool is_write, struct pt_regs *regs);
207
208#ifdef CONFIG_PRINTK
209struct 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 * @slab: the slab
215 *
216 * Return:
217 * * false - not a KFENCE object
218 * * true - a KFENCE object, filled @kpp
219 *
220 * Copies information to @kpp for KFENCE objects.
221 */
222bool __kfence_obj_info(struct kmem_obj_info *kpp, void *object, struct slab *slab);
223#endif
224
225#else /* CONFIG_KFENCE */
226
227#define kfence_sample_interval	(0)
228
229static inline bool is_kfence_address(const void *addr) { return false; }
230static inline void kfence_alloc_pool_and_metadata(void) { }
231static inline void kfence_init(void) { }
232static inline void kfence_shutdown_cache(struct kmem_cache *s) { }
233static inline void *kfence_alloc(struct kmem_cache *s, size_t size, gfp_t flags) { return NULL; }
234static inline size_t kfence_ksize(const void *addr) { return 0; }
235static inline void *kfence_object_start(const void *addr) { return NULL; }
236static inline void __kfence_free(void *addr) { }
237static inline bool __must_check kfence_free(void *addr) { return false; }
238static inline bool __must_check kfence_handle_page_fault(unsigned long addr, bool is_write,
239							 struct pt_regs *regs)
240{
241	return false;
242}
243
244#ifdef CONFIG_PRINTK
245struct kmem_obj_info;
246static inline bool __kfence_obj_info(struct kmem_obj_info *kpp, void *object, struct slab *slab)
247{
248	return false;
249}
250#endif
251
252#endif
253
254#endif /* _LINUX_KFENCE_H */