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