cortex-cycle-budget

Static cycle-count estimation for ARM Cortex-M binaries — CI-friendly, framework-agnostic, zero runtime dependencies.

cortex-cycle-budget analyzes an ELF binary (via arm-none-eabi-objdump) and estimates the cycle cost of a user-defined critical path through your firmware. It supports Cortex-M0, Cortex-M4, Cortex-M7, and Cortex-M33 with per-variant timing tables sourced from the ARM Technical Reference Manuals.

It is designed for hard-real-time loops (motor control, signal processing, servo loops) where you must guarantee that a control iteration fits inside a fixed cycle budget.

✨ Features

🚀 Quickstart

1. Install

pip install cortex-cycle-budget

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

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

{
  "path_name": "FOC Control Loop",
  "loop_rates_khz": [20, 40, 100],
  "path_stages": [
    {"label": "ADC Read",  "patterns": ["^adc_read$"]},
    {"label": "FOC Math",  "entry": "^foc_step$", "patterns": ["^foc_.*$"]},
    {"label": "PWM Write", "patterns": ["^pwm_write$"]}
  ]
}

See docs/config-schema.md for the full schema.

3. Run

cortex-cycle-budget cycle-analysis.json \
    --elf build/firmware.elf \
    --target nucleo-h743zi \
    --build-config Release \
    --clock-mhz 480 \
    --cortex m7 \
    --output-dir reports

Outputs in reports/:

4. Use in GitHub Actions

- uses: your-org/cortex-cycle-budget@v0
  with:
    config-path: cycle-analysis.json
    elf-path: build/firmware.elf
    target: nucleo-h743zi
    build-config: Release
    clock-mhz: 480
    cortex: m7
    fail-over-max-cycles: 20000   # fail the PR if the budget is blown

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

Four runnable examples ship in examples/:

⚠️ Scope & limitations

This tool gives static, deterministic estimates. It does not model:

• Cache hits/misses (Cortex-M7 I-cache, D-cache, AXI bus contention).
• Branch prediction accuracy on M7.
• Memory wait states from external flash / SDRAM.
• Interrupt nesting and tail-chaining beyond the documented worst case.
• Cortex-M7 dual-issue at the instruction-pair level (planned).

Estimates are intended as a CI guardrail, not a substitute for cycle-accurate hardware profiling (e.g., DWT/CYCCNT or a logic analyzer).

📄 License

Apache-2.0 — see LICENSE.