Memory Manager#

Overview#

The Memory Manager is a platform-level software module that provides different ways to perform runtime allocations, either one shot or dynamic. The Memory Manager complements the toolchain linker by managing the RAM memory not allocated/partitioned by the linker. It offers different constructs that will help the different Silicon Labs SDK software modules and your application to build, as much as possible, an efficient and optimized RAM layout. The main Memory Manager constructs will be:

• A dynamic allocation API

• A memory pool API

• A dynamic reservation API

The Memory Manager can be used in an RTOS context as it is thread-safe by protecting adequately its internal shared resources.

Initialization#

The initialization part includes the following configuration files:

• sl_memory_manager_region_config.h

• sl_memory_manager_config.h

These header files offer a few configurations for the Memory Manager. They use the CMSIS Configuration Wizard Annotations that can be rendered by Simplicity Studio to set graphically the configuration settings value.

The API function sl_memory_init() is used to initialize the Memory Manager module. This function must be called early during your initialization sequence. If the SL System component (System Initialization and Action Processing) is used by your application, the sl_memory_init() call will be added automatically to your initialization sequence.

sl_memory_manager_region_config.h allows to configure the stack size for the application. The default value of 4096 bytes for SL_STACK_SIZE will be used by the linker to allocate a stack zone in the RAM. In a baremetal application, the stack size is bound to the value set by SL_STACK_SIZE. So you should carefully size the stack in that case. In an RTOS application, the stack size SL_STACK_SIZE will serve mainly for the code running in the main() context until the kernel is launched. Once the kernel is started, the different tasks' stacks, created upon tasks' creation, will allow to save the different contexts (that is task, function, ISR contexts). The main stack will be less active while the application's tasks are running.

Note

• It is not possible to specify a minimum heap size via a configuration value in sl_memory_manager_region_config.h. The GCC and IAR linker files define a heap section in RAM that will be the last zone of the RAM partitioned by the toolchain linker. The size of this heap zone will be the remaining space of the RAM. If you need to perform some checks on the heap size, you should do it at runtime using the Memory Manager statistics API. You cannot do it during the toolchain preprocessor time.

Functionalities#

The Memory Manager offers different functionalities such as:

• Dynamically allocating and freeing blocks.

• Creating and deleting memory pools. Allocating and freeing fixed-size blocks from a given pool.

• Reserving and releasing blocks.

• Getting statistics about the heap usage and the stack.

• Retargeting the standard C library memory functions malloc()/free()/ calloc()/realloc() to the Memory Manager ones.

• Overloading the C++ standard new/delete operators to the Memory Manager malloc()/free()

Dynamic Allocation#

The dynamic allocation API allows to dynamically allocate and free memory blocks of various sizes. The API supports the classic signatures of memory functions malloc()/free()/calloc()/realloc() while also offering variants of the same functions.

The variants functions sl_memory_xxxx() differs from the standard-like functions with the following:

• They return an error code of type sl_status_t. You may want to process any returned error code different from SL_STATUS_OK.

• They allow to specify a block alignment requirement in bytes. The alignment can be any power-of-two values between 1 and 512 bytes inclusively. The default block alignment the Memory Manager will use is 8 bytes to maximize CPU accesses to allocated memory blocks.

• They allow to specify a block type as long-term or short-term (further explained below). The Memory Manager allows to allocate a block from different ends of the heap to limit the fragmentation.

Allocating a block can be done by specifying your requested size with the simple sl_malloc(). If you have a special alignment requirement, the function sl_memory_alloc_advanced() is the one to use. The Memory Manager will use a first fit algorithm to find the block fitting the requested size. If the found block is too large, the allocator tries to split it to create a new free block from the unwanted portion of the found block. The block internal split operation helps to limit the internal fragmentation.

