Add firmware overview tool for quick structural analysis

tools/firmware_overview.py analyzes PM binaries and reports:
- Memory map (empty / DSP kernel / control flow / code+data)
- Entry point detection
- All DO UNTIL loops with MAC operation count
- All immediate constants with register names and addresses
- I/O operations with ADSP-2191 peripheral register names
- Optional DM cross-reference (I-reg targets)
- Summary statistics

Includes ADSP-2191 I/O register name table for SPORT, SPI,
UART, Timer, GPIO, DMA, System Controller, and Interrupts.

tools/firmware_overview.py

@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+"""firmware_overview.py -- Quick structural overview of ADSP-219x firmware.
+
+Analyzes a PM binary and produces a human-readable report:
+  - Memory map (code vs data vs empty regions)
+  - Function-like blocks (code between RTS/JUMP boundaries)
+  - DSP kernels (DO UNTIL loops with MAC operations)
+  - I/O configuration (peripheral register writes)
+  - All immediate constants loaded into registers
+  - Cross-reference: which addresses are referenced
+
+Usage:
+    python3 firmware_overview.py firmware_pm.bin
+    python3 firmware_overview.py firmware_pm.bin --dm firmware_dm.bin
+"""
+
+import argparse
+import os
+import struct
+import sys
+
+
+# ADSP-2191 I/O register names (partial, most common)
+IO_NAMES = {
+    0x00: "SYSCTRL", 0x01: "SYSTAT", 0x02: "IOPG",
+    0x04: "BWCTRL", 0x05: "BWSTAT",
+    0x10: "PICR0", 0x11: "PICR1", 0x12: "PICR2", 0x13: "PICR3",
+    0x14: "IMASK0", 0x15: "IMASK1",
+    0x20: "TCTL", 0x21: "TCOUNT", 0x22: "TPERIOD", 0x23: "TSCALE",
+    0x40: "SPORT0_CTL", 0x41: "SPORT0_DIV",
+    0x42: "SPORT0_MCTL", 0x43: "SPORT0_CS0",
+    0x44: "SPORT0_TX", 0x45: "SPORT0_RX",
+    0x46: "SPORT0_STAT",
+    0x60: "SPORT1_CTL", 0x61: "SPORT1_DIV",
+    0x62: "SPORT1_MCTL", 0x63: "SPORT1_CS0",
+    0x64: "SPORT1_TX", 0x65: "SPORT1_RX",
+    0x66: "SPORT1_STAT",
+    0x80: "SPICTL", 0x81: "SPISTAT", 0x82: "SPIFLG",
+    0x83: "SPIBAUD", 0x84: "SPIRX", 0x85: "SPITX",
+    0xA0: "UART_TX", 0xA1: "UART_RX", 0xA2: "UART_CTL",
+    0xA3: "UART_STAT", 0xA4: "UART_DIV",
+    0xC0: "FLAGD", 0xC1: "FLAGP", 0xC2: "FLAGS",
+    0xC3: "FLAGC",
+}
+
+REG0 = ["AX0", "AX1", "MX0", "MX1", "AY0", "AY1", "MY0", "MY1",
+        "MR2", "SR2", "AR", "SI", "MR1", "SR1", "MR0", "SR0"]
+REG1 = ["I0", "I1", "I2", "I3", "M0", "M1", "M2", "M3",
+        "L0", "L1", "L2", "L3", "IMASK", "IRPTL", "ICNTL", "STACKA"]
+REG2 = ["I4", "I5", "I6", "I7", "M4", "M5", "M6", "M7",
+        "L4", "L5", "L6", "L7", "RES", "RES", "CNTR", "LPSTACKA"]
+
+
+def read_pm(path):
+    """Read 24-bit PM words from packed binary."""
+    data = open(path, "rb").read()
+    words = []
+    for i in range(0, len(data) - 2, 3):
+        w = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2]
+        words.append(w)
+    return words
+
+
+def classify_word(w):
+    """Return a rough classification of a PM word."""
+    if w == 0:
+        return "null"
+    b23_22 = (w >> 22) & 3
+    if b23_22 == 3:
+        return "compute_multi"  # Type 1
+    b23_16 = (w >> 16) & 0xFF
+    if b23_16 == 0x0A:
+        return "rts"
+    if (w >> 18) == 0x07:
+        return "jump"
+    if (w >> 19) == 0x03:
+        return "jump_cond"
+    if b23_16 == 0x16:
+        return "do_until"
+    if b23_16 == 0x0B:
+        return "jump_indirect"
+    if b23_16 == 0x05:
+        return "ljump"
+    return "code"
+
+
+def find_constants(words):
+    """Extract all immediate constant loads."""
+    constants = []
+    for i, w in enumerate(words):
+        addr = i * 3
+        b23_22 = (w >> 22) & 3
+        b21_20 = (w >> 20) & 3
+
+        # Type 6: Dreg = Imm16
+        if b23_22 == 1 and b21_20 == 0:
+            val = (w >> 4) & 0xFFFF
+            reg = REG0[w & 0xF]
+            constants.append((addr, reg, val, "dreg"))
+
+        # Type 7 REG1: Reg1 = Imm16
+        elif b23_22 == 1 and b21_20 == 1:
+            val = (w >> 4) & 0xFFFF
+            reg = REG1[w & 0xF]
+            constants.append((addr, reg, val, "reg1"))
+
+        # Type 7 REG2: Reg2 = Imm16
+        elif b23_22 == 0 and b21_20 == 3:
+            val = (w >> 4) & 0xFFFF
+            reg = REG2[w & 0xF]
+            constants.append((addr, reg, val, "reg2"))
+
+        # Type 33: Reg3 = Data12
+        elif (w >> 16) == 0x10:
+            val = (w >> 4) & 0xFFF
+            constants.append((addr, "REG3", val, "short"))
+
+        # Type 34: IO write
+        if (w >> 16) == 0x06 and ((w >> 15) & 1):
+            d = (w >> 12) & 1
+            io_addr = (((w >> 13) & 3) << 8) | ((w >> 4) & 0xFF)
+            dreg = REG0[w & 0xF]
+            io_name = IO_NAMES.get(io_addr, f"IO_0x{io_addr:03X}")
+            if d:
+                constants.append((addr, io_name, None,
+                                  f"io_write({dreg})"))
+            else:
+                constants.append((addr, dreg, None,
+                                  f"io_read({io_name})"))
+
+    return constants
+
+
+def find_do_loops(words):
+    """Find DO UNTIL loops and their bodies."""
+    loops = []
+    for i, w in enumerate(words):
+        if (w >> 16) == 0x16:
+            rel = (w >> 4) & 0xFFF
+            term = w & 0xF
+            cond = ["EQ", "NE", "GT", "LE", "LT", "GE",
+                    "AV", "NOT AV", "AC", "NOT AC",
+                    "SWCOND", "NOT SWCOND", "MV", "NOT MV",
+                    "NOT CE", "TRUE"][term]
+            srel = rel if rel < 0x800 else rel - 0x1000
+            target = i * 3 + srel * 3
+            # Count MAC ops in loop body
+            mac_count = 0
+            for j in range(i + 1, min(i + srel + 1, len(words))):
+                if (words[j] >> 22) & 3 == 3:  # Type 1
+                    amf = (words[j] >> 13) & 0x1F
+                    if amf < 16:  # MAC operation
+                        mac_count += 1
+            loops.append((i * 3, target, cond, srel, mac_count))
+    return loops
+
+
+def memory_map(words, chunk_size=64):
+    """Build a coarse memory map."""
+    regions = []
+    i = 0
+    while i < len(words):
+        end = min(i + chunk_size, len(words))
+        chunk = words[i:end]
+        n_null = sum(1 for w in chunk if w == 0)
+        n_multi = sum(1 for w in chunk
+                      if (w >> 22) & 3 == 3)
+        n_jump = sum(1 for w in chunk
+                     if classify_word(w) in
+                     ("jump", "jump_cond", "rts", "do_until"))
+
+        if n_null > len(chunk) * 0.9:
+            kind = "empty"
+        elif n_multi > len(chunk) * 0.3:
+            kind = "dsp_kernel"
+        elif n_jump > len(chunk) * 0.1:
+            kind = "control_flow"
+        else:
+            kind = "code/data"
+
+        if regions and regions[-1][2] == kind:
+            regions[-1] = (regions[-1][0], end * 3, kind)
+        else:
+            regions.append((i * 3, end * 3, kind))
+        i = end
+    return regions
+
+
+def analyze_pm(path, dm_path=None):
+    """Full PM analysis."""
+    words = read_pm(path)
+    size = len(words) * 3
+
+    print(f"=== PM Firmware Overview ===")
+    print(f"File: {path}")
+    print(f"Size: {size} bytes ({len(words)} instructions)")
+    print()
+
+    # Memory map
+    regions = memory_map(words)
+    print(f"--- Memory Map ---")
+    for start, end, kind in regions:
+        label = {"empty": "EMPTY (null)",
+                 "dsp_kernel": "DSP KERNEL (MAC-heavy)",
+                 "control_flow": "CONTROL FLOW (jumps)",
+                 "code/data": "CODE / DATA"}[kind]
+        print(f"  0x{start:06X}-0x{end:06X}"
+              f"  ({(end-start)//3:4d} words)  {label}")
+    print()
+
+    # Entry point
+    if words:
+        w0 = words[0]
+        if (w0 >> 18) == 0x07:
+            rel = ((w0 >> 4) & 0x3FFF) | ((w0 & 3) << 14)
+            srel = rel if rel < 0x8000 else rel - 0x10000
+            target = srel * 3
+            print(f"--- Entry Point ---")
+            print(f"  Reset vector: JUMP 0x{target:06X}")
+            print()
+        elif w0 == 0:
+            print(f"--- Entry Point ---")
+            print(f"  Reset vector: NOP (code starts at 0x000003)")
+            print()
+
+    # DO UNTIL loops (DSP kernels)
+    loops = find_do_loops(words)
+    if loops:
+        print(f"--- DSP Loops ({len(loops)} found) ---")
+        for addr, end, cond, length, macs in loops:
+            kind = ""
+            if macs > 0:
+                kind = f" [MAC kernel, {macs} multiply-accumulate ops]"
+            elif cond == "NOT CE":
+                kind = " [counter loop]"
+            print(f"  0x{addr:06X}: DO 0x{end:06X} UNTIL {cond}"
+                  f" ({length} words){kind}")
+        print()
+
+    # Constants
+    constants = find_constants(words)
+    if constants:
+        # Group by type
+        reg_loads = [(a, r, v, t) for a, r, v, t in constants
+                     if t in ("dreg", "reg1", "reg2", "short")]
+        io_ops = [(a, r, v, t) for a, r, v, t in constants
+                  if t.startswith("io_")]
+
+        if reg_loads:
+            print(f"--- Constants ({len(reg_loads)} register loads) ---")
+            # Show unique values
+            seen = {}
+            for addr, reg, val, _ in reg_loads:
+                key = (reg, val)
+                if key not in seen:
+                    seen[key] = []
+                seen[key].append(addr)
+
+            for (reg, val), addrs in sorted(seen.items(),
+                                            key=lambda x: x[0][1]):
+                sval = val - 0x10000 if val >= 0x8000 else val
+                locs = ", ".join(f"0x{a:06X}" for a in addrs[:3])
+                more = f" +{len(addrs)-3} more" if len(addrs) > 3 else ""
+                print(f"  {reg:8s} = 0x{val:04X}"
+                      f" ({sval:6d})  @ {locs}{more}")
+            print()
+
+        if io_ops:
+            print(f"--- I/O Operations ({len(io_ops)} found) ---")
+            for addr, reg, _, typ in io_ops:
+                print(f"  0x{addr:06X}: {typ}")
+            print()
+
+    # DM analysis if provided
+    if dm_path and os.path.isfile(dm_path):
+        print(f"--- DM Cross-Reference ---")
+        dm_data = open(dm_path, "rb").read()
+        dm_size = len(dm_data)
+        print(f"  DM file: {dm_path} ({dm_size} bytes,"
+              f" {dm_size//2} words)")
+
+        # Find all I-register loads and show what's at those
+        # DM addresses
+        for addr, reg, val, typ in constants:
+            if reg.startswith("I") and reg[1:].isdigit() \
+                    and typ in ("reg1", "reg2"):
+                dm_byte = val * 2
+                if dm_byte + 20 <= dm_size:
+                    sample = []
+                    for j in range(10):
+                        w = struct.unpack_from(
+                            ">H", dm_data, dm_byte + j * 2)[0]
+                        sample.append(f"0x{w:04X}")
+                    print(f"  {reg} = 0x{val:04X} -> DM content:"
+                          f" [{', '.join(sample[:5])} ...]")
+        print()
+
+    # Summary
+    n_code = sum(1 for w in words if w != 0)
+    n_mac = sum(1 for w in words if (w >> 22) & 3 == 3)
+    n_jump = sum(1 for w in words
+                 if classify_word(w) in
+                 ("jump", "jump_cond", "jump_indirect"))
+    n_rts = sum(1 for w in words
+                if classify_word(w) == "rts")
+
+    print(f"--- Summary ---")
+    print(f"  Total words:    {len(words)}")
+    print(f"  Non-zero:       {n_code}"
+          f" ({n_code*100//max(len(words),1)}%)")
+    print(f"  Multifunction:  {n_mac} (MAC/ALU + memory)")
+    print(f"  Jumps/Calls:    {n_jump}")
+    print(f"  Returns:        {n_rts}")
+    print(f"  DO loops:       {len(loops)}")
+    print(f"  I/O accesses:   {len(io_ops) if constants else 0}")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Quick overview of ADSP-219x PM firmware.")
+    parser.add_argument("file", help="PM binary file (packed 3-byte)")
+    parser.add_argument("--dm", help="Optional DM binary for"
+                        " cross-reference")
+    args = parser.parse_args()
+
+    if not os.path.isfile(args.file):
+        print(f"Error: {args.file} not found", file=sys.stderr)
+        sys.exit(1)
+
+    analyze_pm(args.file, args.dm)
+
+
+if __name__ == "__main__":
+    main()