1/* SPDX-License-Identifier: GPL-2.0 */
  2/*
  3 * Kernel Electric-Fence (KFENCE). For more info please see
  4 * Documentation/dev-tools/kfence.rst.
  5 *
  6 * Copyright (C) 2020, Google LLC.
  7 */
  8
  9#ifndef MM_KFENCE_KFENCE_H
 10#define MM_KFENCE_KFENCE_H
 11
 12#include <linux/mm.h>
 13#include <linux/slab.h>
 14#include <linux/spinlock.h>
 15#include <linux/types.h>
 16
 17#include "../slab.h" /* for struct kmem_cache */
 18
 19/*
 20 * Get the canary byte pattern for @addr. Use a pattern that varies based on the
 21 * lower 3 bits of the address, to detect memory corruptions with higher
 22 * probability, where similar constants are used.
 23 */
 24#define KFENCE_CANARY_PATTERN(addr) ((u8)0xaa ^ (u8)((unsigned long)(addr) & 0x7))
 25
 26/* Maximum stack depth for reports. */
 27#define KFENCE_STACK_DEPTH 64
 28
 29/* KFENCE object states. */
 30enum kfence_object_state {
 31	KFENCE_OBJECT_UNUSED,		/* Object is unused. */
 32	KFENCE_OBJECT_ALLOCATED,	/* Object is currently allocated. */
 33	KFENCE_OBJECT_FREED,		/* Object was allocated, and then freed. */
 34};
 35
 36/* Alloc/free tracking information. */
 37struct kfence_track {
 38	pid_t pid;
 39	int num_stack_entries;
 40	unsigned long stack_entries[KFENCE_STACK_DEPTH];
 41};
 42
 43/* KFENCE metadata per guarded allocation. */
 44struct kfence_metadata {
 45	struct list_head list;		/* Freelist node; access under kfence_freelist_lock. */
 46	struct rcu_head rcu_head;	/* For delayed freeing. */
 47
 48	/*
 49	 * Lock protecting below data; to ensure consistency of the below data,
 50	 * since the following may execute concurrently: __kfence_alloc(),
 51	 * __kfence_free(), kfence_handle_page_fault(). However, note that we
 52	 * cannot grab the same metadata off the freelist twice, and multiple
 53	 * __kfence_alloc() cannot run concurrently on the same metadata.
 54	 */
 55	raw_spinlock_t lock;
 56
 57	/* The current state of the object; see above. */
 58	enum kfence_object_state state;
 59
 60	/*
 61	 * Allocated object address; cannot be calculated from size, because of
 62	 * alignment requirements.
 63	 *
 64	 * Invariant: ALIGN_DOWN(addr, PAGE_SIZE) is constant.
 65	 */
 66	unsigned long addr;
 67
 68	/*
 69	 * The size of the original allocation.
 70	 */
 71	size_t size;
 72
 73	/*
 74	 * The kmem_cache cache of the last allocation; NULL if never allocated
 75	 * or the cache has already been destroyed.
 76	 */
 77	struct kmem_cache *cache;
 78
 79	/*
 80	 * In case of an invalid access, the page that was unprotected; we
 81	 * optimistically only store one address.
 82	 */
 83	unsigned long unprotected_page;
 84
 85	/* Allocation and free stack information. */
 86	struct kfence_track alloc_track;
 87	struct kfence_track free_track;
 88};
 89
 90extern struct kfence_metadata kfence_metadata[CONFIG_KFENCE_NUM_OBJECTS];
 91
 92/* KFENCE error types for report generation. */
 93enum kfence_error_type {
 94	KFENCE_ERROR_OOB,		/* Detected a out-of-bounds access. */
 95	KFENCE_ERROR_UAF,		/* Detected a use-after-free access. */
 96	KFENCE_ERROR_CORRUPTION,	/* Detected a memory corruption on free. */
 97	KFENCE_ERROR_INVALID,		/* Invalid access of unknown type. */
 98	KFENCE_ERROR_INVALID_FREE,	/* Invalid free. */
 99};
100
101void kfence_report_error(unsigned long address, bool is_write, struct pt_regs *regs,
102			 const struct kfence_metadata *meta, enum kfence_error_type type);
103
104void kfence_print_object(struct seq_file *seq, const struct kfence_metadata *meta);
105
106#endif /* MM_KFENCE_KFENCE_H */