deity-informant

NMOS 6510 toolkit: a 6510 -> raw-P-Code lifter + pure-Python P-Code VM (all 105 documented illegal opcodes are first-class), and a 6510 Ghidra/pypcode SLEIGH processor module. The jennings package supplies the opcode table, assembler and disassembler, and its py65-compatible MPU executes on this lifter + VM.

SID tune decompilation (tuneprog, trackerprog) built on this toolkit lives in anarkiwi/trackerprog.

Components

• deity_informant/lifter.py — lift(mem, pc) -> {"ops", "len", "cyc", "pen", "ctrl", "prov", "stk"} raw P-Code; CYCLETIME/EXTRACYCLES tables.
• deity_informant/vm.py — PcodeVM interpreter over a flat 64 KiB image (SID/VIC/CIA volatile IO modeled); run_sub/run_irq/run_irq_driven drivers.
• deity_informant/c64.py — power-on RAM, PSID/RSID loader, IRQ vector discovery, ROM-free IRQ dispatch stubs.
• deity_informant/cli.py — deity-informant console script.
• deity_informant/sleigh/ — SLEIGH module (languages/6510.slaspec = stock 6502 + 6510_illegal.sinc), smc.py (SMC context constructors), build.py, and pypcode_context() (a loaded pypcode Context for the 6510).
• ghidra/6510/headless/ — headless Ghidra integration test, run via Dockerfile.ghidra.
• deity_informant/hello_world.py — 33-byte C64 program using LAX/ISC + self-modifying code; the fixture for the VM and Ghidra tests.
• tools/doclinks.py — every [text](target) in docs/ and README.md resolved: the file, and the #anchor against the target's own headings.

Install

pip install deity-informant         # from PyPI; the SLEIGH sources ship as package data
pip install -e ".[dev]"             # from a checkout: + test/lint tooling, py65, pypcode

CLI

deity-informant disasm IMAGE [--org ADDR] [--start ADDR] [--count N]   # illegal-aware disassembly
deity-informant pcode  IMAGE --at ADDR [--org ADDR]                    # raw P-Code for one instruction
deity-informant run    IMAGE --init ADDR [--play ADDR --frames N]      # execute in PcodeVM, dump $D400.. grid
deity-informant emit-sleigh [-o DIR] [--magic 0xEE]                    # build/install the 6510 SLEIGH module

Python API

from deity_informant import lift, PcodeVM, run_sub
vm = PcodeVM(mem); run_sub(vm, entry, {}, lift)   # execute a subroutine to its RTS

Ghidra

deity-informant emit-sleigh -o "$GHIDRA_INSTALL_DIR/Ghidra/Processors/6510/data/languages"

Resolves the stock 6502.slaspec + SLEIGH compiler from $GHIDRA_INSTALL_DIR or a pypcode install; the stock spec's JSR/RTS return address and SBC borrow are patched to the hardware's. Import a C64 image as Raw Binary, language 6510:LE:16:default. docker build -f Dockerfile.ghidra -t di-ghidra . && docker run --rm di-ghidra runs the headless integration test.

Tests

black --check deity_informant/ tests/ && pylint deity_informant/
deity-informant emit-sleigh
pytest tests/ -n auto --cov=deity_informant --cov-fail-under=85

References

Illegal-opcode semantics and cycles: "No More Secrets — NMOS 6510 Unintended Opcodes" (csdb.dk/release/?id=258111).