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  *
00022  */
00023 #ifndef NSDYNMEMLIB_H_
00024 #define NSDYNMEMLIB_H_
00025 #ifdef __cplusplus
00026 extern "C" {
00027 #endif
00028 
00029 #include "ns_types.h"
00030 
00031 /*!
00032  * \enum heap_fail_t
00033  * \brief Dynamically heap system failure call back event types.
00034  */
00035 typedef enum {
00036     NS_DYN_MEM_NULL_FREE,               /**< ns_dyn_mem_free(), NULL pointer free [obsolete - no longer faulted]  */
00037     NS_DYN_MEM_DOUBLE_FREE,                     /**< ns_dyn_mem_free(), Possible double pointer free */
00038     NS_DYN_MEM_ALLOCATE_SIZE_NOT_VALID, /**< Allocate size is 0 or smaller or size is bigger than max heap size  */
00039     NS_DYN_MEM_POINTER_NOT_VALID,       /**< ns_dyn_mem_free(), try to free pointer which not at heap sector */
00040     NS_DYN_MEM_HEAP_SECTOR_CORRUPTED,   /**< Heap system detect sector corruption */
00041     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() */
00042 } heap_fail_t;
00043 
00044 /**
00045  * /struct mem_stat_t
00046  * /brief Struct for Memory stats Buffer structure
00047  */
00048 typedef struct mem_stat_t {
00049     /*Heap stats*/
00050     int16_t heap_sector_size;                   /**< Heap total Sector len. */
00051     int16_t heap_sector_alloc_cnt;              /**< Reserved Heap sector cnt. */
00052     int16_t heap_sector_allocated_bytes;        /**< Reserved Heap data in bytes. */
00053     int16_t heap_sector_allocated_bytes_max;    /**< Reserved Heap data in bytes max value. */
00054     uint32_t heap_alloc_total_bytes;            /**< Total Heap allocated bytes. */
00055     uint32_t heap_alloc_fail_cnt;               /**< Counter for Heap allocation fail. */
00056 } mem_stat_t;
00057 
00058 /**
00059   * \brief Init and set Dynamical heap pointer and length.
00060   *
00061   * \param heap_ptr Pointer to dynamically heap buffer
00062   * \param heap_size size of the heap buffer
00063   * \return None
00064   */
00065 extern void ns_dyn_mem_init(uint8_t *heap, uint16_t h_size, void (*passed_fptr)(heap_fail_t), mem_stat_t *info_ptr);
00066 
00067 
00068 /**
00069   * \brief Free allocated memory.
00070   *
00071   * \param heap_ptr Pointer to allocated memory
00072   *
00073   * \return 0, Free OK
00074   * \return <0, Free Fail
00075   */
00076 extern void ns_dyn_mem_free(void *heap_ptr);
00077 /**
00078   * \brief Allocate temporary data.
00079   *
00080   * Space allocate started from beginning of the heap sector
00081   *
00082   * \param alloc_size Allocated data size
00083   *
00084   * \return 0, Allocate Fail
00085   * \return >0, Pointer to allocated data sector.
00086   */
00087 extern void *ns_dyn_mem_temporary_alloc(int16_t alloc_size);
00088 /**
00089   * \brief Allocate long period data.
00090   *
00091   * Space allocate started from end of the heap sector
00092   *
00093   * \param alloc_size Allocated data size
00094   *
00095   * \return 0, Allocate Fail
00096   * \return >0, Pointer to allocated data sector.
00097   */
00098 extern void *ns_dyn_mem_alloc(int16_t alloc_size);
00099 
00100 /**
00101   * \brief Get pointer to the current mem_stat_t set via ns_dyn_mem_init.
00102   *
00103   * Get pointer to the statistics information, if one is set during the
00104   * initialization. This may be useful for statistics collection purposes.
00105   *
00106   * Note: the caller may not modify the returned structure.
00107   *
00108   * \return NULL, no mem_stat_t was given on initialization
00109   * \return !=0, Pointer to mem_stat_t.
00110   */
00111 extern const mem_stat_t *ns_dyn_mem_get_mem_stat(void);
00112 
00113 #ifdef __cplusplus
00114 }
00115 #endif
00116 #endif /* NSDYNMEMLIB_H_ */
00117