1 files changed, 97 insertions, 0 deletions
diff --git a/debug/risc-v-gsp-rm-vm/gpgpu-sim/README.md b/debug/risc-v-gsp-rm-vm/gpgpu-sim/README.md
new file mode 100644
index 0000000..d9e4ff7
--- /dev/null
+++ b/debug/risc-v-gsp-rm-vm/gpgpu-sim/README.md
@@ -0,0 +1,97 @@
+# GreenEye-GPGPU-Sim overlay (in development)
+
+> **Status: Phase 0 scaffold.** This directory is the tracked overlay that will
+> turn GPGPU-Sim into the execution substrate of the
+> [risc-v-gsp-rm-debugger](../README.md). Today it contains a reproducible
+> build/setup path, a Turing TU104 (RTX 2080 SUPER) **configuration scaffold**,
+> a run wrapper, a config-consistency test, and draft engineering-admission
+> records. **It makes no accuracy, timing, performance or support claim**, and
+> it is **not** calibrated to silicon.
+
+## 1. What this is
+
+GPGPU-Sim is an open-source, data-driven GPGPU performance/functional
+simulator (BSD-3-Clause, University of British Columbia). The debugger program
+needs an off-hardware execution substrate that can host the GPU model, the
+GSP/microcontroller models and the debugger's hooks/watchpoints/session
+recording on one deterministic clock. This overlay is how the project tracks
+its changes to upstream:
+
+* `upstream/` — a pinned clone of upstream GPGPU-Sim (gitignored, never
+  committed; see [UPSTREAM.md](UPSTREAM.md));
+* `patches/` — our overlay patch set, applied in lexical order by `setup.sh`
+  (`0001` CUDA-12 toolchain/soname, `0002` gcc-13/CUDA-12 source fixes; the
+  build record is in [BUILD-PORT.md](BUILD-PORT.md));
+* `configs/` — tracked device configurations. `turing-tu104-2080super/` is the
+  first target (the local TU104 card);
+* `scripts/` — `run_sim.sh` (run a CUDA binary against the simulator) and
+  `config_sanity.py` (config consistency test);
+* `ADMISSION.md` — draft admission records TOOL-2026-SIM-01..05, pending
+  maintainer filing.
+
+**Development-only.** This is analysis tooling. It is never shipped, never
+becomes a product dependency or guest component, and never touches GPU
+hardware, the kernel module, mdev, or a guest. Real-firmware simulation is
+Phase-1 work behind explicit gates; nothing here should be imported by
+product code.
+
+## 2. Relationship to risc-v-gsp-rm-debugger
+
+The debugger already has two execution backends: QEMU (real image probe,
+device-map harvest) and the native reference core under `../sim/`
+(instruction-level, L0/L1). GPGPU-Sim becomes the third backend once the
+Backend-ABI work lands (Phase 0/1.8): the same session format, hooks,
+watchpoints, probes, Ghidra bridge and MCP surface drive all of them. The
+TU104 config scaffold establishes the first GPU-side device profile; the GSP
+and MCU models (Phase 1.5) are planned to run as clock-domain citizens of
+this simulator. Nothing in this directory is on the critical path of the
+existing tool: deleting it leaves the debugger fully functional.
+
+See `../docs/30-GPGPU-SIM-INTEGRATION.md` for the public integration note.
+
+## 3. Quick start
+
+```bash
+cd open-iov/debug/risc-v-gsp-rm-vm/gpgpu-sim
+
+# 1. Clone the pinned upstream, apply patches/, build (see UPSTREAM.md).
+#    --no-build materialises the checkout only. Needs a CUDA toolkit;
+#    CUDA_INSTALL_PATH overrides the default /usr/local/cuda.
+./setup.sh
+
+# 2. Check the TU104 scaffold config is internally consistent.
+python3 scripts/config_sanity.py
+
+# 3. Run a CUDA binary (built with --cudart shared) against the simulator.
+./scripts/run_sim.sh --help
+./scripts/run_sim.sh ~/path/to/vectorAdd
+```
+
+Requirements: git, gcc/g++, make, bison, flex, zlib, and a CUDA toolkit.
+`setup.sh` uses at most 4 compile jobs by default (`JOBS` overrides) to respect
+the host budget.
+
+## 4. What is *not* claimed
+
+* **Not calibrated.** Every latency, timing and bandwidth parameter not tied
+  to a published TU104 number is marked `UNKNOWN:` in the config and is
+  inherited from the upstream SM75 Turing model.
+* **Not a full GPU model yet.** No GSP core, no microcontroller models, no
+  fabric/PCIe/RDMA/NVMe models, no guest co-simulation.
+* **No accuracy claim of any kind** until the Phase-1 calibration report
+  exists (admission TOOL-2026-SIM-02). Config-only modeling without
+  calibration evidence is an explicit anti-goal.
+* **Not a product/guest component** and never a support claim.
+
+## 5. Layout
+
+| Path | Purpose |
+|---|---|
+| `UPSTREAM.md` | pinned upstream commit, provenance, patch policy |
+| `setup.sh` | idempotent clone/checkout + patch + build |
+| `patches/` | overlay patches applied in lexical order |
+| `configs/turing-tu104-2080super/` | TU104/RTX 2080 SUPER scaffold config + Booksim interconnect file |
+| `scripts/run_sim.sh` | LD_LIBRARY_PATH-substitution runner for CUDA binaries |
+| `scripts/config_sanity.py` | stdlib-only config consistency test (also wired into `make test`) |
+| `ADMISSION.md` | draft admission records (pending maintainer filing) |
+| `build/` | build logs and run directories (gitignored) |