Heaps

First-fit heaps over caller-provided memory regions. More...

Data Structures
struct	pbl_heap_lock
	Locking of a heap. More...
struct	pbl_heap
	Heap. More...

Typedefs
typedef void(*	pbl_heap_error_handler_t) (void *ptr)
	Handler of a heap error, called with the pointer being freed (double free) or the block where corruption was found.

Functions
void	pbl_heap_init (struct pbl_heap *heap, void *start, void *end, bool fuzz_on_free)
	Initialize a heap over a memory region, zeroing it.
void	pbl_heap_set_lock (struct pbl_heap *heap, struct pbl_heap_lock lock)
	Make a heap thread safe with a lock.
void	pbl_heap_set_double_free_handler (struct pbl_heap *heap, pbl_heap_error_handler_t handler)
	Set the function called on a double free, instead of asserting.
void	pbl_heap_set_corruption_handler (struct pbl_heap *heap, pbl_heap_error_handler_t handler)
	Set the function called when corruption is detected, instead of asserting.
void *	pbl_heap_alloc (struct pbl_heap *heap, size_t size, uintptr_t caller)
	Allocate memory.
void *	pbl_heap_zalloc (struct pbl_heap *heap, size_t size, uintptr_t caller)
	Allocate zeroed memory.
void *	pbl_heap_calloc (struct pbl_heap *heap, size_t count, size_t size, uintptr_t caller)
	Allocate a zeroed array.
void *	pbl_heap_realloc (struct pbl_heap *heap, void *ptr, size_t size, uintptr_t caller)
	Reallocate memory.
char *	pbl_heap_strdup (struct pbl_heap *heap, const char *s, uintptr_t caller)
	Duplicate a string.
void	pbl_heap_free (struct pbl_heap *heap, void *ptr, uintptr_t caller)
	Free memory, merging it with adjacent free blocks.
void	pbl_heap_oom (struct pbl_heap *heap, size_t size, uintptr_t caller)
	Report an allocation failure the caller cannot recover from.
void	pbl_heap_oom_handler (struct pbl_heap *heap, size_t size, uintptr_t caller)
	Handle an allocation failure the caller cannot recover from.
bool	pbl_heap_contains (const struct pbl_heap *heap, const void *ptr)
	Check whether an address is within a heap.
bool	pbl_heap_is_allocated (struct pbl_heap *heap, void *ptr)
	Check whether a pointer is an allocated block of a heap.
size_t	pbl_heap_size (const struct pbl_heap *heap)
	Get the size of a heap.
size_t	pbl_heap_used (const struct pbl_heap *heap)
	Get the number of allocated bytes, including block headers.
size_t	pbl_heap_min_headroom (const struct pbl_heap *heap)
	Get the smallest amount of free memory the heap has had.
void	pbl_heap_reset_high_water_mark (struct pbl_heap *heap)
	Restart the high water mark from the current usage.
void	pbl_heap_stats (struct pbl_heap *heap, unsigned int *used, unsigned int *free, unsigned int *max_free)
	Walk a heap to calculate its usage.
void	pbl_heap_dump (struct pbl_heap *heap)
	Dump every block and the heap totals to the debug serial port.

Detailed Description

First-fit heaps over caller-provided memory regions.

Small allocations are taken from the start of the region and large ones (256 bytes or more) from the end, to limit fragmentation. Each block carries a small header and, with CONFIG_MALLOC_INSTRUMENTATION, the address of the caller that allocated it. A heap is not thread safe unless given a lock with pbl_heap_set_lock().

The kernel heap is behind pbl_malloc(); other heaps belong to whoever initializes them.

static uint8_t s_region[4096];
static struct pbl_heap s_heap;
 
pbl_heap_init(&s_heap, s_region, s_region + sizeof(s_region), false);
void *p = pbl_heap_alloc(&s_heap, 100, (uintptr_t)PBL_RETURN_ADDRESS(0));
pbl_heap_free(&s_heap, p, 0);

---

Data Structure Documentation

pbl_heap

struct pbl_heap

Heap.

Data Fields
HeapInfo_t *	begin	First block of the heap.
void *	corrupt_block	Corrupted block found while locked, reported once unlocked.
pbl_heap_error_handler_t	corruption_handler	Corruption handler, NULL to assert.
unsigned int	current_size	Number of allocated bytes, including block headers.
pbl_heap_error_handler_t	double_free_handler	Double free handler, NULL to assert.
HeapInfo_t *	end	End of the heap, right after the last block.
bool	fuzz_on_free	Fill freed memory with a junk pattern (non-release builds).
unsigned int	high_water_mark	Peak of current_size.
struct pbl_heap_lock	lock	Locking.

Typedef Documentation

pbl_heap_error_handler_t

typedef void(* pbl_heap_error_handler_t) (void *ptr)

Handler of a heap error, called with the pointer being freed (double free) or the block where corruption was found.

Called with the heap unlocked.

Function Documentation

pbl_heap_alloc()

void * pbl_heap_alloc	(	struct pbl_heap *	heap,
		size_t	size,
		uintptr_t	caller
	)

Allocate memory.

Parameters

heap	Heap, initialized.
size	Number of bytes, greater than 0.
caller	Caller address, recorded with CONFIG_MALLOC_INSTRUMENTATION.

Returns

Allocated memory, or NULL if there is not enough contiguous free space.

pbl_heap_calloc()

void * pbl_heap_calloc	(	struct pbl_heap *	heap,
		size_t	count,
		size_t	size,
		uintptr_t	caller
	)

Allocate a zeroed array.

Parameters

heap	Heap.
count	Number of elements.
size	Size of an element in bytes.
caller	Caller address, for instrumentation.

Returns

Allocated memory, or NULL if there is not enough space or count times size overflows.

