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

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

int 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 – [inout] Pointer to lwmem_stats_t to store result

void lwmem_get_size(lwmem_stats_t *stats)

Get statistics of a default LwMEM instance.

Parameters

stats – [inout] Pointer to lwmem_stats_t to store result

size_t lwmem_assignmem(const lwmem_region_t *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

void *lwmem_malloc(size_t 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

void *lwmem_calloc(size_t nitems, size_t 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

void *lwmem_realloc(void *ptr, size_t 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

int lwmem_realloc_s(void **ptr2ptr, size_t 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

  • ptr2ptr – [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(void *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

void lwmem_free_s(void **ptr2ptr)

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

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

size_t lwmem_get_size(void *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

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

size_t mem_available_bytes

Memory size available for allocation

uint8_t *mem_next_available_ptr

Pointer for next allocation

uint8_t is_initialized

Set to 1 when initialized

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