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_ */