pbl_heap_contains()

bool pbl_heap_contains	(	const struct pbl_heap *	heap,
		const void *	ptr
	)

Check whether an address is within a heap.

Parameters

heap	Heap.
ptr	Address.

Returns

true if ptr is in the heap region.

pbl_heap_dump()

void pbl_heap_dump

(

struct pbl_heap *

heap

)

Dump every block and the heap totals to the debug serial port.

Only available with CONFIG_MALLOC_INSTRUMENTATION.

Parameters

heap

Heap.

pbl_heap_free()

void pbl_heap_free	(	struct pbl_heap *	heap,
		void *	ptr,
		uintptr_t	caller
	)

Free memory, merging it with adjacent free blocks.

Parameters

heap	Heap, initialized.
ptr	Memory allocated from heap, or NULL (no-op).
caller	Caller address, for instrumentation.

pbl_heap_init()

void pbl_heap_init	(	struct pbl_heap *	heap,
		void *	start,
		void *	end,
		bool	fuzz_on_free
	)

Initialize a heap over a memory region, zeroing it.

The usable size is capped to about 32767 alignment units (128 KiB with 4-byte units).

Parameters

[out]	heap	Heap.
	start	Start of the region, rounded up to the alignment.
	end	End of the region, exclusive, rounded down to the alignment.
	fuzz_on_free	Fill freed memory with a junk pattern to catch use after free sooner.

pbl_heap_is_allocated()

bool pbl_heap_is_allocated	(	struct pbl_heap *	heap,
		void *	ptr
	)

Check whether a pointer is an allocated block of a heap.

Parameters

heap	Heap.
ptr	Pointer.

Returns

true if ptr was returned by an allocation and not freed.

pbl_heap_min_headroom()

size_t pbl_heap_min_headroom

(

const struct pbl_heap *

heap

)

Get the smallest amount of free memory the heap has had.

Parameters

heap

Heap.

Returns

Heap size minus the high water mark, in bytes.

pbl_heap_oom()

void pbl_heap_oom	(	struct pbl_heap *	heap,
		size_t	size,
		uintptr_t	caller
	)

Report an allocation failure the caller cannot recover from.

Logs the heap usage, dumps the heap with CONFIG_MALLOC_INSTRUMENTATION and calls pbl_heap_oom_handler().

Parameters

heap	Heap the allocation failed on.
size	Number of bytes requested.
caller	Caller address.

pbl_heap_oom_handler()

void pbl_heap_oom_handler	(	struct pbl_heap *	heap,
		size_t	size,
		uintptr_t	caller
	)

Handle an allocation failure the caller cannot recover from.

Implemented by the platform, called by pbl_heap_oom().

Parameters

heap	Heap the allocation failed on.
size	Number of bytes requested.
caller	Caller address.

pbl_heap_realloc()

void * pbl_heap_realloc	(	struct pbl_heap *	heap,
		void *	ptr,
		size_t	size,
		uintptr_t	caller
	)

Reallocate memory.

Always allocates a new block, copies as much of the old data as fits, then frees ptr.

Parameters

heap	Heap.
ptr	Memory to reallocate, or NULL.
size	New size in bytes.
caller	Caller address, recorded with CONFIG_MALLOC_INSTRUMENTATION.

Returns

New memory, or NULL on failure (ptr is then left untouched).

pbl_heap_reset_high_water_mark()

void pbl_heap_reset_high_water_mark

(

struct pbl_heap *

heap

)

Restart the high water mark from the current usage.

Parameters

heap

Heap.

pbl_heap_set_corruption_handler()

void pbl_heap_set_corruption_handler	(	struct pbl_heap *	heap,
		pbl_heap_error_handler_t	handler
	)

Set the function called when corruption is detected, instead of asserting.

Parameters

heap	Heap.
handler	Handler.

pbl_heap_set_double_free_handler()

void pbl_heap_set_double_free_handler	(	struct pbl_heap *	heap,
		pbl_heap_error_handler_t	handler
	)

Set the function called on a double free, instead of asserting.

Parameters

heap	Heap.
handler	Handler; the free is then ignored.

pbl_heap_set_lock()

void pbl_heap_set_lock	(	struct pbl_heap *	heap,
		struct pbl_heap_lock	lock
	)

Make a heap thread safe with a lock.

Parameters

heap	Heap.
lock	Lock functions; either may be NULL.

pbl_heap_size()

size_t pbl_heap_size

(

const struct pbl_heap *

heap

)

Get the size of a heap.

Parameters

heap

Heap.

Returns

Size in bytes.

pbl_heap_stats()

void pbl_heap_stats	(	struct pbl_heap *	heap,
		unsigned int *	used,
		unsigned int *	free,
		unsigned int *	max_free
	)

Walk a heap to calculate its usage.

Parameters

	heap	Heap.
[out]	used	Bytes allocated.
[out]	free	Bytes free.
[out]	max_free	Size of the largest free block.

pbl_heap_strdup()

char * pbl_heap_strdup	(	struct pbl_heap *	heap,
		const char *	s,
		uintptr_t	caller
	)

Duplicate a string.

Parameters

heap	Heap.
s	String.
caller	Caller address, for instrumentation.

Returns

Copy of s, or NULL.

pbl_heap_used()

size_t pbl_heap_used

(

const struct pbl_heap *

heap

)

Get the number of allocated bytes, including block headers.

Parameters

heap

Heap.

Returns

Allocated bytes.

pbl_heap_zalloc()

void * pbl_heap_zalloc	(	struct pbl_heap *	heap,
		size_t	size,
		uintptr_t	caller
	)

Allocate zeroed memory.

Parameters

heap	Heap.
size	Number of bytes.
caller	Caller address, for instrumentation.

Returns

Allocated memory, or NULL.