PRISM: hardware ray tracing, graphics pipeline, Vulkan/HIP stacks, and CI 2.0

.github/workflows/apptainer-ci.yml

@@ -100,8 +100,11 @@ jobs:
               mkdir -p build32 && cd build32
               ../configure --tooldir=$APPTAINER_TOOLDIR --xlen=32
               make software -s
-              make tests -s
-              pip install --quiet pytest pyyaml
+              # Build only the regression category the smoke actually runs.
+              # `make tests` also builds the opencl category, which links
+              # -lOpenCL from the (ICD-less prebuilt pocl) toolchain and fails
+              # in the container -- and the smoke never runs those tests.
+              make -C tests regression -s
               chmod -R +x .
               VX_XLEN=32 python3 -m pytest ci -m "regression and simx" --strict-markers -v
           EOF

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ on:
         description: "comma list: simx,rtlsim,xrtsim,opaesim (blank = all)"
         default: ""
       tier:
-        description: "comma list: smoke,fast,slow,nightly (blank = all)"
+        description: "comma list: smoke,full,nightly (blank = all)"
         default: ""
 
 env:
@@ -68,15 +68,17 @@ jobs:
           IN_DRIVERS: ${{ github.event.inputs.drivers }}
           IN_TIER: ${{ github.event.inputs.tier }}
           TOOLCHAIN_CACHE_HIT: ${{ steps.tc.outputs.cache-hit }}
+          PUSH_BEFORE: ${{ github.event.before }}
+          PR_BASE: ${{ github.event.pull_request.base.sha }}
         run: |
           set -euo pipefail
           # Driver/tier policy by event (workflow_dispatch overrides).
           case "$EVENT" in
             schedule)          DRIVERS=""; TIER="" ;;                        # everything
-            pull_request)      DRIVERS="simx,rtlsim"; TIER="smoke,fast,slow" ;;
-            push)              DRIVERS="simx"; TIER="smoke,fast" ;;
+            pull_request)      DRIVERS="simx,rtlsim"; TIER="smoke,full" ;;
+            push)              DRIVERS="simx"; TIER="smoke" ;;
             workflow_dispatch) DRIVERS="$IN_DRIVERS"; TIER="$IN_TIER" ;;
-            *)                 DRIVERS="simx"; TIER="smoke,fast" ;;
+            *)                 DRIVERS="simx"; TIER="smoke" ;;
           esac
           # Toolchain (re)built -> 100% coverage. If the toolchain cache missed
           # (deleted / out-of-date / evicted / key changed / first run) the build
@@ -90,6 +92,21 @@ jobs:
               DRIVERS=""; TIER=""
             fi
           fi
+          # Change-aware driver escalation: simx is a separate C++ model and cannot
+          # exercise the RTL, so a change under hw/rtl, hw/dpi, sim/rtlsim|xrtsim|
+          # opaesim, or vendored RTL must force the matching sim driver in even on a
+          # push (which is otherwise simx-only). An indeterminate diff (zero/missing
+          # base, e.g. a new branch or force-push) escalates to full coverage.
+          if { [ "$EVENT" = "push" ] || [ "$EVENT" = "pull_request" ]; } && [ -n "$DRIVERS" ]; then
+            BASE="$PUSH_BEFORE"; [ "$EVENT" = "pull_request" ] && BASE="$PR_BASE"
+            ESC=$(python3 ci/testcase.py drivers --changed-from="$BASE" || echo ALL)
+            if [ "$ESC" = "ALL" ]; then
+              echo "indeterminate diff -> full driver coverage"; DRIVERS=""
+            elif [ -n "$ESC" ]; then
+              DRIVERS=$(printf '%s\n' "$DRIVERS" "$ESC" | tr ',' '\n' | grep . | sort -u | paste -sd,)
+              echo "RTL-affecting change -> drivers=$DRIVERS"
+            fi
+          fi
           F=""
           [ -n "$DRIVERS" ] && F="$F --drivers=$DRIVERS"
           [ -n "$TIER" ] && F="$F --tier=$TIER"
@@ -185,6 +202,14 @@ jobs:
           chmod -R +x .
           EXPR="${{ matrix.category }}"
           [ "${{ matrix.driver }}" != "host" ] && EXPR="$EXPR and ${{ matrix.driver }}"
+          # model_parity / perf_gate are cross-cutting check markers with
+          # their own dedicated cells; exclude them from every other category's
+          # cell so a distributed check spec runs once (in its check cell), not
+          # twice (also in its owning category's cell).
+          case "${{ matrix.category }}" in
+            model_parity|perf_gate) ;;
+            *) EXPR="$EXPR and not model_parity and not perf_gate" ;;
+          esac
           VX_XLEN=${{ matrix.xlen }} python3 -m pytest ci -m "$EXPR" --strict-markers \
             -v \
             --junitxml="$GITHUB_WORKSPACE/junit-${{ matrix.category }}-${{ matrix.driver }}-${{ matrix.xlen }}.xml"

.gitignore

@@ -1,2 +1,4 @@
 /build*
-/.*
+/.*
+# Archived/superseded docs — kept on disk, never tracked
+docs/archives/

AGENTS.md

