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 * This file is provided under the Apache License 2.0, or the 11 * GNU General Public License v2.0 or later. 12 * 13 * ********** 14 * Apache License 2.0: 15 * 16 * Licensed under the Apache License, Version 2.0 (the "License"); you may 17 * not use this file except in compliance with the License. 18 * You may obtain a copy of the License at 19 * 20 * http://www.apache.org/licenses/LICENSE-2.0 21 * 22 * Unless required by applicable law or agreed to in writing, software 23 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 24 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 25 * See the License for the specific language governing permissions and 26 * limitations under the License. 27 * 28 * ********** 29 * 30 * ********** 31 * GNU General Public License v2.0 or later: 32 * 33 * This program is free software; you can redistribute it and/or modify 34 * it under the terms of the GNU General Public License as published by 35 * the Free Software Foundation; either version 2 of the License, or 36 * (at your option) any later version. 37 * 38 * This program is distributed in the hope that it will be useful, 39 * but WITHOUT ANY WARRANTY; without even the implied warranty of 40 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 41 * GNU General Public License for more details. 42 * 43 * You should have received a copy of the GNU General Public License along 44 * with this program; if not, write to the Free Software Foundation, Inc., 45 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 46 * 47 * ********** 48 */ 49 #ifndef MBEDTLS_MEMORY_BUFFER_ALLOC_H 50 #define MBEDTLS_MEMORY_BUFFER_ALLOC_H 51 52 #if !defined(MBEDTLS_CONFIG_FILE) 53 #include "config.h" 54 #else 55 #include MBEDTLS_CONFIG_FILE 56 #endif 57 58 #include <stddef.h> 59 60 /** 61 * \name SECTION: Module settings 62 * 63 * The configuration options you can set for this module are in this section. 64 * Either change them in config.h or define them on the compiler command line. 65 * \{ 66 */ 67 68 #if !defined(MBEDTLS_MEMORY_ALIGN_MULTIPLE) 69 #define MBEDTLS_MEMORY_ALIGN_MULTIPLE 4 /**< Align on multiples of this value */ 70 #endif 71 72 /* \} name SECTION: Module settings */ 73 74 #define MBEDTLS_MEMORY_VERIFY_NONE 0 75 #define MBEDTLS_MEMORY_VERIFY_ALLOC (1 << 0) 76 #define MBEDTLS_MEMORY_VERIFY_FREE (1 << 1) 77 #define MBEDTLS_MEMORY_VERIFY_ALWAYS (MBEDTLS_MEMORY_VERIFY_ALLOC | MBEDTLS_MEMORY_VERIFY_FREE) 78 79 #ifdef __cplusplus 80 extern "C" { 81 #endif 82 83 /** 84 * \brief Initialize use of stack-based memory allocator. 85 * The stack-based allocator does memory management inside the 86 * presented buffer and does not call calloc() and free(). 87 * It sets the global mbedtls_calloc() and mbedtls_free() pointers 88 * to its own functions. 89 * (Provided mbedtls_calloc() and mbedtls_free() are thread-safe if 90 * MBEDTLS_THREADING_C is defined) 91 * 92 * \note This code is not optimized and provides a straight-forward 93 * implementation of a stack-based memory allocator. 94 * 95 * \param buf buffer to use as heap 96 * \param len size of the buffer 97 */ 98 void mbedtls_memory_buffer_alloc_init( unsigned char *buf, size_t len ); 99 100 /** 101 * \brief Free the mutex for thread-safety and clear remaining memory 102 */ 103 void mbedtls_memory_buffer_alloc_free( void ); 104 105 /** 106 * \brief Determine when the allocator should automatically verify the state 107 * of the entire chain of headers / meta-data. 108 * (Default: MBEDTLS_MEMORY_VERIFY_NONE) 109 * 110 * \param verify One of MBEDTLS_MEMORY_VERIFY_NONE, MBEDTLS_MEMORY_VERIFY_ALLOC, 111 * MBEDTLS_MEMORY_VERIFY_FREE or MBEDTLS_MEMORY_VERIFY_ALWAYS 112 */ 113 void mbedtls_memory_buffer_set_verify( int verify ); 114 115 #if defined(MBEDTLS_MEMORY_DEBUG) 116 /** 117 * \brief Print out the status of the allocated memory (primarily for use 118 * after a program should have de-allocated all memory) 119 * Prints out a list of 'still allocated' blocks and their stack 120 * trace if MBEDTLS_MEMORY_BACKTRACE is defined. 121 */ 122 void mbedtls_memory_buffer_alloc_status( void ); 123 124 /** 125 * \brief Get the peak heap usage so far 126 * 127 * \param max_used Peak number of bytes in use or committed. This 128 * includes bytes in allocated blocks too small to split 129 * into smaller blocks but larger than the requested size. 130 * \param max_blocks Peak number of blocks in use, including free and used 131 */ 132 void mbedtls_memory_buffer_alloc_max_get( size_t *max_used, size_t *max_blocks ); 133 134 /** 135 * \brief Reset peak statistics 136 */ 137 void mbedtls_memory_buffer_alloc_max_reset( void ); 138 139 /** 140 * \brief Get the current heap usage 141 * 142 * \param cur_used Current number of bytes in use or committed. This 143 * includes bytes in allocated blocks too small to split 144 * into smaller blocks but larger than the requested size. 145 * \param cur_blocks Current number of blocks in use, including free and used 146 */ 147 void mbedtls_memory_buffer_alloc_cur_get( size_t *cur_used, size_t *cur_blocks ); 148 #endif /* MBEDTLS_MEMORY_DEBUG */ 149 150 /** 151 * \brief Verifies that all headers in the memory buffer are correct 152 * and contain sane values. Helps debug buffer-overflow errors. 153 * 154 * Prints out first failure if MBEDTLS_MEMORY_DEBUG is defined. 155 * Prints out full header information if MBEDTLS_MEMORY_DEBUG 156 * is defined. (Includes stack trace information for each block if 157 * MBEDTLS_MEMORY_BACKTRACE is defined as well). 158 * 159 * \return 0 if verified, 1 otherwise 160 */ 161 int mbedtls_memory_buffer_alloc_verify( void ); 162 163 #if defined(MBEDTLS_SELF_TEST) 164 /** 165 * \brief Checkup routine 166 * 167 * \return 0 if successful, or 1 if a test failed 168 */ 169 int mbedtls_memory_buffer_alloc_self_test( int verbose ); 170 #endif 171 172 #ifdef __cplusplus 173 } 174 #endif 175 176 #endif /* memory_buffer_alloc.h */ 177