The dynamic allocation API allows to specify the block type as long-term (BLOCK_TYPE_LONG_TERM) or short-term (BLOCK_TYPE_SHORT_TERM) with the functions sl_memory_alloc() or sl_memory_alloc_advanced(). The long-term (LT) allocations are allocated from the heap start, while short-term (ST) ones are allocated from the heap end. LT/ST allocations relate to the expected lifetime of the block allocation. LT blocks are used for the full duration of the application or for something that is expected to last a long time. For instance, a control data structure enabling the proper functioning of a stack's layer, a driver, a part of the application layer. ST blocks are used for something that is expected to be freed quite quickly. For example, a received buffer that needs to be processed and once processed will be freed. Grouping your allocations as LT blocks and/or ST blocks can help to limit the heap fragmentation. Certain functions does not allow to indicate the block type. In that case, a default type is selected by the allocator.

Freeing a block is done by calling sl_free() or sl_memory_free(). sl_memory_free() returns an error code of type sl_status_t that you may want to test. Passing a NULL pointer to sl_free() or sl_memory_free() results in a neutral situation where the free() function will do nothing. If the same block is freed twice, the function sl_memory_free() will return an error. During the free operation, the function will try to merge adjacent blocks to the block that is being freed in order to limit the internal fragmentation. The adjacent blocks must, of course, not be in use to be merged.

If you want to get a block from the heap whose content has been initialized to zero to avoid any garbage values, the function sl_calloc() or sl_memory_calloc() can be called.

If you need to reallocate a block, the function sl_realloc() or sl_memory_realloc() should be called. Both versions allow to:

• Extend the block with the requested size greater than the original size.

• Reduce the block with the requested size smaller than the original size.

• Extend a different block with the requested size greater than the original size.

The block can be moved elsewhere in the heap if it is impossible to extend it in its current memory space. A reduced block will always stay in the original block space as the allocator does not need to provide a different block. The content of the reallocated memory block is preserved up to the lesser of the new and old sizes, even if the block is moved to a new location. If the new size is larger, the value of the newly allocated portion is indeterminate. Some combinations of input parameters when calling sl_realloc() or sl_memory_realloc() will lead to the same behavior as sl_malloc(), sl_memory_alloc() or sl_free(), sl_memory_free() (cf. the sl_realloc() or sl_memory_realloc() function description for more details about those combinations).

The following code snippet shows a basic block allocation and deallocation using the standard-like functions:

uint8_t *ptr8;

ptr8 = (uint8_t *)sl_malloc(200);
memset(ptr8, 0xAA, 100);
sl_free(ptr8);

This other code snippet shows the same basic block allocation and deallocation using the variant functions:

uint8_t *ptr8;
sl_status_t status;

status = sl_memory_alloc(100, BLOCK_TYPE_LONG_TERM, (void **)&ptr8);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

memset(ptr8, 0xBB, 100);

status = sl_memory_free(ptr8);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

Memory Pool#

The memory pool API allows to:

• Create a pool composed of N number of fixed-size blocks: sl_memory_create_pool().

• Delete a pool: sl_memory_delete_pool().

• Get a block from the pool: sl_memory_pool_alloc().

• Free a pool's block: sl_memory_pool_free().

Memory pools are convenient if you want to ensure a sort of guaranteed quotas for some memory allocations situations. It is also more robust to unexpected allocations errors as opposed to the dynamic allocation API in which a block allocation can fail randomly if there is no free block to satisfy the requested size.

The memory pool API uses a pool handle. This handle is initialized when the pool is created with sl_memory_create_pool(). Then this handle is passed as an input parameter of the other functions. The handle can be allocated statically or dynamically. A static pool handle means the handle of type sl_memory_pool_t{} is a global variable for example. A dynamic pool handle means the handle is obtained from the heap itself by calling the function sl_memory_pool_handle_alloc().The dynamic pool handle will be freed with a call to sl_memory_pool_handle_free().

The following code snippet shows a typical memory pool API sequence using a static pool handle:

uint8_t *ptr8;
sl_status_t status;
sl_memory_pool_t pool1_handle = { 0 };

// Create a pool of 15 blocks whose size is 100 bytes for each block.
status = sl_memory_create_pool(100, 15, &pool1_handle);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

