leo hendrickson / Mbed OS example-Ethernet-mbed-Cloud-connect

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.

simple-mbed-cloud-client/mbed-cloud-client/nanostack-libservice/mbed-client-libservice/nsdynmemLIB.h@0:8f0bb79ddd48, 2021-05-04 (annotated)

Committer:
leothedragon
Date:
Tue May 04 08:55:12 2021 +0000
Revision:
0:8f0bb79ddd48
nmn

Who changed what in which revision?

UserRevisionLine numberNew contents of line
leothedragon 0:8f0bb79ddd48 1 /*
leothedragon 0:8f0bb79ddd48 2 * Copyright (c) 2014-2018 ARM Limited. All rights reserved.
leothedragon 0:8f0bb79ddd48 3 * SPDX-License-Identifier: Apache-2.0
leothedragon 0:8f0bb79ddd48 4 * Licensed under the Apache License, Version 2.0 (the License); you may
leothedragon 0:8f0bb79ddd48 5 * not use this file except in compliance with the License.
leothedragon 0:8f0bb79ddd48 6 * You may obtain a copy of the License at
leothedragon 0:8f0bb79ddd48 7 *
leothedragon 0:8f0bb79ddd48 8 * http://www.apache.org/licenses/LICENSE-2.0
leothedragon 0:8f0bb79ddd48 9 *
leothedragon 0:8f0bb79ddd48 10 * Unless required by applicable law or agreed to in writing, software
leothedragon 0:8f0bb79ddd48 11 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
leothedragon 0:8f0bb79ddd48 12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
leothedragon 0:8f0bb79ddd48 13 * See the License for the specific language governing permissions and
leothedragon 0:8f0bb79ddd48 14 * limitations under the License.
leothedragon 0:8f0bb79ddd48 15 */
leothedragon 0:8f0bb79ddd48 16
leothedragon 0:8f0bb79ddd48 17
leothedragon 0:8f0bb79ddd48 18 /**
leothedragon 0:8f0bb79ddd48 19 * \file nsdynmemLIB.h
leothedragon 0:8f0bb79ddd48 20 * \brief Dynamical Memory API for library model
leothedragon 0:8f0bb79ddd48 21 * nsdynmemlib provides access to one default heap, along with the ability to use extra user heaps.
leothedragon 0:8f0bb79ddd48 22 * ns_dyn_mem_alloc/free always access the default heap initialised by ns_dyn_mem_init.
leothedragon 0:8f0bb79ddd48 23 * ns_mem_alloc/free access a user heap initialised by ns_mem_init. User heaps are identified by a book-keeping pointer.
leothedragon 0:8f0bb79ddd48 24 */
leothedragon 0:8f0bb79ddd48 25
leothedragon 0:8f0bb79ddd48 26 #ifndef NSDYNMEMLIB_H_
leothedragon 0:8f0bb79ddd48 27 #define NSDYNMEMLIB_H_
leothedragon 0:8f0bb79ddd48 28 #ifdef __cplusplus
leothedragon 0:8f0bb79ddd48 29 extern "C" {
leothedragon 0:8f0bb79ddd48 30 #endif
leothedragon 0:8f0bb79ddd48 31
leothedragon 0:8f0bb79ddd48 32 #include "ns_types.h"
leothedragon 0:8f0bb79ddd48 33
leothedragon 0:8f0bb79ddd48 34 // Added to maintain backward compatibility with older implementation of ns_dyn_mem APIs
leothedragon 0:8f0bb79ddd48 35 #define NSDYNMEMLIB_API_VERSION 3
leothedragon 0:8f0bb79ddd48 36
leothedragon 0:8f0bb79ddd48 37 typedef size_t ns_mem_block_size_t; //external interface unsigned heap block size type
leothedragon 0:8f0bb79ddd48 38 typedef size_t ns_mem_heap_size_t; //total heap size type.
leothedragon 0:8f0bb79ddd48 39
leothedragon 0:8f0bb79ddd48 40 /*!
leothedragon 0:8f0bb79ddd48 41 * \enum heap_fail_t
leothedragon 0:8f0bb79ddd48 42 * \brief Dynamically heap system failure call back event types.
leothedragon 0:8f0bb79ddd48 43 */
leothedragon 0:8f0bb79ddd48 44 typedef enum {
leothedragon 0:8f0bb79ddd48 45 NS_DYN_MEM_NULL_FREE, /**< ns_dyn_mem_free(), NULL pointer free [obsolete - no longer faulted] */
leothedragon 0:8f0bb79ddd48 46 NS_DYN_MEM_DOUBLE_FREE, /**< ns_dyn_mem_free(), Possible double pointer free */
leothedragon 0:8f0bb79ddd48 47 NS_DYN_MEM_ALLOCATE_SIZE_NOT_VALID, /**< Allocate size is 0 or smaller or size is bigger than max heap size */
leothedragon 0:8f0bb79ddd48 48 NS_DYN_MEM_POINTER_NOT_VALID, /**< ns_dyn_mem_free(), try to free pointer which not at heap sector */
leothedragon 0:8f0bb79ddd48 49 NS_DYN_MEM_HEAP_SECTOR_CORRUPTED, /**< Heap system detect sector corruption */
leothedragon 0:8f0bb79ddd48 50 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() */
leothedragon 0:8f0bb79ddd48 51 } heap_fail_t;
leothedragon 0:8f0bb79ddd48 52
leothedragon 0:8f0bb79ddd48 53 /**
leothedragon 0:8f0bb79ddd48 54 * /struct mem_stat_t
leothedragon 0:8f0bb79ddd48 55 * /brief Struct for Memory stats Buffer structure
leothedragon 0:8f0bb79ddd48 56 */
leothedragon 0:8f0bb79ddd48 57 typedef struct mem_stat_t {
leothedragon 0:8f0bb79ddd48 58 /*Heap stats*/
leothedragon 0:8f0bb79ddd48 59 ns_mem_heap_size_t heap_sector_size; /**< Heap total Sector len. */
leothedragon 0:8f0bb79ddd48 60 ns_mem_heap_size_t heap_sector_alloc_cnt; /**< Reserved Heap sector cnt. */
leothedragon 0:8f0bb79ddd48 61 ns_mem_heap_size_t heap_sector_allocated_bytes; /**< Reserved Heap data in bytes. */
leothedragon 0:8f0bb79ddd48 62 ns_mem_heap_size_t heap_sector_allocated_bytes_max; /**< Reserved Heap data in bytes max value. */
leothedragon 0:8f0bb79ddd48 63 uint32_t heap_alloc_total_bytes; /**< Total Heap allocated bytes. */
leothedragon 0:8f0bb79ddd48 64 uint32_t heap_alloc_fail_cnt; /**< Counter for Heap allocation fail. */
leothedragon 0:8f0bb79ddd48 65 } mem_stat_t;
leothedragon 0:8f0bb79ddd48 66
leothedragon 0:8f0bb79ddd48 67
leothedragon 0:8f0bb79ddd48 68 typedef struct ns_mem_book ns_mem_book_t;
leothedragon 0:8f0bb79ddd48 69
leothedragon 0:8f0bb79ddd48 70 /**
leothedragon 0:8f0bb79ddd48 71 * \brief Init and set Dynamical heap pointer and length.
leothedragon 0:8f0bb79ddd48 72 *
leothedragon 0:8f0bb79ddd48 73 * \param heap_ptr Pointer to dynamically heap buffer
leothedragon 0:8f0bb79ddd48 74 * \param heap_size size of the heap buffer
leothedragon 0:8f0bb79ddd48 75 * \return None
leothedragon 0:8f0bb79ddd48 76 */
leothedragon 0:8f0bb79ddd48 77 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);
leothedragon 0:8f0bb79ddd48 78
leothedragon 0:8f0bb79ddd48 79
leothedragon 0:8f0bb79ddd48 80 /**
leothedragon 0:8f0bb79ddd48 81 * \brief Free allocated memory.
leothedragon 0:8f0bb79ddd48 82 *
leothedragon 0:8f0bb79ddd48 83 * \param heap_ptr Pointer to allocated memory
leothedragon 0:8f0bb79ddd48 84 *
leothedragon 0:8f0bb79ddd48 85 * \return 0, Free OK
leothedragon 0:8f0bb79ddd48 86 * \return <0, Free Fail
leothedragon 0:8f0bb79ddd48 87 */
leothedragon 0:8f0bb79ddd48 88 extern void ns_dyn_mem_free(void *heap_ptr);
leothedragon 0:8f0bb79ddd48 89 /**
leothedragon 0:8f0bb79ddd48 90 * \brief Allocate temporary data.
leothedragon 0:8f0bb79ddd48 91 *
leothedragon 0:8f0bb79ddd48 92 * Space allocate started from beginning of the heap sector
leothedragon 0:8f0bb79ddd48 93 *
leothedragon 0:8f0bb79ddd48 94 * \param alloc_size Allocated data size
leothedragon 0:8f0bb79ddd48 95 *
leothedragon 0:8f0bb79ddd48 96 * \return 0, Allocate Fail
leothedragon 0:8f0bb79ddd48 97 * \return >0, Pointer to allocated data sector.
leothedragon 0:8f0bb79ddd48 98 */
leothedragon 0:8f0bb79ddd48 99 extern void *ns_dyn_mem_temporary_alloc(ns_mem_block_size_t alloc_size);
leothedragon 0:8f0bb79ddd48 100 /**
leothedragon 0:8f0bb79ddd48 101 * \brief Allocate long period data.
leothedragon 0:8f0bb79ddd48 102 *
leothedragon 0:8f0bb79ddd48 103 * Space allocate started from end of the heap sector
leothedragon 0:8f0bb79ddd48 104 *
leothedragon 0:8f0bb79ddd48 105 * \param alloc_size Allocated data size
leothedragon 0:8f0bb79ddd48 106 *
leothedragon 0:8f0bb79ddd48 107 * \return 0, Allocate Fail
leothedragon 0:8f0bb79ddd48 108 * \return >0, Pointer to allocated data sector.
leothedragon 0:8f0bb79ddd48 109 */
leothedragon 0:8f0bb79ddd48 110 extern void *ns_dyn_mem_alloc(ns_mem_block_size_t alloc_size);
leothedragon 0:8f0bb79ddd48 111
leothedragon 0:8f0bb79ddd48 112 /**
leothedragon 0:8f0bb79ddd48 113 * \brief Get pointer to the current mem_stat_t set via ns_dyn_mem_init.
leothedragon 0:8f0bb79ddd48 114 *
leothedragon 0:8f0bb79ddd48 115 * Get pointer to the statistics information, if one is set during the
leothedragon 0:8f0bb79ddd48 116 * initialization. This may be useful for statistics collection purposes.
leothedragon 0:8f0bb79ddd48 117 *
leothedragon 0:8f0bb79ddd48 118 * Note: the caller may not modify the returned structure.
leothedragon 0:8f0bb79ddd48 119 *
leothedragon 0:8f0bb79ddd48 120 * \return NULL, no mem_stat_t was given on initialization
leothedragon 0:8f0bb79ddd48 121 * \return !=0, Pointer to mem_stat_t.
leothedragon 0:8f0bb79ddd48 122 */
leothedragon 0:8f0bb79ddd48 123 extern const mem_stat_t *ns_dyn_mem_get_mem_stat(void);
leothedragon 0:8f0bb79ddd48 124
leothedragon 0:8f0bb79ddd48 125 /**
leothedragon 0:8f0bb79ddd48 126 * \brief Set amount of free heap that must be available for temporary memory allocation to succeed.
leothedragon 0:8f0bb79ddd48 127 *
leothedragon 0:8f0bb79ddd48 128 * Temporary memory allocation will fail if system does not have defined amount of heap free.
leothedragon 0:8f0bb79ddd48 129 *
leothedragon 0:8f0bb79ddd48 130 * Note: the caller must set mem_stat_t structure in initialization.
leothedragon 0:8f0bb79ddd48 131 *
leothedragon 0:8f0bb79ddd48 132 * \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.
leothedragon 0:8f0bb79ddd48 133 * \param free_heap_amount Amount of free heap that must be free for temporary memory allocation. This value takes preference over percentage parameter value.
leothedragon 0:8f0bb79ddd48 134 *
leothedragon 0:8f0bb79ddd48 135 * \return 0 on success, <0 otherwise
leothedragon 0:8f0bb79ddd48 136 */
leothedragon 0:8f0bb79ddd48 137 extern int ns_dyn_mem_set_temporary_alloc_free_heap_threshold(uint8_t free_heap_percentage, ns_mem_heap_size_t free_heap_amount);
leothedragon 0:8f0bb79ddd48 138
leothedragon 0:8f0bb79ddd48 139 /**
leothedragon 0:8f0bb79ddd48 140 * \brief Init and set Dynamical heap pointer and length.
leothedragon 0:8f0bb79ddd48 141 *
leothedragon 0:8f0bb79ddd48 142 * \param heap_ptr Pointer to dynamically heap buffer
leothedragon 0:8f0bb79ddd48 143 * \param heap_size size of the heap buffer
leothedragon 0:8f0bb79ddd48 144 * \return !=0, Pointer to ns_mem_book_t.
leothedragon 0:8f0bb79ddd48 145 */
leothedragon 0:8f0bb79ddd48 146 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);
leothedragon 0:8f0bb79ddd48 147
leothedragon 0:8f0bb79ddd48 148 /**
leothedragon 0:8f0bb79ddd48 149 * \brief Free allocated memory.
leothedragon 0:8f0bb79ddd48 150 *
leothedragon 0:8f0bb79ddd48 151 * \param book Address of book keeping structure
leothedragon 0:8f0bb79ddd48 152 * \param heap_ptr Pointer to allocated memory
leothedragon 0:8f0bb79ddd48 153 *
leothedragon 0:8f0bb79ddd48 154 * \return 0, Free OK
leothedragon 0:8f0bb79ddd48 155 * \return <0, Free Fail
leothedragon 0:8f0bb79ddd48 156 */
leothedragon 0:8f0bb79ddd48 157 extern void ns_mem_free(ns_mem_book_t *book, void *heap_ptr);
leothedragon 0:8f0bb79ddd48 158 /**
leothedragon 0:8f0bb79ddd48 159 * \brief Allocate temporary data.
leothedragon 0:8f0bb79ddd48 160 *
leothedragon 0:8f0bb79ddd48 161 * Space allocate started from beginning of the heap sector
leothedragon 0:8f0bb79ddd48 162 *
leothedragon 0:8f0bb79ddd48 163 * \param book Address of book keeping structure
leothedragon 0:8f0bb79ddd48 164 * \param alloc_size Allocated data size
leothedragon 0:8f0bb79ddd48 165 *
leothedragon 0:8f0bb79ddd48 166 * \return 0, Allocate Fail
leothedragon 0:8f0bb79ddd48 167 * \return >0, Pointer to allocated data sector.
leothedragon 0:8f0bb79ddd48 168 */
leothedragon 0:8f0bb79ddd48 169 extern void *ns_mem_temporary_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size);
leothedragon 0:8f0bb79ddd48 170 /**
leothedragon 0:8f0bb79ddd48 171 * \brief Allocate long period data.
leothedragon 0:8f0bb79ddd48 172 *
leothedragon 0:8f0bb79ddd48 173 * Space allocate started from end of the heap sector
leothedragon 0:8f0bb79ddd48 174 *
leothedragon 0:8f0bb79ddd48 175 * \param book Address of book keeping structure
leothedragon 0:8f0bb79ddd48 176 * \param alloc_size Allocated data size
leothedragon 0:8f0bb79ddd48 177 *
leothedragon 0:8f0bb79ddd48 178 * \return 0, Allocate Fail
leothedragon 0:8f0bb79ddd48 179 * \return >0, Pointer to allocated data sector.
leothedragon 0:8f0bb79ddd48 180 */
leothedragon 0:8f0bb79ddd48 181 extern void *ns_mem_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size);
leothedragon 0:8f0bb79ddd48 182
leothedragon 0:8f0bb79ddd48 183 /**
leothedragon 0:8f0bb79ddd48 184 * \brief Get pointer to the current mem_stat_t set via ns_mem_init.
leothedragon 0:8f0bb79ddd48 185 *
leothedragon 0:8f0bb79ddd48 186 * Get pointer to the statistics information, if one is set during the
leothedragon 0:8f0bb79ddd48 187 * initialization. This may be useful for statistics collection purposes.
leothedragon 0:8f0bb79ddd48 188 *
leothedragon 0:8f0bb79ddd48 189 * Note: the caller may not modify the returned structure.
leothedragon 0:8f0bb79ddd48 190 *
leothedragon 0:8f0bb79ddd48 191 * \param book Address of book keeping structure
leothedragon 0:8f0bb79ddd48 192 *
leothedragon 0:8f0bb79ddd48 193 * \return NULL, no mem_stat_t was given on initialization
leothedragon 0:8f0bb79ddd48 194 * \return !=0, Pointer to mem_stat_t.
leothedragon 0:8f0bb79ddd48 195 */
leothedragon 0:8f0bb79ddd48 196 extern const mem_stat_t *ns_mem_get_mem_stat(ns_mem_book_t *book);
leothedragon 0:8f0bb79ddd48 197
leothedragon 0:8f0bb79ddd48 198 /**
leothedragon 0:8f0bb79ddd48 199 * \brief Set amount of free heap that must be available for temporary memory allocation to succeed.
leothedragon 0:8f0bb79ddd48 200 *
leothedragon 0:8f0bb79ddd48 201 * Temporary memory allocation will fail if system does not have defined amount of heap free.
leothedragon 0:8f0bb79ddd48 202 *
leothedragon 0:8f0bb79ddd48 203 * Note: the caller must set mem_stat_t structure in initialization.
leothedragon 0:8f0bb79ddd48 204 *
leothedragon 0:8f0bb79ddd48 205 * \param book Address of book keeping structure
leothedragon 0:8f0bb79ddd48 206 * \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.
leothedragon 0:8f0bb79ddd48 207 * \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.
leothedragon 0:8f0bb79ddd48 208 *
leothedragon 0:8f0bb79ddd48 209 * \return 0 on success, <0 otherwise
leothedragon 0:8f0bb79ddd48 210 */
leothedragon 0:8f0bb79ddd48 211 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);
leothedragon 0:8f0bb79ddd48 212
leothedragon 0:8f0bb79ddd48 213 #ifdef __cplusplus
leothedragon 0:8f0bb79ddd48 214 }
leothedragon 0:8f0bb79ddd48 215 #endif
leothedragon 0:8f0bb79ddd48 216 #endif /* NSDYNMEMLIB_H_ */
leothedragon 0:8f0bb79ddd48 217
leothedragon 0:8f0bb79ddd48 218