cortex-crash 1.0.0__tar.gz

cortex_crash-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trust & Thread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cortex_crash-1.0.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: cortex-crash
+Version: 1.0.0
+Summary: All-in-one ARM Cortex-M HardFault triage suite (CFSR decoder, stack unwinder, C handlers)
+Author-email: Trust & Thread <contact@trustandthread.com>
+Project-URL: Homepage, https://www.trustandthread.com
+Project-URL: Bug Tracker, https://github.com/GaneshMba4066/cortex-crash/issues
+Project-URL: Documentation, https://www.trustandthread.com/firmware-checklist/
+Keywords: arm,cortex-m,stm32,hardfault,firmware,debugging,unwind,cfsr
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cortex-crash
+
+All-in-one ARM Cortex-M HardFault triage suite: decode CFSR status registers, unwind hardware-stacked frames with `addr2line`, and generate drop-in C/ASM fault capture stubs.
+
+## Installation
+
+pip install cortex-crash
+
+## Usage
+
+# Print drop-in naked C/ASM HardFault handler
+cortex-crash init-c
+
+# Decode fault registers
+cortex-crash cfsr 0x00010200 0x20001FF7
+
+# Unwind 8-word stack frame and resolve line from ELF
+cortex-crash unwind 0x0 0x1 0x20000000 0x40021000 0x0 0x08001255 0x08001290 0x21000000 app.elf
+
+# Unified triage
+cortex-crash parse --cfsr 0x00010200 --bfar 0x20001FF7 --frame 0x0 0x1 0x20000000 0x40021000 0x0 0x08001255 0x08001290 0x21000000
+
+## License
+
+MIT — Trust & Thread

cortex_crash-1.0.0/README.md

@@ -0,0 +1,25 @@
+# cortex-crash
+
+All-in-one ARM Cortex-M HardFault triage suite: decode CFSR status registers, unwind hardware-stacked frames with `addr2line`, and generate drop-in C/ASM fault capture stubs.
+
+## Installation
+
+pip install cortex-crash
+
+## Usage
+
+# Print drop-in naked C/ASM HardFault handler
+cortex-crash init-c
+
+# Decode fault registers
+cortex-crash cfsr 0x00010200 0x20001FF7
+
+# Unwind 8-word stack frame and resolve line from ELF
+cortex-crash unwind 0x0 0x1 0x20000000 0x40021000 0x0 0x08001255 0x08001290 0x21000000 app.elf
+
+# Unified triage
+cortex-crash parse --cfsr 0x00010200 --bfar 0x20001FF7 --frame 0x0 0x1 0x20000000 0x40021000 0x0 0x08001255 0x08001290 0x21000000
+
+## License
+
+MIT — Trust & Thread

cortex_crash-1.0.0/cortex_crash/__init__.py

@@ -0,0 +1,2 @@
+"""cortex-crash: Unified ARM Cortex-M HardFault triage suite."""
+__version__ = "1.0.0"

cortex_crash-1.0.0/cortex_crash/cfsr.py

