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.

Operation

Standard-Like Function

Variant Function

Allocating a block

sl_malloc()

Freeing a block

sl_free()

sl_memory_free()

Allocating a block whose content is zero'ed

sl_calloc()

sl_memory_calloc()

Re-allocating a block

sl_realloc()

sl_memory_realloc()

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.

Function

Block type

sl_malloc()

Long-term by default

sl_memory_alloc()

Long-term or short-term

sl_memory_alloc_advanced()

Long-term or short-term

sl_calloc()

Long-term by default

sl_memory_calloc()

Long-term or short-term

sl_realloc()

Long-term by default

sl_memory_realloc()

Long-term by default

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:

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:

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

  • 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.

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_heap_info_t

sl_memory_reservation_t

sl_memory_pool_t

sl_memory_region_t

Enumerations#

enum
BLOCK_TYPE_LONG_TERM = 0
BLOCK_TYPE_SHORT_TERM = 1
}

Block type.

Functions#

sl_status_t

Initializes the memory manager.

sl_status_t
sl_memory_reserve_no_retention(size_t size, size_t align, void **block)

Reserves a memory block that will never need retention in EM2.

void *
sl_malloc(size_t size)

Allocates a memory block of at least requested size from the heap.

sl_status_t
sl_memory_alloc(size_t size, sl_memory_block_type_t type, void **block)

Dynamically allocates a block of memory.

sl_status_t
sl_memory_alloc_advanced(size_t size, size_t align, sl_memory_block_type_t type, void **block)

Dynamically allocates a block of memory.

void
sl_free(void *ptr)

Frees a previously allocated block back into the heap.

sl_status_t
sl_memory_free(void *block)

Frees a dynamically allocated block of memory.

void *
sl_calloc(size_t item_count, size_t size)

Dynamically allocates a block of memory cleared to 0.

sl_status_t
sl_memory_calloc(size_t item_count, size_t size, sl_memory_block_type_t type, void **block)

Dynamically allocates a block of memory cleared to 0.

void *
sl_realloc(void *ptr, size_t size)

Resizes a previously allocated memory block.

sl_status_t
sl_memory_realloc(void *ptr, size_t size, void **block)

Resizes a previously allocated memory block.

sl_status_t
sl_memory_reserve_block(size_t size, size_t align, sl_memory_reservation_t *handle, void **block)

Dynamically reserves a block of memory.

sl_status_t
sl_memory_release_block(sl_memory_reservation_t *handle)

Frees a dynamically reserved block of memory.

sl_status_t
sl_memory_reservation_handle_alloc(sl_memory_reservation_t **handle)

Dynamically allocates a block reservation handle.

sl_status_t
sl_memory_reservation_handle_free(sl_memory_reservation_t *handle)

Frees a dynamically allocated block reservation handle.

uint32_t

Gets the size of the memory reservation handle structure.

sl_status_t
sl_memory_create_pool(size_t block_size, uint32_t block_count, sl_memory_pool_t *pool_handle)

Creates a memory pool.

sl_status_t
sl_memory_delete_pool(sl_memory_pool_t *pool_handle)

Deletes a memory pool.

sl_status_t
sl_memory_pool_alloc(sl_memory_pool_t *pool_handle, void **block)

Allocates a block from a memory pool.

sl_status_t
sl_memory_pool_free(sl_memory_pool_t *pool_handle, void *block)

Frees a block from a memory pool.

sl_status_t
sl_memory_pool_handle_alloc(sl_memory_pool_t **pool_handle)

Dynamically allocates a memory pool handle.

sl_status_t
sl_memory_pool_handle_free(sl_memory_pool_t *pool_handle)

Frees a dynamically allocated memory pool handle.

uint32_t

Gets the size of the memory pool handle structure.

sl_status_t
sl_memory_get_heap_info(sl_memory_heap_info_t *heap_info)

Populates an sl_memory_heap_info_t{} structure with the current status of the heap.

size_t

Gets the total size of the heap.

size_t

Gets the current free heap size.

size_t

Gets the current used heap size.

size_t

Gets heap high watermark.

void

Reset heap high watermark to the current heap used.

Gets size and location of the stack.

Gets size and location of the heap.

Macros#

#define

Special value to indicate the default block alignment to the Memory Manager allocator.

#define

Pre-defined values for block alignment managed by the Memory Manager allocator.

#define

16 bytes alignment.

#define

32 bytes alignment.

#define

64 bytes alignment.

#define

128 bytes alignment.

#define

256 bytes alignment.

#define

512 bytes alignment.

Enumeration Documentation#

