softsparc

An architecturally-exact SPARC64 full-system emulator, written in C++17.

The first target is a Sun Ultra 25 workstation (UltraSPARC IIIi), booting the machine's real 2 MiB OpenBoot PROM (OBP) firmware dump — 4.25.9 — from cold reset through the ok prompt and beyond. The bus scope for this target is PCI/PCIe only (no ISA, no SBus). A T4-1 / sun4v target is a deliberately deferred stretch goal: sun4v has a different MMU/trap architecture and blocks direct ROM access on real hardware, so it is out of scope until the UltraSPARC IIIi path is solid.

"Architecturally exact" means: correctness is measured against the SPARC V9 architecture manual, the JPS1 commonality specification, and the UltraSPARC-IIIi processor user's manual — not against "good enough to run some code". See include/softsparc/common/inventory.h for the running ledger of which instructions, ASIs, and traps are implemented, and against which manual section each was verified.

Building

cmake -B build -S .
cmake --build build -j

Requires a C++17 compiler and CMake >= 3.16. No third-party dependencies are required to build; a later work item vendors Berkeley SoftFloat 3e under third_party/softfloat for IEEE-754 semantics matching real UltraSPARC IIIi hardware (see the guarded stanza at the bottom of CMakeLists.txt).

For stricter warnings-as-errors builds (used in CI):

cmake -B build -S . -DSOFTSPARC_WERROR=ON
cmake --build build -j

Testing

ctest --test-dir build --output-on-failure

That is the fast tier: every tests/test_*.cpp is registered automatically and the whole set runs in a few seconds. Some cases inside it are gated on environment variables and skip silently without them, printing a SKIP line that names what is missing — a 0.00 s pass on one of those proves nothing, so read the skip lines.

The gate set

Three tiers, in increasing cost. All three should be green before a branch is merged.

1. Fast unit tests — the ctest line above. No environment needed.

2. Slow real-ROM and real-OS gates — need the real Ultra 25 OBP dump, and SOFTSPARC_SLOW_TESTS=1 to acknowledge the minutes they cost:

env SOFTSPARC_SLOW_TESTS=1 \
    SOFTSPARC_U25_ROM=/path/to/ultra25-obp.rom \
    SOFTSPARC_LINUX_BOOT_MEDIA=/path/to/dbn10-instB.iso \
    ctest --test-dir build --output-on-failure

SOFTSPARC_U25_ROM alone unlocks the ROM decode/FCode sweeps; adding SOFTSPARC_SLOW_TESTS=1 unlocks the full boot-to-ok gates (test_real_rom_console, test_real_rom_pci_probe, test_pci_config_boot, test_machine's clean-ok case). SOFTSPARC_LINUX_BOOT_MEDIA additionally unlocks test_linux_boot_pbm, which boots a real Debian 10 sparc64 kernel until it has enumerated both Fire PCIe leaves — the only gate in the tree that exercises what a kernel reads out of OBP's device tree, and the one that would have caught WI-BRIDGED3's missing IO PBM range regression. See that file's header for exactly which strings it requires and forbids, and why its step budget is tight.

3. The OBP equivalence gate — every execution lane must produce a byte-identical console transcript over a 200M-step OBP boot. --trace-ring 0 is required: without it the run takes ~18 minutes instead of ~30 seconds and hashes differently.

./build/softsparc --rom /path/to/ultra25-obp.rom \
  --ram-mb 2048 --trace-ring 0 --serial-stdout --steps 200000000 2>&1 | md5sum

Run it six times — plain, --dynarec, SOFTSPARC_NO_OPT=1, --dynarec with SOFTSPARC_NO_BUSFAST=1, --jit, and --jit with SOFTSPARC_NO_OPT=1 — and all six hashes must match. PERFORMANCE.md records the current expected value and the reasoning behind each arm. Always pass --ram-mb 2048: below that OBP still believes it has 2 GB, so the machine is misconfigured rather than smaller.

Running

./build/softsparc              # prints current status
./build/softsparc --inventory  # prints the instruction/ASI/trap accuracy ledger

Nothing is emulated yet — WI-01 is scaffold plus the common module only.

Where to look next

• AGENTS.md — house style and working rules for anyone (human or agent) implementing a module.
• docs/SOURCES.md — index of every reference manual under docs/, with provenance and integrity hashes.
• ROADMAP.md — work item sequencing (added as work items land; not present in WI-01).