wolfSSL is an embedded cryptographic library that includes a TLS/DTLS implementation. For resource-constrained devices or safety-critical applications, dynamic memory allocation via malloc and free system calls may be unavailable. To address these scenarios, wolfSSL offers the –enable-staticmemory feature. This feature provides a robust and straightforward allocation mechanism as an alternative. It utilizes a pre-allocated buffer, segmenting it into sections that applications can acquire by calling XMALLOC and release back to the memory pool using XFREE.

To activate this feature, compile wolfSSL using ./configure –enable-staticmemory or, if utilizing a user_settings.h file, define WOLFSSL_STATIC_MEMORY. Subsequently, execute make. Following compilation, the application must invoke wc_LoadStaticMemory to designate the buffer for partitioning and utilization, and then transmit the resulting “heap hint” to all XMALLOC and XFREE calls. By default, XMALLOC and XFREE calls will revert to the system’s malloc and free if no “heap hint” is provided. To circumvent all system malloc and free calls, the macro WOLFSSL_NO_MALLOC can be defined. For instance, this can be achieved via ./configure –enable-staticmemory CPPFLAGS=-DWOLFSSL_NO_MALLOC.

An additional option available, introduced in wolfSSL version 5.7.0 and subsequent releases, is the utilization of a globally defined “heap hint.” This global heap hint is established by invoking the setter function void* wolfSSL_SetGlobalHeapHint(void* heap). Consequently, any invocation of XMALLOC or XFREE that receives a NULL pointer as the “heap hint” will default to employing the globally configured “heap hint” pointer.

Setting up the memory sizes to use for each of the sections can be a difficult problem. To help some with a base configuration of the memory sizes there is a relatively new memory “bucket” optimizer tool located in the wolfssl-examples repository. It takes in the logging output of memory allocation calls from an application and provides a suggested static memory configuration based on the results. It’s possible in some cases to get even more optimized with the configuration but this example application gives a very good starting point.

The following is an example output when providing the memory logs of testwolfcrypt to the optimizer:

Building wolfSSL and collecting memory usage logs

$ ./configure --enable-staticmemory CPPFLAGS="-DWOLFSSL_DEBUG_MEMORY -DWOLFSSL_DEBUG_MEMORY_PRINT" -q && make > /dev/null && ./wolfcrypt/test/testwolfcrypt &> testwolfcrypt.log

Running the optimizer application on the resulting memory usage log ```

$ make gcc -o memory_bucket_optimizer memory_bucket_optimizer.c -lwolfssl

$./memory_bucket_optimizer testwolfcrypt.log Found 24 unique allocation sizes Peak heap usage: 60074 bytes (maximum concurrent memory usage) Allocation Sizes, Frequencies, and Concurrent Usage: Size Count Max Concurrent —- —– ————– 4208 1 1 3128 914 19 2112 85 1 1600 13 1 1120 13 1 1040 1 1 1024 4 2 800 37 1 257 65 2 256 9 1 235 7 1 227 5 1 223 5 1 207 5 1 191 5 1 136 5 1 128 8 1 104 5 1 72 5 1 64 6 1 48 5 1 32 2 1 28 1 1 0 0 0 Optimization Summary: Padding size per bucket: 32 bytes Maximum unique buckets allowed: 9 Total buckets created: 9 Note: Reached maximum bucket limit (9). Some allocations may use larger buckets. Note: Allocations with waste Additional documentation about the staticmemory feature can be found in the wolfSSL manual.

If you have questions about any of the above, please contact us at facts@wolfssl.com or call us at +1 425 245 8247. Download wolfSSL Now