From 6a01122c476e89e78319d77d8b69aa6f802cd246 Mon Sep 17 00:00:00 2001 From: JacobBarthelmeh Date: Wed, 30 Jul 2025 14:50:44 -0600 Subject: [PATCH 1/3] add static memory doxygen comments for APIs --- doc/dox_comments/header_files/memory.h | 219 +++++++++++++++++++++++++ 1 file changed, 219 insertions(+) diff --git a/doc/dox_comments/header_files/memory.h b/doc/dox_comments/header_files/memory.h index fbc2172fc..4a869a9a3 100644 --- a/doc/dox_comments/header_files/memory.h +++ b/doc/dox_comments/header_files/memory.h @@ -409,3 +409,222 @@ int wolfSSL_is_static_memory(WOLFSSL* ssl, WOLFSSL_MEM_CONN_STATS* mem_stats); */ int wc_LoadStaticMemory(WOLFSSL_HEAP_HINT* hint, unsigned char* buf, unsigned int sz, int flag, int max); + +/*! + \ingroup Memory + + \brief This function is used to set aside static memory for wolfCrypt use with custom + bucket sizes and distributions. Memory can be used by passing the created heap hint + into functions. This extended version allows for custom bucket sizes and distributions + instead of using the default predefined sizes. + + \return If successful, 0 will be returned. + \return All unsuccessful return values will be less than 0. + + \param hint WOLFSSL_HEAP_HINT structure to use + \param buf memory to use for all operations. + \param sz size of memory buffer being passed in. + \param flag type of memory. + \param max max concurrent operations (handshakes, IO). + \param bucket_sizes array of bucket sizes to use + \param bucket_count number of bucket sizes in the array + + _Example_ + \code + WOLFSSL_HEAP_HINT hint; + int ret; + unsigned char memory[MAX]; + int memorySz = MAX; + int flag = WOLFMEM_GENERAL | WOLFMEM_TRACK_STATS; + word16 bucket_sizes[] = {64, 128, 256, 512, 1024}; + int bucket_count = 5; + ... + + // load in memory for use with custom bucket sizes + + ret = wc_LoadStaticMemory_ex(&hint, memory, memorySz, flag, 0, + bucket_sizes, bucket_count); + if (ret != SSL_SUCCESS) { + // handle error case + } + ... + + ret = wc_InitRng_ex(&rng, hint, 0); + + // check ret value + \endcode + + \sa wc_LoadStaticMemory + \sa wc_UnloadStaticMemory +*/ +int wc_LoadStaticMemory_ex(WOLFSSL_HEAP_HINT* hint, unsigned char* buf, unsigned int sz, + int flag, int max, word16* bucket_sizes, int bucket_count); + +/*! + \ingroup Memory + + \brief This function sets a global heap hint that will be used when NULL heap hint + is passed to memory allocation functions. This allows for setting a default heap + hint that will be used across the entire application. + + \return Returns the previous global heap hint that was set. + + \param hint WOLFSSL_HEAP_HINT structure to use as the global heap hint + + _Example_ + \code + WOLFSSL_HEAP_HINT hint; + WOLFSSL_HEAP_HINT* prev_hint; + int ret; + unsigned char memory[MAX]; + int memorySz = MAX; + ... + + // load in memory for use + ret = wc_LoadStaticMemory(&hint, memory, memorySz, WOLFMEM_GENERAL, 0); + if (ret != SSL_SUCCESS) { + // handle error case + } + + // set as global heap hint + prev_hint = wolfSSL_SetGlobalHeapHint(&hint); + if (prev_hint != NULL) { + // there was a previous global heap hint + } + \endcode + + \sa wolfSSL_GetGlobalHeapHint + \sa wc_LoadStaticMemory +*/ +WOLFSSL_HEAP_HINT* wolfSSL_SetGlobalHeapHint(WOLFSSL_HEAP_HINT* hint); + +/*! + \ingroup Memory + + \brief This function gets the current global heap hint that is used when NULL + heap hint is passed to memory allocation functions. + + \return Returns the current global heap hint, or NULL if none is set. + + \param none No parameters. + + _Example_ + \code + WOLFSSL_HEAP_HINT* current_hint; + ... + + current_hint = wolfSSL_GetGlobalHeapHint(); + if (current_hint != NULL) { + // there is a global heap hint set + // can use current_hint for operations + } + \endcode + + \sa wolfSSL_SetGlobalHeapHint + \sa wc_LoadStaticMemory +*/ +WOLFSSL_HEAP_HINT* wolfSSL_GetGlobalHeapHint(void); + +/*! + \ingroup Memory + + \brief This function sets a debug callback function for static memory allocation + tracking. Used with WOLFSSL_STATIC_MEMORY_DEBUG_CALLBACK build option. The callback + function will be called during memory allocation and deallocation operations to + provide debugging information. + + \return If successful, 0 will be returned. + \return All unsuccessful return values will be less than 0. + + \param cb debug callback function to set + + _Example_ + \code + static void debug_memory_cb(const char* func, const char* file, int line, + void* ptr, size_t size, int type) + { + printf("Memory %s: %s:%d ptr=%p size=%zu type=%d\n", + func, file, line, ptr, size, type); + } + ... + + // set debug callback + int ret = wolfSSL_SetDebugMemoryCb(debug_memory_cb); + if (ret != 0) { + // handle error case + } + \endcode + + \sa none +*/ +int wolfSSL_SetDebugMemoryCb(wolfSSL_DebugMemoryCb cb); + +/*! + \ingroup Memory + + \brief This function frees static memory heap and associated mutex. Should be + called when done using static memory allocation to properly clean up resources. + + \return If successful, 0 will be returned. + \return All unsuccessful return values will be less than 0. + + \param hint WOLFSSL_HEAP_HINT structure to unload + + _Example_ + \code + WOLFSSL_HEAP_HINT hint; + int ret; + unsigned char memory[MAX]; + int memorySz = MAX; + ... + + // load in memory for use + ret = wc_LoadStaticMemory(&hint, memory, memorySz, WOLFMEM_GENERAL, 0); + if (ret != SSL_SUCCESS) { + // handle error case + } + + // use memory for operations + ... + + // cleanup when done + ret = wc_UnloadStaticMemory(&hint); + if (ret != 0) { + // handle error case + } + \endcode + + \sa wc_LoadStaticMemory + \sa wc_LoadStaticMemory_ex +*/ +int wc_UnloadStaticMemory(WOLFSSL_HEAP_HINT* hint); + +/*! + \ingroup Memory + + \brief This function calculates the required buffer size for static memory allocation + with custom bucket sizes and distributions. This extended version allows for custom + bucket sizes instead of using the default predefined sizes. + + \return On successfully completing buffer size calculations a positive value is returned. + \return All negative values are considered to be error cases. + + \param bucket_sizes array of bucket sizes to use + \param bucket_count number of bucket sizes in the array + \param flag desired type of memory ie WOLFMEM_GENERAL or WOLFMEM_IO_POOL + + _Example_ + \code + word16 bucket_sizes[] = {64, 128, 256, 512, 1024}; + int bucket_count = 5; + int optimum; + optimum = wolfSSL_StaticBufferSz_ex(bucket_sizes, bucket_count, WOLFMEM_GENERAL); + if (optimum < 0) { //handle error case } + printf("The optimum buffer size with custom buckets is %d\n", optimum); + ... + \endcode + + \sa wolfSSL_StaticBufferSz + \sa wc_LoadStaticMemory_ex +*/ +int wolfSSL_StaticBufferSz_ex(word16* bucket_sizes, int bucket_count, int flag); From ee4e511a010a661a88ac351a11e663016439a583 Mon Sep 17 00:00:00 2001 From: JacobBarthelmeh Date: Wed, 30 Jul 2025 17:02:23 -0600 Subject: [PATCH 2/3] remove trailing white spaces --- doc/dox_comments/header_files/memory.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/dox_comments/header_files/memory.h b/doc/dox_comments/header_files/memory.h index 4a869a9a3..328004d93 100644 --- a/doc/dox_comments/header_files/memory.h +++ b/doc/dox_comments/header_files/memory.h @@ -442,7 +442,7 @@ int wc_LoadStaticMemory(WOLFSSL_HEAP_HINT* hint, unsigned char* buf, unsigned in // load in memory for use with custom bucket sizes - ret = wc_LoadStaticMemory_ex(&hint, memory, memorySz, flag, 0, + ret = wc_LoadStaticMemory_ex(&hint, memory, memorySz, flag, 0, bucket_sizes, bucket_count); if (ret != SSL_SUCCESS) { // handle error case @@ -543,7 +543,7 @@ WOLFSSL_HEAP_HINT* wolfSSL_GetGlobalHeapHint(void); static void debug_memory_cb(const char* func, const char* file, int line, void* ptr, size_t size, int type) { - printf("Memory %s: %s:%d ptr=%p size=%zu type=%d\n", + printf("Memory %s: %s:%d ptr=%p size=%zu type=%d\n", func, file, line, ptr, size, type); } ... From 367e3e4246295fcd4454db2d8452b6fc117883f2 Mon Sep 17 00:00:00 2001 From: JacobBarthelmeh Date: Fri, 1 Aug 2025 10:32:41 -0600 Subject: [PATCH 3/3] fix for wolfSSL_StaticBufferSz_ex function signature --- doc/dox_comments/header_files/memory.h | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/doc/dox_comments/header_files/memory.h b/doc/dox_comments/header_files/memory.h index 328004d93..84742f9dd 100644 --- a/doc/dox_comments/header_files/memory.h +++ b/doc/dox_comments/header_files/memory.h @@ -159,6 +159,8 @@ int wolfSSL_SetAllocators(wolfSSL_Malloc_cb, (--enable-staticmemory). It gives the optimum buffer size for memory “buckets”. This allows for a way to compute buffer size so that no extra unused memory is left at the end after it has been partitioned. + For the none _ex version of this function the default bucket and + distribution list set during compile time is used. The returned value, if positive, is the computed buffer size to use. \return Success On successfully completing buffer size calculations a @@ -174,6 +176,7 @@ int wolfSSL_SetAllocators(wolfSSL_Malloc_cb, byte buffer[1000]; word32 size = sizeof(buffer); int optimum; + optimum = wolfSSL_StaticBufferSz(buffer, size, WOLFMEM_GENERAL); if (optimum < 0) { //handle error case } printf(“The optimum buffer size to make use of all memory is %d\n”, @@ -615,10 +618,13 @@ int wc_UnloadStaticMemory(WOLFSSL_HEAP_HINT* hint); _Example_ \code - word16 bucket_sizes[] = {64, 128, 256, 512, 1024}; - int bucket_count = 5; + word32 sizeList[] = {64, 128, 256, 512, 1024}; + word32 distList[] = {1, 2, 1, 1, 1}; + int listSz = 5; int optimum; - optimum = wolfSSL_StaticBufferSz_ex(bucket_sizes, bucket_count, WOLFMEM_GENERAL); + + optimum = wolfSSL_StaticBufferSz_ex(listSz, sizeList, distList, NULL, 0, + WOLFMEM_GENERAL); if (optimum < 0) { //handle error case } printf("The optimum buffer size with custom buckets is %d\n", optimum); ... @@ -627,4 +633,7 @@ int wc_UnloadStaticMemory(WOLFSSL_HEAP_HINT* hint); \sa wolfSSL_StaticBufferSz \sa wc_LoadStaticMemory_ex */ -int wolfSSL_StaticBufferSz_ex(word16* bucket_sizes, int bucket_count, int flag); +int wolfSSL_StaticBufferSz_ex(unsigned int listSz, + const word32 *sizeList, const word32 *distList, + byte* buffer, word32 sz, int flag); +