5.2.13.1 Stack Guidance Information

The stack guidance features estimates the stack usage of several stacks which are used by programs compiled with the MPLAB XC8 C Compiler, those being:
  • The hardware stack, used for function return addresses
  • The software data stack, used by any function compiled using a reentrant model

The hardware stack is described in 5.7.1 Function Return Address Stack. The size of this stack is fixed by the device. Nesting function calls too deeply will overflow the stack and ultimately cause program failure. Interrupts also use this stack. With some devices, the -mstackcall option can be used to employ a different function call method that reduces stack usage.

Functions are encoded by the compiler to use either a software or compiled stack for data objects they define, as described in 5.7.2 Data Stacks. A function will only ever use one stack type, but a program can be comprised of functions that use a compiled stack and functions that use the software stack. Typically, a program will follow a stack model (-mstack option) and have all functions compiled to use the same stacks.

A compiled stack is a static allocation of data memory for stack-based objects. As the size of this stack can be accurately determined at compile time and cannot change at runtime, the memory errors issued by the compiler should this stack become too large will alert you to this situation. The stack guidance feature will not issue any additional information for the compiled stack used by a program, other than to indicate its use.

By comparison, a software stack is a dynamic allocation of memory that occurs at runtime and its size is more difficult to predict. This is where the information produced by the stack guidance feature will be useful. The stack guidance feature will alert you to potential runtime overflow of this stack.

The following example shows a stack usage information summary that might be displayed after a successful build.
=============================== STACK USAGE GUIDANCE ================================

The program uses a compiled stack model.

The call-graph beginning at main(),
   uses an estimated 17 of 31 hardware stack locations and a compiled stack

However, the following cautions exist:

1) There is 1 "high-priority" interrupt service routine detected:
   isr() call-graph uses an estimated 1 hardware stack location and a compiled stack
You must add stack allowances for those functions.

2) Current optimization level might use a level of hardware stack.
You must add a hardware stack allowance for this feature.

=====================================================================================
The information will show the following.
  • The stack model used by the program
  • The hardware stack usage estimate
  • The software stack usage estimate

In addition, a number of cautionary messages might be displayed. These clarify potential stack overflows reported by the above estimates and indicate additional stack usage that must be considered to determine the total program stack usage. Due to factors that make it impossible to know when this additional memory might be used, these are not incorporated into the earlier summary.

The following cautions might be displayed in the described circumstances.
Recursive functions
Recursive function calls were detected in the program. As the number of iterations of a recursive call cannot be predicted, the number of hardware stack levels and the total software stack size cannot be determined, so no stack guidance is possible. The names of recursive functions detected are listed in this caution.
External functions
Calls to external functions were detected in the program. External functions are those not defined in the C program. Assembly routines, for example, are considered as external functions. External functions cannot be scanned for the number of hardware stack levels they consume, nor for any data they place on a software stack. If external functions are called, no guidance is possible. The name of any external functions called are listed in this caution.
Deviations from the current stack model
Although the compiler will build programs using a stack model (specified by the -mstack option), which dictates the stack type used by all functions, there are instances where a function might use a different stack type, e.g., if that function used a stack specifier. This caution lists those functions using a different stack type to that specified by the model.
Main-line code exceeds hardware stack size
This caution indicates that the function call depth of the main-line code call-graph has exceeded the number of hardware stack levels available on the target device. If the option is supported by your target device, you may use -mstackcall (see 4.6.1.24 Stackcall Option) to have the compiler use an alternate method of calling functions that does not need as many stack levels. The reduced stack usage of this method will then be reflected in the stack guidance report printed by the compiler.
Interrupts might exceed hardware stack size
Even though the depth of the call graphs associated with main-line and interrupt code might be known, interrupts can trigger at any time, and in such a situation, the compiler cannot reliably determine the program's total function call depth. This caution alerts you to the existence of interrupt functions and that the stack usage of these will need to be taken into account when considering the total hardware stack usage of your program.
Call graph exceeds software stack size
The stack guidance feature has estimated that the indicated call graph (main-line or interrupt) has or might have used more software data stack than it was allocated. The -mstack option can be used to change the size allocated to each call graph, see 4.6.1.23 Stack Option.
Interrupts might exceed software stack size
Even though the size of the software stack used by main-line and interrupt call graphs might be accurately known, interrupts can trigger at any time, and given this is the case, the compiler cannot reliably determine the program's total stack usage. This caution alerts you to the existence of interrupt functions and that the stack usage of these will need to be taken into account when considering the total software stack usage of your program.
Optimization level might use hardware stack
Some optimizations might result in additional calls being made that will increase the usage of the hardware stack over what has been reported. This caution indicates that the current optimization settings could lead to increased hardware stack usage and must be taken into account when considering the hardware stack usage of your program.
Debugger might use hardware stack
The debug executives used by some debuggers consume levels of the device's hardware stack. In this caution, the indicated number of levels required by the debugger must be taken into account when considering the hardware stack usage of your program.