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