sl_memory_block_type_t#

sl_memory_block_type_t

Block type.

Enumerator
BLOCK_TYPE_LONG_TERM

Long-term block type.

BLOCK_TYPE_SHORT_TERM

Short-term block type.


Definition at line 532 of file platform/service/memory_manager/inc/sl_memory_manager.h

Function Documentation#

sl_memory_init#

sl_status_t sl_memory_init (void )

Initializes the memory manager.

Parameters
N/A

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Note

  • This function should only be called once.


Definition at line 579 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_reserve_no_retention#

sl_status_t sl_memory_reserve_no_retention (size_t size, size_t align, void ** block)

Reserves a memory block that will never need retention in EM2.

Parameters
[in]size

Size of the block, in bytes.

[in]align

Required alignment for the block, in bytes.

[out]block

Pointer to variable that will receive the start address of the allocated block. NULL in case of error condition.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Note

  • Required alignment of memory block (in bytes) MUST be a power of 2 and can range from 1 to 512 bytes. The define SL_MEMORY_BLOCK_ALIGN_DEFAULT can be specified to select the default alignment.


Definition at line 596 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_malloc#

void * sl_malloc (size_t size)

Allocates a memory block of at least requested size from the heap.

Parameters
[in]size

Size of the block, in bytes.

Simple version.

Returns

  • Pointer to allocated block if successful. Null pointer if allocation failed.

Note

  • Requesting a block of 0 byte will return a null pointer.

  • All allocated blocks using this function will be considered long-term allocations.


Definition at line 614 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_alloc#

sl_status_t sl_memory_alloc (size_t size, sl_memory_block_type_t type, void ** block)

Dynamically allocates a block of memory.

Parameters
[in]size

Size of the block, in bytes.

[in]type

Type of block (long-term or short-term). BLOCK_TYPE_LONG_TERM BLOCK_TYPE_SHORT_TERM

[out]block

Pointer to variable that will receive the start address of the allocated block. NULL in case of error condition.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 628 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_alloc_advanced#

sl_status_t sl_memory_alloc_advanced (size_t size, size_t align, sl_memory_block_type_t type, void ** block)

Dynamically allocates a block of memory.

Parameters
[in]size

Size of the block, in bytes.

[in]align

Required alignment for the block, in bytes.

[in]type

Type of block (long-term or short term). BLOCK_TYPE_LONG_TERM BLOCK_TYPE_SHORT_TERM

[out]block

Pointer to variable that will receive the start address of the allocated block. NULL in case of error condition.

Advanced version that allows to specify alignment.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Note

  • Required alignment of memory block (in bytes) MUST be a power of 2 and can range from 1 to 512 bytes. The define SL_MEMORY_BLOCK_ALIGN_DEFAULT can be specified to select the default alignment.


Definition at line 651 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_free#

void sl_free (void * ptr)

Frees a previously allocated block back into the heap.

Parameters
[in]ptr

Pointer to memory block to be freed.

Simple version.

Note

  • Passing a null pointer does nothing.


Definition at line 663 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_free#

sl_status_t sl_memory_free (void * block)

Frees a dynamically allocated block of memory.

Parameters
[in]block

Pointer to the block that must be freed.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 672 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_calloc#

void * sl_calloc (size_t item_count, size_t size)

Dynamically allocates a block of memory cleared to 0.

Parameters
[in]item_count

Number of elements to be allocated.

[in]size

Size of each elements, in bytes.

Simple version.

Returns

  • Pointer to allocated block if successful. Null pointer if allocation failed.

Note

  • All allocated blocks using this function will be considered long-term allocations.


Definition at line 686 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_calloc#

sl_status_t sl_memory_calloc (size_t item_count, size_t size, sl_memory_block_type_t type, void ** block)

Dynamically allocates a block of memory cleared to 0.

Parameters
[in]item_count

Number of elements to be allocated.

[in]size

Size of each elements, in bytes.

[in]type

Type of block (long-term or short-term). BLOCK_TYPE_LONG_TERM BLOCK_TYPE_SHORT_TERM

[out]block

Pointer to variable that will receive the start address of the allocated block. NULL in case of error condition.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 703 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_realloc#

void * sl_realloc (void * ptr, size_t size)

Resizes a previously allocated memory block.

Parameters
[in]ptr

Pointer to the allocation to resize. If NULL, behavior is same as sl_malloc(), sl_memory_alloc().

[in]size

New size of the block, in bytes. If 0, behavior is same as sl_free(), sl_memory_free().

Simple version.

Returns

  • Pointer to newly allocated block, if successful. Null pointer if re-allocation failed.

