64kramsystem / 64kramsystem/ghidra-vice-connector

Memory access heatmap: runtime code-vs-data classification

Aperta
#18 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
priority: high
Lingua principale
Python
Stelle
1
Fork
0
Metriche di merge delle PR
Nessuna PR unita negli ultimi 30g

Descrizione

## Summary

The fundamental challenge in C64 game disassembly is distinguishing code from data in a flat 64KB address space (sprite frames, music data, lookup tables, level maps all live alongside executable code). Using VICE tracepoints (non-stopping checkpoints) to record which addresses are executed vs. read as data vs. written, then annotating the Ghidra listing accordingly, can solve this automatically at runtime.

Inspired by RetroDebugger's memory access layers and IceBroLite's memory visualization.

---

## How VICE supports this

Checkpoints with `stop_on_hit=False` fire without pausing execution. VICE still sends `RESP_CHECKPOINT_INFO` (0x11) events when these tracepoints are hit — with `currently_hit=True` and the `cpu_op` flag (EXEC/LOAD/STORE) identifying the access type.

`checkpoint_set()` in `util.py:480` already accepts `stop_on_hit` — it just needs to be `False`. The event handler in `hooks.py` currently only handles `RESP_STOPPED` (0x62) and `RESP_RESUMED` (0x63); a handler for `RESP_CHECKPOINT_INFO` (0x11) needs to be registered.

---

## Implementation plan

### Phase 1 — Collect access data

1. **`util.py`**: Register a `RESP_CHECKPOINT_INFO` (0x11) event handler in `ViceBmpClient` that accumulates `(address, cpu_op)` hits into a dict without blocking. The address is already in the checkpoint info struct at `start` field (`util.py:98-116`).

2. **`methods.py`**: Add three new remote methods:
- `start_heatmap(process: C64, start: Address, end: Address)` — calls `checkpoint_set()` three times (EXEC, LOAD, STORE) with `stop_on_hit=False` over the given range.
- `stop_heatmap(process: C64)` — deletes the heatmap checkpoints.
- `apply_heatmap(process: C64)` — applies collected data to the program (Phase 2).

### Phase 2 — Annotate the Ghidra listing

`apply_heatmap()` iterates the accumulated access dict and for each address:
- EXEC hits → set Ghidra bookmark type `"Code"` (or call `trace.disassemble()` at those addresses)
- LOAD-only (never EXEC) → set bookmark type `"Data"`, add plate comment `"Read as data (heatmap)"`
- STORE hits → add plate comment `"Written at runtime"`

Bookmarks are written via the trace: `trace.proxy_object_path(...).set_value(...)` or via a post-analysis Ghidra script that reads from a persisted set.

### Alternative: CPU History bulk approach

If tracepoints prove too noisy (too many RESP_CHECKPOINT_INFO events flooding the socket), use `CMD_CPU_HISTORY` (0x86) on each stop instead: retrieve the last N instructions, extract their PCs, and accumulate them. This gives executed addresses only, not data reads.

---

## BMP commands involved

| Command | Hex | Already in util.py? |
|---------|-----|-------------------|
| `CMD_CHECKPOINT_SET` | 0x12 | Yes (`util.py:480`) |
| `CMD_CHECKPOINT_DELETE` | 0x13 | Yes (`util.py:512`) |
| `RESP_CHECKPOINT_INFO` event | 0x11 | Not handled as event |

---

## Files to change

- `src/main/py/src/vice/util.py` — add `RESP_CHECKPOINT_INFO` event handling
- `src/main/py/src/vice/methods.py` — add `start_heatmap`, `stop_heatmap`, `apply_heatmap` methods
- `src/main/py/src/vice/commands.py` — add accumulated access state and annotation logic

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Direzione di ricerca

La issue descrive la modifica di tre file: util.py per aggiungere un gestore dell’evento RESP_CHECKPOINT_INFO, methods.py per aggiungere tre nuovi metodi remoti (start_heatmap, stop_heatmap, apply_heatmap) e commands.py per la logica dello stato e delle annotazioni. Inizia leggendo la funzione checkpoint_set esistente in util.py e la gestione degli eventi in hooks.py. Comprendi i comandi del protocollo VICE BMP (CMD_CHECKPOINT_SET, CMD_CHECKPOINT_DELETE). Il lavoro è completo quando i nuovi metodi sono implementati e possono raccogliere e applicare dati di accesso alla memoria per annotare un listing di Ghidra.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Ambito
devtools
Tipo di issue
Funzionalità
Difficoltà
4/5
Tempo stimato
3-5 giorni
Stato di attività
Ferma
Chiarezza
Specificata chiaramente
Idoneità per principianti
40/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.