# 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) |