status = sl_memory_pool_alloc(&pool1_handle, (void **)&ptr8);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

memset(ptr8, 0xCC, 100);

status = sl_memory_pool_free(&pool1_handle, ptr8);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

status = sl_memory_delete_pool(&pool1_handle);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

This other code snippet presents the previous typical memory pool API sequence using a dynamic pool handle:

sl_status_t status;
sl_memory_pool_t *pool1_handle = NULL;

status = sl_memory_pool_handle_alloc(&pool1_handle);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

// Create a pool of 15 blocks of 100 bytes in size.
status = sl_memory_create_pool(100, 15, &pool1_handle);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

// Get blocks from the pool, use them and free them once done.
...

status = sl_memory_delete_pool(&pool1_handle);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

status = sl_memory_pool_handle_free(pool1_handle);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

Dynamic Reservation#

The dynamic reservation is a special construct allowing to reserve a block of a given size with sl_memory_reserve_block() and to release it with sl_memory_release_block(). The reserved block can then be used to any application purposes. The reserved block will be taken from the short-term section at the end of the heap. Please note that the dynamic reservation API is not meant to be used in the same way as the dynamic allocation API.

The dynamic reservation API uses a reservation handle. This handle is initialized when the block is reserved with sl_memory_reserve_block(). Then this handle is passed as an input parameter to the other functions. The handle can be allocated statically or dynamically. A static reservation handle means the handle of type sl_memory_reservation_t{} is a global variable for example. A dynamic reservation handle means the handle is obtained from the heap itself by calling the function sl_memory_reservation_handle_alloc(). The dynamic reservaiton handle will be freed with a call to sl_memory_reservation_handle_free().

The following code snippet shows a typical dynamic reservation API sequence using a static reservation handle:

uint8_t *ptr8;
sl_status_t status;
sl_memory_reservation_t reservation_handle1 = { 0 };

status = sl_memory_reserve_block(1024,
                                 SL_MEMORY_BLOCK_ALIGN_8_BYTES,
                                 reservation_handle1,
                                 (void **)&ptr8);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

memset(ptr8, 0xDD, 1024);

status = sl_memory_release_block(&reservation_handle1);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

This other code snippet demonstrates the previous typical dynamic reservation API sequence using a dynamic reservation handle:

uint8_t *ptr8;
sl_status_t status;
sl_memory_reservation_t *reservation_handle1;

status = sl_memory_reservation_handle_alloc(&reservation_handle1);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

status = sl_memory_reserve_block(1024,
                                 SL_MEMORY_BLOCK_ALIGN_8_BYTES,
                                 reservation_handle1,
                                 (void **)&ptr8);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

memset(ptr8, 0xEE, 1024);

status = sl_memory_release_block(&reservation_handle1);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

status = sl_memory_reservation_handle_free(reservation_handle1);
if (status != SL_STATUS_OK) {
  // Process the error condition.
}

Statistics#

As your code is allocating and freeing blocks, you may want to know at a certain instant what the current state of the heap is. Some heap statistics queries at runtime can help to understand the current usage of the heap. By using the following statistics functions, you may be able to perform some asynchronous runtime heap checks:

• Total heap size: sl_memory_get_total_heap_size().

• Current free heap size: sl_memory_get_free_heap_size().

• Current used heap size: sl_memory_get_used_heap_size().

• Highest accumulated heap size usage: sl_memory_get_heap_high_watermark().

  • You can reset the high heap usage watermark with sl_memory_reset_heap_high_watermark().

Besides a few functions each dedicated to a specific statistic, the function sl_memory_get_heap_info() allows to get a general heap information structure of type sl_memory_heap_info_t{} with several heap statistics. Some of them overlap the statistics returned by the dedicated functions while the others complements statistics returned by the dedicated functions. Refer to the description of sl_memory_heap_info_t{} for more information of each field.

If you want to know the start address and the total size of the program's stack and/or heap, simply call respectively the function sl_memory_get_stack_region() and/or sl_memory_get_heap_region().