Note

  • All re-allocated blocks using this function will be considered long-term allocations.

  • 'ptr' NULL and 'size' of 0 bytes is an incorrect parameters combination. No reallocation will be done by the function as it is an error condition.

  • If the new 'size' is the same as the old, the function changes nothing and returns the same provided address 'ptr'.


Definition at line 729 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_realloc#

sl_status_t sl_memory_realloc (void * ptr, size_t size, void ** block)

Resizes a previously allocated memory block.

Parameters
[in]ptr

Pointer to the allocation to resize. If NULL, behavior is same as sl_malloc(), sl_memory_alloc().

[in]size

New size of the block, in bytes. If 0, behavior is same as sl_free(), sl_memory_free().

[out]block

Pointer to variable that will receive the start address of the new allocated memory. NULL in case of error condition.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Note

  • All re-allocated blocks using this function will be considered long-term allocations.

  • 'ptr' NULL and 'size' of 0 bytes is an incorrect parameters combination. No reallocation will be done by the function as it is an error condition.

  • If the new 'size' is the same as the old, the function changes nothing and returns the same provided address 'ptr'.


Definition at line 754 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_reserve_block#

sl_status_t sl_memory_reserve_block (size_t size, size_t align, sl_memory_reservation_t * handle, void ** block)

Dynamically reserves a block of memory.

Parameters
[in]size

Size of the block, in bytes.

[in]align

Required alignment for the block, in bytes.

[in]handle

Handle to the reserved block.

[out]block

Pointer to variable that will receive the start address of the allocated block. NULL in case of error condition.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Note

  • Required alignment of memory block (in bytes) MUST be a power of 2 and can range from 1 to 512 bytes. The define SL_MEMORY_BLOCK_ALIGN_DEFAULT can be specified to select the default alignment.


Definition at line 774 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_release_block#

sl_status_t sl_memory_release_block (sl_memory_reservation_t * handle)

Frees a dynamically reserved block of memory.

Parameters
[in]handle

Handle to the reserved block.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 786 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_reservation_handle_alloc#

sl_status_t sl_memory_reservation_handle_alloc (sl_memory_reservation_t ** handle)

Dynamically allocates a block reservation handle.

Parameters
[out]handle

Handle to the reserved block.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 795 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_reservation_handle_free#

sl_status_t sl_memory_reservation_handle_free (sl_memory_reservation_t * handle)

Frees a dynamically allocated block reservation handle.

Parameters
[in]handle

Handle to the reserved block.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 804 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_reservation_handle_get_size#

uint32_t sl_memory_reservation_handle_get_size (void )

Gets the size of the memory reservation handle structure.

Parameters
N/A

Returns

  • Memory reservation handle structure's size in bytes.


Definition at line 811 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_create_pool#

sl_status_t sl_memory_create_pool (size_t block_size, uint32_t block_count, sl_memory_pool_t * pool_handle)

Creates a memory pool.

Parameters
[in]block_size

Size of each block, in bytes.

[in]block_count

Number of blocks in the pool.

[in]pool_handle

Handle to the memory pool.

Note

  • This function assumes the 'pool_handle' is provided by the caller:

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 826 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_delete_pool#

sl_status_t sl_memory_delete_pool (sl_memory_pool_t * pool_handle)

Deletes a memory pool.

Parameters
[in]pool_handle

Handle to the memory pool.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.

Note


Definition at line 843 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_pool_alloc#

sl_status_t sl_memory_pool_alloc (sl_memory_pool_t * pool_handle, void ** block)

Allocates a block from a memory pool.

Parameters
[in]pool_handle

Handle to the memory pool.

[out]block

Pointer to a variable that will receive the address of the allocated block. NULL in case of error condition.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 855 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_pool_free#

sl_status_t sl_memory_pool_free (sl_memory_pool_t * pool_handle, void * block)

Frees a block from a memory pool.

Parameters
[in]pool_handle

Handle to the memory pool.

[in]block

Pointer to the block to free.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 866 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_pool_handle_alloc#

sl_status_t sl_memory_pool_handle_alloc (sl_memory_pool_t ** pool_handle)

Dynamically allocates a memory pool handle.

Parameters
[out]pool_handle

Handle to the memory pool.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 876 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_pool_handle_free#

sl_status_t sl_memory_pool_handle_free (sl_memory_pool_t * pool_handle)

Frees a dynamically allocated memory pool handle.

Parameters
[in]pool_handle

Handle to the memory pool.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 885 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_pool_handle_get_size#

uint32_t sl_memory_pool_handle_get_size (void )

