include/linux/kfence.h

1 /* SPDX-License-Identifier: GPL-2.0 */
3  * Kernel Electric-Fence (KFENCE). Public interface for allocator and fault
4  * handler integration. For more info see Documentation/dev-tools/kfence.rst.
34  * is_kfence_address() - check if an address belongs to KFENCE pool
40  * KFENCE objects live in a separate page range and are not to be intermixed
46  * Note: This function may be used in fast-paths, and is performance critical.
48  * introducing another load and therefore need to keep KFENCE_POOL_SIZE a
55 	 * where __kfence_pool == NULL && addr < KFENCE_POOL_SIZE. Keep it in  in is_kfence_address()
56 	 * the slow-path after the range-check!  in is_kfence_address()
58 	return unlikely((unsigned long)((char *)addr - __kfence_pool) < KFENCE_POOL_SIZE && __kfence_pool);  in is_kfence_address()
62  * kfence_alloc_pool_and_metadata() - allocate the KFENCE pool and KFENCE
68  * kfence_init() - perform KFENCE initialization at boot time
76  * kfence_shutdown_cache() - handle shutdown_cache() for KFENCE objects
79  * Before shutting down a cache, one must ensure there are no remaining objects
85  * simply aborts destruction of a cache, leaking memory.
97  * Allocate a KFENCE object. Allocators must not call this function directly,
103  * kfence_alloc() - allocate a KFENCE object with a low probability
105  * @size:  exact size of the object to allocate (can be less than @s->size
110  * * NULL     - must proceed with allocating as usual,
111  * * non-NULL - pointer to a KFENCE object.
114  * allowing it to transparently return KFENCE-allocated objects with a low
115  * probability using a static branch (the probability is controlled by the
133  * kfence_ksize() - get actual amount of memory allocated for a KFENCE object
134  * @addr: pointer to a heap object
137  * * 0     - not a KFENCE object, must call __ksize() instead,
138  * * non-0 - this many bytes can be accessed without causing a memory error.
140  * kfence_ksize() returns the number of bytes requested for a KFENCE object at
147  * kfence_object_start() - find the beginning of a KFENCE object
148  * @addr: address within a KFENCE-allocated object
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
156  * beginning of a KFENCE-allocated object.
161  * __kfence_free() - release a KFENCE heap object to KFENCE pool
166  * Release a KFENCE object and mark it as freed.
171  * kfence_free() - try to release an arbitrary heap object to KFENCE pool
175  * * false - object doesn't belong to KFENCE pool and was ignored,
176  * * true  - object was released to KFENCE pool.
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
181  * determine if it was a KFENCE object or not.
192  * kfence_handle_page_fault() - perform page fault handling for KFENCE pages
194  * @is_write: is access a write
198  * * false - address outside KFENCE pool,
199  * * true  - page fault handled by KFENCE, no additional handling required.
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
211  * __kfence_obj_info() - fill kmem_obj_info struct
216  * * false - not a KFENCE object
217  * * true - a KFENCE object, filled @kpp