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