Metadata-Version: 2.4
Name: cortex-unwind
Version: 1.1.0
Summary: ARM Cortex-M HardFault stack frame unwinder and address mapper CLI
Author-email: Trust & Thread <contact@trustandthread.com>
License: MIT
Project-URL: Homepage, https://www.trustandthread.com
Project-URL: Bug Tracker, https://github.com/GaneshMba4066/cortex-unwind/issues
Project-URL: Documentation, https://www.trustandthread.com/firmware-checklist/
Keywords: arm,cortex-m,stm32,hardfault,stack,unwinder,debugging
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Dynamic: license-file

\# cortex-unwind



Zero-dependency CLI tool to decode ARM Cortex-M hardware stack frames and map

crash sites to source lines via `arm-none-eabi-addr2line`.



When a Cortex-M core takes a HardFault, hardware stacks 8 registers

(`r0..r3, r12, lr, pc, xPSR`) onto the active stack. Paste those 8 words from a

UART fault log or GDB (`x/8wx $sp`) and this tool gives you the crash site.



Free \& Open Source (MIT) by \[Trust \& Thread](https://www.trustandthread.com).



\## Installation



pip install cortex-unwind



Or run with zero install:



curl -sL https://raw.githubusercontent.com/GaneshMba4066/cortex-unwind/main/cortex\_unwind.py | python3



\## Quick Start



Pass the 8 hardware-stacked registers (`R0` `R1` `R2` `R3` `R12` `LR` `PC` `xPSR`):



cortex-unwind 0x0 0x1 0x20000000 0x40021000 0x0 0x08001255 0x08001290 0x21000000



With an ELF file for instant symbol resolution of PC and LR:



cortex-unwind 0x0 0x1 0x20000000 0x40021000 0x0 0x08001255 0x08001290 0x21000000 build/firmware.elf



Got a raw hex dump from UART? Let `--auto` find the frame for you:



cortex-unwind --auto "0x00 0x01 0x20000000 0x40021000 0x00 0x08001255 0x08001290 0x21000000"



\## What you get



\- Stacked register breakdown with Thumb-bit notes on PC/LR

\- Execution state: IPSR → active exception (HardFault, NMI, IRQn...), APSR flags

\- Thumb-bit validation (clear T-bit = corrupt PC, flagged immediately)

\- `EXC\_RETURN` decoding of LR — MSP/PSP selection and basic (8-word) vs FP-extended (26-word) frame detection, per ARMv7-M/ARMv8-M bit 4 encoding

\- `PC` and `LR` mapped to `function @ file:line` when an ELF and `arm-none-eabi-addr2line` are available

\- EXC\_RETURN LRs are never symbolized (they aren't addresses — no misleading output)



\## Requirements



\- Python 3.6+, zero pip dependencies

\- Optional: `arm-none-eabi-addr2line` (GNU Arm Embedded toolchain) + an unstripped `.elf` for source mapping



\## Companion tools



\- \[`cfsr-decode`](https://github.com/GaneshMba4066/cfsr-decode) — decode the CFSR/HFSR fault \*cause\*

\- `cortex-unwind` (this tool) — decode the crash \*location\*

\- \[Production Toolkit ($49)](https://www.trustandthread.com/toolkit/) — drop-in C HardFault handlers + runtime crash logging

\- \[Firmware Crash Checklist (free)](https://www.trustandthread.com/firmware-checklist/)



\## License



MIT — Trust \& Thread

