Line data Source code
1 1 : /*
2 : * Copyright (c) 2021 Carlo Caione, <ccaione@baylibre.com>
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief Public API for Shared Multi-Heap framework
10 : */
11 :
12 : #ifndef ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_
13 : #define ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_
14 :
15 : #ifdef __cplusplus
16 : extern "C" {
17 : #endif
18 :
19 : /**
20 : * @brief Heap Management
21 : * @defgroup heaps Heap Management
22 : * @ingroup os_services
23 : * @{
24 : * @}
25 : */
26 :
27 : /**
28 : * @brief Shared Multi-Heap (SMH) interface
29 : * @defgroup shared_multi_heap Shared multi-heap interface
30 : * @ingroup heaps
31 : * @{
32 : *
33 : * The shared multi-heap manager uses the multi-heap allocator to manage a set
34 : * of memory regions with different capabilities / attributes (cacheable,
35 : * non-cacheable, etc...).
36 : *
37 : * All the different regions can be added at run-time to the shared multi-heap
38 : * pool providing an opaque "attribute" value (an integer or enum value) that
39 : * can be used by drivers or applications to request memory with certain
40 : * capabilities.
41 : *
42 : * This framework is commonly used as follow:
43 : *
44 : * - At boot time some platform code initialize the shared multi-heap
45 : * framework using @ref shared_multi_heap_pool_init and add the memory
46 : * regions to the pool with @ref shared_multi_heap_add, possibly gathering
47 : * the needed information for the regions from the DT.
48 : *
49 : * - Each memory region encoded in a @ref shared_multi_heap_region structure.
50 : * This structure is also carrying an opaque and user-defined integer value
51 : * that is used to define the region capabilities (for example:
52 : * cacheability, cpu affinity, etc...)
53 : *
54 : * - When a driver or application needs some dynamic memory with a certain
55 : * capability, it can use @ref shared_multi_heap_alloc (or the aligned
56 : * version) to request the memory by using the opaque parameter to select
57 : * the correct set of attributes for the needed memory. The framework will
58 : * take care of selecting the correct heap (thus memory region) to carve
59 : * memory from, based on the opaque parameter and the runtime state of the
60 : * heaps (available memory, heap state, etc...)
61 : */
62 :
63 : /**
64 : * @brief SMH region attributes enumeration type.
65 : *
66 : * Enumeration type for some common memory region attributes.
67 : *
68 : */
69 1 : enum shared_multi_heap_attr {
70 : /** cacheable */
71 : SMH_REG_ATTR_CACHEABLE,
72 :
73 : /** non-cacheable */
74 : SMH_REG_ATTR_NON_CACHEABLE,
75 :
76 : /** external Memory */
77 : SMH_REG_ATTR_EXTERNAL,
78 :
79 : /** must be the last item */
80 : SMH_REG_ATTR_NUM,
81 : };
82 :
83 : /** Maximum number of standard attributes. */
84 1 : #define MAX_SHARED_MULTI_HEAP_ATTR SMH_REG_ATTR_NUM
85 :
86 : /**
87 : * @brief SMH region struct
88 : *
89 : * This struct is carrying information about the memory region to be added in
90 : * the multi-heap pool.
91 : */
92 1 : struct shared_multi_heap_region {
93 : /** Memory heap attribute */
94 1 : uint32_t attr;
95 :
96 : /** Memory heap starting virtual address */
97 1 : uintptr_t addr;
98 :
99 : /** Memory heap size in bytes */
100 1 : size_t size;
101 : };
102 :
103 : /**
104 : * @brief Init the pool
105 : *
106 : * This must be the first function to be called to initialize the shared
107 : * multi-heap pool. All the individual heaps must be added later with @ref
108 : * shared_multi_heap_add.
109 : *
110 : * @note As for the generic multi-heap allocator the expectation is that this
111 : * function will be called at soc- or board-level.
112 : *
113 : * @retval 0 on success.
114 : * @retval -EALREADY when the pool was already inited.
115 : * @retval other errno codes
116 : */
117 1 : int shared_multi_heap_pool_init(void);
118 :
119 : /**
120 : * @brief Allocate memory from the memory shared multi-heap pool
121 : *
122 : * Allocates a block of memory of the specified size in bytes and with a
123 : * specified capability / attribute. The opaque attribute parameter is used
124 : * by the backend to select the correct heap to allocate memory from.
125 : *
126 : * @param attr capability / attribute requested for the memory block.
127 : * @param bytes requested size of the allocation in bytes.
128 : *
129 : * @retval ptr a valid pointer to heap memory.
130 : * @retval err NULL if no memory is available.
131 : */
132 1 : void *shared_multi_heap_alloc(enum shared_multi_heap_attr attr, size_t bytes);
133 :
134 : /**
135 : * @brief Allocate aligned memory from the memory shared multi-heap pool
136 : *
137 : * Allocates a block of memory of the specified size in bytes and with a
138 : * specified capability / attribute. Takes an additional parameter specifying a
139 : * power of two alignment in bytes.
140 : *
141 : * @param attr capability / attribute requested for the memory block.
142 : * @param align power of two alignment for the returned pointer, in bytes.
143 : * @param bytes requested size of the allocation in bytes.
144 : *
145 : * @retval ptr a valid pointer to heap memory.
146 : * @retval err NULL if no memory is available.
147 : */
148 1 : void *shared_multi_heap_aligned_alloc(enum shared_multi_heap_attr attr,
149 : size_t align, size_t bytes);
150 :
151 : /**
152 : * @brief Free memory from the shared multi-heap pool
153 : *
154 : * Used to free the passed block of memory that must be the return value of a
155 : * previously call to @ref shared_multi_heap_alloc or @ref
156 : * shared_multi_heap_aligned_alloc.
157 : *
158 : * @param block block to free, must be a pointer to a block allocated
159 : * by shared_multi_heap_alloc or
160 : * shared_multi_heap_aligned_alloc.
161 : */
162 1 : void shared_multi_heap_free(void *block);
163 :
164 : /**
165 : * @brief Add an heap region to the shared multi-heap pool
166 : *
167 : * This adds a shared multi-heap region to the multi-heap pool.
168 : *
169 : * @param user_data pointer to any data for the heap.
170 : * @param region pointer to the memory region to be added.
171 : *
172 : * @retval 0 on success.
173 : * @retval -EINVAL when the region attribute is out-of-bound.
174 : * @retval -ENOMEM when there are no more heaps available.
175 : * @retval other errno codes
176 : */
177 1 : int shared_multi_heap_add(struct shared_multi_heap_region *region, void *user_data);
178 :
179 : /**
180 : * @}
181 : */
182 :
183 : #ifdef __cplusplus
184 : }
185 : #endif
186 :
187 : #endif /* ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_ */
|
