LwMEM

group LWMEM

Lightweight dynamic memory manager.

Defines

LWMEM_ARRAYSIZE(x)

Get size of statically allocated array.

Parameters

x – [in] Object to get array size of

Returns

Number of elements in array

lwmem_assignmem(regions)

Note

This is a wrapper for lwmem_assignmem_ex function. It operates in default LwMEM instance and uses first available region for memory operations

Parameters

regions – [in] Pointer to array of regions with address and respective size. Regions must be in increasing order (start address) and must not overlap in-between. Last region entry must have address NULL and size set to 0

//Example definition
lwmem_region_t regions[] = {
    { (void *)0x10000000, 0x1000 }, //Region starts at address 0x10000000 and is 0x1000 bytes long
    { (void *)0x20000000, 0x2000 }, //Region starts at address 0x20000000 and is 0x2000 bytes long
    { (void *)0x30000000, 0x3000 }, //Region starts at address 0x30000000 and is 0x3000 bytes long
    { NULL, 0 }                     //Array termination indicator
}

Returns

0 on failure, number of final regions used for memory manager on success

lwmem_malloc(size)

Note

This is a wrapper for lwmem_malloc_ex function. It operates in default LwMEM instance and uses first available region for memory operations

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

size – [in] Size to allocate in units of bytes

Returns

Pointer to allocated memory on success, NULL otherwise

lwmem_calloc(nitems, size)

Note

This is a wrapper for lwmem_calloc_ex function. It operates in default LwMEM instance and uses first available region for memory operations

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

nitems – [in] Number of elements to be allocated
size – [in] Size of each element, in units of bytes

Returns

Pointer to allocated memory on success, NULL otherwise

lwmem_realloc(ptr, size)

Note

This is a wrapper for lwmem_realloc_ex function. It operates in default LwMEM instance and uses first available region for memory operations

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

ptr – [in] Memory block previously allocated with one of allocation functions. It may be set to NULL to create new clean allocation
size – [in] Size of new memory to reallocate

Returns

Pointer to allocated memory on success, NULL otherwise

lwmem_realloc_s(ptrptr, size)

Note

This is a wrapper for lwmem_realloc_s_ex function. It operates in default LwMEM instance and uses first available region for memory operations

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

ptrptr – [in] Pointer to pointer to allocated memory. Must not be set to NULL. If reallocation is successful, it modifies pointer’s pointing address, or sets it to NULL in case of free operation
size – [in] New requested size in bytes

Returns

1 if successfully reallocated, 0 otherwise

lwmem_free(ptr)

Note

This is a wrapper for lwmem_free_ex function. It operates in default LwMEM instance and uses first available region for memory operations

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

ptr – [in] Memory to free. NULL pointer is valid input

lwmem_free_s(ptrptr)

Note

This is a wrapper for lwmem_free_s_ex function. It operates in default LwMEM instance and uses first available region for memory operations

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

ptrptr – [in] Pointer to pointer to allocated memory. When set to non NULL, pointer is freed and set to NULL

lwmem_get_size(ptr)

Note

This is a wrapper for lwmem_get_size_ex function. It operates in default LwMEM instance and uses first available region for memory operations

Parameters

ptr – [in] Pointer to allocated memory

Returns

Block size for user in units of bytes

lwmem_get_stats(stats)

Note

This is a wrapper for lwmem_get_stats_ex function. It operates in default LwMEM instance

Parameters

ptr – [in] Pointer to lwmem_stats_t to store result

Functions

size_t lwmem_assignmem_ex(lwmem_t *lwobj, const lwmem_region_t *regions)

Initializes and assigns user regions for memory used by allocator algorithm.

Note

This function is not thread safe when used with operating system. It must be called only once to setup memory regions

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance

regions – [in] Pointer to array of regions with address and respective size. Regions must be in increasing order (start address) and must not overlap in-between. Last region entry must have address NULL and size set to 0

//Example definition
lwmem_region_t regions[] = {
    { (void *)0x10000000, 0x1000 }, //Region starts at address 0x10000000 and is 0x1000 bytes long
    { (void *)0x20000000, 0x2000 }, //Region starts at address 0x20000000 and is 0x2000 bytes long
    { (void *)0x30000000, 0x3000 }, //Region starts at address 0x30000000 and is 0x3000 bytes long
    { NULL, 0 }                     //Array termination indicator
}

Returns

0 on failure, number of final regions used for memory manager on success

void *lwmem_malloc_ex(lwmem_t *lwobj, const lwmem_region_t *region, const size_t size)

Allocate memory of requested size in specific lwmem instance and optional region.

Note

This is an extended malloc version function declaration to support advanced features

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance
region – [in] Optional region instance within LwMEM instance to force allocation from. Set to NULL to use any region within LwMEM instance
size – [in] Number of bytes to allocate

Returns

Pointer to allocated memory on success, NULL otherwise

void *lwmem_calloc_ex(lwmem_t *lwobj, const lwmem_region_t *region, const size_t nitems, const size_t size)

Allocate contiguous block of memory for requested number of items and its size in specific lwmem instance and region.

It resets allocated block of memory to zero if allocation is successful

Note