@@ -0,0 +1,59 @@
+"""CFSR and fault status register decoder logic."""
+
+FAULT_STATUS_BITS = {
+    "DIVBYZERO":   (1 << 25, "UsageFault", "Divide by zero executed (CCR.DIV_0_TRP enabled)."),
+    "UNALIGNED":   (1 << 24, "UsageFault", "Unaligned memory access performed (CCR.UNALIGN_TRP enabled)."),
+    "NOCP":        (1 << 19, "UsageFault", "Attempted coprocessor access without enable (e.g. FPU CPACR)."),
+    "INVPC":       (1 << 18, "UsageFault", "Invalid PC load on EXC_RETURN or illegal integrity check."),
+    "INVSTATE":    (1 << 17, "UsageFault", "Attempted execution in invalid EPSR state (e.g. Thumb bit cleared)."),
+    "UNDEFINSTR":  (1 << 16, "UsageFault", "Undefined instruction encountered."),
+    "BFARVALID":   (1 << 15, "BusFault",   "BFAR address holds the valid faulting location."),
+    "LSPERR":      (1 << 13, "BusFault",   "Bus fault occurred during lazy FP state preservation."),
+    "STKERR":      (1 << 12, "BusFault",   "Bus fault on exception entry stacking."),
+    "UNSTKERR":    (1 << 11, "BusFault",   "Bus fault on exception exit unstacking."),
+    "IMPRECISERR": (1 << 10, "BusFault",   "Imprecise data bus error (asynchronous)."),
+    "PRECISERR":   (1 << 9,  "BusFault",   "Precise data bus error on valid address."),
+    "IBUSERR":     (1 << 8,  "BusFault",   "Instruction bus error during prefetch."),
+    "MMARVALID":   (1 << 7,  "MemManage",  "MMFAR holds valid address of memory management fault."),
+    "MLSPERR":     (1 << 5,  "MemManage",  "MemManage fault during lazy FP preservation."),
+    "MSTKERR":     (1 << 4,  "MemManage",  "MemManage fault during exception entry stacking."),
+    "MUNSTKERR":   (1 << 3,  "MemManage",  "MemManage fault during exception exit unstacking."),
+    "DACCVIOL":    (1 << 1,  "MemManage",  "Data access violation (MPU protection or NULL pointer dereference)."),
+    "IACCVIOL":    (1 << 0,  "MemManage",  "Instruction access violation (MPU XN region or unmapped memory)."),
+}
+
+
+def classify_address(addr):
+    if 0x00000000 <= addr < 0x20000000:
+        return "Flash / Code Memory"
+    if 0x20000000 <= addr < 0x40000000:
+        return "SRAM"
+    if 0x40000000 <= addr < 0x60000000:
+        return "Peripheral Bus"
+    if 0x60000000 <= addr < 0xA0000000:
+        return "External RAM / Memory"
+    if 0xE0000000 <= addr <= 0xFFFFFFFF:
+        return "Private Peripheral Bus (PPB / System Control)"
+    return "Reserved / Undefined Region"
+
+
+def decode_cfsr(cfsr, bfar=None, mmfar=None):
+    lines = [f"CFSR: 0x{cfsr:08X}"]
+    active = []
+    for bit_name, (mask, fault_type, desc) in FAULT_STATUS_BITS.items():
+        if cfsr & mask:
+            active.append((fault_type, bit_name, desc))
+
+    if not active:
+        lines.append("  No standard CFSR fault flags set.")
+    else:
+        for fault_type, bit_name, desc in active:
+            lines.append(f"  [{fault_type}] {bit_name:<11} : {desc}")
+
+    if bfar is not None and (cfsr & (1 << 15)):
+        lines.append(f"\n  BFAR:  0x{bfar:08X} ({classify_address(bfar)})")
+
+    if mmfar is not None and (cfsr & (1 << 7)):
+        lines.append(f"\n  MMFAR: 0x{mmfar:08X} ({classify_address(mmfar)})")
+
+    return lines

cortex_crash-1.0.0/cortex_crash/cli.py

