Skip to content

README.md

Latest commit

 

History

History
142 lines (99 loc) · 5.07 KB

README.md

File metadata and controls

142 lines (99 loc) · 5.07 KB

custom-worst-stack

A command-line tool to compute worst-case static stack usage for functions generated in ncs connect, with optional call-graph visualization using Graphviz.

Features

  • Exact and Regex Targets: Analyze specific functions by name (-wcs/--worst-case-stack) or by regex patterns (-wcr/--worst-case-regex).

  • Auto-Detection: Automatically finds the ELF and build directory under build/<project_name> or build/<project_name>/zephyr/, including common names (<project>.elf, zephyr.elf, zephyr_pre0.elf).

  • Graphviz Output: Generate DOT files (--dot-output) or render graphs to png, svg, or pdf (--graph-format), with optional suppression of DOT via --no-dot.

  • Symbol Listing: Print all symbols or those matching a regex (--list-symbols).

  • Verbose Logging: Detailed INFO/WARN messages with --verbose.

Prerequisites

  • Python 3.6+
  • GNU objdump and c++filt in your PATH (or specify --gcc-prefix).
  • (Optional) Graphviz Python package for graph output.
pip install graphviz

Installation

Clone or copy custom-worst-stack.py into your project’s scripts directory.

Ensure it is executable:

chmod +x custom-worst-stack.py

Usage

First build you project using the following extra flag:

-DEXTRA_CFLAGS="-fstack-usage"

Auto-Detect Mode

If you run without --elf and --build-dir, the script attempts to locate them automatically under:

./build/<project>/zephyr/<project>.elf
# or zephyr.elf / zephyr_pre0.elf

If exactly one ELF is found, it proceeds. Otherwise you'll see an error with instructions.

Explicit Mode

Specify both the ELF path and build directory manually:

./custom-worst-stack.py \
  --elf path/to/project.elf \
  --build-dir path/to/build/project \
  -wcs main -wcs init_function \
  --dot-output stack_graph \
  --graph-format svg

Analyze by Regex

./custom-worst-stack.py \
  --elf build/myapp/myapp.elf \
  --build-dir build/myapp \
  -wcr "^init_.*" \
  -wcr "handle_.*" \
  --no-dot  # only render images, no .dot files

List Symbols

./custom-worst-stack.py --list-symbols             # list all symbols
./custom-worst-stack.py --list-symbols "^us.*"   # symbols starting with 'us'

Command-Line Options

Option Description
-wcs, --worst-case-stack Literal function name(s), repeatable or joined with &&.
-wcr, --worst-case-regex Regex pattern(s), repeatable.
--list-symbols [REGEX] List symbols (filtered by REGEX if provided) and exit.
--elf <path> Path to the ELF binary.
--build-dir <dir> Directory containing .su files (stack usage data).
--dot-output <prefix> Prefix for Graphviz .dot files (one per function).
--no-dot Suppress .dot file creation even if --dot-output is set.
`--graph-format <png svg pdf>` Render graph images in given format (requires graphviz).
--output <file> JSON report output path (default: stack_report.json).
--gcc-prefix <prefix> GCC toolchain prefix (e.g. arm-none-eabi-).
--verbose Enable verbose INFO/WARN logging.

Output

  • JSON Report (--output): Contains each function’s maximum static stack size and the call stack leading to that usage.
  • Graph Files: DOT or rendered images illustrating the worst-case call path.

Examples

  1. Basic: Analyze main with auto-detection:

    ./custom-worst-stack.py -wcs main

  2. Multiple Functions:

    ./custom-worst-stack.py --elf app.elf --build-dir build/app \
  -wcs funcA && funcB

  3. Regex + SVG:

    ./custom-worst-stack.py -wcr "^task_.*" --graph-format svg

License

MIT © Dag Erik Refshal Gjørvad