SoftGPU

SoftGPU is a Rust-first, developer-oriented GPU emulation, testing, debugging, sanitization, and CI runtime. It aims to let real AMD HIP userspace talk to a SoftGPU ROCr/HSA compatibility adapter, then execute and diagnose kernels on a vendor-neutral core—without pretending to be a cycle-accurate Radeon AI PRO R9700 or inventing undocumented AMD behavior.

v0.5.0 — Reproducible debugging beta (Phase 9): SoftGPU Functional IR debugger (traces, breakpoints, seeded schedule exploration). This is not gfx1201 ISA emulation. See docs/status.md, docs/functional-path.md, and CHANGELOG.md.

What SoftGPU is (and is not)

Is: a fail-closed, evidence-driven path from ABI/protocol observation → functional execution → sanitizers → a verified gfx1201 subset → hardware differential tests.

Is not (initially): a HIP SDK replacement, kernel-mode AMDGPU driver, PCIe/MMIO/firmware device model, cycle-accurate simulator, graphics API, performance oracle, or permission to return success for unimplemented behavior.

Fidelity vocabulary

Every run, diagnostic, and public report must name its fidelity level:

Do not use “R9700 emulator,” “gfx1201 compatible,” or “conformant” without attaching scope and evidence.

Unsupported behavior policy

Unsupported or malformed input must produce a stable error category, human context, and (where applicable) structured diagnostics. SoftGPU never silently fakes unsupported behavior. Optional permissive/approximation modes (future) must warn loudly, mark non-conformance, and stay out of default CI.

Release roadmap

Releases are organized around what a developer can accomplish. Engineering phases are gates inside those releases (see the staged implementation charter). Phase numbers express dependency, not calendar dates. No tagged release without the cross-phase gates in the charter (CI green, support matrix match, fail-closed unsupported paths, provenance, etc.).

Quick start

Pinned toolchain: Rust 1.85.0 (rust-toolchain.toml). MSRV: 1.85. Nightly host features: prohibited.

# Install / run (crates.io, once published):
#   cargo install softgpu --locked
# From a checkout:
cargo test --workspace --locked
cargo run --locked -- info
cargo run --locked -- validate-profile profiles/softgpu-generic-v0.json
cargo build -p softgpu-hsa --locked
cc -I third_party/rocr-headers -o target/hsa-layout-probe tools/hsa-layout-probe/probe.c && ./target/hsa-layout-probe
# Linux x86_64 + ROCm 7.14 load proof (CI): see environments/rocm-x86_64/README.md
cargo fmt --check
cargo clippy --workspace --locked --all-targets -- -D warnings

Cargo emits libhsa_runtime64. For ROCr-style substitution on Linux, the Phase 1 script stages libhsa-runtime64.so.

ROCm integration details and local reproduction (Docker / Apple Container): environments/rocm-x86_64/README.md.

Repository map

crates/softgpu-core/   # handles, runtime, agents, traces, profiles
crates/softgpu-hsa/    # cdylib HSA adapter (minimal exports)
src/                   # softgpu CLI
profiles/              # versioned device profiles with provenance
third_party/rocr-headers/  # pinned hsa.h for probes (NCSA)
tests/                 # CLI/profile tests
docs/                  # architecture, status, sources, ADRs, articles

CI workflows

Release secrets: set repository secret CARGO_REGISTRY_TOKEN (crates.io API token) before tagging v0.5.0. Coveralls uses GITHUB_TOKEN via the Coveralls GitHub App (enable the repo on coveralls.io).

Linux builds of softgpu-hsa need the workspace .cargo/config.toml linker wrapper (or an equivalent) so the cdylib advertises ELF version ROCR_1 for HIP. Cloning this repo already includes that config.

Documentation

• Status — what works, active phase, next gate
• Changelog
• Architecture
• Support matrix
• Sources ledger
• Unsafe / FFI policy
• ROCm x86_64 env — pinned image; local CI via Docker or Apple Container
• ADR-0001 · ADR-0002
• Article 1 · Article 2 · Article 3 · Article 4 · Article 5 · Article 6 · Article 7 · Article 8
• Article 19 (draft)
• Phase 3 concurrency invariants
• AQL diagnostic contract
• Code-object metadata
• Functional IR path

License

Dual-licensed under Apache-2.0 OR MIT. See LICENSE and LICENSE-MIT.