suc Files

Assumpltions:
It is assumed that GCC based toolchain is used to build project.
It is also assumed that:
1. Sources are compiled using compiler options -fstack-usage and -fdump-final-insns.
2. Map file is generated during linking.
3. Symbol file is generated using toolchain provided nm utility with option --format=sysv.

Pre-requisites:
Python 3.9+ is required.

Invocation:
    python suc.py <command_line_arguments>

Problems:
Stack usage calculation requires, in general, several steps to complete as well as human involvement.
Only for very simple projects it might be done in one step without extra manual input.
There are several factors which increase complexity. Among them are linking of external libraries,
use of assembly both pure and inline, use of indirect calls and recursions.
Inline assembly that performs function call(s) and/or consumes stack is insidious -
compiler does not detect such cases.

How to:
1. Run with -t <template> and -f <functions> and perhaps -s <report> options.
2. Have a look at a template. It might contain only a single comment "No missing data found" which is
   a weak indicator that all necessary data have been collected from compiler output.
   It is not enough provided inline assembly that performs function calls or consumes stack exists.
   Provided "No missing data found" and high confidence it is true, skip to either step 6 or 5
   depending on whether report is already generated or not.
3. If necessary, rename template file and type in missing data.
   Several input files can be created from template, e.g. for application and every linked library.
4. Verify inline assembly, if any, does not perform function call(s) and does not use stack.
   Otherwise, such cases shall be added to manual input.
5. Run with -m <manual_input>, if any, and -s <report> options.
   The -t <template> option can also be used. Provided the manual input is complete, the expected
   content of template file is a single comment "No missing data found". But it is not sufficient.
6. Verify there are no warnings in the stack usage report. At least non-deliberate.
7. Verify the number of call trees in the stack usage report is equal to expected.
   Odd call trees can be explained by:
     - rtl dump parsing errors or
     - incorrect manual input where callees are missing.
8. Obtained results do not consider either particular architecture or
   implementation (e.g. interrupt nesting). Some extra work might need to be done.