95
The static allocation area, located at the beginning of RAM, includes all module-level variables defined by
your application and all statically allocated system variables. This includes the task stacks that are
statically allocated by your application. The task stack for Main() occupies all of the RAM between the
end of the static allocation area and the heap. The stack pointer for all task stacks is initialized to the end
of the task stack space and moves toward lower RAM addresses as it is used. By default, the Heap Limit
is set at 512 bytes from the end of RAM. For devices with external RAM, the heap is located at the end of
external RAM as determined at startup.
The heap will not grow beyond the Heap Limit. When the heap is exhausted, further allocation attempts
will fail, possibly resulting in malfunctioning of your application. The heap is used for storing most RAM-
based strings (but not BoundedString or fixed-string types) including strings that are returned by functions
you define in your application and System Library functions that return strings. Additionally, on devices
which have Program Memory in internal Flash memory, when a Program Memory write operation is
performed a temporary buffer is allocated from the heap. The size of this buffer is equal to the Flash
page size for the microcontroller, typically 256 bytes. This additional temporary use of heap space must
be considered if your application performs write operations on Program Memory. Lastly, the System
Library function System.Alloc() may be used by your application to allocate memory from the heap.
All of these uses must be considered when determining how much heap space is needed by your
application. The function System.HeapHeadRoom() may be helpful for determining the minimum heap
size for your application.
If the default heap size is insufficient for your application, you can specify the Heap Limit setting in several
different ways, each of which may be useful in different circumstances. Perhaps the simplest method of
setting the Heap Limit is to specify the desired size for the Main() task stack. This can be done using the
directive Option MainTaskStackSize in your Main module or by using the compiler option -main-
task-stack-size. In both cases, the Heap Limit is set by adding the specified size to the address of
the end of the static allocation area.
The second method of setting the Heap Limit is to specify the desired size of the heap using the directive
Option HeapSize in your Main module or by using the compiler option -heap-size. The Heap Limit
is set by subtracting the specified value from the address one past the end of RAM. For devices that
have external RAM, the end of RAM is determined at startup. If you have external RAM, you may specify
that all of the external RAM should be used for the heap by specifying the heap size using the special
values 65535 or &HFFFF.
The final method for setting the Heap Limit is to specify an absolute address using the directive Option
HeapLimit in your Main module or by using the compiler option -heap-limit. This method is
recommended for use only by advanced programmers who understand completely how memory is
allocated in a native ZBasic application.