LwMEM

group LWMEM

Lightweight dynamic memory manager.

Defines

LWMEM_ARRAYSIZE(x)

Get size of statically allocated array.

Return

Number of elements in array

Parameters
  • [in] x: Object to get array size of

lwmem_assignmem(regions, len)

Note

This is a wrapper for lwmem_assignmem_ex function

Parameters
  • [in] regions: Array of regions with address and its size. Regions must be in increasing order (start address) and must not overlap in-between

  • [in] len: Number of regions in array

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

Parameters
  • [in] size: Size to allocate in units of bytes

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

Parameters
  • [in] nitems: Number of elements to be allocated

  • [in] size: Size of each element, in units of bytes

lwmem_realloc(ptr, size)

Note

This is a wrapper for lwmem_realloc_ex function

Parameters
  • [in] ptr: Memory block previously allocated with one of allocation functions. It may be set to NULL to create new clean allocation

  • [in] size: Size of new memory to reallocate

lwmem_realloc_s(ptrptr, size)

Note

This is a wrapper for lwmem_realloc_s_ex function

Parameters
  • [in] ptrptr: Pointer to pointer to allocated memory. Must not be set to NULL. If reallocation is successful, it modified where pointer points to, or sets it to NULL in case of free operation

  • [in] size: New requested size

lwmem_free(ptr)

Note

This is a wrapper for lwmem_free_ex function

Parameters
  • [in] ptr: Memory to free. NULL pointer is valid input

lwmem_free_s(ptrptr)

Note

This is a wrapper for lwmem_free_s_ex function

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

Functions

size_t lwmem_assignmem_ex(lwmem_t *const lw, const lwmem_region_t *regions, const size_t len)

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

Return

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

Note

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

Parameters
  • [in] lw: LwMEM instance. Set to NULL to use default instance

  • [in] regions: Array of regions with address and its size. Regions must be in increasing order (start address) and must not overlap in-between

  • [in] len: Number of regions in array

void *lwmem_malloc_ex(lwmem_t *const lw, 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

Return

Pointer to allocated memory on success, NULL otherwise

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters
  • [in] lw: LwMEM instance. Set to NULL to use default instance

  • [in] region: Optional region instance within LwMEM instance to force allocation from. Set to NULL to use any region within LwMEM instance

  • [in] size: Number of bytes to allocate

void *lwmem_calloc_ex(lwmem_t *const lw, 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

Return

Pointer to allocated memory on success, NULL otherwise

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters
  • [in] lw: LwMEM instance. Set to NULL to use default instance

  • [in] region: Optional region instance within LwMEM instance to force allocation from. Set to NULL to use any region within LwMEM instance

  • [in] nitems: Number of elements to be allocated

  • [in] size: Size of each element, in units of bytes

void *lwmem_realloc_ex(lwmem_t *const lw, 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:
Note

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

  • 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

Return

Pointer to allocated memory on success, NULL otherwise

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters
  • [in] lw: LwMEM instance. Set to NULL to use default instance

  • [in] region: 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

  • [in] ptr: Memory block previously allocated with one of allocation functions. It may be set to NULL to create new clean allocation

  • [in] size: Size of new memory to reallocate

unsigned char lwmem_realloc_s_ex(lwmem_t *const lw, 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

Return

1 if successfully reallocated, 0 otherwise

Note

This function is thread safe when LWMEM_CFG_OS is enabled

Parameters
  • [in] lw: LwMEM instance. Set to NULL to use default instance

  • [in] region: 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

  • [in] ptr: Pointer to pointer to allocated memory. Must not be set to NULL. If reallocation is successful, it modified where pointer points to, or sets it to NULL in case of free operation

  • [in] size: New requested size

void lwmem_free_ex(lwmem_t *const lw, 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
  • [in] lw: LwMEM instance. Set to NULL to use default instance. Instance must be the same as used during allocation procedure

Parameters
  • [in] ptr: Memory to free. NULL pointer is valid input

void lwmem_free_s_ex(lwmem_t *const lw, 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
  • [in] lw: LwMEM instance. Set to NULL to use default instance. Instance must be the same as used during allocation procedure

  • [in] ptr: Pointer to pointer to allocated memory. When set to non NULL, pointer is freed and set to NULL

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_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

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