Gets the size of the memory pool handle structure.

Parameters
N/A

Returns

  • Memory pool handle structure's size.


Definition at line 892 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_get_heap_info#

sl_status_t sl_memory_get_heap_info (sl_memory_heap_info_t * heap_info)

Populates an sl_memory_heap_info_t{} structure with the current status of the heap.

Parameters
[in]heap_info

Pointer to structure that will receive further heap information data.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 903 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_get_total_heap_size#

size_t sl_memory_get_total_heap_size (void )

Gets the total size of the heap.

Parameters
N/A

Returns

  • Heap's size in bytes.


Definition at line 910 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_get_free_heap_size#

size_t sl_memory_get_free_heap_size (void )

Gets the current free heap size.

Parameters
N/A

Returns

  • Free heap size in bytes.


Definition at line 917 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_get_used_heap_size#

size_t sl_memory_get_used_heap_size (void )

Gets the current used heap size.

Parameters
N/A

Returns

  • Used heap size in bytes.


Definition at line 924 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_get_heap_high_watermark#

size_t sl_memory_get_heap_high_watermark (void )

Gets heap high watermark.

Parameters
N/A

Returns

  • Highest heap usage in bytes recorded.


Definition at line 931 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_reset_heap_high_watermark#

void sl_memory_reset_heap_high_watermark (void )

Reset heap high watermark to the current heap used.

Parameters
N/A

Definition at line 936 of file platform/service/memory_manager/inc/sl_memory_manager.h

sl_memory_get_stack_region#

sl_memory_region_t sl_memory_get_stack_region (void )

Gets size and location of the stack.

Parameters
N/A

Returns

  • description of the region reserved for the C stack.


Definition at line 62 of file platform/service/memory_manager/inc/sl_memory_manager_region.h

sl_memory_get_heap_region#

sl_memory_region_t sl_memory_get_heap_region (void )

Gets size and location of the heap.

Parameters
N/A

Returns

  • description of the region reserved for the C heap.


Definition at line 69 of file platform/service/memory_manager/inc/sl_memory_manager_region.h

Macro Definition Documentation#

SL_MEMORY_BLOCK_ALIGN_DEFAULT#

#define SL_MEMORY_BLOCK_ALIGN_DEFAULT
Value:
0xFFFFFFFFU

Special value to indicate the default block alignment to the Memory Manager allocator.

8 bytes is the minimum alignment to account for largest CPU data type that can be used in some block allocation scenarios.


Definition at line 517 of file platform/service/memory_manager/inc/sl_memory_manager.h

SL_MEMORY_BLOCK_ALIGN_8_BYTES#

#define SL_MEMORY_BLOCK_ALIGN_8_BYTES
Value:
8U

Pre-defined values for block alignment managed by the Memory Manager allocator.

8 bytes alignment.


Definition at line 520 of file platform/service/memory_manager/inc/sl_memory_manager.h

SL_MEMORY_BLOCK_ALIGN_16_BYTES#

#define SL_MEMORY_BLOCK_ALIGN_16_BYTES
Value:
16U

16 bytes alignment.


Definition at line 521 of file platform/service/memory_manager/inc/sl_memory_manager.h

SL_MEMORY_BLOCK_ALIGN_32_BYTES#

#define SL_MEMORY_BLOCK_ALIGN_32_BYTES
Value:
32U

32 bytes alignment.


Definition at line 522 of file platform/service/memory_manager/inc/sl_memory_manager.h

SL_MEMORY_BLOCK_ALIGN_64_BYTES#

#define SL_MEMORY_BLOCK_ALIGN_64_BYTES
Value:
64U

64 bytes alignment.


Definition at line 523 of file platform/service/memory_manager/inc/sl_memory_manager.h

SL_MEMORY_BLOCK_ALIGN_128_BYTES#

#define SL_MEMORY_BLOCK_ALIGN_128_BYTES
Value:
128U

128 bytes alignment.


Definition at line 524 of file platform/service/memory_manager/inc/sl_memory_manager.h

SL_MEMORY_BLOCK_ALIGN_256_BYTES#

#define SL_MEMORY_BLOCK_ALIGN_256_BYTES
Value:
256U

256 bytes alignment.


Definition at line 525 of file platform/service/memory_manager/inc/sl_memory_manager.h

SL_MEMORY_BLOCK_ALIGN_512_BYTES#

#define SL_MEMORY_BLOCK_ALIGN_512_BYTES
Value:
512U

512 bytes alignment.


Definition at line 526 of file platform/service/memory_manager/inc/sl_memory_manager.h