| """The debugger. |
| |
| A debugger for this machine has an unusual job: the instruction stream is not |
| readable by construction, so inspection *is* decoding. Every view here goes |
| through cleanup and carries its confidence, which means a low-confidence |
| decode is visible as a fact about the program rather than hidden behind a |
| plausible-looking mnemonic. |
| |
| What it offers: |
| |
| * breakpoints by cell index or by label; |
| * step / step-over, with the PC held at a BREAK trap; |
| * a trace ring of executed instructions with decode confidence and the |
| registers each one wrote; |
| * symbolic register inspection — for each register, the nearest named symbol |
| and its similarity, which is the HDC equivalent of a type readout; |
| * raw bit-plane views of registers and storage cells. |
| """ |
|
|
| from __future__ import annotations |
|
|
| from dataclasses import dataclass |
|
|
| from .isa import REG_NAMES, format_operands |
| from .interpreter import Machine, TraceEntry |
|
|
|
|
| @dataclass |
| class StopReason: |
| """Why execution stopped.""" |
|
|
| reason: str |
| pc: int |
| detail: str = "" |
|
|
| def __str__(self) -> str: |
| return "%s at pc=%d%s" % (self.reason, self.pc, (" (%s)" % self.detail) if self.detail else "") |
|
|
|
|
| class Debugger: |
| """Interactive control of a :class:`~hdc.interpreter.Machine`.""" |
|
|
| def __init__(self, machine: Machine): |
| self.m = machine |
| self.breakpoints: set[int] = set() |
| self.labels: dict[str, int] = {} |
| self._trap_pc: int | None = None |
|
|
| |
| def attach_program(self, program) -> "Debugger": |
| """Take label -> cell mapping from an assembled program.""" |
| self.labels = dict(program.labels) |
| self.breakpoints.clear() |
| self._trap_pc = None |
| return self |
|
|
| def add_break(self, where: int | str) -> int: |
| """Set a breakpoint at a cell index or a label name.""" |
| pc = self._where(where) |
| self.breakpoints.add(pc) |
| return pc |
|
|
| def remove_break(self, where: int | str) -> bool: |
| pc = self._where(where) |
| if pc in self.breakpoints: |
| self.breakpoints.discard(pc) |
| return True |
| return False |
|
|
| def _where(self, where: int | str) -> int: |
| if isinstance(where, int): |
| return where |
| if where in self.labels: |
| return self.labels[where] |
| if where.startswith("@"): |
| return int(where[1:]) |
| raise KeyError("no such label: %r" % (where,)) |
|
|
| def check(self) -> StopReason | None: |
| """Does the current PC sit on a fresh breakpoint?""" |
| pc = self.m.pc |
| if pc == self._trap_pc: |
| return None |
| if pc in self.breakpoints: |
| self._trap_pc = pc |
| return StopReason("break", pc, "breakpoint") |
| return None |
|
|
| |
| def step(self) -> TraceEntry | None: |
| """Execute exactly one instruction, ignoring breakpoints.""" |
| entry = self.m.step() |
| if self.m.status == "break": |
| self._trap_pc = self.m.pc |
| else: |
| self._trap_pc = None |
| return entry |
|
|
| def step_over(self) -> TraceEntry | None: |
| """Step one instruction; a CALL runs to completion first.""" |
| entry = self.m.step() |
| if entry is not None and entry.op == "CALL": |
| depth = len(self.m.stack) |
| guard = 0 |
| while len(self.m.stack) >= depth and not self.m.halted and guard < 100_000: |
| self.m.step() |
| guard += 1 |
| self._trap_pc = None |
| return entry |
|
|
| def continue_(self, max_steps: int = 100_000) -> StopReason: |
| """Run until the next breakpoint, HALT, fault or budget.""" |
| m = self.m |
| if m.halted: |
| return StopReason("halt", m.pc, "already halted") |
| if m.status == "ready": |
| m.status = "running" |
| |
| if m.pc == self._trap_pc: |
| m.skip_break = True |
| self._trap_pc = None |
| while m.steps < max_steps: |
| stop = self.check() |
| if stop is not None: |
| m.status = "break" |
| return stop |
| if m.halted: |
| return StopReason("halt", m.pc) |
| if m.pc >= m.prog_len: |
| m.halted = True |
| m.status = "halted" |
| return StopReason("halt", m.pc, "past end of program") |
| before = m.pc |
| entry = m.step() |
| if entry is None: |
| return StopReason("halt", m.pc) |
| if m.status == "error": |
| return StopReason("error", m.pc, self.trace_tail(1)) |
| if entry.op == "BREAK" and m.status == "break": |
| self._trap_pc = before |
| return StopReason("break", before, "BREAK trap") |
| m.status = "budget" |
| return StopReason("budget", m.pc, "step budget exhausted") |
|
|
| |
| def trace_tail(self, n: int = 10) -> str: |
| rows = self.m.trace[-n:] |
| if not rows: |
| return "<no steps yet>" |
| return "\n".join(e.render() for e in rows) |
|
|
| def disasm(self, start: int | None = None, count: int = 12) -> str: |
| """Disassemble cells, marking the PC and any breakpoints.""" |
| m = self.m |
| if start is None: |
| start = max(0, m.pc - 2) |
| rows = [] |
| for pc in range(start, min(start + count, m.prog_len)): |
| dec = m.decode_at(pc) |
| marks = [] |
| if pc == m.pc: |
| marks.append("=>") |
| else: |
| marks.append(" ") |
| if pc in self.breakpoints: |
| marks.append("B") |
| else: |
| marks.append(" ") |
| rows.append( |
| "%s%s %04d %-8s %-26s conf=%.2f" |
| % ("".join(marks), "", pc, dec.op, format_operands(dec), dec.confidence) |
| ) |
| return "\n".join(rows) if rows else "<empty program>" |
|
|
| def regs(self) -> str: |
| """Registers: integer payload, and nearest named symbol (cleanup).""" |
| m = self.m |
| rows = [ |
| "REG VALUE POP SYMBOL SIM HV(head)" |
| , |
| "-" * 78, |
| ] |
| for i in range(len(m.regs)): |
| val = m.get_int(i) |
| hits = m.storage.nearest_symbol(m.regs[i], k=1) |
| sym, s = (hits[0] if hits else ("", 0.0)) |
| if s < 0.15: |
| |
| |
| sym, s = "", 0.0 |
| from .hypervec import bits |
|
|
| rows.append( |
| "%-5s %-10d %-6d %-25s %-5.2f %s" |
| % ( |
| REG_NAMES[i], |
| val, |
| m.regs[i].bit_count(), |
| sym[:25] or "-", |
| s, |
| bits(m.regs[i], m.d)[:24], |
| ) |
| ) |
| rows.append( |
| "PC=%d ZF=%d STACK=%d STEPS=%d STATUS=%s" |
| % (m.pc, int(m.flag_z), len(m.stack), m.steps, m.status) |
| ) |
| return "\n".join(rows) |
|
|
| def sim_table(self, regs: list[int] | None = None) -> str: |
| """Pairwise register similarity — the 'how HDC is my state' view.""" |
| m = self.m |
| idx = regs if regs is not None else list(range(len(m.regs))) |
| head = " " + " ".join("%6s" % REG_NAMES[i] for i in idx) |
| rows = [head] |
| for i in idx: |
| cells = [] |
| for j in idx: |
| cells.append("%6.3f" % m.get_sim(i, j)) |
| rows.append("%5s " % REG_NAMES[i] + " ".join(cells)) |
| return "\n".join(rows) |
|
|
| def bits(self, reg: int) -> str: |
| """Bit planes of one register.""" |
| from .hypervec import bitplanes |
|
|
| return "\n".join(bitplanes(self.m.regs[reg], self.m.d)) |
|
|
| def cell_bits(self, name: str) -> str: |
| """Bit planes of a storage cell.""" |
| return "\n".join(self.m.storage.bitplanes(name)) |
|
|
| def summary(self) -> str: |
| m = self.m |
| return ( |
| "status=%-8s pc=%-4d steps=%-5d halted=%-5s zf=%d bps=%s\n%s" |
| % ( |
| m.status, |
| m.pc, |
| m.steps, |
| m.halted, |
| int(m.flag_z), |
| sorted(self.breakpoints) or "[]", |
| self.disasm(count=5), |
| ) |
| ) |
|
|
|
|
| def debug_program(machine: Machine, program, breakpoints: list[int | str] = ()) -> str: |
| """Convenience: attach, set breaks, run, and return a session transcript.""" |
| dbg = Debugger(machine).attach_program(program) |
| for b in breakpoints: |
| dbg.add_break(b) |
| lines = [dbg.summary()] |
| stop = dbg.continue_() |
| lines.append("stopped: %s" % stop) |
| lines.append(dbg.regs()) |
| lines.append("trace:\n" + dbg.trace_tail(8)) |
| return "\n".join(lines) |
|
|
