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