nsdynmemLIB.h

00001 /*
00002  * Copyright (c) 2014-2016 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 2
00036 
00037 typedef uint16_t ns_mem_block_size_t; //external interface unsigned heap block size type
00038 typedef uint16_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 Init and set Dynamical heap pointer and length.
00127   *
00128   * \param heap_ptr Pointer to dynamically heap buffer
00129   * \param heap_size size of the heap buffer
00130   * \return !=0, Pointer to ns_mem_book_t.
00131   */
00132 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);
00133 
00134 /**
00135   * \brief Free allocated memory.
00136   *
00137   * \param book Address of book keeping structure
00138   * \param heap_ptr Pointer to allocated memory
00139   *
00140   * \return 0, Free OK
00141   * \return <0, Free Fail
00142   */
00143 extern void ns_mem_free(ns_mem_book_t *book, void *heap_ptr);
00144 /**
00145   * \brief Allocate temporary data.
00146   *
00147   * Space allocate started from beginning of the heap sector
00148   *
00149   * \param book Address of book keeping structure
00150   * \param alloc_size Allocated data size
00151   *
00152   * \return 0, Allocate Fail
00153   * \return >0, Pointer to allocated data sector.
00154   */
00155 extern void *ns_mem_temporary_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size);
00156 /**
00157   * \brief Allocate long period data.
00158   *
00159   * Space allocate started from end of the heap sector
00160   *
00161   * \param book Address of book keeping structure
00162   * \param alloc_size Allocated data size
00163   *
00164   * \return 0, Allocate Fail
00165   * \return >0, Pointer to allocated data sector.
00166   */
00167 extern void *ns_mem_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size);
00168 
00169 /**
00170   * \brief Get pointer to the current mem_stat_t set via ns_mem_init.
00171   *
00172   * Get pointer to the statistics information, if one is set during the
00173   * initialization. This may be useful for statistics collection purposes.
00174   *
00175   * Note: the caller may not modify the returned structure.
00176   *
00177   * \param book Address of book keeping structure
00178   *
00179   * \return NULL, no mem_stat_t was given on initialization
00180   * \return !=0, Pointer to mem_stat_t.
00181   */
00182 extern const mem_stat_t *ns_mem_get_mem_stat(ns_mem_book_t *book);
00183 
00184 #ifdef __cplusplus
00185 }
00186 #endif
00187 #endif /* NSDYNMEMLIB_H_ */
00188