@@ -0,0 +1,88 @@
+"""Main entry point for unified CLI."""
+
+import argparse
+import sys
+from .cfsr import decode_cfsr
+from .unwind import decode_frame
+from .snippet import print_snippet
+
+VERSION = "1.0.0"
+
+
+def parse_hex(val):
+    return int(val.strip().lower().replace("0x", "").replace(",", ""), 16)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="cortex-crash",
+        description="Unified ARM Cortex-M Crash Diagnostics Suite by Trust & Thread"
+    )
+    parser.add_argument("-v", "--version", action="version", version=f"cortex-crash v{VERSION}")
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Command: parse
+    p_parse = subparsers.add_parser("parse", help="Decode registers and unwound stack frame")
+    p_parse.add_argument("--cfsr", type=str, help="CFSR hex value (e.g. 0x00010200)")
+    p_parse.add_argument("--bfar", type=str, help="BFAR hex value")
+    p_parse.add_argument("--mmfar", type=str, help="MMFAR hex value")
+    p_parse.add_argument("--frame", nargs=8, help="8 stacked registers: r0 r1 r2 r3 r12 lr pc xpsr")
+    p_parse.add_argument("elf", nargs="?", help="Optional .elf file to resolve symbols")
+
+    # Command: cfsr
+    p_cfsr = subparsers.add_parser("cfsr", help="Quickly decode CFSR hex")
+    p_cfsr.add_argument("cfsr", type=str, help="CFSR register hex value")
+    p_cfsr.add_argument("bfar", nargs="?", type=str, help="Optional BFAR address")
+
+    # Command: unwind
+    p_unwind = subparsers.add_parser("unwind", help="Quickly unwind stack frame")
+    p_unwind.add_argument("regs", nargs=8, help="8 stacked registers: r0 r1 r2 r3 r12 lr pc xpsr")
+    p_unwind.add_argument("elf", nargs="?", help="Optional .elf file")
+
+    # Command: init-c
+    subparsers.add_parser("init-c", help="Print drop-in C/ASM HardFault handler source")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    print("=" * 66)
+    print(f" TRUST & THREAD :: CORTEX-M CRASH ANALYZER v{VERSION}")
+    print("=" * 66)
+
+    if args.command == "init-c":
+        print_snippet()
+        return 0
+
+    if args.command == "cfsr":
+        cfsr_val = parse_hex(args.cfsr)
+        bfar_val = parse_hex(args.bfar) if args.bfar else None
+        print("\n".join(decode_cfsr(cfsr_val, bfar_val)))
+
+    elif args.command == "unwind":
+        frame_vals = [parse_hex(x) for x in args.regs]
+        print("\n".join(decode_frame(frame_vals, args.elf)))
+
+    elif args.command == "parse":
+        if args.cfsr:
+            cfsr_val = parse_hex(args.cfsr)
+            bfar_val = parse_hex(args.bfar) if args.bfar else None
+            mmfar_val = parse_hex(args.mmfar) if args.mmfar else None
+            print("\n[Fault Registers]")
+            print("\n".join(decode_cfsr(cfsr_val, bfar_val, mmfar_val)))
+        if args.frame:
+            frame_vals = [parse_hex(x) for x in args.frame]
+            print("\n[Stack Frame]")
+            print("\n".join(decode_frame(frame_vals, args.elf)))
+
+    print("\n" + "=" * 66)
+    print(" Free Firmware Checklist: https://www.trustandthread.com/firmware-checklist/")
+    print("=" * 66)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cortex_crash-1.0.0/cortex_crash/snippet.py

@@ -0,0 +1,44 @@
+"""Embedded C/assembly snippet generator."""
+
+C_STUB = r"""/* Drop-in HardFault Handler for ARM Cortex-M (Trust & Thread) */
+#include <stdint.h>
+#include <stdio.h>
+
+#define SCB_CFSR  (*(volatile uint32_t *)0xE000ED28)
+#define SCB_BFAR  (*(volatile uint32_t *)0xE000ED38)
+
+typedef struct __attribute__((packed)) {
+    uint32_t r0, r1, r2, r3, r12, lr, pc, xpsr;
+} StackFrame_t;
+
+void HardFault_Handler_C(StackFrame_t *frame, uint32_t lr_val) {
+    uint32_t cfsr = SCB_CFSR;
+    uint32_t bfar = SCB_BFAR;
+    printf("\r\n--- CORTEX-M CRASH DUMP ---\r\n");
+    printf("CFSR: 0x%08lX | BFAR: 0x%08lX\r\n", cfsr, bfar);
+    printf("STACK: 0x%08lX 0x%08lX 0x%08lX 0x%08lX 0x%08lX 0x%08lX 0x%08lX 0x%08lX\r\n",
+           frame->r0, frame->r1, frame->r2, frame->r3,
+           frame->r12, frame->lr, frame->pc, frame->xpsr);
+    printf("RUN COMMAND:\r\n");
+    printf("cortex-crash parse --cfsr 0x%08lX --bfar 0x%08lX --frame 0x%08lX 0x%08lX 0x%08lX 0x%08lX 0x%08lX 0x%08lX 0x%08lX 0x%08lX app.elf\r\n",
+           cfsr, bfar, frame->r0, frame->r1, frame->r2, frame->r3,
+           frame->r12, frame->lr, frame->pc, frame->xpsr);
+    __asm volatile("bkpt #1");
+    while (1);
+}
+
+__attribute__((naked)) void HardFault_Handler(void) {
+    __asm volatile(
+        "tst lr, #4       \n"
+        "ite eq           \n"
+        "mrseq r0, msp    \n"
+        "mrsne r0, psp    \n"
+        "mov r1, lr       \n"
+        "b HardFault_Handler_C\n"
+    );
+}
+"""
+
+
+def print_snippet():
+    print(C_STUB)

