memory_buffer_alloc.h (4722B)
1 /** 2 * \file memory_buffer_alloc.h 3 * 4 * \brief Buffer-based memory allocator 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 8 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 9 */ 10 #ifndef MBEDTLS_MEMORY_BUFFER_ALLOC_H 11 #define MBEDTLS_MEMORY_BUFFER_ALLOC_H 12 13 #include "mbedtls/build_info.h" 14 15 #include <stddef.h> 16 17 /** 18 * \name SECTION: Module settings 19 * 20 * The configuration options you can set for this module are in this section. 21 * Either change them in mbedtls_config.h or define them on the compiler command line. 22 * \{ 23 */ 24 25 #if !defined(MBEDTLS_MEMORY_ALIGN_MULTIPLE) 26 #define MBEDTLS_MEMORY_ALIGN_MULTIPLE 4 /**< Align on multiples of this value */ 27 #endif 28 29 /** \} name SECTION: Module settings */ 30 31 #define MBEDTLS_MEMORY_VERIFY_NONE 0 32 #define MBEDTLS_MEMORY_VERIFY_ALLOC (1 << 0) 33 #define MBEDTLS_MEMORY_VERIFY_FREE (1 << 1) 34 #define MBEDTLS_MEMORY_VERIFY_ALWAYS (MBEDTLS_MEMORY_VERIFY_ALLOC | \ 35 MBEDTLS_MEMORY_VERIFY_FREE) 36 37 #ifdef __cplusplus 38 extern "C" { 39 #endif 40 41 /** 42 * \brief Initialize use of stack-based memory allocator. 43 * The stack-based allocator does memory management inside the 44 * presented buffer and does not call calloc() and free(). 45 * It sets the global mbedtls_calloc() and mbedtls_free() pointers 46 * to its own functions. 47 * (Provided mbedtls_calloc() and mbedtls_free() are thread-safe if 48 * MBEDTLS_THREADING_C is defined) 49 * 50 * \note This code is not optimized and provides a straight-forward 51 * implementation of a stack-based memory allocator. 52 * 53 * \param buf buffer to use as heap 54 * \param len size of the buffer 55 */ 56 void mbedtls_memory_buffer_alloc_init(unsigned char *buf, size_t len); 57 58 /** 59 * \brief Free the mutex for thread-safety and clear remaining memory 60 */ 61 void mbedtls_memory_buffer_alloc_free(void); 62 63 /** 64 * \brief Determine when the allocator should automatically verify the state 65 * of the entire chain of headers / meta-data. 66 * (Default: MBEDTLS_MEMORY_VERIFY_NONE) 67 * 68 * \param verify One of MBEDTLS_MEMORY_VERIFY_NONE, MBEDTLS_MEMORY_VERIFY_ALLOC, 69 * MBEDTLS_MEMORY_VERIFY_FREE or MBEDTLS_MEMORY_VERIFY_ALWAYS 70 */ 71 void mbedtls_memory_buffer_set_verify(int verify); 72 73 #if defined(MBEDTLS_MEMORY_DEBUG) 74 /** 75 * \brief Print out the status of the allocated memory (primarily for use 76 * after a program should have de-allocated all memory) 77 * Prints out a list of 'still allocated' blocks and their stack 78 * trace if MBEDTLS_MEMORY_BACKTRACE is defined. 79 */ 80 void mbedtls_memory_buffer_alloc_status(void); 81 82 /** 83 * \brief Get the number of alloc/free so far. 84 * 85 * \param alloc_count Number of allocations. 86 * \param free_count Number of frees. 87 */ 88 void mbedtls_memory_buffer_alloc_count_get(size_t *alloc_count, size_t *free_count); 89 90 /** 91 * \brief Get the peak heap usage so far 92 * 93 * \param max_used Peak number of bytes in use or committed. This 94 * includes bytes in allocated blocks too small to split 95 * into smaller blocks but larger than the requested size. 96 * \param max_blocks Peak number of blocks in use, including free and used 97 */ 98 void mbedtls_memory_buffer_alloc_max_get(size_t *max_used, size_t *max_blocks); 99 100 /** 101 * \brief Reset peak statistics 102 */ 103 void mbedtls_memory_buffer_alloc_max_reset(void); 104 105 /** 106 * \brief Get the current heap usage 107 * 108 * \param cur_used Current number of bytes in use or committed. This 109 * includes bytes in allocated blocks too small to split 110 * into smaller blocks but larger than the requested size. 111 * \param cur_blocks Current number of blocks in use, including free and used 112 */ 113 void mbedtls_memory_buffer_alloc_cur_get(size_t *cur_used, size_t *cur_blocks); 114 #endif /* MBEDTLS_MEMORY_DEBUG */ 115 116 /** 117 * \brief Verifies that all headers in the memory buffer are correct 118 * and contain sane values. Helps debug buffer-overflow errors. 119 * 120 * Prints out first failure if MBEDTLS_MEMORY_DEBUG is defined. 121 * Prints out full header information if MBEDTLS_MEMORY_DEBUG 122 * is defined. (Includes stack trace information for each block if 123 * MBEDTLS_MEMORY_BACKTRACE is defined as well). 124 * 125 * \return 0 if verified, 1 otherwise 126 */ 127 int mbedtls_memory_buffer_alloc_verify(void); 128 129 #if defined(MBEDTLS_SELF_TEST) 130 /** 131 * \brief Checkup routine 132 * 133 * \return 0 if successful, or 1 if a test failed 134 */ 135 int mbedtls_memory_buffer_alloc_self_test(int verbose); 136 #endif 137 138 #ifdef __cplusplus 139 } 140 #endif 141 142 #endif /* memory_buffer_alloc.h */