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.
Diff: simple-mbed-cloud-client/mbed-cloud-client/nanostack-libservice/mbed-client-libservice/nsdynmemLIB.h
- Revision:
- 0:8f0bb79ddd48
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/simple-mbed-cloud-client/mbed-cloud-client/nanostack-libservice/mbed-client-libservice/nsdynmemLIB.h Tue May 04 08:55:12 2021 +0000 @@ -0,0 +1,218 @@ +/* + * Copyright (c) 2014-2018 ARM Limited. All rights reserved. + * SPDX-License-Identifier: Apache-2.0 + * Licensed under the Apache License, Version 2.0 (the License); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an AS IS BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +/** + * \file nsdynmemLIB.h + * \brief Dynamical Memory API for library model + * nsdynmemlib provides access to one default heap, along with the ability to use extra user heaps. + * ns_dyn_mem_alloc/free always access the default heap initialised by ns_dyn_mem_init. + * ns_mem_alloc/free access a user heap initialised by ns_mem_init. User heaps are identified by a book-keeping pointer. + */ + +#ifndef NSDYNMEMLIB_H_ +#define NSDYNMEMLIB_H_ +#ifdef __cplusplus +extern "C" { +#endif + +#include "ns_types.h" + +// Added to maintain backward compatibility with older implementation of ns_dyn_mem APIs +#define NSDYNMEMLIB_API_VERSION 3 + +typedef size_t ns_mem_block_size_t; //external interface unsigned heap block size type +typedef size_t ns_mem_heap_size_t; //total heap size type. + +/*! + * \enum heap_fail_t + * \brief Dynamically heap system failure call back event types. + */ +typedef enum { + NS_DYN_MEM_NULL_FREE, /**< ns_dyn_mem_free(), NULL pointer free [obsolete - no longer faulted] */ + NS_DYN_MEM_DOUBLE_FREE, /**< ns_dyn_mem_free(), Possible double pointer free */ + NS_DYN_MEM_ALLOCATE_SIZE_NOT_VALID, /**< Allocate size is 0 or smaller or size is bigger than max heap size */ + NS_DYN_MEM_POINTER_NOT_VALID, /**< ns_dyn_mem_free(), try to free pointer which not at heap sector */ + NS_DYN_MEM_HEAP_SECTOR_CORRUPTED, /**< Heap system detect sector corruption */ + 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() */ +} heap_fail_t; + +/** + * /struct mem_stat_t + * /brief Struct for Memory stats Buffer structure + */ +typedef struct mem_stat_t { + /*Heap stats*/ + ns_mem_heap_size_t heap_sector_size; /**< Heap total Sector len. */ + ns_mem_heap_size_t heap_sector_alloc_cnt; /**< Reserved Heap sector cnt. */ + ns_mem_heap_size_t heap_sector_allocated_bytes; /**< Reserved Heap data in bytes. */ + ns_mem_heap_size_t heap_sector_allocated_bytes_max; /**< Reserved Heap data in bytes max value. */ + uint32_t heap_alloc_total_bytes; /**< Total Heap allocated bytes. */ + uint32_t heap_alloc_fail_cnt; /**< Counter for Heap allocation fail. */ +} mem_stat_t; + + +typedef struct ns_mem_book ns_mem_book_t; + +/** + * \brief Init and set Dynamical heap pointer and length. + * + * \param heap_ptr Pointer to dynamically heap buffer + * \param heap_size size of the heap buffer + * \return None + */ +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); + + +/** + * \brief Free allocated memory. + * + * \param heap_ptr Pointer to allocated memory + * + * \return 0, Free OK + * \return <0, Free Fail + */ +extern void ns_dyn_mem_free(void *heap_ptr); +/** + * \brief Allocate temporary data. + * + * Space allocate started from beginning of the heap sector + * + * \param alloc_size Allocated data size + * + * \return 0, Allocate Fail + * \return >0, Pointer to allocated data sector. + */ +extern void *ns_dyn_mem_temporary_alloc(ns_mem_block_size_t alloc_size); +/** + * \brief Allocate long period data. + * + * Space allocate started from end of the heap sector + * + * \param alloc_size Allocated data size + * + * \return 0, Allocate Fail + * \return >0, Pointer to allocated data sector. + */ +extern void *ns_dyn_mem_alloc(ns_mem_block_size_t alloc_size); + +/** + * \brief Get pointer to the current mem_stat_t set via ns_dyn_mem_init. + * + * Get pointer to the statistics information, if one is set during the + * initialization. This may be useful for statistics collection purposes. + * + * Note: the caller may not modify the returned structure. + * + * \return NULL, no mem_stat_t was given on initialization + * \return !=0, Pointer to mem_stat_t. + */ +extern const mem_stat_t *ns_dyn_mem_get_mem_stat(void); + +/** + * \brief Set amount of free heap that must be available for temporary memory allocation to succeed. + * + * Temporary memory allocation will fail if system does not have defined amount of heap free. + * + * Note: the caller must set mem_stat_t structure in initialization. + * + * \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. + * \param free_heap_amount Amount of free heap that must be free for temporary memory allocation. This value takes preference over percentage parameter value. + * + * \return 0 on success, <0 otherwise + */ +extern int ns_dyn_mem_set_temporary_alloc_free_heap_threshold(uint8_t free_heap_percentage, ns_mem_heap_size_t free_heap_amount); + +/** + * \brief Init and set Dynamical heap pointer and length. + * + * \param heap_ptr Pointer to dynamically heap buffer + * \param heap_size size of the heap buffer + * \return !=0, Pointer to ns_mem_book_t. + */ +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); + +/** + * \brief Free allocated memory. + * + * \param book Address of book keeping structure + * \param heap_ptr Pointer to allocated memory + * + * \return 0, Free OK + * \return <0, Free Fail + */ +extern void ns_mem_free(ns_mem_book_t *book, void *heap_ptr); +/** + * \brief Allocate temporary data. + * + * Space allocate started from beginning of the heap sector + * + * \param book Address of book keeping structure + * \param alloc_size Allocated data size + * + * \return 0, Allocate Fail + * \return >0, Pointer to allocated data sector. + */ +extern void *ns_mem_temporary_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size); +/** + * \brief Allocate long period data. + * + * Space allocate started from end of the heap sector + * + * \param book Address of book keeping structure + * \param alloc_size Allocated data size + * + * \return 0, Allocate Fail + * \return >0, Pointer to allocated data sector. + */ +extern void *ns_mem_alloc(ns_mem_book_t *book, ns_mem_block_size_t alloc_size); + +/** + * \brief Get pointer to the current mem_stat_t set via ns_mem_init. + * + * Get pointer to the statistics information, if one is set during the + * initialization. This may be useful for statistics collection purposes. + * + * Note: the caller may not modify the returned structure. + * + * \param book Address of book keeping structure + * + * \return NULL, no mem_stat_t was given on initialization + * \return !=0, Pointer to mem_stat_t. + */ +extern const mem_stat_t *ns_mem_get_mem_stat(ns_mem_book_t *book); + +/** + * \brief Set amount of free heap that must be available for temporary memory allocation to succeed. + * + * Temporary memory allocation will fail if system does not have defined amount of heap free. + * + * Note: the caller must set mem_stat_t structure in initialization. + * + * \param book Address of book keeping structure + * \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. + * \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. + * + * \return 0 on success, <0 otherwise + */ +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); + +#ifdef __cplusplus +} +#endif +#endif /* NSDYNMEMLIB_H_ */ + +