Memory Manager API Reference#

The Memory Manager provides five main API categories for comprehensive memory management:

The following table lists all the functions in each API category for a quick reference by function names.

The following subsections cover the most frequently used APIs for typical applications. For complete API documentation of all functions not described in the subsections below, refer to the Memory Manager full API documentation.

Dynamic Allocation API#

The following subsections describe the standard-like functions and their variants that return specific error codes.

Allocation#

void *sl_malloc(size_t size);
void *sl_calloc(size_t item_count, size_t size);
void *sl_realloc(void *ptr, size_t size);
sl_status_t sl_memory_alloc(size_t size, uint8_t type, void **block);
sl_status_t sl_memory_calloc(size_t item_count, size_t size, uint8_t type, void **block);
sl_status_t sl_memory_realloc(void *ptr, size_t size, void **block);
sl_status_t sl_memory_alloc_advanced(size_t size, size_t align, uint8_t type, void **block);

sl_malloc(size) / sl_memory_alloc(size, type, block) / sl_memory_alloc_advanced(size, align, type, block)

• Purpose: Dynamically allocates a memory block from the general-purpose heap

• Parameters:

  • size - Size of the block to allocate, in bytes

  • type (variant functions only) - Type of block (BLOCK_TYPE_LONG_TERM or BLOCK_TYPE_SHORT_TERM)

  • align (sl_memory_alloc_advanced only) - Required alignment for the block, in bytes (must be power of 2, 1-512 bytes)

  • block (variant functions only) - Pointer to variable that will receive the start address of the allocated block

• Standard-like versus Variant: sl_malloc() is the standard-like function that returns a pointer or NULL. sl_memory_alloc() is the variant function that returns sl_status_t and allows specifying block type (long-term or short-term). sl_memory_alloc_advanced() adds alignment specification, useful for DMA buffers or hardware-specific alignment requirements.

sl_calloc(item_count, size) / sl_memory_calloc(item_count, size, type, block)

• Purpose: Dynamically allocates a memory block cleared to 0 from the general-purpose heap

• Parameters:

  • item_count - Number of elements to be allocated

  • size - Size of each element, in bytes

  • type (variant function only) - Type of block (BLOCK_TYPE_LONG_TERM or BLOCK_TYPE_SHORT_TERM)

  • block (variant function only) - Pointer to variable that will receive the start address of the allocated block

• Standard-like versus Variant: sl_calloc() is the standard-like function that returns a pointer or NULL. sl_memory_calloc() is the variant function that returns sl_status_t and allows specifying a block type.

sl_realloc(ptr, size) / sl_memory_realloc(ptr, size, block)

• Purpose: Resizes a previously allocated memory block in the general-purpose heap

• Parameters:

  • ptr - Pointer to the allocation to resize (can be NULL to allocate a new block)

  • size - New size of the block, in bytes

  • block (variant function only) - Pointer to variable that will receive the start address of the new allocated memory

• Standard-like versus Variant: sl_realloc() is the standard-like function that returns a pointer or NULL. sl_memory_realloc() is the variant function that returns sl_status_t and provides the new address through the block parameter.

• Important: The original block may be moved to a new location. With sl_realloc(), do not use the original pointer after a successful realloc. With sl_memory_realloc(), the new address is provided through the block parameter.

For complete functions return values documentation, refer to the Memory Manager full API documentation.

Block Type Constants

You can specify the block type when using the function sl_memory_alloc(), sl_memory_calloc(), or sl_memory_alloc_advanced().

typedef enum {
  BLOCK_TYPE_LONG_TERM = 0,   // Long-term block type
  BLOCK_TYPE_SHORT_TERM = 1   // Short-term block type
} sl_memory_block_type_t;

Example Usage:

For additional practical examples, refer to the code snippet in section Scenario 1: Basic Dynamic Allocation.

sl_malloc/sl_free:

void *ptr = sl_malloc(200);
if (ptr != NULL) {
  memset(ptr, 0xAA, 200);
  sl_free(ptr);
}
// Note: If the allocated block must be initialized to 0, use sl_calloc() instead.

sl_realloc:

void *ptr = sl_malloc(100);
if (ptr != NULL) {
  ptr = sl_realloc(ptr, 200);  // Extend to 200 bytes
  if (ptr != NULL) {
    sl_free(ptr);
  }
}

sl_memory_alloc/sl_memory_free:

void *block;
sl_status_t status = sl_memory_alloc(100, BLOCK_TYPE_LONG_TERM, &block);
if (status == SL_STATUS_OK) {
  memset(block, 0xBB, 100);
  status = sl_memory_free(block);
  if (status != SL_STATUS_OK) {
    // Handle free error
  }
}
// Note: If the allocated block must be initialized to 0, use sl_memory_calloc() instead.

sl_memory_realloc:

void *block;
sl_status_t status = sl_memory_alloc(100, BLOCK_TYPE_LONG_TERM, &block);
if (status == SL_STATUS_OK) {
  status = sl_memory_realloc(block, 200, &block);
  if (status == SL_STATUS_OK) {
    sl_memory_free(block);
  }
}

sl_memory_alloc_advanced:

void *block;
sl_status_t status = sl_memory_alloc_advanced(100, SL_MEMORY_BLOCK_ALIGN_32_BYTES,
                                              BLOCK_TYPE_LONG_TERM, &block);