cortex_crash-1.0.0/cortex_crash/unwind.py

@@ -0,0 +1,111 @@
+"""Stack unwinder and symbol resolution logic."""
+
+import shutil
+import subprocess
+
+FRAME_REGS = ["r0", "r1", "r2", "r3", "r12", "lr", "pc", "xpsr"]
+
+EXC_RETURN_KIND = {
+    0x01: ("Handler mode, MSP, no FP", False),
+    0x09: ("Thread mode, MSP, no FP", False),
+    0x0D: ("Thread mode, PSP, no FP", False),
+    0x11: ("Handler mode, MSP, FP extended frame", True),
+    0x19: ("Thread mode, MSP, FP extended frame", True),
+    0x1D: ("Thread mode, PSP, FP extended frame", True),
+}
+
+
+def pick_addr2line():
+    for t in ("arm-none-eabi-addr2line", "addr2line"):
+        if shutil.which(t):
+            return t
+    return None
+
+
+def addr2line(tool, elf, addr):
+    if not tool or not elf:
+        return None
+    try:
+        r = subprocess.run([tool, "-f", "-C", "-e", elf, f"0x{addr:08X}"],
+                           capture_output=True, text=True, timeout=10)
+        lines = [l.strip() for l in r.stdout.strip().splitlines() if l.strip()]
+        if len(lines) >= 2 and "??" not in lines[0]:
+            return lines[0], lines[1]
+    except Exception:
+        pass
+    return None
+
+
+def decode_xpsr(xpsr):
+    lines = []
+    ipsr = xpsr & 0x1FF
+    lines.append(f"IPSR = {ipsr}")
+    if ipsr == 0:
+        lines.append("  Active execution mode: Thread Mode")
+    elif ipsr == 2:
+        lines.append("  Active exception: NMI")
+    elif ipsr == 3:
+        lines.append("  Active exception: HardFault")
+    elif ipsr == 4:
+        lines.append("  Active exception: MemManage")
+    elif ipsr == 5:
+        lines.append("  Active exception: BusFault")
+    elif ipsr == 6:
+        lines.append("  Active exception: UsageFault")
+    elif 16 <= ipsr < 256:
+        lines.append(f"  Active interrupt: IRQ{ipsr - 16}")
+
+    if xpsr & (1 << 24):
+        lines.append("  Thumb bit set (EPSR.T=1) — valid execution state")
+    else:
+        lines.append("  [!] Thumb bit CLEAR (EPSR.T=0) — invalid state / corrupt branch target")
+    return lines
+
+
+def decode_frame(frame, elf=None):
+    tool = pick_addr2line()
+    lines = []
+    lines.append(f" {'Reg':<6} {'Value':<12} Notes")
+    lines.append("-" * 40)
+    lr_val = frame[5]
+    exc_return = (lr_val & 0xFFFFFFF0) == 0xFFFFFFF0
+    for name, val in zip(FRAME_REGS, frame):
+        if name == "lr" and exc_return:
+            note = "(EXC_RETURN)"
+        elif name in ("pc", "lr") and (val & 1):
+            note = "(Thumb bit set)"
+        else:
+            note = ""
+        lines.append(f" {name:<6} 0x{val:08X} {note}")
+    lines.append("-" * 40)
+
+    lines.append("\n[Execution State]")
+    for l in decode_xpsr(frame[7]):
+        lines.append("  " + l)
+
+    if exc_return:
+        n = lr_val & 0x1F
+        desc, fp = EXC_RETURN_KIND.get(n, (f"Variant 0x{lr_val & 0xFF:X}", not bool(lr_val & (1 << 4))))
+        lines.append(f"\n[EXC_RETURN] 0x{lr_val:08X} ({desc})")
+        if fp:
+            lines.append("  Extended frame: 26 words stacked (includes FP registers).")
+        else:
+            lines.append("  Basic frame: 8 words stacked.")
+
+    pc = frame[6] & ~1
+    lines.append("\n[Crash Site]")
+    lines.append(f"  PC: 0x{pc:08X}")
+    res_pc = addr2line(tool, elf, pc)
+    if res_pc:
+        lines.append(f"      -> {res_pc[0]} at {res_pc[1]}")
+
+    if not exc_return:
+        lr = lr_val & ~1
+        lines.append(f"  LR: 0x{lr:08X}")
+        res_lr = addr2line(tool, elf, lr)
+        if res_lr:
+            lines.append(f"      -> {res_lr[0]} at {res_lr[1]}")
+
+    if elf and not tool:
+        lines.append("\n  [!] arm-none-eabi-addr2line not found in PATH.")
+    return lines

