nsdynmemLIB.h

00001 /*
00002  * Copyright (c) 2014-2019 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 h_size size of the heap buffer
00075   * \param passed_fptr pointer to heap error callback function
00076   * \param info_ptr Pointer to mem_stat_t for memory statistics. Can be NULL.
00077   *
00078   * \return None
00079   */
00080 extern void ns_dyn_mem_init(void *heap_ptr, ns_mem_heap_size_t h_size, void (*passed_fptr)(heap_fail_t), mem_stat_t *info_ptr);
00081 
00082 /**
00083   * \brief Add memory region to initialized heap.
00084   *
00085   * This method adds memory region to already initialized heap.
00086   * Method will reset temporary heap threshold to the default value.
00087   *
00088   * \param region_ptr Pointer to memory region to be added
00089   * \param region_size size of the region buffer
00090   * \return 0 on success, <0 in case of errors.
00091   */
00092 extern int ns_dyn_mem_region_add(void *region_ptr, ns_mem_heap_size_t region_size);
00093 
00094 /**
00095   * \brief Free allocated memory.
00096   *
00097   * \param heap_ptr Pointer to allocated memory
00098   *
00099   * \return 0, Free OK
00100   * \return <0, Free Fail
00101   */
00102 extern void ns_dyn_mem_free(void *heap_ptr);
00103 
00104 /**
00105   * \brief Allocate temporary data.
00106   *
00107   * Space allocate started from beginning of the heap sector
00108   *
00109   * \param alloc_size Allocated data size
00110   *
00111   * \return 0, Allocate Fail
00112   * \return >0, Pointer to allocated data sector.
00113   */
00114 extern void *ns_dyn_mem_temporary_alloc(ns_mem_block_size_t alloc_size);
00115 
00116 /**
00117   * \brief Allocate long period data.
00118   *
00119   * Space allocate started from end of the heap sector
00120   *
00121   * \param alloc_size Allocated data size
00122   *
00123   * \return 0, Allocate Fail
00124   * \return >0, Pointer to allocated data sector.
00125   */
00126 extern void *ns_dyn_mem_alloc(ns_mem_block_size_t alloc_size);
00127 
00128 /**
00129   * \brief Get pointer to the current mem_stat_t set via ns_dyn_mem_init.
00130   *
00131   * Get pointer to the statistics information, if one is set during the
00132   * initialization. This may be useful for statistics collection purposes.
00133   *
00134   * Note: the caller may not modify the returned structure.
00135   *
00136   * \return NULL, no mem_stat_t was given on initialization
00137   * \return Pointer to mem_stat_t or NULL.
00138   */
00139 extern const mem_stat_t *ns_dyn_mem_get_mem_stat(void);
00140 
00141 /**
00142   * \brief Set amount of free heap that must be available for temporary memory allocation to succeed.
00143   *
00144   * Temporary memory allocation will fail if system does not have defined amount of heap free.
00145   *
00146   * Note: the caller must set mem_stat_t structure in initialization.
00147   *
00148   * \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.
00149   * \param free_heap_amount Amount of free heap that must be free for temporary memory allocation. This value takes preference over percentage parameter value.
00150   *
00151   * \return 0 on success, <0 otherwise
00152   */
00153 extern int ns_dyn_mem_set_temporary_alloc_free_heap_threshold(uint8_t free_heap_percentage, ns_mem_heap_size_t free_heap_amount);
00154 
00155 /**
00156   * \brief Init and set Dynamical heap pointer and length.
00157   *
00158   * \param heap_ptr Pointer to dynamically heap buffer.
00159   * \param h_size size of the heap buffer.
00160   * \param passed_fptr pointer to heap error callback function.
00161   * \param info_ptr Pointer to mem_stat_t for memory statistics. Can be NULL.
00162   * \return Pointer to ns_mem_book_t.
00163   */
00164 extern ns_mem_book_t *ns_mem_init(void *heap_ptr, ns_mem_heap_size_t h_size, void (*passed_fptr)(heap_fail_t), mem_stat_t *info_ptr);
00165 
00166 /**
00167   * \brief Add memory region to initialized heap.
00168   *
00169   * This method adds memory region to already initialized heap.
00170   * Method will reset temporary heap threshold to the default value.
00171   *
00172   * \param book Address of book keeping structure.
00173   * \param region_ptr Pointer to memory region buffer.
00174   * \param region_size size of the memory region to add
00175   *
00176   * \return 0 on success, <0 in case of errors.
00177   */
00178 extern int ns_mem_region_add(ns_mem_book_t *book, void *region_ptr, ns_mem_heap_size_t region_size);
00179 
00180 /**
00181   * \brief Free allocated memory.
00182   *
00183   * \param book Address of book keeping structure
00184   * \param heap_ptr Pointer to allocated memory
00185   *
00186   * \return 0, Free OK
00187   * \return <0, Free Fail
00188   */
00189 extern void ns_mem_free(ns_mem_book_t *book, void *heap_ptr);
00190 
00191 /**
00192   * \brief Allocate temporary data.
00193   *
00194   * Space allocate started from beginning of the heap sector
00195   *
00196   * \param book Address of book keeping structure
00197   * \param alloc_size Allocated data size
00198   *
00199   * \return 0, Allocate Fail
00200   * \return >0, Pointer to allocated data sector.
00201   */
00202 extern void *ns_mem_temporary_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size);
00203 
00204 /**
00205   * \brief Allocate long period data.
00206   *
00207   * Space allocate started from end of the heap sector
00208   *
00209   * \param book Address of book keeping structure
00210   * \param alloc_size Allocated data size
00211   *
00212   * \return 0, Allocate Fail
00213   * \return >0, Pointer to allocated data sector.
00214   */
00215 extern void *ns_mem_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size);
00216 
00217 /**
00218   * \brief Get pointer to the current mem_stat_t set via ns_mem_init.
00219   *
00220   * Get pointer to the statistics information, if one is set during the
00221   * initialization. This may be useful for statistics collection purposes.
00222   *
00223   * Note: the caller may not modify the returned structure.
00224   *
00225   * \param book Address of book keeping structure
00226   *
00227   * \return NULL, no mem_stat_t was given on initialization
00228   * \return !=0, Pointer to mem_stat_t.
00229   */
00230 extern const mem_stat_t *ns_mem_get_mem_stat(ns_mem_book_t *book);
00231 
00232 /**
00233   * \brief Set amount of free heap that must be available for temporary memory allocation to succeed.
00234   *
00235   * Temporary memory allocation will fail if system does not have defined amount of heap free.
00236   *
00237   * Note: the caller must set mem_stat_t structure in initialization.
00238   *
00239   * \param book Address of book keeping structure
00240   * \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.
00241   * \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.
00242   *
00243   * \return 0 on success, <0 otherwise
00244   */
00245 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);
00246 
00247 #ifdef __cplusplus
00248 }
00249 #endif
00250 #endif /* NSDYNMEMLIB_H_ */
00251 
00252