include/mbedtls/memory_buffer_alloc.h

0001 /**
0002  * \file memory_buffer_alloc.h
0003  *
0004  * \brief Buffer-based memory allocator
0005  */
0006 /*
0007  *  Copyright The Mbed TLS Contributors
0008  *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
0009  */
0010 #ifndef MBEDTLS_MEMORY_BUFFER_ALLOC_H
0011 #define MBEDTLS_MEMORY_BUFFER_ALLOC_H
0012
0013 #include "mbedtls/build_info.h"
0014
0015 #include <stddef.h>
0016
0017 /**
0018  * \name SECTION: Module settings
0019  *
0020  * The configuration options you can set for this module are in this section.
0021  * Either change them in mbedtls_config.h or define them on the compiler command line.
0022  * \{
0023  */
0024
0025 #if !defined(MBEDTLS_MEMORY_ALIGN_MULTIPLE)
0026 #define MBEDTLS_MEMORY_ALIGN_MULTIPLE       4 /**< Align on multiples of this value */
0027 #endif
0028
0029 /** \} name SECTION: Module settings */
0030
0031 #define MBEDTLS_MEMORY_VERIFY_NONE         0
0032 #define MBEDTLS_MEMORY_VERIFY_ALLOC        (1 << 0)
0033 #define MBEDTLS_MEMORY_VERIFY_FREE         (1 << 1)
0034 #define MBEDTLS_MEMORY_VERIFY_ALWAYS       (MBEDTLS_MEMORY_VERIFY_ALLOC | \
0035                                             MBEDTLS_MEMORY_VERIFY_FREE)
0036
0037 #ifdef __cplusplus
0038 extern "C" {
0039 #endif
0040
0041 /**
0042  * \brief   Initialize use of stack-based memory allocator.
0043  *          The stack-based allocator does memory management inside the
0044  *          presented buffer and does not call calloc() and free().
0045  *          It sets the global mbedtls_calloc() and mbedtls_free() pointers
0046  *          to its own functions.
0047  *          (Provided mbedtls_calloc() and mbedtls_free() are thread-safe if
0048  *           MBEDTLS_THREADING_C is defined)
0049  *
0050  * \note    This code is not optimized and provides a straight-forward
0051  *          implementation of a stack-based memory allocator.
0052  *
0053  * \param buf   buffer to use as heap
0054  * \param len   size of the buffer
0055  */
0056 void mbedtls_memory_buffer_alloc_init(unsigned char *buf, size_t len);
0057
0058 /**
0059  * \brief   Free the mutex for thread-safety and clear remaining memory
0060  */
0061 void mbedtls_memory_buffer_alloc_free(void);
0062
0063 /**
0064  * \brief   Determine when the allocator should automatically verify the state
0065  *          of the entire chain of headers / meta-data.
0066  *          (Default: MBEDTLS_MEMORY_VERIFY_NONE)
0067  *
0068  * \param verify    One of MBEDTLS_MEMORY_VERIFY_NONE, MBEDTLS_MEMORY_VERIFY_ALLOC,
0069  *                  MBEDTLS_MEMORY_VERIFY_FREE or MBEDTLS_MEMORY_VERIFY_ALWAYS
0070  */
0071 void mbedtls_memory_buffer_set_verify(int verify);
0072
0073 #if defined(MBEDTLS_MEMORY_DEBUG)
0074 /**
0075  * \brief   Print out the status of the allocated memory (primarily for use
0076  *          after a program should have de-allocated all memory)
0077  *          Prints out a list of 'still allocated' blocks and their stack
0078  *          trace if MBEDTLS_MEMORY_BACKTRACE is defined.
0079  */
0080 void mbedtls_memory_buffer_alloc_status(void);
0081
0082 /**
0083  * \brief   Get the number of alloc/free so far.
0084  *
0085  * \param alloc_count   Number of allocations.
0086  * \param free_count    Number of frees.
0087  */
0088 void mbedtls_memory_buffer_alloc_count_get(size_t *alloc_count, size_t *free_count);
0089
0090 /**
0091  * \brief   Get the peak heap usage so far
0092  *
0093  * \param max_used      Peak number of bytes in use or committed. This
0094  *                      includes bytes in allocated blocks too small to split
0095  *                      into smaller blocks but larger than the requested size.
0096  * \param max_blocks    Peak number of blocks in use, including free and used
0097  */
0098 void mbedtls_memory_buffer_alloc_max_get(size_t *max_used, size_t *max_blocks);
0099
0100 /**
0101  * \brief   Reset peak statistics
0102  */
0103 void mbedtls_memory_buffer_alloc_max_reset(void);
0104
0105 /**
0106  * \brief   Get the current heap usage
0107  *
0108  * \param cur_used      Current number of bytes in use or committed. This
0109  *                      includes bytes in allocated blocks too small to split
0110  *                      into smaller blocks but larger than the requested size.
0111  * \param cur_blocks    Current number of blocks in use, including free and used
0112  */
0113 void mbedtls_memory_buffer_alloc_cur_get(size_t *cur_used, size_t *cur_blocks);
0114 #endif /* MBEDTLS_MEMORY_DEBUG */
0115
0116 /**
0117  * \brief   Verifies that all headers in the memory buffer are correct
0118  *          and contain sane values. Helps debug buffer-overflow errors.
0119  *
0120  *          Prints out first failure if MBEDTLS_MEMORY_DEBUG is defined.
0121  *          Prints out full header information if MBEDTLS_MEMORY_DEBUG
0122  *          is defined. (Includes stack trace information for each block if
0123  *          MBEDTLS_MEMORY_BACKTRACE is defined as well).
0124  *
0125  * \return             0 if verified, 1 otherwise
0126  */
0127 int mbedtls_memory_buffer_alloc_verify(void);
0128
0129 #if defined(MBEDTLS_SELF_TEST)
0130 /**
0131  * \brief          Checkup routine
0132  *
0133  * \return         0 if successful, or 1 if a test failed
0134  */
0135 int mbedtls_memory_buffer_alloc_self_test(int verbose);
0136 #endif
0137
0138 #ifdef __cplusplus
0139 }
0140 #endif
0141
0142 #endif /* memory_buffer_alloc.h */