diff options
Diffstat (limited to 'debug/risc-v-gsp-rm-vm/gpgpu-sim/README.md')
| -rw-r--r-- | debug/risc-v-gsp-rm-vm/gpgpu-sim/README.md | 97 |
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) | |