sys_heap.h File Reference

#include <stddef.h>
#include <stdbool.h>
#include <zephyr/types.h>
#include <zephyr/sys/mem_stats.h>

Go to the source code of this file.

Data Structures
struct	sys_heap

Macros
#define	sys_heap_realloc(heap, ptr, bytes)    sys_heap_aligned_realloc(heap, ptr, 0, bytes)

Functions
void	sys_heap_init (struct sys_heap *heap, void *mem, size_t bytes)
	Initialize sys_heap.
void *	sys_heap_alloc (struct sys_heap *heap, size_t bytes)
	Allocate memory from a sys_heap.
void *	sys_heap_aligned_alloc (struct sys_heap *heap, size_t align, size_t bytes)
	Allocate aligned memory from a sys_heap.
void	sys_heap_free (struct sys_heap *heap, void *mem)
	Free memory into a sys_heap.
void *	sys_heap_aligned_realloc (struct sys_heap *heap, void *ptr, size_t align, size_t bytes)
	Expand the size of an existing allocation.
size_t	sys_heap_usable_size (struct sys_heap *heap, void *mem)
	Return allocated memory size.
bool	sys_heap_validate (struct sys_heap *heap)
	Validate heap integrity.
void	sys_heap_stress (void *(*alloc_fn)(void *arg, size_t bytes), void(*free_fn)(void *arg, void *p), void *arg, size_t total_bytes, uint32_t op_count, void *scratch_mem, size_t scratch_bytes, int target_percent, struct z_heap_stress_result *result)
	sys_heap stress test rig
void	sys_heap_print_info (struct sys_heap *heap, bool dump_chunks)
	Print heap internal structure information to the console.

Macro Definition Documentation

sys_heap_realloc

#define sys_heap_realloc	(		heap,
			ptr,
			bytes
	)		sys_heap_aligned_realloc(heap, ptr, 0, bytes)

Function Documentation

sys_heap_aligned_alloc()

void * sys_heap_aligned_alloc	(	struct sys_heap *	heap,
		size_t	align,
		size_t	bytes
	)

Allocate aligned memory from a sys_heap.

Behaves in all ways like sys_heap_alloc(), except that the returned memory (if available) will have a starting address in memory which is a multiple of the specified power-of-two alignment value in bytes. With align=0 this behaves exactly like sys_heap_alloc(). The resulting memory can be returned to the heap using sys_heap_free().

Parameters

heap	Heap from which to allocate
align	Alignment in bytes, must be a power of two
bytes	Number of bytes requested

Returns

Pointer to memory the caller can now use

sys_heap_aligned_realloc()

void * sys_heap_aligned_realloc	(	struct sys_heap *	heap,
		void *	ptr,
		size_t	align,
		size_t	bytes
	)

Expand the size of an existing allocation.

Returns a pointer to a new memory region with the same contents, but a different allocated size. If the new allocation can be expanded in place, the pointer returned will be identical. Otherwise the data will be copies to a new block and the old one will be freed as per sys_heap_free(). If the specified size is smaller than the original, the block will be truncated in place and the remaining memory returned to the heap. If the allocation of a new block fails, then NULL will be returned and the old block will not be freed or modified.

Note

The return of a NULL on failure is a different behavior than POSIX realloc(), which specifies that the original pointer will be returned (i.e. it is not possible to safely detect realloc() failure in POSIX, but it is here).

Parameters

heap	Heap from which to allocate
ptr	Original pointer returned from a previous allocation
align	Alignment in bytes, must be a power of two
bytes	Number of bytes requested for the new block

Returns

Pointer to memory the caller can now use, or NULL

sys_heap_alloc()

void * sys_heap_alloc	(	struct sys_heap *	heap,
		size_t	bytes
	)

Allocate memory from a sys_heap.

Returns a pointer to a block of unused memory in the heap. This memory will not otherwise be used until it is freed with sys_heap_free(). If no memory can be allocated, NULL will be returned. The allocated memory is guaranteed to have a starting address which is a multiple of sizeof(void *). If a bigger alignment is necessary then sys_heap_aligned_alloc() should be used instead.