This is an extended calloc version function declaration to support advanced features

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance
region – [in] Optional region instance within LwMEM instance to force allocation from. Set to NULL to use any region within LwMEM instance
nitems – [in] Number of elements to be allocated
size – [in] Size of each element, in units of bytes

Returns

Pointer to allocated memory on success, NULL otherwise

void *lwmem_realloc_ex(lwmem_t *lwobj, const lwmem_region_t *region, void *const ptr, const size_t size)

Reallocates already allocated memory with new size in specific lwmem instance and region.

Function behaves differently, depends on input parameter of ptr and size:

ptr == NULL; size == 0: Function returns NULL, no memory is allocated or freed
ptr == NULL; size > 0: Function tries to allocate new block of memory with size length, equivalent to malloc(region, size)
ptr != NULL; size == 0: Function frees memory, equivalent to free(ptr)
ptr != NULL; size > 0: Function tries to allocate new memory of copy content before returning pointer on success

Note

This function may only be used with allocations returned by any of _from API functions

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance
region – [in] Pointer to region to allocate from. Set to NULL to use any region within LwMEM instance. Instance must be the same as used during allocation procedure
ptr – [in] Memory block previously allocated with one of allocation functions. It may be set to NULL to create new clean allocation
size – [in] Size of new memory to reallocate

Returns

Pointer to allocated memory on success, NULL otherwise

uint8_t lwmem_realloc_s_ex(lwmem_t *lwobj, const lwmem_region_t *region, void **const ptr, const size_t size)

Safe version of realloc_ex function.

After memory is reallocated, input pointer automatically points to new memory to prevent use of dangling pointers. When reallocation is not successful, original pointer is not modified and application still has control of it.

It is advised to use this function when reallocating memory.

Function behaves differently, depends on input parameter of ptr and size:

ptr == NULL: Invalid input, function returns 0
*ptr == NULL; size == 0: Function returns 0, no memory is allocated or freed
*ptr == NULL; size > 0: Function tries to allocate new block of memory with size length, equivalent to malloc(size)
*ptr != NULL; size == 0: Function frees memory, equivalent to free(ptr), sets input pointer pointing to NULL
*ptr != NULL; size > 0: Function tries to reallocate existing pointer with new size and copy content to new block

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance
region – [in] Pointer to region to allocate from. Set to NULL to use any region within LwMEM instance. Instance must be the same as used during allocation procedure
ptr – [in] Pointer to pointer to allocated memory. Must not be set to NULL. If reallocation is successful, it modifies pointer’s pointing address, or sets it to NULL in case of free operation
size – [in] New requested size in bytes

Returns

1 if successfully reallocated, 0 otherwise

void lwmem_free_ex(lwmem_t *lwobj, void *const ptr)

Free previously allocated memory using one of allocation functions in specific lwmem instance.

Note

This is an extended free version function declaration to support advanced features

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance. Instance must be the same as used during allocation procedure
ptr – [in] Memory to free. NULL pointer is valid input

void lwmem_free_s_ex(lwmem_t *lwobj, void **const ptr)

Safe version of free function.

After memory is freed, input pointer is safely set to NULL to prevent use of dangling pointers.

It is advised to use this function when freeing memory.

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance. Instance must be the same as used during allocation procedure
ptr – [in] Pointer to pointer to allocated memory. When set to non NULL, pointer is freed and set to NULL

size_t lwmem_get_size_ex(lwmem_t *lwobj, void *ptr)

Get user size of allocated memory.

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance. Instance must be the same as used during allocation procedure
ptr – [in] Pointer to allocated memory

Returns

Block size for user in units of bytes

void lwmem_get_stats_ex(lwmem_t *lwobj, lwmem_stats_t *stats)

Get statistics of a LwMEM instance.

Parameters

lwobj – [in] LwMEM instance. Set to NULL to use default instance. Instance must be the same as used during allocation procedure
stats – [in] Pointer to lwmem_stats_t to store result

struct lwmem_block_t

#include <lwmem.h>

Memory block structure.

Public Members

struct lwmem_block *next: Next free memory block on linked list. Set to LWMEM_BLOCK_ALLOC_MARK when block is allocated and in use

size_t size: Size of block, including metadata part. MSB bit is set to 1 when block is allocated and in use, or 0 when block is considered free

struct lwmem_stats_t

#include <lwmem.h>

Statistics structure.

Public Members

uint32_t mem_size_bytes: Total memory size of all regions combined

uint32_t mem_available_bytes: Free memory available for allocation

uint32_t minimum_ever_mem_available_bytes: Minimum amount of total free memory there has been in the heap since the system booted.

uint32_t nr_alloc: Number of all allocated blocks in single instance

uint32_t nr_free: Number of frees in the LwMEM instance

struct lwmem_t

#include <lwmem.h>

LwMEM main structure.

Public Members

lwmem_block_t start_block: Holds beginning of memory allocation regions

lwmem_block_t *end_block: Pointer to the last memory location in regions linked list

size_t mem_available_bytes: Memory size available for allocation

size_t mem_regions_count: Number of regions used for allocation

LWMEM_CFG_OS_MUTEX_HANDLE mutex: System mutex for OS

lwmem_stats_t stats: Statistics

struct lwmem_region_t

#include <lwmem.h>

Memory region descriptor.

Public Members

void *start_addr: Region start address

size_t size: Size of region in units of bytes