7c21df641d
Although very unlikely for this value to ever be negative in practice, this would make Coverity happy. Fixes #67969 Signed-off-by: Nicolas Pitre <npitre@baylibre.com>
166 lines
6.1 KiB
C
166 lines
6.1 KiB
C
/* Copyright (c) 2021 Intel Corporation
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef ZEPHYR_INCLUDE_SYS_MULTI_HEAP_H_
|
|
#define ZEPHYR_INCLUDE_SYS_MULTI_HEAP_H_
|
|
|
|
#include <zephyr/types.h>
|
|
|
|
#define MAX_MULTI_HEAPS 8
|
|
|
|
/**
|
|
* @brief Multi-heap allocator
|
|
*
|
|
* A sys_multi_heap represents a single allocator made from multiple,
|
|
* separately managed pools of memory that must be accessed via a
|
|
* unified API. They can be discontiguous, and in many cases will be
|
|
* expected to have different capabilities (for example: latency,
|
|
* cacheability, cpu affinity, etc...)
|
|
*
|
|
* Allocation from the multiheap provides an opaque "configuration"
|
|
* value to specify requirements and heuristics to assist the choice
|
|
* in backend, which is then provided to a user-specified "choice"
|
|
* function whose job it is to select a heap based on information in
|
|
* the config specifier and runtime state (heap full state, etc...)
|
|
*/
|
|
struct sys_multi_heap;
|
|
|
|
/**
|
|
* @brief Multi-heap choice function
|
|
*
|
|
* This is a user-provided functions whose responsibility is selecting
|
|
* a specific sys_heap backend based on the opaque cfg value, which is
|
|
* specified by the user as an argument to sys_multi_heap_alloc(), and
|
|
* performing the allocation on behalf of the caller. The callback is
|
|
* free to choose any registered heap backend to perform the
|
|
* allocation, and may choose to pad the user-provided values as
|
|
* needed, and to use an aligned allocation where required by the
|
|
* specified configuration.
|
|
*
|
|
* NULL may be returned, which will cause the
|
|
* allocation to fail and a NULL reported to the calling code.
|
|
*
|
|
* @param mheap Multi-heap structure.
|
|
* @param cfg An opaque user-provided value. It may be interpreted in
|
|
* any way by the application
|
|
* @param align Alignment of requested memory (or zero for no alignment)
|
|
* @param size The user-specified allocation size in bytes
|
|
* @return A pointer to the allocated memory
|
|
*/
|
|
typedef void *(*sys_multi_heap_fn_t)(struct sys_multi_heap *mheap, void *cfg,
|
|
size_t align, size_t size);
|
|
|
|
|
|
struct sys_multi_heap_rec {
|
|
struct sys_heap *heap;
|
|
void *user_data;
|
|
};
|
|
|
|
struct sys_multi_heap {
|
|
unsigned int nheaps;
|
|
sys_multi_heap_fn_t choice;
|
|
struct sys_multi_heap_rec heaps[MAX_MULTI_HEAPS];
|
|
};
|
|
|
|
/**
|
|
* @brief Initialize multi-heap
|
|
*
|
|
* Initialize a sys_multi_heap struct with the specified choice
|
|
* function. Note that individual heaps must be added later with
|
|
* sys_multi_heap_add_heap so that the heap bounds can be tracked by
|
|
* the multi heap code.
|
|
*
|
|
* @note In general a multiheap is likely to be instantiated
|
|
* semi-statically from system configuration (for example, via
|
|
* linker-provided bounds on available memory in different regions, or
|
|
* from devicetree definitions of hardware-provided addressable
|
|
* memory, etc...). The general expectation is that a soc- or
|
|
* board-level platform device will be initialized at system boot from
|
|
* these upstream configuration sources and not that an application
|
|
* will assemble a multi-heap on its own.
|
|
*
|
|
* @param heap A sys_multi_heap to initialize
|
|
* @param choice_fn A sys_multi_heap_fn_t callback used to select
|
|
* heaps at allocation time
|
|
*/
|
|
void sys_multi_heap_init(struct sys_multi_heap *heap,
|
|
sys_multi_heap_fn_t choice_fn);
|
|
|
|
/**
|
|
* @brief Add sys_heap to multi heap
|
|
*
|
|
* This adds a known sys_heap backend to an existing multi heap,
|
|
* allowing the multi heap internals to track the bounds of the heap
|
|
* and determine which heap (if any) from which a freed block was
|
|
* allocated.
|
|
*
|
|
* @param mheap A sys_multi_heap to which to add a heap
|
|
* @param heap The heap to add
|
|
* @param user_data pointer to any data for the heap
|
|
*/
|
|
void sys_multi_heap_add_heap(struct sys_multi_heap *mheap, struct sys_heap *heap, void *user_data);
|
|
|
|
/**
|
|
* @brief Allocate memory from multi heap
|
|
*
|
|
* Just as for sys_heap_alloc(), allocates a block of memory of the
|
|
* specified size in bytes. Takes an opaque configuration pointer
|
|
* passed to the multi heap choice function, which is used by
|
|
* integration code to choose a heap backend.
|
|
*
|
|
* @param mheap Multi heap pointer
|
|
* @param cfg Opaque configuration parameter, as for sys_multi_heap_fn_t
|
|
* @param bytes Requested size of the allocation, in bytes
|
|
* @return A valid pointer to heap memory, or NULL if no memory is available
|
|
*/
|
|
void *sys_multi_heap_alloc(struct sys_multi_heap *mheap, void *cfg, size_t bytes);
|
|
|
|
/**
|
|
* @brief Allocate aligned memory from multi heap
|
|
*
|
|
* Just as for sys_multi_heap_alloc(), allocates a block of memory of
|
|
* the specified size in bytes. Takes an additional parameter
|
|
* specifying a power of two alignment, in bytes.
|
|
*
|
|
* @param mheap Multi heap pointer
|
|
* @param cfg Opaque configuration parameter, as for sys_multi_heap_fn_t
|
|
* @param align Power of two alignment for the returned pointer, in bytes
|
|
* @param bytes Requested size of the allocation, in bytes
|
|
* @return A valid pointer to heap memory, or NULL if no memory is available
|
|
*/
|
|
void *sys_multi_heap_aligned_alloc(struct sys_multi_heap *mheap,
|
|
void *cfg, size_t align, size_t bytes);
|
|
|
|
/**
|
|
* @brief Get a specific heap for provided address
|
|
*
|
|
* Finds a single system heap (with user_data)
|
|
* controlling the provided pointer
|
|
*
|
|
* @param mheap Multi heap pointer
|
|
* @param addr address to be found, must be a pointer to a block allocated by sys_multi_heap_alloc
|
|
* @return 0 multi_heap_rec pointer to a structure to be filled with return data
|
|
* or NULL if the heap has not been found
|
|
*/
|
|
const struct sys_multi_heap_rec *sys_multi_heap_get_heap(const struct sys_multi_heap *mheap,
|
|
void *addr);
|
|
|
|
/**
|
|
* @brief Free memory allocated from multi heap
|
|
*
|
|
* Returns the specified block, which must be the return value of a
|
|
* previously successful sys_multi_heap_alloc() or
|
|
* sys_multi_heap_aligned_alloc() call, to the heap backend from which
|
|
* it was allocated.
|
|
*
|
|
* Accepts NULL as a block parameter, which is specified to have no
|
|
* effect.
|
|
*
|
|
* @param mheap Multi heap pointer
|
|
* @param block Block to free, must be a pointer to a block allocated by sys_multi_heap_alloc
|
|
*/
|
|
void sys_multi_heap_free(struct sys_multi_heap *mheap, void *block);
|
|
|
|
#endif /* ZEPHYR_INCLUDE_SYS_MULTI_HEAP_H_ */
|