
                    Free Stack Space Functions
                    ~~~~~~~~~~~~~~~~~~~~~~~~~~

These files contain Neuron C functions to determine the amount of free
space on the application processor stack.  To use these functions, copy
the files FREESTAK.H and FREESTAK.NS to your working directory, and add
the line:

            #include "freestak.h"

to your Neuron C source file.

The function free_stack() returns an unsigned int with the number
of bytes currently available on the application processor stack.
This may help you avoid a stack overflow, which usually crashes
the Neuron Chip.  The application processor stack is used for
non-static variables declared inside a task or function body, function
parameters, temporary variables, and function call return addresses.

To find the worst-case stack usage of a running Neuron C program, use
the functions fill_stack() and min_stack().

The function fill_stack(pattern) fills the currently free stack space
with the pattern byte.  Choose a pattern that is unlikely to occur in
the used stack space.  For example, don't choose 0x00 or 0xFF.

The function min_stack(pattern) returns an unsigned int with the
length of the longest run of pattern bytes in the free stack space.
In other words, it returns the low water mark of free stack space
since a previous call to fill_stack() specifying the same pattern.
Because of the dual-stack architecture of the Neuron Chip, the
returned result may be less (more conservative) than the actual
low water mark.