C/C++ Toolchains Standard Memory Functions Retarget/Overload#

A program can perform dynamic memory allocations and deallocations using the standard memory functions whose implementation is provided by the C or C++ toolchain libraries.

• C toolchain for the classic malloc()/free()/calloc()/realloc()

• C++ toolchain for the new/delete operators

The Memory Manager supports the C standard memory functions retarget and the C++ new/delete overload.

When the memory_manager component is installed, the C standard memory functions are automatically retargeted to the Memory Manager ones:

• GCC: coupled to the linker option "--wrap", the functions retargeted are

  • standard _malloc_r() -> sl_malloc()

  • standard _free_r() -> sl_free()

  • standard _calloc_r() -> sl_calloc()

  • standard _realloc_r() -> sl_realloc()

• IAR: it has three separate heap memory handlers (the basic, the advanced, and the no-free heap handlers). IAR generally auto-selects one of the handlers.

  • Basic heap

    • standard __basic_malloc() -> sl_malloc()

    • standard __basic_free() -> sl_free()

    • standard __basic_calloc() -> sl_calloc()

    • standard __basic_realloc() -> sl_realloc()

  • Advanced heap

    • standard __iar_dl_malloc() -> sl_malloc()

    • standard __iar_dl_free() -> sl_free()

    • standard __iar_dl_calloc() -> sl_calloc()

    • standard __iar_dl_realloc() -> sl_realloc()

  • No Free heap

    • standard __no_free_malloc() -> sl_malloc()

    • standard __no_free_calloc() -> sl_calloc()

If you need the C++ new/delete global overload calling sl_memory_alloc() and sl_memory_free(), please install the additional component memory_manager_cpp. This global overload of new/delete operators will also apply to any C++ standard containers (for example vector, string, list).

Note

• The Silicon Labs SDK generates a GCC or IAR linker script with Simplicity Studio. A typical toolchain linker script will define a section called "heap" or "HEAP". Usually, the C memory standard functions will assume a linker-defined "heap" section exists. If the memory_manager component is present, the toolchain linker script will define a new heap section named "memory_manager_heap" or "MEMORY_MANAGER_HEAP". Since the Memory Manager retargets the standard function malloc()/free()/calloc()/realloc() to the Memory Manager ones, there should not be any issues in your program. If an unlikely situation occurs where the toolchain standard memory functions retarget does not work, your application might end up calling a standard malloc() implementation from the toolchain instead of the Memory Manager one. In that case, a runtime error can occur and it is expected. You should then review the project settings to detect why the Memory Manager retarget did not work properly.

Hints#

Memory Allocations from ISR#

In general, ISR must be kept short. Allocating and freeing blocks from an ISR is possible but you should be careful. Nothing really prevents you from calling the dynamic allocation API functions such as sl_malloc() and sl_free(). But keep in mind a few things with the dynamic allocation API:

• The dynamic allocation API functions protect their internal resources such as global lists managing the heap metadata by using critical sections. So when in your ISR, you will disable interrupts for a certain period of time, preventing other interrupts to be processed in time if your application has hard real-time constraints. This increases the overall interrupt latency of your system if this ISR executes very often to perform a dynamic memory operation

• They can introduce non-deterministic behavior which is undesirable if your application requires crucial precise timing

• A function such as sl_malloc() can fail if there is no block to satisfy your requested size allocation. Implementing the proper error handling in the ISR may increase the time spent in the ISR.

In the end, it really depends of your ISR processing context doing memory allocations/deallocations. If you really need to perform dynamic allocation from ISR, it may be better at least to use a memory pool. Getting and releasing a block from a pool is an operation more deterministic. And if you have properly sized your pool with a number of available blocks, you are less likely to encounter an allocation error.

Modules#

sl_memory_region_t

sl_memory_heap_info_t

sl_memory_reservation_t

sl_memory_pool_t

0xFFFFFFFFU

8U

16U

32U

64U

128U

256U

512U