Page 103 of 229 Start Back Next End ZBasic Language Reference 93 ZBasic Microcontrollers 3.29 Controlling the Heap Size and Main() Task Stack Size The diagram below illustrates how RAM is allocated between defined variables, task stacks and the heap. 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. For native mode devices, the task stack for Main() occupies all of the RAM between the end of the static allocation area and the heap limit. The task stack grows downward from the heap limit while the heap grows downward from the end of RAM. For native mode ZX devices, the heap limit is set at 512 bytes from the end of RAM by default. For generic ZBasic devices, the default heap size depends on a number of factors including RAM size and Program Memory page size. For VM mode devices, the space between the end of the static allocation area and the end of RAM is shared by default between the Main() task stack and the heap. The task stack grows upward from the end of the static allocation area while the heap grows downward from the end of RAM. There is no specific heap limit in the default case but you may specify one as described below. If a heap limit exists, the heap will not grow beyond that point. 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-length string types) including strings that are returned by functions you define in your application and System Library functions that return strings. Additionally, for devices that use internal Flash memory for Program Memory (including all generic devices), 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. 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 ZBasic application.