kfence.h 7.9 KB

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