granicus.if.org Git - esp-idf/blob - components/heap/include/esp_heap_alloc_caps.h

   1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD
   2 //
   3 // Licensed under the Apache License, Version 2.0 (the "License");
   4 // you may not use this file except in compliance with the License.
   5 // You may obtain a copy of the License at
   6
   7 //     http://www.apache.org/licenses/LICENSE-2.0
   8 //
   9 // Unless required by applicable law or agreed to in writing, software
  10 // distributed under the License is distributed on an "AS IS" BASIS,
  11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 // See the License for the specific language governing permissions and
  13 // limitations under the License.
  14 #ifndef HEAP_ALLOC_CAPS_H
  15 #define HEAP_ALLOC_CAPS_H
  16
  17 #ifdef __cplusplus
  18 extern "C" {
  19 #endif
  20
  21 #include <stdint.h>
  22 #include <stdlib.h>
  23
  24 /**
  25  * @brief Flags to indicate the capabilities of the various memory systems
  26  */
  27 #define MALLOC_CAP_EXEC             (1<<0)  ///< Memory must be able to run executable code
  28 #define MALLOC_CAP_32BIT            (1<<1)  ///< Memory must allow for aligned 32-bit data accesses
  29 #define MALLOC_CAP_8BIT             (1<<2)  ///< Memory must allow for 8/16/...-bit data accesses
  30 #define MALLOC_CAP_DMA              (1<<3)  ///< Memory must be able to accessed by DMA
  31 #define MALLOC_CAP_PID2             (1<<4)  ///< Memory must be mapped to PID2 memory space
  32 #define MALLOC_CAP_PID3             (1<<5)  ///< Memory must be mapped to PID3 memory space
  33 #define MALLOC_CAP_PID4             (1<<6)  ///< Memory must be mapped to PID4 memory space
  34 #define MALLOC_CAP_PID5             (1<<7)  ///< Memory must be mapped to PID5 memory space
  35 #define MALLOC_CAP_PID6             (1<<8)  ///< Memory must be mapped to PID6 memory space
  36 #define MALLOC_CAP_PID7             (1<<9)  ///< Memory must be mapped to PID7 memory space
  37 #define MALLOC_CAP_SPISRAM          (1<<10) ///< Memory must be in SPI SRAM
  38 #define MALLOC_CAP_INVALID          (1<<31) ///< Memory can't be used / list end marker
  39
  40
  41 /**
  42  * @brief Initialize the capability-aware heap allocator.
  43  *
  44  * For the ESP32, this is called once in the startup code.
  45  */
  46 void heap_alloc_caps_init();
  47
  48 /**
  49  * @brief Enable the memory region where the startup stacks are located for allocation
  50  *
  51  * On startup, the pro/app CPUs have a certain memory region they use as stack, so we
  52  * cannot do allocations in the regions these stack frames are. When FreeRTOS is
  53  * completely started, they do not use that memory anymore and allocation there can
  54  * be re-enabled.
  55  */
  56 void heap_alloc_enable_nonos_stack_tag();
  57
  58 /**
  59  * @brief Allocate a chunk of memory which has the given capabilities
  60  *
  61  * @param xWantedSize Size, in bytes, of the amount of memory to allocate
  62  * @param caps        Bitwise OR of MALLOC_CAP_* flags indicating the type
  63  *                    of memory to be returned
  64  *
  65  * @return A pointer to the memory allocated on success, NULL on failure
  66  */
  67 void *pvPortMallocCaps(size_t xWantedSize, uint32_t caps);
  68
  69 /**
  70  * @brief Get the total free size of all the regions that have the given capabilities
  71  *
  72  * This function takes all regions capable of having the given capabilities allocated in them
  73  * and adds up the free space they have.
  74  *
  75  * @param caps        Bitwise OR of MALLOC_CAP_* flags indicating the type
  76  *                    of memory
  77  *
  78  * @return Amount of free bytes in the regions
  79  */
  80 size_t xPortGetFreeHeapSizeCaps( uint32_t caps );
  81
  82 /**
  83  * @brief Get the total minimum free memory of all regions with the given capabilities
  84  *
  85  * This adds all the lowmarks of the regions capable of delivering the memory with the
  86  * given capabilities
  87  *
  88  * @param caps        Bitwise OR of MALLOC_CAP_* flags indicating the type
  89  *                    of memory
  90  *
  91  * @return Amount of free bytes in the regions
  92  */
  93 size_t xPortGetMinimumEverFreeHeapSizeCaps( uint32_t caps );
  94
  95
  96
  97 /**
  98  * @brief Convenience function to check if a pointer is DMA-capable.
  99  *
 100  * @param ptr         Pointer to check
 101  *
 102  * @return True if DMA-capable, false if not.
 103  */
 104 static inline bool  esp_ptr_dma_capable( const void *ptr )
 105 {
 106     return ( (int)ptr >= 0x3FFAE000 && (int)ptr < 0x40000000 );
 107 }
 108
 109 #ifdef __cplusplus
 110 }
 111 #endif
 112
 113 #endif //HEAP_ALLOC_CAPS_H