Doug Anson / mbedTLSLibrary

mbed TLS library

Dependents:   HTTPClient-SSL WS_SERVER

include/polarssl/memory_buffer_alloc.h@0:137634ff4186, 2015-06-11 (annotated)

Committer:
ansond
Date:
Thu Jun 11 03:27:03 2015 +0000
Revision:
0:137634ff4186
initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ansond 0:137634ff4186 1 /**
ansond 0:137634ff4186 2 * \file memory_buffer_alloc.h
ansond 0:137634ff4186 3 *
ansond 0:137634ff4186 4 * \brief Buffer-based memory allocator
ansond 0:137634ff4186 5 *
ansond 0:137634ff4186 6 * Copyright (C) 2006-2014, ARM Limited, All Rights Reserved
ansond 0:137634ff4186 7 *
ansond 0:137634ff4186 8 * This file is part of mbed TLS (https://tls.mbed.org)
ansond 0:137634ff4186 9 *
ansond 0:137634ff4186 10 * This program is free software; you can redistribute it and/or modify
ansond 0:137634ff4186 11 * it under the terms of the GNU General Public License as published by
ansond 0:137634ff4186 12 * the Free Software Foundation; either version 2 of the License, or
ansond 0:137634ff4186 13 * (at your option) any later version.
ansond 0:137634ff4186 14 *
ansond 0:137634ff4186 15 * This program is distributed in the hope that it will be useful,
ansond 0:137634ff4186 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
ansond 0:137634ff4186 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
ansond 0:137634ff4186 18 * GNU General Public License for more details.
ansond 0:137634ff4186 19 *
ansond 0:137634ff4186 20 * You should have received a copy of the GNU General Public License along
ansond 0:137634ff4186 21 * with this program; if not, write to the Free Software Foundation, Inc.,
ansond 0:137634ff4186 22 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
ansond 0:137634ff4186 23 */
ansond 0:137634ff4186 24 #ifndef POLARSSL_MEMORY_BUFFER_ALLOC_H
ansond 0:137634ff4186 25 #define POLARSSL_MEMORY_BUFFER_ALLOC_H
ansond 0:137634ff4186 26
ansond 0:137634ff4186 27 #if !defined(POLARSSL_CONFIG_FILE)
ansond 0:137634ff4186 28 #include "config.h"
ansond 0:137634ff4186 29 #else
ansond 0:137634ff4186 30 #include POLARSSL_CONFIG_FILE
ansond 0:137634ff4186 31 #endif
ansond 0:137634ff4186 32
ansond 0:137634ff4186 33 #include <stddef.h>
ansond 0:137634ff4186 34
ansond 0:137634ff4186 35 /**
ansond 0:137634ff4186 36 * \name SECTION: Module settings
ansond 0:137634ff4186 37 *
ansond 0:137634ff4186 38 * The configuration options you can set for this module are in this section.
ansond 0:137634ff4186 39 * Either change them in config.h or define them on the compiler command line.
ansond 0:137634ff4186 40 * \{
ansond 0:137634ff4186 41 */
ansond 0:137634ff4186 42
ansond 0:137634ff4186 43 #if !defined(POLARSSL_MEMORY_ALIGN_MULTIPLE)
ansond 0:137634ff4186 44 #define POLARSSL_MEMORY_ALIGN_MULTIPLE 4 /**< Align on multiples of this value */
ansond 0:137634ff4186 45 #endif
ansond 0:137634ff4186 46
ansond 0:137634ff4186 47 /* \} name SECTION: Module settings */
ansond 0:137634ff4186 48
ansond 0:137634ff4186 49 #define MEMORY_VERIFY_NONE 0
ansond 0:137634ff4186 50 #define MEMORY_VERIFY_ALLOC (1 << 0)
ansond 0:137634ff4186 51 #define MEMORY_VERIFY_FREE (1 << 1)
ansond 0:137634ff4186 52 #define MEMORY_VERIFY_ALWAYS (MEMORY_VERIFY_ALLOC | MEMORY_VERIFY_FREE)
ansond 0:137634ff4186 53
ansond 0:137634ff4186 54 #ifdef __cplusplus
ansond 0:137634ff4186 55 extern "C" {
ansond 0:137634ff4186 56 #endif
ansond 0:137634ff4186 57
ansond 0:137634ff4186 58 /**
ansond 0:137634ff4186 59 * \brief Initialize use of stack-based memory allocator.
ansond 0:137634ff4186 60 * The stack-based allocator does memory management inside the
ansond 0:137634ff4186 61 * presented buffer and does not call malloc() and free().
ansond 0:137634ff4186 62 * It sets the global polarssl_malloc() and polarssl_free() pointers
ansond 0:137634ff4186 63 * to its own functions.
ansond 0:137634ff4186 64 * (Provided polarssl_malloc() and polarssl_free() are thread-safe if
ansond 0:137634ff4186 65 * POLARSSL_THREADING_C is defined)
ansond 0:137634ff4186 66 *
ansond 0:137634ff4186 67 * \note This code is not optimized and provides a straight-forward
ansond 0:137634ff4186 68 * implementation of a stack-based memory allocator.
ansond 0:137634ff4186 69 *
ansond 0:137634ff4186 70 * \param buf buffer to use as heap
ansond 0:137634ff4186 71 * \param len size of the buffer
ansond 0:137634ff4186 72 *
ansond 0:137634ff4186 73 * \return 0 if successful
ansond 0:137634ff4186 74 */
ansond 0:137634ff4186 75 int memory_buffer_alloc_init( unsigned char *buf, size_t len );
ansond 0:137634ff4186 76
ansond 0:137634ff4186 77 /**
ansond 0:137634ff4186 78 * \brief Free the mutex for thread-safety and clear remaining memory
ansond 0:137634ff4186 79 */
ansond 0:137634ff4186 80 void memory_buffer_alloc_free( void );
ansond 0:137634ff4186 81
ansond 0:137634ff4186 82 /**
ansond 0:137634ff4186 83 * \brief Determine when the allocator should automatically verify the state
ansond 0:137634ff4186 84 * of the entire chain of headers / meta-data.
ansond 0:137634ff4186 85 * (Default: MEMORY_VERIFY_NONE)
ansond 0:137634ff4186 86 *
ansond 0:137634ff4186 87 * \param verify One of MEMORY_VERIFY_NONE, MEMORY_VERIFY_ALLOC,
ansond 0:137634ff4186 88 * MEMORY_VERIFY_FREE or MEMORY_VERIFY_ALWAYS
ansond 0:137634ff4186 89 */
ansond 0:137634ff4186 90 void memory_buffer_set_verify( int verify );
ansond 0:137634ff4186 91
ansond 0:137634ff4186 92 #if defined(POLARSSL_MEMORY_DEBUG)
ansond 0:137634ff4186 93 /**
ansond 0:137634ff4186 94 * \brief Print out the status of the allocated memory (primarily for use
ansond 0:137634ff4186 95 * after a program should have de-allocated all memory)
ansond 0:137634ff4186 96 * Prints out a list of 'still allocated' blocks and their stack
ansond 0:137634ff4186 97 * trace if POLARSSL_MEMORY_BACKTRACE is defined.
ansond 0:137634ff4186 98 */
ansond 0:137634ff4186 99 void memory_buffer_alloc_status( void );
ansond 0:137634ff4186 100
ansond 0:137634ff4186 101 /**
ansond 0:137634ff4186 102 * \brief Get the peak heap usage so far
ansond 0:137634ff4186 103 *
ansond 0:137634ff4186 104 * \param max_used Peak number of bytes reauested by the application
ansond 0:137634ff4186 105 * \param max_blocks Peak number of blocks reauested by the application
ansond 0:137634ff4186 106 */
ansond 0:137634ff4186 107 void memory_buffer_alloc_max_get( size_t *max_used, size_t *max_blocks );
ansond 0:137634ff4186 108
ansond 0:137634ff4186 109 /**
ansond 0:137634ff4186 110 * \brief Reset peak statistics
ansond 0:137634ff4186 111 */
ansond 0:137634ff4186 112 void memory_buffer_alloc_max_reset( void );
ansond 0:137634ff4186 113
ansond 0:137634ff4186 114 /**
ansond 0:137634ff4186 115 * \brief Get the current heap usage
ansond 0:137634ff4186 116 *
ansond 0:137634ff4186 117 * \param cur_used Number of bytes reauested by the application
ansond 0:137634ff4186 118 * \param cur_blocks Number of blocks reauested by the application
ansond 0:137634ff4186 119 */
ansond 0:137634ff4186 120 void memory_buffer_alloc_cur_get( size_t *cur_used, size_t *cur_blocks );
ansond 0:137634ff4186 121 #endif /* POLARSSL_MEMORY_DEBUG */
ansond 0:137634ff4186 122
ansond 0:137634ff4186 123 /**
ansond 0:137634ff4186 124 * \brief Verifies that all headers in the memory buffer are correct
ansond 0:137634ff4186 125 * and contain sane values. Helps debug buffer-overflow errors.
ansond 0:137634ff4186 126 *
ansond 0:137634ff4186 127 * Prints out first failure if POLARSSL_MEMORY_DEBUG is defined.
ansond 0:137634ff4186 128 * Prints out full header information if POLARSSL_MEMORY_DEBUG_HEADERS
ansond 0:137634ff4186 129 * is defined. (Includes stack trace information for each block if
ansond 0:137634ff4186 130 * POLARSSL_MEMORY_BACKTRACE is defined as well).
ansond 0:137634ff4186 131 *
ansond 0:137634ff4186 132 * \returns 0 if verified, 1 otherwise
ansond 0:137634ff4186 133 */
ansond 0:137634ff4186 134 int memory_buffer_alloc_verify( void );
ansond 0:137634ff4186 135
ansond 0:137634ff4186 136 #if defined(POLARSSL_SELF_TEST)
ansond 0:137634ff4186 137 /**
ansond 0:137634ff4186 138 * \brief Checkup routine
ansond 0:137634ff4186 139 *
ansond 0:137634ff4186 140 * \return 0 if successful, or 1 if a test failed
ansond 0:137634ff4186 141 */
ansond 0:137634ff4186 142 int memory_buffer_alloc_self_test( int verbose );
ansond 0:137634ff4186 143 #endif
ansond 0:137634ff4186 144
ansond 0:137634ff4186 145 #ifdef __cplusplus
ansond 0:137634ff4186 146 }
ansond 0:137634ff4186 147 #endif
ansond 0:137634ff4186 148
ansond 0:137634ff4186 149 #endif /* memory_buffer_alloc.h */
ansond 0:137634ff4186 150