cfsr-decoder 1.1.0__tar.gz

cfsr_decoder-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GaneshMba4066
+
+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.

cfsr_decoder-1.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: cfsr-decoder
+Version: 1.1.0
+Summary: Zero-dependency ARM Cortex-M fault status register decoder CLI
+Author-email: Trust & Thread <contact@trustandthread.com>
+Project-URL: Homepage, https://www.trustandthread.com
+Project-URL: Bug Tracker, https://github.com/GaneshMba4066/cfsr-decoder/issues
+Project-URL: Documentation, https://www.trustandthread.com/firmware-checklist/
+Keywords: arm,cortex-m,stm32,hardfault,firmware,debugging,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
+
+# cfsr-decoder
+
+A zero-dependency ARM Cortex-M fault status register decoder for embedded systems students, hobbyists, and firmware engineers.
+
+Whenever an STM32, RP2040, NXP, or SAM microcontroller locks up in an infinite `HardFault_Handler` loop, the CPU writes the failure cause into the ARM core registers (`CFSR`, `HFSR`, `BFAR`, `MMFAR`). 
+
+Decoding those bitmasks manually from the ARM Architecture Reference Manual is slow. `cfsr-decode` turns raw hex register dumps into clear, plain-English diagnostics and recovery steps.
+
+---
+
+## Quick Start (Zero Dependencies)
+
+Runs directly with standard Python 3.6+:
+
+```bash
+# General syntax
+python cfsr_decode.py <CFSR_HEX> [BFAR_HEX] [MMFAR_HEX] [HFSR_HEX]
+
+# Try a realistic unaligned access fault
+python cfsr_decode.py 0x00010200 0x20001FF7
+
+# View all built-in examples
+python cfsr_decode.py --example

cfsr_decoder-1.1.0/README.md

@@ -0,0 +1,23 @@
+# cfsr-decoder
+
+A zero-dependency ARM Cortex-M fault status register decoder for embedded systems students, hobbyists, and firmware engineers.
+
+Whenever an STM32, RP2040, NXP, or SAM microcontroller locks up in an infinite `HardFault_Handler` loop, the CPU writes the failure cause into the ARM core registers (`CFSR`, `HFSR`, `BFAR`, `MMFAR`). 
+
+Decoding those bitmasks manually from the ARM Architecture Reference Manual is slow. `cfsr-decode` turns raw hex register dumps into clear, plain-English diagnostics and recovery steps.
+
+---
+
+## Quick Start (Zero Dependencies)
+
+Runs directly with standard Python 3.6+:
+
+```bash
+# General syntax
+python cfsr_decode.py <CFSR_HEX> [BFAR_HEX] [MMFAR_HEX] [HFSR_HEX]
+
+# Try a realistic unaligned access fault
+python cfsr_decode.py 0x00010200 0x20001FF7
+
+# View all built-in examples
+python cfsr_decode.py --example

