Zephyr API Documentation  3.6.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
sys_heap.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2019 Intel Corporation
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6#ifndef ZEPHYR_INCLUDE_SYS_SYS_HEAP_H_
7#define ZEPHYR_INCLUDE_SYS_SYS_HEAP_H_
8
9#include <stddef.h>
10#include <stdbool.h>
11#include <zephyr/types.h>
13
14#ifdef __cplusplus
15extern "C" {
16#endif
17
18/* Simple, fast heap implementation.
19 *
20 * A more or less conventional segregated fit allocator with
21 * power-of-two buckets.
22 *
23 * Excellent space efficiency. Chunks can be split arbitrarily in 8
24 * byte units. Overhead is only four bytes per allocated chunk (eight
25 * bytes for heaps >256kb or on 64 bit systems), plus a log2-sized
26 * array of 2-word bucket headers. No coarse alignment restrictions
27 * on blocks, they can be split and merged (in units of 8 bytes)
28 * arbitrarily.
29 *
30 * Simple API. Initialize at runtime with any blob of memory and not
31 * a macro-generated, carefully aligned static array. Allocate and
32 * free by user pointer and not an opaque block handle.
33 *
34 * Good fragmentation resistance. Freed blocks are always immediately
35 * merged with adjacent free blocks. Allocations are attempted from a
36 * sample of the smallest bucket that might fit, falling back rapidly
37 * to the smallest block guaranteed to fit. Split memory remaining in
38 * the chunk is always returned immediately to the heap for other
39 * allocation.
40 *
41 * Excellent performance with firmly bounded runtime. All operations
42 * are constant time (though there is a search of the smallest bucket
43 * that has a compile-time-configurable upper bound, setting this to
44 * extreme values results in an effectively linear search of the
45 * list), objectively fast (~hundred instructions) and and amenable to
46 * locked operation.
47 */
48
49/* Note: the init_mem/bytes fields are for the static initializer to
50 * have somewhere to put the arguments. The actual heap metadata at
51 * runtime lives in the heap memory itself and this struct simply
52 * functions as an opaque pointer. Would be good to clean this up and
53 * put the two values somewhere else, though it would make
54 * SYS_HEAP_DEFINE a little hairy to write.
55 */
56struct sys_heap {
57 struct z_heap *heap;
58 void *init_mem;
59 size_t init_bytes;
60};
61
62struct z_heap_stress_result {
63 uint32_t total_allocs;
64 uint32_t successful_allocs;
65 uint32_t total_frees;
66 uint64_t accumulated_in_use_bytes;
67};
68
69#ifdef CONFIG_SYS_HEAP_RUNTIME_STATS
70
78int sys_heap_runtime_stats_get(struct sys_heap *heap,
79 struct sys_memory_stats *stats);
80
90int sys_heap_runtime_stats_reset_max(struct sys_heap *heap);
91
92#endif
93
102void sys_heap_init(struct sys_heap *heap, void *mem, size_t bytes);
103
121void *sys_heap_alloc(struct sys_heap *heap, size_t bytes);
122
136void *sys_heap_aligned_alloc(struct sys_heap *heap, size_t align, size_t bytes);
137
151void sys_heap_free(struct sys_heap *heap, void *mem);
152
171void *sys_heap_aligned_realloc(struct sys_heap *heap, void *ptr,
172 size_t align, size_t bytes);
173
174#define sys_heap_realloc(heap, ptr, bytes) \
175 sys_heap_aligned_realloc(heap, ptr, 0, bytes)
176
191size_t sys_heap_usable_size(struct sys_heap *heap, void *mem);
192
206bool sys_heap_validate(struct sys_heap *heap);
207
237void sys_heap_stress(void *(*alloc_fn)(void *arg, size_t bytes),
238 void (*free_fn)(void *arg, void *p),
239 void *arg, size_t total_bytes,
240 uint32_t op_count,
241 void *scratch_mem, size_t scratch_bytes,
242 int target_percent,
243 struct z_heap_stress_result *result);
244
253void sys_heap_print_info(struct sys_heap *heap, bool dump_chunks);
254
255
256#ifdef __cplusplus
257}
258#endif
259
260#endif /* ZEPHYR_INCLUDE_SYS_SYS_HEAP_H_ */
Memory Statistics.
__UINT32_TYPE__ uint32_t
Definition: stdint.h:90
__UINT64_TYPE__ uint64_t
Definition: stdint.h:91
Definition: sys_heap.h:56
size_t init_bytes
Definition: sys_heap.h:59
struct z_heap * heap
Definition: sys_heap.h:57
void * init_mem
Definition: sys_heap.h:58
Definition: mem_stats.h:24
void * sys_heap_aligned_realloc(struct sys_heap *heap, void *ptr, size_t align, size_t bytes)
Expand the size of an existing allocation.
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.
bool sys_heap_validate(struct sys_heap *heap)
Validate heap integrity.
void sys_heap_free(struct sys_heap *heap, void *mem)
Free memory into a sys_heap.
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.
size_t sys_heap_usable_size(struct sys_heap *heap, void *mem)
Return allocated memory size.