1 files changed, 105 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md b/debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md
new file mode 100644
index 0000000..857102e
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/docs/05-GHIDRA-BRIDGE.md
@@ -0,0 +1,105 @@
+# 05 — Ghidra bridge
+
+> **# TOOL IN DEVELOPMENT - NOT READY YET!** See 00 for status.
+
+Ghidra answers *what is the code*; green-eye answers *what did it do*. The
+bridge joins them in both directions: Ghidra symbols into the runtime session,
+runtime hit addresses back into the Ghidra project.
+
+## 1. Address conventions (read this first)
+
+| Space | Meaning | Transformation |
+|---|---|---|
+| file vaddr | offset in the binary (`libcuda+0x…`) | base |
+| Ghidra program addr | what the decompiler shows | file vaddr + image base (`0x100000` for libcuda) |
+| runtime addr | live process / emulator address | file vaddr + load bias |
+
+* Firmware linked at its load address: bias 0 (the demo, and a
+  relocated-to-RAM GSP image when using the probe bias).
+* CUDA `libcuda` in the host oracle: runtime base from `/proc/<pid>/maps`;
+  `--bias` normalises it if you want runtime addresses in the DB.
+* The project's `decompiled_index.tsv`/bucket TSVs carry **both** program and
+  file addresses; green-eye parses both and stores the program address in
+  `symbol.extras["program_addr"]`.
+
+## 2. Build a symbol DB from Ghidra exports
+
+```bash
+./greeneye.sh symbols export \
+    --names   ../../userspace/cuda/570.144/annotations/names.tsv \
+    --index   ../../userspace/cuda/570.144/run/analysis/decompiled/decompiled_index.tsv \
+    --exports ../../userspace/cuda/570.144/run/analysis/elf-index/exports.tsv \
+    --callgraph ../../userspace/cuda/570.144/run/analysis/elf-index/callgraph.tsv \
+    --bias 0 -o symbols-cuda.json
+```
+
+For the GSP firmware project (`tools/ghidra/gsp-fwimage-570.144/`), first run
+the existing export scripts (`ExportFunctionIndex.java`,
+`DecompileFunctions.java`, …) to produce TSVs, then:
+
+```bash
+./greeneye.sh symbols export --index <export.tsv> --bias 0 -o symbols-gsp.json
+```
+
+`load_index_tsv` is column-aware: it accepts
+`<program>\t<file>\t<size>\t<name>\t<bucket>\t<line>\t<status>`, the 4-column
+exports form, or a plain `<addr>\t<name>` two-column form.
+
+## 3. Runtime addresses in the session
+
+```python
+db = SymbolDB()
+db.load_json("symbols-cuda.json")
+db.load_names_tsv("names.tsv", bias=runtime_base - file_base)
+s.symbols = db            # or pass symbols= to attach()/launch()
+```
+
+`resolve()` then annotates every hit with the Ghidra name, and
+`greeneye.ghidra.corpus_location(symbol, corpus_root)` returns
+`<bucket>:<line>` when the index carried that information — the pointer from a
+live hit to the decompiled body.
+
+## 4. Annotate hits back into Ghidra
+
+```bash
+./greeneye.sh analyze dumps/<run> --symbols symbols-gsp.json --out run.md
+python3 - <<'PY'
+from greeneye.ghidra import export_hits
+from greeneye.symbols import SymbolDB
+db = SymbolDB(); db.load_json("symbols-gsp.json")
+print(export_hits("dumps/<run>", "greeneye_hits.tsv", symbols=db))
+PY
+```
+
+`greeneye_hits.tsv` is `addr<TAB>hits<TAB>symbol<TAB>annotation`. Then run the
+bundled Java script in Ghidra headless:
+
+```bash
+$GHIDRA/support/analyzeHeadless <proj_dir> <project> -process <program> -noanalysis \
+    -scriptPath debug/risc-v-gsp-rm-vm/ghidra \
+    -postScript MarkGreenEyeHits.java /abs/path/greeneye_hits.tsv
+```
+
+`ExportForGreenEye.java` is the reverse helper: it walks the current program
+and writes a green-eye-compatible `addr<TAB>name<TAB>size` TSV.
+
+## 5. Breakpoints from Ghidra
+
+Two practical routes today:
+
+1. `greeneye decompose/decompile` → note the file vaddr → script
+   `s.hook("0x…")` (green-eye translates to runtime via the bias you loaded).
+2. Use `symbols export` from the Ghidra index, then `s.hook("<name>")` by
+   name — the most robust route across recompilations.
+
+A future Ghidra-side green-eye console (roadmap item) can call
+`greeneye` through its CLI to set breakpoints directly from the tool.
+
+## 6. Limits
+
+* Wrapper-generated functions are re-laid-out between driver patch versions;
+  transfer names, never raw wrapper addresses (the CUDA playbook's lesson).
+* The decompiler does not recover struct types; structure schemas for
+  green-eye decoding must be written or exported separately.
+* `decompiled_index.tsv` buckets are large and gitignored; keep symbol JSONs
+  small (name/size/subsystem only) if they must be tracked.