cfsr_decoder-1.1.0/cfsr_decode.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""
+cfsr-decode: ARM Cortex-M Fault Register Decoder (CFSR / HFSR / MMFAR / BFAR)
+Free & Open Source (MIT) by Trust & Thread — https://www.trustandthread.com
+
+Zero dependencies. Pure stdlib Python 3.6+. Run:
+    python3 cfsr_decode.py <CFSR_HEX> [BFAR_HEX] [MMFAR_HEX] [HFSR_HEX]
+    python3 cfsr_decode.py --example
+"""
+
+import sys
+
+VERSION = "1.1.0"
+SITE = "https://www.trustandthread.com"
+
+UFSR_BITS = [
+    (1 << 9, "DIVBYZERO", "Integer divide by zero executed (SDIV/UDIV).",
+     "Set CCR.DIV_0_TRP deliberately, or guard divisors before executing."),
+    (1 << 8, "UNALIGNED", "Unaligned memory access with alignment trapping enabled.",
+     "Unaligned LDM/STM/STRD/LDRD or CCR.UNALIGN_TRP triggered. Fix the pointer or the packed struct."),
+    (1 << 3, "NOCP", "Coprocessor access with CPACR disabled (classic: FPU used before it is enabled).",
+     "Enable FPU in CPACR before any float code runs — check startup code and ISRs that use float."),
+    (1 << 2, "INVPC", "Invalid PC load — integrity check failed on EXC_RETURN.",
+     "Corrupted exception stack frame or wrong EXC_RETURN value returned from an ISR."),
+    (1 << 1, "INVSTATE", "Attempted invalid instruction-set state (e.g. EPSR.T=0, ARM-mode branch).",
+     "Bad function pointer, corrupted link register, or branch to data. Check BL/BX targets."),
+    (1 << 0, "UNDEFINSTR", "Undefined instruction executed.",
+     "Usually PC ran into data or flash was read incorrectly (wrong clock/flash latency). Check the LR/PC."),
+]
+
+BFSR_BITS = [
+    (1 << 7, "BFARVALID", "BFAR holds the valid faulting address.",
+     "Inspect BFAR — it points at the exact offending access."),
+    (1 << 5, "LSPERR", "Bus fault during floating-point lazy state preservation.",
+     "Fault in FP stack frame push on exception entry. Check stack region validity."),
+    (1 << 4, "STKERR", "Bus fault on stacking for exception entry.",
+     "Stack pointer invalid or stack overflowed into unmapped memory."),
+    (1 << 3, "UNSTKERR", "Bus fault on unstacking for exception return.",
+     "Stack frame corrupted or SP altered before exception return."),
+    (1 << 2, "IMPRECISERR", "Imprecise data bus error (async, from write buffer).",
+     "The reported PC is NOT the faulting instruction. Enable write buffering flush or use precise mode to localize."),
+    (1 << 1, "PRECISERR", "Precise data bus error on a valid address.",
+     "BFAR is valid — the faulting instruction and address are both known."),
+    (1 << 0, "IBUSERR", "Instruction bus error during prefetch.",
+     "Branch into unmapped/non-executable memory. Check the branch target and linker script regions."),
+]
+
+MMFSR_BITS = [
+    (1 << 7, "MMARVALID", "MMFAR holds the valid faulting address.",
+     "Inspect MMFAR — it points at the exact offending access."),
+    (1 << 5, "MLSPERR", "MemManage fault during FP lazy state preservation.",
+     "MPU rejects stack frame push on exception entry. Check stack region MPU config."),
+    (1 << 4, "MSTKERR", "MemManage fault on stacking for exception entry.",
+     "MPU blocks exception stack push — classic MPU stack-overflow signature."),
+    (1 << 3, "MUNSTKERR", "MemManage fault on unstacking for exception return.",
+     "MPU blocks exception stack pop. Stack region changed while exception active."),
+    (1 << 1, "DACCVIOL", "Data access violation (MPU region or null-pointer dereference).",
+     "MMFAR shows the address. Address 0x0 usually means a NULL pointer was dereferenced."),
+    (1 << 0, "IACCVIOL", "Instruction access violation (execute-never region or bad branch).",
+     "Jumped into a non-executable MPU region. Check function pointers and XN attributes."),
+]
+
+HFSR_BITS = [
+    (1 << 30, "FORCED", "HardFault is an escalated configurable fault (configurable fault handler missing or itself faulted).",
+     "CFSR holds the real cause. A fault handler was missing, or the handler faulted again."),
+    (1 << 1,  "VECTTBL", "Fault on vector table read (bad VTOR or corrupted vector table).",
+     "Check VTOR value and that the vector table is in mapped, readable memory."),
+    (1 << 31, "DEBUGEVT", "HardFault triggered by debug event.",
+     "Only relevant under a debugger (DCFSR holds details)."),
+]
+
+def parse_hex(tok, name):
+    t = tok.strip().lower().replace("0x", "").replace("0X", "")
+    try:
+        return int(t, 16)
+    except ValueError:
+        sys.exit(f"error: {name} value '{tok}' is not valid hex")
+
+
+def banner(char="=", width=66):
+    return char * width
+
+
+def report(cfsr, bfar=None, mmfar=None, hfsr=None):
+    out = []
+    w = out.append
+    w(banner())
+    w(" TRUST & THREAD :: ARM CORTEX-M FAULT REGISTER DECODER v" + VERSION)
+    w(banner())
+    w(f" CFSR : 0x{cfsr:08X}")
+    if hfsr is not None:
+        w(f" HFSR : 0x{hfsr:08X}")
+    if mmfar is not None:
+        w(f" MMFAR: 0x{mmfar:08X}")
+    if bfar is not None:
+        w(f" BFAR : 0x{bfar:08X}")
+    w(banner("-"))
+
+    ufsr = (cfsr >> 16) & 0xFFFF
+    bfsr = (cfsr >> 8) & 0xFF
+    mmfsr = cfsr & 0xFF
+    found = 0
+
+    def section(title, val, table):
+        nonlocal found
+        if not val:
+            return
+        w(f"\n [!] {title} (0x{val:0{'4' if table is UFSR_BITS else '2'}X}):")
+        for mask, name, desc, fix in table:
+            if val & mask:
+                w(f"     * {name:<12} {desc}")
+                w(f"       {'':<12} -> {fix}")
+                found += 1
+
+    section("UsageFault", ufsr, UFSR_BITS)
+    section("BusFault", bfsr, BFSR_BITS)
+    section("MemManage Fault", mmfsr, MMFSR_BITS)
+
+    if hfsr is not None:
+        if hfsr & (1 << 30):
+            w("\n [!] HardFault: FORCED — escalated configurable fault (see CFSR above).")
+            found += 1
+        if hfsr & (1 << 1):
+            w("\n [!] HardFault: VECTTBL — vector table read fault (check VTOR).")
+            found += 1
+        if hfsr & (1 << 31):
+            w("\n [!] HardFault: DEBUGEVT — debug event escalated (debugger context).")
+            found += 1
+
+    if mmfsr & (1 << 7) and mmfar is not None:
+        tip = "NULL POINTER DEREFERENCE" if mmfar == 0 else "inspect this MPU region / linker map"
+        w(f"\n [>] MMFAR = 0x{mmfar:08X}  ({tip})")
+    if bfsr & (1 << 7) and bfar is not None:
+        region = classify_address(bfar)
+        w(f" [>] BFAR  = 0x{bfar:08X}  ({region})")
+
+    if found == 0:
+        w("\n [?] No standard bits set. If this is a HardFault, capture CFSR/HFSR at")
+        w("     the fault handler entry (See 'HardFault in handlers' in the checklist).")
+
+    w("\n" + banner())
+    w(" NEXT STEPS & REMEDIATION:")
+    w("  1. Free register-level crash checklist (5 min read):")
+    w(f"     --> {SITE}/firmware-checklist/")
+    w("  2. Production-grade C HardFault handlers + memory templates ($49):")
+    w(f"     --> {SITE}/toolkit/")
+    w("  3. Need this crash root-caused in 48 hours? Book engineering triage ($199):")
+    w(f"     --> {SITE}/consultation/")
+    w(banner() + "\n")
+    print("\n".join(out))
+    return 0 if found else 2
+
+
+def classify_address(addr):
+    if addr == 0:
+        return "NULL pointer"
+    if 0x00000000 <= addr < 0x20000000:
+        return "Code / flash region"
+    if 0x20000000 <= addr < 0x40000000:
+        return "SRAM region"
+    if 0x40000000 <= addr < 0x60000000:
+        return "Peripheral region (bit-band / APB / AHB)"
+    if 0xE0000000 <= addr < 0xE0100000:
+        return "Private peripheral bus (SCB/NVIC/sysctl)"
+    if 0x60000000 <= addr < 0xA0000000:
+        return "External RAM region"
+    return "Vendor-specific / external memory region"
+
+
+EXAMPLE = """
+ # Realistic example: unaligned access fault with known address
+ python cfsr_decode.py 0x00010200 0x20001FF7
+
+ # Null-pointer dereference caught by MPU (MemManage):
+ python cfsr_decode.py 0x00000082 0x00000000 0x00000000
+
+ # HardFault with FORCED set (escalated fault) + faulting address:
+ python cfsr_decode.py 0x00008200 0x40021000 -- 0x40000000
+"""
+
+
+def usage():
+    print(__doc__.strip())
+    print(EXAMPLE)
+
+
+def main():
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help"):
+        usage()
+        return 1
+    if args[0] == "--example":
+        print(EXAMPLE)
+        return 0
+    if args[0] in ("-v", "--version"):
+        print(f"cfsr-decode v{VERSION}")
+        return 0
+
+    vals = [a for a in args if a != "--"]
+    if len(vals) < 1 or len(vals) > 4:
+        usage()
+        return 1
+    cfsr = parse_hex(vals[0], "CFSR")
+    bfar = parse_hex(vals[1], "BFAR") if len(vals) > 1 else None
+    mmfar = parse_hex(vals[2], "MMFAR") if len(vals) > 2 else None
+    hfsr = parse_hex(vals[3], "HFSR") if len(vals) > 3 else None
+    return report(cfsr, bfar, mmfar, hfsr)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cfsr_decoder-1.1.0/cfsr_decoder.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: cfsr-decoder
+Version: 1.1.0
+Summary: Zero-dependency ARM Cortex-M fault status register decoder CLI
+Author-email: Trust & Thread <contact@trustandthread.com>
+Project-URL: Homepage, https://www.trustandthread.com
+Project-URL: Bug Tracker, https://github.com/GaneshMba4066/cfsr-decoder/issues
+Project-URL: Documentation, https://www.trustandthread.com/firmware-checklist/
+Keywords: arm,cortex-m,stm32,hardfault,firmware,debugging,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
+
+# cfsr-decoder
+
+A zero-dependency ARM Cortex-M fault status register decoder for embedded systems students, hobbyists, and firmware engineers.
+
+Whenever an STM32, RP2040, NXP, or SAM microcontroller locks up in an infinite `HardFault_Handler` loop, the CPU writes the failure cause into the ARM core registers (`CFSR`, `HFSR`, `BFAR`, `MMFAR`). 
+
+Decoding those bitmasks manually from the ARM Architecture Reference Manual is slow. `cfsr-decode` turns raw hex register dumps into clear, plain-English diagnostics and recovery steps.
+
+---
+
+## Quick Start (Zero Dependencies)
+
+Runs directly with standard Python 3.6+:
+
+```bash
+# General syntax
+python cfsr_decode.py <CFSR_HEX> [BFAR_HEX] [MMFAR_HEX] [HFSR_HEX]
+
+# Try a realistic unaligned access fault
+python cfsr_decode.py 0x00010200 0x20001FF7
+
+# View all built-in examples
+python cfsr_decode.py --example

cfsr_decoder-1.1.0/cfsr_decoder.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+cfsr_decode.py
+pyproject.toml
+cfsr_decoder.egg-info/PKG-INFO
+cfsr_decoder.egg-info/SOURCES.txt
+cfsr_decoder.egg-info/dependency_links.txt
+cfsr_decoder.egg-info/entry_points.txt
+cfsr_decoder.egg-info/top_level.txt

cfsr_decoder-1.1.0/cfsr_decoder.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cfsr_decoder-1.1.0/cfsr_decoder.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cfsr-decode = cfsr_decode:main

cfsr_decoder-1.1.0/cfsr_decoder.egg-info/top_level.txt

@@ -0,0 +1 @@
+cfsr_decode

cfsr_decoder-1.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cfsr-decoder"
+version = "1.1.0"
+authors = [
+  { name="Trust & Thread", email="contact@trustandthread.com" },
+]
+description = "Zero-dependency ARM Cortex-M fault status register decoder CLI"
+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", "cfsr"]
+
+[project.urls]
+"Homepage" = "https://www.trustandthread.com"
+"Bug Tracker" = "https://github.com/GaneshMba4066/cfsr-decoder/issues"
+"Documentation" = "https://www.trustandthread.com/firmware-checklist/"
+
+[project.scripts]
+cfsr-decode = "cfsr_decode:main"

cfsr_decoder-1.1.0/setup.cfg

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