CortexFault

简体中文

Turn an ARM Cortex-M fault dump into an actionable diagnosis.

CortexFault is a zero-dependency, offline CLI for the moment when the device is gone and all you have left is a UART log. It decodes Cortex-M fault status registers, explains EXC_RETURN, ranks likely causes, optionally resolves addresses against the exact firmware ELF, and creates text, JSON, or self-contained HTML reports.

$ cortexfault analyze examples/precise-bus-fault.log

CortexFault analysis
====================
Likely cause : Precise data bus fault at 0x2000FFF0
Confidence   : high
PC           : 0x08001234
LR           : 0x08001001
EXC_RETURN   : thread, PSP, basic frame

Findings
- HIGH    BUS_FAULT_ADDRESS: Bus fault address captured
  Evidence: BFAR=0x2000FFF0
- HIGH    PRECISERR: Precise data bus error
  Evidence: CFSR bit 9 is set

Why CortexFault?

GDB and RTOS coredump tools are excellent when a reproducible target or complete coredump is available. CortexFault covers a smaller, common gap: a customer, test rack, or field device sends a handful of register values and you need a useful first answer now.

• Accepts messy name=value / name: value logs and structured JSON.
• Decodes CFSR, HFSR, DFSR, BFAR, MMFAR, stacked xPSR, and common EXC_RETURN values.
• Distinguishes precise and imprecise bus faults so the stacked PC is not over-trusted.
• Symbolizes PC and LR with GNU or LLVM addr2line.
• Produces stable JSON for automation and a single-file HTML report for sharing.
• Runs locally, sends nothing over the network, and has no runtime dependencies.

Install

git clone https://github.com/269394628/CortexFault.git
cd CortexFault
python -m pip install -e .

Python 3.9 or newer is required.

Use

Analyze a text or JSON dump:

cortexfault analyze crash.log
cortexfault analyze examples/divide-by-zero.json --format json

Read from stdin:

cat crash.log | cortexfault analyze -

Resolve PC/LR using the exact ELF that produced the running firmware:

cortexfault analyze crash.log \
  --elf build/firmware.elf \
  --html fault-report.html

CortexFault looks for arm-none-eabi-addr2line, llvm-addr2line, then addr2line. Use --addr2line /path/to/tool to select one explicitly.

Decode values without creating a dump file:

cortexfault decode --cfsr 0x02000000 --hfsr 0x40000000 --lr 0xFFFFFFFD

Accepted input

Text can be copied directly from a serial console:

r0=0x00000000 lr=0x08001001 pc=0x08001234 xpsr=0x21000000
exc_return=0xFFFFFFFD
cfsr=0x00008200 hfsr=0x40000000 bfar=0x2000FFF0

Eight-digit values without 0x are treated as hexadecimal. JSON may put registers at the top level or under registers:

{
  "registers": {
    "pc": "0x08001234",
    "lr": "0x08001001",
    "exc_return": "0xFFFFFFFD",
    "cfsr": "0x00008200",
    "bfar": "0x2000FFF0"
  }
}

Supported names include r0-r15, sp, msp, psp, lr, pc, exc_return, xpsr, cfsr, hfsr, dfsr, afsr, shcsr, icsr, mmfar, and bfar.

How it works

flowchart LR
    A[UART log or JSON] --> B[Normalize registers]
    B --> C[Decode SCB fault bits]
    C --> D[Rank evidence-based findings]
    B --> E[Optional ELF symbolization]
    D --> F[Text / JSON / HTML]
    E --> F

Loading

The diagnosis is deterministic. There is no model call and no hidden upload. Every finding includes the register bit or address used as evidence.

Architecture scope and limitations

CortexFault targets the configurable fault status layout used by Armv7-M and Armv8-M Mainline implementations, including common Cortex-M3, M4, M7, M33, and M55 systems. Availability and behavior of registers still depend on the exact core and MCU. Cortex-M0/M0+ and other Baseline systems expose less fault state, so only the supplied common registers can be analyzed.

CortexFault is a triage tool, not a proof engine:

• An incomplete dump can support several explanations.
• For IMPRECISERR, the stacked PC can be later than the failing store.
• Symbolization is reliable only with the exact, unstripped ELF and matching memory layout.
• Stack unwinding, TrustZone/SecureFault analysis, vendor-specific fault registers, and RTOS task reconstruction are not implemented yet.
• A corrupted exception frame can make every stacked register misleading.

Always validate the result against the processor technical reference manual, MCU memory map, linker map, and source code.

Capture a useful dump

The analyzer is only as good as the captured data. Start with:

r0 r1 r2 r3 r12 lr pc xpsr
msp psp exc_return
cfsr hfsr dfsr afsr shcsr icsr mmfar bfar

See the fault capture guide for an exception-context checklist and a minimal CMSIS/GCC template. A Chinese capture guide is also available.

Development

python -m pip install -e .
python -m unittest discover -s tests -v
python -m cortexfault analyze examples/precise-bus-fault.log

See CONTRIBUTING.md for adding parsers, fault definitions, or sample dumps.

Roadmap

• Exception-frame and stack-range validation
• Zephyr and FreeRTOS log adapters
• SecureFault and TrustZone context
• Vendor memory-map/SVD annotations
• Call-stack recovery from captured stack words
• CI annotation output for hardware-in-the-loop test logs

License

MIT