Zephyr API Documentation
3.7.0
A Scalable Open Source RTOS
|
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. | |
#define sys_heap_realloc | ( | heap, | |
ptr, | |||
bytes | |||
) | sys_heap_aligned_realloc(heap, ptr, 0, bytes) |
#include <zephyr/sys/sys_heap.h>
#include <zephyr/sys/sys_heap.h>
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().
heap | Heap from which to allocate |
align | Alignment in bytes, must be a power of two |
bytes | Number of bytes requested |
#include <zephyr/sys/sys_heap.h>
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.
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 |
#include <zephyr/sys/sys_heap.h>
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.
heap | Heap from which to allocate |
bytes | Number of bytes requested |
void sys_heap_free | ( | struct sys_heap * | heap, |
void * | mem | ||
) |
#include <zephyr/sys/sys_heap.h>
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.
heap | Heap to which to return the memory |
mem | A pointer previously returned from sys_heap_alloc() |
#include <zephyr/sys/sys_heap.h>
Initialize sys_heap.
Initializes a sys_heap struct to manage the specified memory.
heap | Heap to initialize |
mem | Untyped pointer to unused memory |
bytes | Size of region pointed to by mem |
#include <zephyr/sys/sys_heap.h>
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.
heap | Heap to print information about |
dump_chunks | True to print the entire heap chunk list |
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 | ||
) |
#include <zephyr/sys/sys_heap.h>
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.
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. |
#include <zephyr/sys/sys_heap.h>
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.
heap | Heap containing the block |
mem | Pointer to memory allocated from this heap |
#include <zephyr/sys/sys_heap.h>
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.
heap | Heap to validate |