Note

The sys_heap implementation is not internally synchronized. No two sys_heap functions should operate on the same heap at the same time. All locking must be provided by the user.

Parameters

heap	Heap from which to allocate
bytes	Number of bytes requested

Returns

Pointer to memory the caller can now use

sys_heap_free()

void sys_heap_free	(	struct sys_heap *	heap,
		void *	mem
	)

Free memory into a sys_heap.

De-allocates a pointer to memory previously returned from sys_heap_alloc such that it can be used for other purposes. The caller must not use the memory region after entry to this function.

Note

The sys_heap implementation is not internally synchronized. No two sys_heap functions should operate on the same heap at the same time. All locking must be provided by the user.

Parameters

heap	Heap to which to return the memory
mem	A pointer previously returned from sys_heap_alloc()

sys_heap_init()

void sys_heap_init	(	struct sys_heap *	heap,
		void *	mem,
		size_t	bytes
	)

Initialize sys_heap.

Initializes a sys_heap struct to manage the specified memory.

Parameters

heap	Heap to initialize
mem	Untyped pointer to unused memory
bytes	Size of region pointed to by mem

sys_heap_print_info()

void sys_heap_print_info	(	struct sys_heap *	heap,
		bool	dump_chunks
	)

Print heap internal structure information to the console.

Print information on the heap structure such as its size, chunk buckets, chunk list and some statistics for debugging purpose.

Parameters

heap	Heap to print information about
dump_chunks	True to print the entire heap chunk list

sys_heap_stress()

void sys_heap_stress	(	void *(*)(void *arg, size_t bytes)	alloc_fn,
		void(*)(void *arg, void *p)	free_fn,
		void *	arg,
		size_t	total_bytes,
		uint32_t	op_count,
		void *	scratch_mem,
		size_t	scratch_bytes,
		int	target_percent,
		struct z_heap_stress_result *	result
	)

sys_heap stress test rig

Test rig for heap allocation validation. This will loop for op_count cycles, in each iteration making a random choice to allocate or free a pointer of randomized (power law) size based on heuristics designed to keep the heap in a state where it is near target_percent full. Allocation and free operations are provided by the caller as callbacks (i.e. this can in theory test any heap). Results, including counts of frees and successful/unsuccessful allocations, are returned via the result struct.

Parameters

alloc_fn	Callback to perform an allocation. Passes back the arg parameter as a context handle.
free_fn	Callback to perform a free of a pointer returned from alloc. Passes back the arg parameter as a context handle.
arg	Context handle to pass back to the callbacks
total_bytes	Size of the byte array the heap was initialized in
op_count	How many iterations to test
scratch_mem	A pointer to scratch memory to be used by the test. Should be about 1/2 the size of the heap for tests that need to stress fragmentation.
scratch_bytes	Size of the memory pointed to by scratch_mem
target_percent	Percentage fill value (1-100) to which the random allocation choices will seek. High values will result in significant allocation failures and a very fragmented heap.
result	Struct into which to store test results.

sys_heap_usable_size()

size_t sys_heap_usable_size	(	struct sys_heap *	heap,
		void *	mem
	)

Return allocated memory size.

Returns the size, in bytes, of a block returned from a successful sys_heap_alloc() or sys_heap_alloc_aligned() call. The value returned is the size of the heap-managed memory, which may be larger than the number of bytes requested due to allocation granularity. The heap code is guaranteed to make no access to this region of memory until a subsequent sys_heap_free() on the same pointer.

Parameters

heap	Heap containing the block
mem	Pointer to memory allocated from this heap

Returns

Size in bytes of the memory region

sys_heap_validate()

bool sys_heap_validate

(

struct sys_heap *

heap

)

Validate heap integrity.

Validates the internal integrity of a sys_heap. Intended for unit test and validation code, though potentially useful as a user API for applications with complicated runtime reliability requirements. Note: this cannot catch every possible error, but if it returns true then the heap is in a consistent state and can correctly handle any sys_heap_alloc() request and free any live pointer returned from a previous allocation.

Parameters

heap	Heap to validate

Returns

true, if the heap is valid, otherwise false