Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
nsdynmemLIB.h
00001 /* 00002 * Copyright (c) 2014-2018 ARM Limited. All rights reserved. 00003 * SPDX-License-Identifier: Apache-2.0 00004 * Licensed under the Apache License, Version 2.0 (the License); you may 00005 * not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an AS IS BASIS, WITHOUT 00012 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 00018 /** 00019 * \file nsdynmemLIB.h 00020 * \brief Dynamical Memory API for library model 00021 * nsdynmemlib provides access to one default heap, along with the ability to use extra user heaps. 00022 * ns_dyn_mem_alloc/free always access the default heap initialised by ns_dyn_mem_init. 00023 * ns_mem_alloc/free access a user heap initialised by ns_mem_init. User heaps are identified by a book-keeping pointer. 00024 */ 00025 00026 #ifndef NSDYNMEMLIB_H_ 00027 #define NSDYNMEMLIB_H_ 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif 00031 00032 #include "ns_types.h" 00033 00034 // Added to maintain backward compatibility with older implementation of ns_dyn_mem APIs 00035 #define NSDYNMEMLIB_API_VERSION 3 00036 00037 typedef size_t ns_mem_block_size_t; //external interface unsigned heap block size type 00038 typedef size_t ns_mem_heap_size_t; //total heap size type. 00039 00040 /*! 00041 * \enum heap_fail_t 00042 * \brief Dynamically heap system failure call back event types. 00043 */ 00044 typedef enum { 00045 NS_DYN_MEM_NULL_FREE, /**< ns_dyn_mem_free(), NULL pointer free [obsolete - no longer faulted] */ 00046 NS_DYN_MEM_DOUBLE_FREE, /**< ns_dyn_mem_free(), Possible double pointer free */ 00047 NS_DYN_MEM_ALLOCATE_SIZE_NOT_VALID, /**< Allocate size is 0 or smaller or size is bigger than max heap size */ 00048 NS_DYN_MEM_POINTER_NOT_VALID, /**< ns_dyn_mem_free(), try to free pointer which not at heap sector */ 00049 NS_DYN_MEM_HEAP_SECTOR_CORRUPTED, /**< Heap system detect sector corruption */ 00050 NS_DYN_MEM_HEAP_SECTOR_UNITIALIZED /**< ns_dyn_mem_free(), ns_dyn_mem_temporary_alloc() or ns_dyn_mem_alloc() called before ns_dyn_mem_init() */ 00051 } heap_fail_t; 00052 00053 /** 00054 * /struct mem_stat_t 00055 * /brief Struct for Memory stats Buffer structure 00056 */ 00057 typedef struct mem_stat_t { 00058 /*Heap stats*/ 00059 ns_mem_heap_size_t heap_sector_size; /**< Heap total Sector len. */ 00060 ns_mem_heap_size_t heap_sector_alloc_cnt; /**< Reserved Heap sector cnt. */ 00061 ns_mem_heap_size_t heap_sector_allocated_bytes; /**< Reserved Heap data in bytes. */ 00062 ns_mem_heap_size_t heap_sector_allocated_bytes_max; /**< Reserved Heap data in bytes max value. */ 00063 uint32_t heap_alloc_total_bytes; /**< Total Heap allocated bytes. */ 00064 uint32_t heap_alloc_fail_cnt; /**< Counter for Heap allocation fail. */ 00065 } mem_stat_t; 00066 00067 00068 typedef struct ns_mem_book ns_mem_book_t; 00069 00070 /** 00071 * \brief Init and set Dynamical heap pointer and length. 00072 * 00073 * \param heap_ptr Pointer to dynamically heap buffer 00074 * \param heap_size size of the heap buffer 00075 * \return None 00076 */ 00077 extern void ns_dyn_mem_init(void *heap, ns_mem_heap_size_t h_size, void (*passed_fptr)(heap_fail_t), mem_stat_t *info_ptr); 00078 00079 00080 /** 00081 * \brief Free allocated memory. 00082 * 00083 * \param heap_ptr Pointer to allocated memory 00084 * 00085 * \return 0, Free OK 00086 * \return <0, Free Fail 00087 */ 00088 extern void ns_dyn_mem_free(void *heap_ptr); 00089 /** 00090 * \brief Allocate temporary data. 00091 * 00092 * Space allocate started from beginning of the heap sector 00093 * 00094 * \param alloc_size Allocated data size 00095 * 00096 * \return 0, Allocate Fail 00097 * \return >0, Pointer to allocated data sector. 00098 */ 00099 extern void *ns_dyn_mem_temporary_alloc(ns_mem_block_size_t alloc_size); 00100 /** 00101 * \brief Allocate long period data. 00102 * 00103 * Space allocate started from end of the heap sector 00104 * 00105 * \param alloc_size Allocated data size 00106 * 00107 * \return 0, Allocate Fail 00108 * \return >0, Pointer to allocated data sector. 00109 */ 00110 extern void *ns_dyn_mem_alloc(ns_mem_block_size_t alloc_size); 00111 00112 /** 00113 * \brief Get pointer to the current mem_stat_t set via ns_dyn_mem_init. 00114 * 00115 * Get pointer to the statistics information, if one is set during the 00116 * initialization. This may be useful for statistics collection purposes. 00117 * 00118 * Note: the caller may not modify the returned structure. 00119 * 00120 * \return NULL, no mem_stat_t was given on initialization 00121 * \return !=0, Pointer to mem_stat_t. 00122 */ 00123 extern const mem_stat_t *ns_dyn_mem_get_mem_stat(void); 00124 00125 /** 00126 * \brief Set amount of free heap that must be available for temporary memory allocation to succeed. 00127 * 00128 * Temporary memory allocation will fail if system does not have defined amount of heap free. 00129 * 00130 * Note: the caller must set mem_stat_t structure in initialization. 00131 * 00132 * \param free_heap_percentage percentage of total heap that must be free for temporary memory allocation. Set free_heap_amount to 0 when this percentage value. 00133 * \param free_heap_amount Amount of free heap that must be free for temporary memory allocation. This value takes preference over percentage parameter value. 00134 * 00135 * \return 0 on success, <0 otherwise 00136 */ 00137 extern int ns_dyn_mem_set_temporary_alloc_free_heap_threshold(uint8_t free_heap_percentage, ns_mem_heap_size_t free_heap_amount); 00138 00139 /** 00140 * \brief Init and set Dynamical heap pointer and length. 00141 * 00142 * \param heap_ptr Pointer to dynamically heap buffer 00143 * \param heap_size size of the heap buffer 00144 * \return !=0, Pointer to ns_mem_book_t. 00145 */ 00146 extern ns_mem_book_t *ns_mem_init(void *heap, ns_mem_heap_size_t h_size, void (*passed_fptr)(heap_fail_t), mem_stat_t *info_ptr); 00147 00148 /** 00149 * \brief Free allocated memory. 00150 * 00151 * \param book Address of book keeping structure 00152 * \param heap_ptr Pointer to allocated memory 00153 * 00154 * \return 0, Free OK 00155 * \return <0, Free Fail 00156 */ 00157 extern void ns_mem_free(ns_mem_book_t *book, void *heap_ptr); 00158 /** 00159 * \brief Allocate temporary data. 00160 * 00161 * Space allocate started from beginning of the heap sector 00162 * 00163 * \param book Address of book keeping structure 00164 * \param alloc_size Allocated data size 00165 * 00166 * \return 0, Allocate Fail 00167 * \return >0, Pointer to allocated data sector. 00168 */ 00169 extern void *ns_mem_temporary_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size); 00170 /** 00171 * \brief Allocate long period data. 00172 * 00173 * Space allocate started from end of the heap sector 00174 * 00175 * \param book Address of book keeping structure 00176 * \param alloc_size Allocated data size 00177 * 00178 * \return 0, Allocate Fail 00179 * \return >0, Pointer to allocated data sector. 00180 */ 00181 extern void *ns_mem_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size); 00182 00183 /** 00184 * \brief Get pointer to the current mem_stat_t set via ns_mem_init. 00185 * 00186 * Get pointer to the statistics information, if one is set during the 00187 * initialization. This may be useful for statistics collection purposes. 00188 * 00189 * Note: the caller may not modify the returned structure. 00190 * 00191 * \param book Address of book keeping structure 00192 * 00193 * \return NULL, no mem_stat_t was given on initialization 00194 * \return !=0, Pointer to mem_stat_t. 00195 */ 00196 extern const mem_stat_t *ns_mem_get_mem_stat(ns_mem_book_t *book); 00197 00198 /** 00199 * \brief Set amount of free heap that must be available for temporary memory allocation to succeed. 00200 * 00201 * Temporary memory allocation will fail if system does not have defined amount of heap free. 00202 * 00203 * Note: the caller must set mem_stat_t structure in initialization. 00204 * 00205 * \param book Address of book keeping structure 00206 * \param free_heap_percentage percentage of total heap that must be free for temporary memory allocation. Set free_heap_amount to 0 when using percentage value. 00207 * \param free_heap_amount Amount of free heap that must be free for temporary memory allocation. This value takes preference over the percentage parameter value. 00208 * 00209 * \return 0 on success, <0 otherwise 00210 */ 00211 extern int ns_mem_set_temporary_alloc_free_heap_threshold(ns_mem_book_t *book, uint8_t free_heap_percentage, ns_mem_heap_size_t free_heap_amount); 00212 00213 #ifdef __cplusplus 00214 } 00215 #endif 00216 #endif /* NSDYNMEMLIB_H_ */ 00217 00218
Generated on Tue Aug 9 2022 00:37:17 by
