| /* |
| * Copyright (c) 2021 Carlo Caione, <ccaione@baylibre.com> |
| * |
| * SPDX-License-Identifier: Apache-2.0 |
| */ |
| |
| /** |
| * @file |
| * @brief Public API for Shared Multi-Heap framework |
| */ |
| |
| #ifndef ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_ |
| #define ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_ |
| |
| #ifdef __cplusplus |
| extern "C" { |
| #endif |
| |
| /** |
| * @brief Heap Management |
| * @defgroup heaps Heap Management |
| * @ingroup os_services |
| * @{ |
| * @} |
| */ |
| |
| /** |
| * @brief Shared Multi-Heap (SMH) interface |
| * @defgroup shared_multi_heap Shared multi-heap interface |
| * @ingroup heaps |
| * @{ |
| * |
| * The shared multi-heap manager uses the multi-heap allocator to manage a set |
| * of memory regions with different capabilities / attributes (cacheable, |
| * non-cacheable, etc...). |
| * |
| * All the different regions can be added at run-time to the shared multi-heap |
| * pool providing an opaque "attribute" value (an integer or enum value) that |
| * can be used by drivers or applications to request memory with certain |
| * capabilities. |
| * |
| * This framework is commonly used as follow: |
| * |
| * - At boot time some platform code initialize the shared multi-heap |
| * framework using @ref shared_multi_heap_pool_init and add the memory |
| * regions to the pool with @ref shared_multi_heap_add, possibly gathering |
| * the needed information for the regions from the DT. |
| * |
| * - Each memory region encoded in a @ref shared_multi_heap_region structure. |
| * This structure is also carrying an opaque and user-defined integer value |
| * that is used to define the region capabilities (for example: |
| * cacheability, cpu affinity, etc...) |
| * |
| * - When a driver or application needs some dynamic memory with a certain |
| * capability, it can use @ref shared_multi_heap_alloc (or the aligned |
| * version) to request the memory by using the opaque parameter to select |
| * the correct set of attributes for the needed memory. The framework will |
| * take care of selecting the correct heap (thus memory region) to carve |
| * memory from, based on the opaque parameter and the runtime state of the |
| * heaps (available memory, heap state, etc...) |
| */ |
| |
| /** |
| * @brief SMH region attributes enumeration type. |
| * |
| * Enumeration type for some common memory region attributes. |
| * |
| */ |
| enum shared_multi_heap_attr { |
| /** cacheable */ |
| SMH_REG_ATTR_CACHEABLE, |
| |
| /** non-cacheable */ |
| SMH_REG_ATTR_NON_CACHEABLE, |
| |
| /** must be the last item */ |
| SMH_REG_ATTR_NUM, |
| }; |
| |
| /** Maximum number of standard attributes. */ |
| #define MAX_SHARED_MULTI_HEAP_ATTR SMH_REG_ATTR_NUM |
| |
| /** |
| * @brief SMH region struct |
| * |
| * This struct is carrying information about the memory region to be added in |
| * the multi-heap pool. |
| */ |
| struct shared_multi_heap_region { |
| /** Memory heap attribute */ |
| uint32_t attr; |
| |
| /** Memory heap starting virtual address */ |
| uintptr_t addr; |
| |
| /** Memory heap size in bytes */ |
| size_t size; |
| }; |
| |
| /** |
| * @brief Init the pool |
| * |
| * This must be the first function to be called to initialize the shared |
| * multi-heap pool. All the individual heaps must be added later with @ref |
| * shared_multi_heap_add. |
| * |
| * @note As for the generic multi-heap allocator the expectation is that this |
| * function will be called at soc- or board-level. |
| * |
| * @retval 0 on success. |
| * @retval -EALREADY when the pool was already inited. |
| * @retval other errno codes |
| */ |
| int shared_multi_heap_pool_init(void); |
| |
| /** |
| * @brief Allocate memory from the memory shared multi-heap pool |
| * |
| * Allocates a block of memory of the specified size in bytes and with a |
| * specified capability / attribute. The opaque attribute parameter is used |
| * by the backend to select the correct heap to allocate memory from. |
| * |
| * @param attr capability / attribute requested for the memory block. |
| * @param bytes requested size of the allocation in bytes. |
| * |
| * @retval ptr a valid pointer to heap memory. |
| * @retval err NULL if no memory is available. |
| */ |
| void *shared_multi_heap_alloc(enum shared_multi_heap_attr attr, size_t bytes); |
| |
| /** |
| * @brief Allocate aligned memory from the memory shared multi-heap pool |
| * |
| * Allocates a block of memory of the specified size in bytes and with a |
| * specified capability / attribute. Takes an additional parameter specifying a |
| * power of two alignment in bytes. |
| * |
| * @param attr capability / attribute requested for the memory block. |
| * @param align power of two alignment for the returned pointer, in bytes. |
| * @param bytes requested size of the allocation in bytes. |
| * |
| * @retval ptr a valid pointer to heap memory. |
| * @retval err NULL if no memory is available. |
| */ |
| void *shared_multi_heap_aligned_alloc(enum shared_multi_heap_attr attr, |
| size_t align, size_t bytes); |
| |
| /** |
| * @brief Free memory from the shared multi-heap pool |
| * |
| * Used to free the passed block of memory that must be the return value of a |
| * previously call to @ref shared_multi_heap_alloc or @ref |
| * shared_multi_heap_aligned_alloc. |
| * |
| * @param block block to free, must be a pointer to a block allocated |
| * by shared_multi_heap_alloc or |
| * shared_multi_heap_aligned_alloc. |
| */ |
| void shared_multi_heap_free(void *block); |
| |
| /** |
| * @brief Add an heap region to the shared multi-heap pool |
| * |
| * This adds a shared multi-heap region to the multi-heap pool. |
| * |
| * @param user_data pointer to any data for the heap. |
| * @param region pointer to the memory region to be added. |
| * |
| * @retval 0 on success. |
| * @retval -EINVAL when the region attribute is out-of-bound. |
| * @retval -ENOMEM when there are no more heaps available. |
| * @retval other errno codes |
| */ |
| int shared_multi_heap_add(struct shared_multi_heap_region *region, void *user_data); |
| |
| /** |
| * @} |
| */ |
| |
| #ifdef __cplusplus |
| } |
| #endif |
| |
| #endif /* ZEPHYR_INCLUDE_MULTI_HEAP_MANAGER_SMH_H_ */ |