Heap KASAN APIs

Macros
#define	SYS_HEAP_KASAN_SHADOW_BITS(_sz)
	Shadow bits required for a heap of _sz bytes (one bit per granule).
#define	SYS_HEAP_KASAN_SHADOW_BUNDLES(_sz)
	uint32_t bundle count for the shadow of a heap of _sz bytes.
#define	SYS_HEAP_KASAN_ENABLE(_heap_name, _heap_sz)
	Enable KASAN shadow tracking on a struct sys_heap.
#define	K_HEAP_KASAN_ENABLE(_heap_name, _heap_sz)
	Enable KASAN shadow tracking on a struct k_heap (K_HEAP_DEFINE).

Functions
void	heap_kasan_report (uintptr_t addr, size_t size)
	Report a heap KASAN violation.
void	heap_kasan_register (struct sys_heap *heap, sys_bitarray_t *ba)
	Associate a shadow bitarray with a heap for KASAN tracking.

Detailed Description

Macro Definition Documentation

K_HEAP_KASAN_ENABLE

#define K_HEAP_KASAN_ENABLE	(		_heap_name,
			_heap_sz )

#include <zephyr/sys/heap_kasan.h>

Value:

static uint32_t _heap_name##_kasan_bundles[SYS_HEAP_KASAN_SHADOW_BUNDLES( \
        MAX(_heap_sz, Z_HEAP_MIN_SIZE))] __noinit __aligned(4); \
static sys_bitarray_t _heap_name##_kasan_ba = { \
        .num_bits = SYS_HEAP_KASAN_SHADOW_BITS(MAX(_heap_sz, Z_HEAP_MIN_SIZE)), \
        .num_bundles = SYS_HEAP_KASAN_SHADOW_BUNDLES(MAX(_heap_sz, Z_HEAP_MIN_SIZE)), \
        .bundles = _heap_name##_kasan_bundles, \
}; \
static int _heap_name##_kasan_init_fn(void) \
{ \
        heap_kasan_register(&(_heap_name).heap, &_heap_name##_kasan_ba); \
        return 0; \
} \
SYS_INIT(_heap_name##_kasan_init_fn, PRE_KERNEL_1, 0)

Enable KASAN shadow tracking on a struct k_heap (K_HEAP_DEFINE).

Place at file scope after the K_HEAP_DEFINE line. Allocates a static shadow buffer and registers it with the heap at PRE_KERNEL_1 priority 0, before static heap init at (PRE_KERNEL_1, CONFIG_KERNEL_INIT_PRIORITY_OBJECTS).

Parameters

_heap_name	k_heap variable name.
_heap_sz	Same size passed to K_HEAP_DEFINE (compile-time constant).

Sample usage:

K_HEAP_DEFINE(my_heap, 4096);
K_HEAP_KASAN_ENABLE(my_heap, 4096);

SYS_HEAP_KASAN_ENABLE

#define SYS_HEAP_KASAN_ENABLE	(		_heap_name,
			_heap_sz )

#include <zephyr/sys/heap_kasan.h>

Value:

static uint32_t \
        _heap_name##_kasan_bundles[SYS_HEAP_KASAN_SHADOW_BUNDLES(_heap_sz)] __noinit \
        __aligned(4); \
static sys_bitarray_t _heap_name##_kasan_ba = { \
        .num_bits = SYS_HEAP_KASAN_SHADOW_BITS(_heap_sz), \
        .num_bundles = SYS_HEAP_KASAN_SHADOW_BUNDLES(_heap_sz), \
        .bundles = _heap_name##_kasan_bundles, \
}; \
static int _heap_name##_kasan_init_fn(void) \
{ \
        heap_kasan_register(&(_heap_name), &_heap_name##_kasan_ba); \
        return 0; \
} \
SYS_INIT(_heap_name##_kasan_init_fn, PRE_KERNEL_1, 0)

Enable KASAN shadow tracking on a struct sys_heap.

Place at file scope after the sys_heap declaration. Allocates a static shadow buffer and registers it with the heap at PRE_KERNEL_1 priority 0. sys_heap_init() must be called after.

Parameters

_heap_name	sys_heap variable name.
_heap_sz	Heap buffer size in bytes (compile-time constant).

Sample usage:

static char heap_buf[4096];
static struct sys_heap my_heap;
 
SYS_HEAP_KASAN_ENABLE(my_heap, sizeof(heap_buf));
 
// call sys_heap_init(&my_heap, heap_buf, sizeof(heap_buf)) at runtime

SYS_HEAP_KASAN_SHADOW_BITS

#define SYS_HEAP_KASAN_SHADOW_BITS

(

_sz

)

#include <zephyr/sys/heap_kasan.h>

Value:

((_sz) / SYS_HEAP_KASAN_GRANULE)

Shadow bits required for a heap of _sz bytes (one bit per granule).

SYS_HEAP_KASAN_SHADOW_BUNDLES

#define SYS_HEAP_KASAN_SHADOW_BUNDLES

(

_sz

)

#include <zephyr/sys/heap_kasan.h>

Value:

DIV_ROUND_UP(SYS_HEAP_KASAN_SHADOW_BITS(_sz), 32)

uint32_t bundle count for the shadow of a heap of _sz bytes.

Function Documentation

heap_kasan_register()

void heap_kasan_register	(	struct sys_heap *	heap,
		sys_bitarray_t *	ba )

#include <zephyr/sys/heap_kasan.h>

Associate a shadow bitarray with a heap for KASAN tracking.

Enables KASAN shadow tracking on a heap that was not registered at build time via SYS_HEAP_KASAN_ENABLE() or K_HEAP_KASAN_ENABLE(). Useful for dynamically created heaps.

Warning

Must be called before sys_heap_init(). Calling after sys_heap_init() has no effect and the heap will not be tracked.

Parameters

heap	sys_heap to track.
ba	Shadow bitarray; must have at least SYS_HEAP_KASAN_SHADOW_BITS(heap_size) bits backed by SYS_HEAP_KASAN_SHADOW_BUNDLES(heap_size) uint32_t bundles.

heap_kasan_report()

void heap_kasan_report	(	uintptr_t	addr,
		size_t	size )

#include <zephyr/sys/heap_kasan.h>

Report a heap KASAN violation.

Weak default calls k_panic(). Override in test code to intercept violations without triggering a panic.

Parameters

addr	Violating address.
size	Write size in bytes.