@@ -52,7 +52,8 @@ See [docs/install_vortex.md](docs/install_vortex.md) for the full recipe. The no
   ```
 - **Separate build dirs per major variant** (`build32/`, `build64/`, `build_fpga64/`, ...) to avoid config/tool contamination. Never reuse one build dir for incompatible configurations.
 - **`configure` generates a runnable tree** by copying and instantiating `ci/`, `runtime/`, `sim/`, and `tests/` into `build/`. For execution and test automation, *always* prefer the generated scripts/Makefiles under `build/` over the source-tree `.in` files.
-- **Re-`../configure` from `build/`** whenever you `git pull`, edit source Makefiles, or add/remove a build-participating directory. Symptom of forgetting this: stale binaries, missing targets, or "I edited this Makefile and nothing happened."
+- **Re-`../configure` from `build/`** whenever you `git pull`, edit source Makefiles, edit `VX_config.toml` / any `*.toml`, or add/remove a build-participating directory. Symptom of forgetting this: stale binaries, missing targets, or "I edited this Makefile and nothing happened."
+- **Always ensure the build is current before running any test or app** — re-run `../configure` from `build/` first. `configure` regenerates `<build>/sw/VX_config.h` and `<build>/hw/*.vh` from `VX_config.toml`, but only when the toml is newer (it guards on mtime). The simx/RTL **cores `#include` this generated header**, so a stale header makes a core compile against old config values and silently diverge from the toml — and from the runtime/RTL, which re-expand the config every build. This is a real footgun: a stale `VX_config.h` once made SimX run a write-back D-cache while the toml/RTL were write-through, producing SimX-only wrong results. **Never** work around such a divergence by injecting `-DVX_CFG_*` overrides into a Makefile — that masks the stale artifact and fights the config system. The toml is the single source of truth; fix it by re-`configure`-ing.
 - **`ccache` can serve stale objects on `fmt`-version mismatches** (typical symptom: `fmt::v8` undefined-reference link errors in sim builds). Before deep-diving, retry with `CCACHE_DISABLE=1`.
 
 ---
@@ -83,6 +84,8 @@ See [docs/testing.md](docs/testing.md) and [docs/debugging.md](docs/debugging.md
 - **`--rebuild=1` forces a driver rebuild** even if the hardware configuration is unchanged. Use it when iterating on the driver itself; `--rebuild=0` suppresses rebuild regardless.
 - **RTL coverage path is `xrt`, not `rtlsim`.** When discussing or planning RTL verification, `xrt` is the canonical path — `rtlsim` bypasses the AFU surface. `rtlsim` remains useful for fast iteration on processor RTL; `xrt` is what proves the full integration.
 - **`ci/regression.sh` is the canonical source of tested configurations.** Use it to discover supported parameter combinations before inventing ad hoc ones.
+- **Perf-regression baselines (`ci/perf/baselines/*.json`) are golden data — never hand-edit them, and never "fix" a red perf gate by bumping the number.** They are regenerated only by `pytest ci -m perf_gate --update-baselines` (a human-run, reviewed step), and CI must never pass that flag. A `perf_gate` failure means real cycles moved: root-cause it, or — if the change is intended — regenerate the baseline so the diff shows the perf delta for review. Same rule as image goldens and `known_issue:`.
+- **SimX is the RTL's timing model — keep them in lockstep.** Any change that moves RTL cycles (pipeline structure, arbitration, queue depths, cache/memory behavior) must land together with the matching SimX timing-model update, and vice-versa. The `model_parity` CI gate enforces this: a `check: model_parity` case (`ci/testcases/model_parity.yaml` + per-extension parity categories) runs the same app/args/configs on simx and rtlsim and asserts exact retired-instruction match plus cycle agreement within the case tolerance (default 5%). Never widen a tolerance to absorb a divergence — model the behavior. When adding a hardware feature, add or extend a parity case that exercises it.
 - **When RTL debugging stalls, switch to the SimX-as-oracle pattern.** For numerical bugs, deep pipeline races, or any failure mode where rtlsim is "close but wrong": (1) build/extend the SimX C++ model so it mirrors the *new* RTL architecture and gets to PASS; (2) add matching trace dumps to both SimX and RTL (cycle, FU events, SRAM addresses+data, hazards) — same CSV format on both sides; (3) diff trace files — the first divergence is the bug. Don't keep guessing from output values; localize via trace diff. See [docs/debugging.md](docs/debugging.md#simx-as-oracle-for-rtl-debug).
 
 ### Smoke tests
@@ -111,6 +114,8 @@ make -C tests/opencl     run-rtlsim
 
 - **Align with mainstream CUDA, HIP, OpenCL, and Vulkan API and driver stacks.** For any design question — driver surface, command-processor model, memory model, scheduling — pick the solution those stacks would use. This keeps Vortex's externals familiar to mainstream software and avoids one-off abstractions.
 
+- **SimX Cardinal Rule — modules communicate *only* through channels.** A `SimObject` may observe or mutate another module's state *only* via its bound `SimChannel` ports (`MemReq`/`MemRsp`, `result_if`, …). **Never reach across the ownership hierarchy** to touch another object directly (`core_->processor()->memsim()`, `parent()->child()->field`, a leaf unit grabbing the global `Memory`). See [docs/simobject.md](docs/simobject.md#the-cardinal-rule).
+
 ---
 
 ## 6. Coding Conventions