Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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
heapHeap from which to allocate
alignAlignment in bytes, must be a power of two
bytesNumber 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.

Parameters
heapHeap from which to allocate
ptrOriginal pointer returned from a previous allocation
alignAlignment in bytes, must be a power of two
bytesNumber 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
heapHeap from which to allocate
bytesNumber 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
heapHeap to which to return the memory
memA 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
heapHeap to initialize
memUntyped pointer to unused memory
bytesSize 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
heapHeap to print information about
dump_chunksTrue 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_fnCallback to perform an allocation. Passes back the arg parameter as a context handle.
free_fnCallback to perform a free of a pointer returned from alloc. Passes back the arg parameter as a context handle.
argContext handle to pass back to the callbacks
total_bytesSize of the byte array the heap was initialized in
op_countHow many iterations to test
scratch_memA 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_bytesSize of the memory pointed to by scratch_mem
target_percentPercentage 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.
resultStruct 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
heapHeap containing the block
memPointer 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
heapHeap to validate
Returns
true, if the heap is valid, otherwise false