cortex-memory-budget

Static flash/RAM footprint analysis for ARM Cortex-M binaries — CI-friendly, framework-agnostic, zero runtime dependencies.

cortex-memory-budget analyzes an ELF binary (via arm-none-eabi-objdump, nm, and addr2line) and reports how much flash and RAM your firmware consumes, broken down by memory region, section, symbol, and source file. Pre-allocated stack and heap are detected via linker symbols with section-based fallback.

It supports Cortex-M0, Cortex-M4, Cortex-M7, and Cortex-M33 and is designed for resource-constrained MCUs where every kilobyte of flash and every byte of RAM matters.

✨ Features

🚀 Quickstart

1. Install

pip install cortex-memory-budget

Runtime dependencies: none (Python ≥ 3.11 stdlib only). At analysis time you need arm-none-eabi-objdump, arm-none-eabi-nm, and arm-none-eabi-addr2line on PATH, or pass --objdump/--nm/--addr2line.

2. Write a config (memory-analysis.json)

{
  "top_n_symbols": 20,
  "top_n_source_files": 15,
  "regions": [
    {"name": "FLASH", "length_kb": 1024},
    {"name": "SRAM",  "length_kb": 192}
  ]
}

regions is optional — if omitted (or for regions not listed), values are taken from the linker script passed via --linker-script. See docs/config-schema.md for the full schema.

3. Run

cortex-memory-budget memory-analysis.json \
    --elf build/firmware.elf \
    --target nucleo-h743zi \
    --build-config Release \
    --cortex m7 \
    --linker-script firmware.ld \
    --output-dir reports

Outputs in reports/:

4. Use in GitHub Actions

- uses: embedded-pro/cortex-memory-budget@v0
  with:
    config-path: memory-analysis.json
    elf-path: build/firmware.elf
    baseline-elf-path: baseline/firmware.elf   # optional, enables diff
    target: nucleo-h743zi
    build-config: Release
    cortex: m7
    linker-script-path: firmware.ld
    fail-over-flash-pct: 85
    fail-over-ram-pct: 80

The action posts an idempotent PR comment, appends a step summary, and uploads all reports as an artifact. See docs/usage.md for the full input/output reference.

📚 Documentation

🧪 Examples

Five runnable examples ship in examples/:

⚠️ Scope & limitations

This tool gives static post-link footprint analysis. It does not model:

• Worst-case dynamic stack depth (use -fstack-usage + a call-graph walker for that). We report only the pre-allocated stack reservation.
• Runtime heap fragmentation. We report only the configured heap budget.
• Cache line / row paddings inserted at runtime.
• Externally loaded / overlay / XIP-from-PSRAM code that isn't part of the ELF.

Estimates are intended as a CI guardrail for the static link image.

📄 License

Apache-2.0 — see LICENSE.