if (status == SL_STATUS_OK) {
  // Block is aligned to 32-byte boundary
  sl_memory_free(block);
}

For another example with this allocation API variant, refer to the code snippet in Scenario 3: Advanced Allocation with Alignment.

Free#

void sl_free(void *ptr);
sl_status_t sl_memory_free(void *block);

sl_free(ptr) / sl_memory_free(block)

• Purpose: Frees a previously allocated memory block, returning it to the heap for reuse

• Parameters: ptr / block - Pointer to the block to free (can be NULL, in which case the function returns without action or SL_STATUS_OK, respectively)

• Standard-like versus Variant: sl_free() is the standard-like function that returns void, while sl_memory_free() is the variant function that returns sl_status_t for error checking. For complete return value documentation, refer to the Memory Manager full API documentation.

Example Usage:

Refer to the Example Usage in the Allocation section for an example of sl_free() and sl_memory_free().

Memory Pool API#

sl_status_t sl_memory_create_pool(size_t block_size, uint32_t block_count, sl_memory_pool_t *pool_handle);
sl_status_t sl_memory_pool_alloc(sl_memory_pool_t *pool_handle, void **block);
sl_status_t sl_memory_pool_free(sl_memory_pool_t *pool_handle, void *block);
sl_status_t sl_memory_delete_pool(sl_memory_pool_t *pool_handle);

sl_memory_create_pool(block_size, block_count, pool_handle)

• Purpose: Creates a memory pool in the general-purpose heap composed of fixed-size blocks

• Parameters:

  • block_size - Size of each block, in bytes

  • block_count - Number of blocks in the pool

  • pool_handle - Handle to the memory pool that will be populated

sl_memory_pool_alloc(pool_handle, block)

• Purpose: Allocates a block from a memory pool

• Parameters:

  • pool_handle - Handle to the memory pool

  • block - Pointer to the variable that will receive the address of the allocated block

sl_memory_pool_free(pool_handle, block)

• Purpose: Frees a block back to a memory pool for reuse

• Parameters:

  • pool_handle - Handle to the memory pool

  • block - Pointer to the block to free

sl_memory_delete_pool(pool_handle)

• Purpose: Deletes a memory pool and returns all memory to the heap

• Parameters:

  • pool_handle - Handle to the memory pool to delete

For complete functions return values documentation, refer to the Memory Manager full API documentation.

Example Usage:

Refer to the code snippets in Scenario 2: Memory Pool for Real-Time Applications and Extended Examples: Complex Memory Management for memory pool API examples.

Statistics API#

sl_status_t sl_memory_get_heap_info(sl_memory_heap_info_t *heap_info);
size_t sl_memory_get_total_heap_size(void);
size_t sl_memory_get_free_heap_size(void);
size_t sl_memory_get_used_heap_size(void);
size_t sl_memory_get_heap_high_watermark(void);
void sl_memory_reset_heap_high_watermark(void);

sl_memory_get_heap_info(heap_info)

• Purpose: Populates an sl_memory_heap_info_t structure with the current status of the general-purpose heap

• Parameters:

  • heap_info - Pointer to structure that will receive heap information data

• Return: SL_STATUS_OK if information retrieval is successful. Proper error code if operation fails (for complete return values documentation, refer to the Memory Manager full API documentation)

sl_memory_get_total_heap_size()

• Purpose: Retrieves the total size of the general-purpose heap in bytes

sl_memory_get_free_heap_size()

• Purpose: Retrieves the current amount of free memory in the general-purpose heap in bytes

sl_memory_get_used_heap_size()

• Purpose: Retrieves the current amount of memory used in the general-purpose heap in bytes

sl_memory_get_heap_high_watermark()

• Purpose: Retrieves the general-purpose heap's high watermark (highest heap usage recorded) in bytes

sl_memory_reset_heap_high_watermark()

• Purpose: Resets the general-purpose heap's high watermark to the current heap used

Example Usage:

For a practical example of monitoring heap usage in an application context, see Scenario 5: Memory Usage Monitoring.

void monitor_heap_usage(void) {
  sl_memory_heap_info_t heap_info;

  // Get detailed heap information
  sl_status_t status = sl_memory_get_heap_info(&heap_info);
  if (status == SL_STATUS_OK) {
    printf("Detailed Heap Statistics:\n");
    printf("  Total Size: %zu bytes\n", heap_info.total_size);
    printf("  Used Size: %zu bytes\n", heap_info.used_size);
    printf("  Free Size: %zu bytes\n", heap_info.free_size);
    printf("  Free Blocks: %zu\n", heap_info.free_block_count);
    printf("  Largest Free Block: %zu bytes\n", heap_info.free_block_largest_size);
  }

  // Get individual heap metrics
  printf("\nIndividual Heap Metrics:\n");
  printf("  Total Heap Size: %zu bytes\n", sl_memory_get_total_heap_size());
  printf("  Free Heap Size: %zu bytes\n", sl_memory_get_free_heap_size());
  printf("  Used Heap Size: %zu bytes\n", sl_memory_get_used_heap_size());
  printf("  High Watermark: %zu bytes\n", sl_memory_get_heap_high_watermark());

  // Reset high watermark after analysis
  sl_memory_reset_heap_high_watermark();
  printf("High watermark reset to current usage\n");
}