Guidance on setting an appropriate task stack size for Storyboard on an MCU

I was asked by one of our customers how to scope and define the maximum size of Stack for the task that Storyboard will run?

There were some follow-up questions and expansions that I wanted to share as useful for the wider community:

1. How much Stack size (in normal case and in maximum case) should we consider at startup?
2. How does Storyboard engine use Stack at startup?
3. What is the engine Stack used for?

It is first important to clarify which 'Stack' that is being considered:

• The System stack which is shared with the RTOS core and other system code and libraries
• The Storyboard Engine Main Task stack which assigned to the runtime task when it is created

For background in an MCU context the Storyboard Engine graphical main task will typically be running under an RTOS task alongside other system and back-end tasks under control of the chosen RTOS scheduler.

How much Stack size (in normal case and in maximum case) should we consider at startup?

In general that the Stack size chosen is usually between 8KB and 16KB for frequent use in most of our example projects, quick start guides and other documentation.

However, when the customer measured the Stack size for their application it was found that ~19KB of Stack is used from the startup of Storyboard until the initial screen is displayed (before the Storyboard application process is executed).

The Storyboard Engine Main Task is used by all of the engine and plugin components and will be dependent on application complexity and configuration.  In general the sample and example applications Crank shares for demos and learning are not as full featured or complex as a finished commercial application and so real-world memory usage will trend a little higher. 
 
It is very difficult to calculate the task stack size as you need to size this for maximum usage to give headroom.

• Through discussions with customers we have not seen any configurations where the engine task stack size has been larger than 32KB nor in any of our reference projects 
• However this is by definition customer configurable so we would not necessarily see all cases...

If you are familiar with or are using IAR EWARM tools then they have a good application note on this area: Mastering stack and heap for system reliability | IAR

How does Storyboard engine use Stack at startup?

Each of the optional engine plugins enabled will consume some stack dynamically during operation especially during start-up.  As previously mentioned there will usually be an initial peak in usage during start-up as the model is being parsed and objects created as some aspects are using recursive calls which increase stack depth.
 
When the Lua plugin in particular is enabled it will use some additional stack as well as heap (for an internal garbage collector).  

• The Lua runtime will load and parse all of the scripts in the root of the project folder at startup and again can contribute to an initial peak in stack usage whilst this is occurring as some recursive functions may be used.
• You can reduce this by exporting pre-compiled Lua scripts in your header export configuration.

What is the engine Stack used for?

The overall system stack usage is dependent on the firmware application complexity and in the case of Storyboard contribution is used by the various core and plugin libraries.  

Storyboard gre library stack usage is predominantly within the Storyboard Engine Main Task stack itself rather than the wider System Stack and is the memory used to support the execution of the model by nested function calls and transient data variables within the engine. Some functionality does use recursive code such as when parsing the model object tree, performed once on startup which can temporarily increase stack usage.

Once the application is running and past start-up you will see some dynamic usage but normally I have observed minimal variance aside from perhaps occasional complex processing behind runtime Lua functionality in the customer application code. 

All large allocations are requested from the heap or statically allocated from SRAM rather than created on the stack.