4.6.1.11 Heap Option

The -mheap=[size|auto] option specifies the size of memory reserved for the heap.

The heap is used with the standard dynamic memory allocation functions, those being malloc(), calloc(), realloc(), and free(), whose operation is described in 5.4.7.1 Dynamic Memory Allocation for PIC Devices.

When this option is used with a size argument, being a decimal number of bytes, the compiler will attempt to reserve the requested amount of memory for the heap. Thus, at runtime, the heap will be able to grow to the specified size with no corruption of data. This memory is reserved unconditionally, even if no dynamic memory allocation functions are used in the program.

Alternatively, the argument may be specified as auto, in which case the compiler will calculate a maximum size for the heap after other static and stack allocations have been made. Memory with this calculated size will only be reserved, however, if the compiler detects calls to any of the dynamic memory allocation functions in the program. If no -mheap option is specified, then the compiler uses an auto setting, as if -mheap=auto was issued. Whenever acting with an auto setting, the compiler will issue a compiler advisory message if dynamic memory allocation functions have been detected and memory has been reserved as a result.

The size of software stacks used by functions compiled to use a reentrant model are also dynamic in nature, and memory must be reserved for their use. That memory is specified using the -mstack option (see 4.6.1.23 Stack Option). A size argument of auto can be used with both the -mheap and -mstack options, in which case the compiler will evenly distribute the free memory remaining between the heap and stacks after other statical allocations have been made.