cortex_crash-1.0.0/cortex_crash.egg-info/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: cortex-crash
+Version: 1.0.0
+Summary: All-in-one ARM Cortex-M HardFault triage suite (CFSR decoder, stack unwinder, C handlers)
+Author-email: Trust & Thread <contact@trustandthread.com>
+Project-URL: Homepage, https://www.trustandthread.com
+Project-URL: Bug Tracker, https://github.com/GaneshMba4066/cortex-crash/issues
+Project-URL: Documentation, https://www.trustandthread.com/firmware-checklist/
+Keywords: arm,cortex-m,stm32,hardfault,firmware,debugging,unwind,cfsr
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# cortex-crash
+
+All-in-one ARM Cortex-M HardFault triage suite: decode CFSR status registers, unwind hardware-stacked frames with `addr2line`, and generate drop-in C/ASM fault capture stubs.
+
+## Installation
+
+pip install cortex-crash
+
+## Usage
+
+# Print drop-in naked C/ASM HardFault handler
+cortex-crash init-c
+
+# Decode fault registers
+cortex-crash cfsr 0x00010200 0x20001FF7
+
+# Unwind 8-word stack frame and resolve line from ELF
+cortex-crash unwind 0x0 0x1 0x20000000 0x40021000 0x0 0x08001255 0x08001290 0x21000000 app.elf
+
+# Unified triage
+cortex-crash parse --cfsr 0x00010200 --bfar 0x20001FF7 --frame 0x0 0x1 0x20000000 0x40021000 0x0 0x08001255 0x08001290 0x21000000
+
+## License
+
+MIT — Trust & Thread

cortex_crash-1.0.0/cortex_crash.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+cortex_crash/__init__.py
+cortex_crash/cfsr.py
+cortex_crash/cli.py
+cortex_crash/snippet.py
+cortex_crash/unwind.py
+cortex_crash.egg-info/PKG-INFO
+cortex_crash.egg-info/SOURCES.txt
+cortex_crash.egg-info/dependency_links.txt
+cortex_crash.egg-info/entry_points.txt
+cortex_crash.egg-info/top_level.txt

cortex_crash-1.0.0/cortex_crash.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cortex_crash-1.0.0/cortex_crash.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cortex-crash = cortex_crash.cli:main

cortex_crash-1.0.0/cortex_crash.egg-info/top_level.txt

@@ -0,0 +1 @@
+cortex_crash

cortex_crash-1.0.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cortex-crash"
+version = "1.0.0"
+authors = [
+  { name="Trust & Thread", email="contact@trustandthread.com" },
+]
+description = "All-in-one ARM Cortex-M HardFault triage suite (CFSR decoder, stack unwinder, C handlers)"
+readme = "README.md"
+requires-python = ">=3.6"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Embedded Systems",
+]
+keywords = ["arm", "cortex-m", "stm32", "hardfault", "firmware", "debugging", "unwind", "cfsr"]
+
+[tool.setuptools]
+packages = ["cortex_crash"]
+
+[project.urls]
+"Homepage" = "https://www.trustandthread.com"
+"Bug Tracker" = "https://github.com/GaneshMba4066/cortex-crash/issues"
+"Documentation" = "https://www.trustandthread.com/firmware-checklist/"
+
+[project.scripts]
+cortex-crash = "cortex_crash.cli:main"

cortex_crash-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+