readme.md

# Unity Memory

This Framework is an optional add-on to Unity.  By including unity.h and then
unity_memory.h, you have the added ability to track malloc and free calls. This 
addon requires that the stdlib functions be overridden by its own defines. These
defines will still malloc / realloc / free etc, but will also track the calls
in order to ensure that you don't have any memory leaks in your programs.

Note that this is only useful in situations where a unit is in charge of both
the allocation and deallocation of memory. When it is not symmetric, unit testing 
can report a number of false failures. A more advanced runtime tool is required to
track complete system memory handling.

# Module API

## `UnityMalloc_StartTest` and `UnityMalloc_EndTest`

These must be called at the beginning and end of each test. For simplicity, they can
be added to `setUp` and `tearDown` in order to do their job. When using the test
runner generator scripts, these will be automatically added to the runner whenever
unity_memory.h is included.

## `UnityMalloc_MakeMallocFailAfterCount`

This can be called from the tests themselves. Passing this function a number will
force the reference counter to start keeping track of malloc calls. During that test,
if the number of malloc calls exceeds the number given, malloc will immediately 
start returning `NULL`. This allows you to test error conditions. Think of it as a 
simplified mock.

# Configuration

## `UNITY_MALLOC` and `UNITY_FREE`

By default, this module tries to use the real stdlib `malloc` and `free` internally. 
If you would prefer it to use something else, like FreeRTOS's `pvPortMalloc` and 
`pvPortFree`, then you can use these defines to make it so.

## `UNITY_EXCLUDE_STDLIB_MALLOC`

If you would like this library to ignore stdlib or other heap engines completely, and
manage the memory on its own, then define this. All memory will be handled internally
(and at likely lower overhead). Note that this is not a very featureful memory manager,
but is sufficient for most testing purposes.

## `UNITY_INTERNAL_HEAP_SIZE_BYTES`

When using the built-in memory manager (see `UNITY_EXCLUDE_STDLIB_MALLOC`) this define
allows you to set the heap size this library will use to manage the memory.