Line data    Source code

       1           0 : /*
       2             :  * Copyright (c) 2023 Carlo Caione, <ccaione@baylibre.com>
       3             :  *
       4             :  * SPDX-License-Identifier: Apache-2.0
       5             :  */
       6             : 
       7             : #ifndef ZEPHYR_INCLUDE_MEM_ATTR_HEAP_H_
       8             : #define ZEPHYR_INCLUDE_MEM_ATTR_HEAP_H_
       9             : 
      10             : /**
      11             :  * @brief Memory heaps based on memory attributes
      12             :  * @defgroup memory_attr_heap Memory heaps based on memory attributes
      13             :  * @ingroup mem_mgmt
      14             :  * @{
      15             :  */
      16             : 
      17             : #include <zephyr/mem_mgmt/mem_attr.h>
      18             : 
      19             : #ifdef __cplusplus
      20             : extern "C" {
      21             : #endif
      22             : 
      23             : /**
      24             :  * @brief Init the memory pool
      25             :  *
      26             :  * This must be the first function to be called to initialize the memory pools
      27             :  * from all the memory regions with the a software attribute.
      28             :  *
      29             :  * @retval 0 on success.
      30             :  * @retval -EALREADY if the pool was already initialized.
      31             :  * @retval -ENOMEM too many regions already allocated.
      32             :  */
      33           1 : int mem_attr_heap_pool_init(void);
      34             : 
      35             : /**
      36             :  * @brief Allocate memory with a specified attribute and size.
      37             :  *
      38             :  * Allocates a block of memory of the specified size in bytes and with a
      39             :  * specified capability / attribute. The attribute is used to select the
      40             :  * correct memory heap to allocate memory from.
      41             :  *
      42             :  * @param attr capability / attribute requested for the memory block.
      43             :  * @param bytes requested size of the allocation in bytes.
      44             :  *
      45             :  * @retval ptr a valid pointer to the allocated memory.
      46             :  * @retval NULL if no memory is available with that attribute and size.
      47             :  */
      48           1 : void *mem_attr_heap_alloc(uint32_t attr, size_t bytes);
      49             : 
      50             : /**
      51             :  * @brief Allocate aligned memory with a specified attribute, size and alignment.
      52             :  *
      53             :  * Allocates a block of memory of the specified size in bytes and with a
      54             :  * specified capability / attribute. Takes an additional parameter specifying a
      55             :  * power of two alignment in bytes.
      56             :  *
      57             :  * @param attr capability / attribute requested for the memory block.
      58             :  * @param align power of two alignment for the returned pointer in bytes.
      59             :  * @param bytes requested size of the allocation in bytes.
      60             :  *
      61             :  * @retval ptr a valid pointer to the allocated memory.
      62             :  * @retval NULL if no memory is available with that attribute and size.
      63             :  */
      64           1 : void *mem_attr_heap_aligned_alloc(uint32_t attr, size_t align, size_t bytes);
      65             : 
      66             : /**
      67             :  * @brief Free the allocated memory
      68             :  *
      69             :  * Used to free the passed block of memory that must be the return value of a
      70             :  * previously call to @ref mem_attr_heap_alloc or @ref
      71             :  * mem_attr_heap_aligned_alloc.
      72             :  *
      73             :  * @param block block to free, must be a pointer to a block allocated by
      74             :  *        @ref mem_attr_heap_alloc or @ref mem_attr_heap_aligned_alloc.
      75             :  */
      76           1 : void mem_attr_heap_free(void *block);
      77             : 
      78             : /**
      79             :  * @brief Get a specific memory region descriptor for a provided address
      80             :  *
      81             :  * Finds the memory region descriptor struct controlling the provided pointer.
      82             :  *
      83             :  * @param addr address to be found, must be a pointer to a block allocated by
      84             :  *             @ref mem_attr_heap_alloc or @ref mem_attr_heap_aligned_alloc.
      85             :  *
      86             :  * @retval str pointer to a memory region structure the address belongs to.
      87             :  */
      88           1 : const struct mem_attr_region_t *mem_attr_heap_get_region(void *addr);
      89             : 
      90             : #ifdef __cplusplus
      91             : }
      92             : #endif
      93             : 
      94             : /**
      95             :  * @}
      96             :  */
      97             : 
      98             : #endif /* ZEPHYR_INCLUDE_MEM_ATTR_HEAP_H_ */