Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 39 additions & 2 deletions HACKING.md
Original file line number Diff line number Diff line change
Expand Up @@ -985,8 +985,45 @@ resident. The idle processor polls the device error sink,
and the first fault is sent once through the machine's fatal channel.
Fatal GPU errors reject reset and restart before touching CPU planes; a
successful quiescent reset after a recoverable rejection rearms notification.
Newport still rejects `[graphics] raster = "wgpu"` until M3; full opcode and
lifecycle coverage are future work. The legacy prototype remains
Stopped resident snapshots take one lifecycle write lock against PIO, DMA and
monitor producers. They require an empty published GFIFO, no worker or active
display cut and no incomplete HostRW transfer, then capture register/context
state and both complete GPU planes at one submitted stream position. The
GFIFO itself is ephemeral and is not serialized. Restore stages validated
register and full-plane halves, uploads both planes into a new epoch, and only
then publishes the registers and permits processor/display restart. Old
scanout bindings and composed captures are invalidated. Missing, duplicate or
failed halves leave the board stopped rather than exposing partial state.
Disk snapshots, CI rollback, live debugger checkpoints and a second Newport
head share this transaction; reset clears authoritative GPU planes without
refreshing stale CPU shadows.

Resident telemetry is aggregate-only and checked. It classifies primitive and
address kinds, mode features, conservative clipped coverage, HostRW transfer
sizes, nonempty batch sizes and flush reasons; board counters cover GFIFO
occupancy, reservation failures, `BUS_BUSY`, frame cuts and render completion.
Snapshots reject epoch changes, decreasing counters and overflow rather than
wrapping. The ordinary resident path performs no telemetry map or readback.
An explicit profiling option waits for each nonempty batch and maps one
64-byte metadata record with timestamps, busy-tile totals and the generated
indirect dispatch. Profiling metadata is separate from raw-plane and composed
capture traffic.

In addition to capacity and architectural boundaries, a continuously fed
resident batch is submitted at the next GFIFO command boundary after 4 ms.
This cannot split a command, HostRW transfer or bounded-set wait. A replay of
66,741 embedded-PROM command-monitor records on Vulkan and D3D12 accepted
20,987 operations with no unsupported operation or read mismatch. It formed
43-51 real batches; 25-31 were latency flushes. Eight direct presentations of
the replayed state had conservative p95 bounds of 2.10 ms for render
completion and 0.26 ms for the frame cut with no capture readback. HostR was
four operations and reused two selected-plane maps, so the measured design
keeps full-plane HostR snapshots. The same evidence retains 8 x 8 tiles,
GPU-generated active-tile dispatch, 1,024 state slots and three reusable sets.
These are gated replay measurements, not production IRIX application timing.

Newport still rejects `[graphics] raster = "wgpu"` until production activation;
live frontend integration remains future work. The legacy prototype remains
CPU-canonical.

Residency tests can opt into replacing each CPU shadow with its own
Expand Down
63 changes: 53 additions & 10 deletions TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -435,17 +435,17 @@ Remove-Item Env:\IRIS_NO_JIT -ErrorAction SilentlyContinue
.\scripts\test-resident-gate.ps1
```

The exact 103-case script requires 28 `resident_` CPU tests, four flat-fill
tests, two line tests, two HostW walker tests, one HostW interpreter/JIT source
test, one shade-DDA test, one pattern-state test, two resident HostR
The exact 130-case script requires 43 `resident_` CPU tests, four flat-fill
tests, two line tests, two HostW walker tests, one HostW interpreter/JIT
source test, one shade-DDA test, one pattern-state test, two resident HostR
port/retirement tests, three command-ABI tests and three direct-state tests,
then **19 resident GPU tests and nine direct scanout tests on each backend**:
103 tests in total. The window test requires an available native desktop and a
GPU that can present to it. The script checks each libtest pass count, rejects
hardware skips and prints the selected adapter; both Vulkan and D3D12 must
succeed for the full gate. `.\scripts\test-resident-gate.ps1 -Backend vulkan`
or `-Backend dx12` runs just one hardware backend and is not the complete
two-backend gate. For manual PowerShell runs set
then **24 resident GPU tests and ten direct scanout tests on each backend**.
That is 130 tests in total. The window test requires an available native
desktop and a GPU that can present to it. The script checks each libtest pass
count, rejects hardware skips and prints the selected adapter; both Vulkan and
D3D12 must succeed for the full gate. `.\scripts\test-resident-gate.ps1
-Backend vulkan` or `-Backend dx12` runs just one hardware backend and is not
the complete two-backend gate. For manual PowerShell runs set
`$env:REX3_RESIDENT_BACKEND = 'vulkan'` or `'dx12'` before each command
instead of the shell prefix. A host that lacks either required hardware
backend cannot claim the complete gate. Metal is not covered by this script.
Expand All @@ -460,6 +460,49 @@ selected display mode unchanged. Assertions distinguish per-mode composed
capture attempts, successes and bytes from attributed raw-plane
`Compatibility` observations.

The lifecycle cases stop and serialize producers at an empty GFIFO boundary,
capture registers and both complete authoritative planes once, and restore
them into a new epoch before restart. They cover disk snapshots, CI rollback,
live debugger checkpoints, a second Newport head, reset, monitor exclusion,
HostW continuation and sticky failure. Hardware cases round-trip complete
GPU-written planes and both resident display modes while the CPU framebuffer
mappings remain protected. Missing, duplicate, incomplete or failed snapshot
halves must not publish registers, pixels, captures or a restartable board.
Metal remains outside this gate.

The M8 cases add checked histogram/delta accounting, exact GFIFO
full-versus-contention telemetry, bounded-set wait accounting, a 4 ms
continuous-stream batch-age boundary and profiling-only validation of the
GPU-generated active-tile dispatch. The independent mixed-workload hardware
gate compares complete planes and context against the CPU engine after fills,
copies, integer/fractional/antialiased lines, HostW, HostR, direct
presentations and explicit observations. It also requires zero ordinary
raw-plane/composed readback and reports typed batch, GFIFO and latency
aggregates.

An optional local recorder file can be replayed through the resident backend
without printing records or pixels. The file is not a test artifact and must
not be committed. `REX3_RESIDENT_PROFILE` enables a 64-byte metadata map and
wait per nonempty batch; omit it to verify the default map-free path.
`REX3_RESIDENT_REPLAY_FRAMES` optionally presents the final replayed state
through direct wgpu scanout that many times without requesting capture. The
recording must contain valid final display state when that option is used.
For example, on PowerShell:

```powershell
$env:REX3_RESIDENT_REPLAY = 'C:\local\newport.rec'
$env:REX3_RESIDENT_BACKEND = 'vulkan' # repeat with dx12
$env:REX3_RESIDENT_PROFILE = '1'
$env:REX3_RESIDENT_REPLAY_FRAMES = '8'
cargo test --locked -p iris --lib --features wgpu,rex-jit,rexdiag,gputrace resident_replay_aggregate_file -- --ignored --nocapture --test-threads=1
```

The aggregate reports records and checked reads, accepted/no-op/unsupported
operations, typed primitive/mode/coverage/HostRW distributions, nonempty
batches and flush reasons, GFIFO/backpressure, attributed transfer bytes and
conservative latency buckets. Replay throughput and optional post-replay
presentations are test-path measurements, not live guest wall-clock timing.

To deliberately regenerate, set `REX3_CORPUS_OUT` to an existing relative
directory with a pre-existing regular `.rex3-corpus-root` file and run
`rex3_corpus_generate -- --ignored --nocapture` with the strict CPU feature
Expand Down
128 changes: 103 additions & 25 deletions clanker/plans/GPUTodo.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# REX3 proper GPU mode: implementation plan

Status: upstream integration in progress 2026-11-13. Upstream
Status: upstream integration in progress 2026-11-15. Upstream
[#569](https://github.com/techomancer/iris/pull/569) merged M0, the gated
test-only M1 resident slice and a minimum M2 scanout slice.
[#731](https://github.com/techomancer/iris/pull/731) merged the test-only
Expand All @@ -10,9 +10,11 @@ common wgpu presenter on a native window, test-only) is on `main` too
(checked 2026-11-15 at `dcd54c20`). #748 reduced DID dispatch latency and
#749 completed the gated M2 readback compatibility slice. #750 is the open
upstream M3 branch and is being expanded to carry paired M3+M4 coverage. The
remaining M3-M10 work exists in an unmerged candidate stack, not in upstream
`main`.
No production GPU-authoritative Newport mode has landed. The tile-binned
local cumulative paired branches now carry M5+M6 and M7+M8. M0-M8 are
complete for the gated, test-only candidate path, but those paired branches
are not yet in upstream `main`. Production activation, application-level M8
acceptance and M9/M10 remain open. No production GPU-authoritative Newport
mode has landed, and live `raster = "wgpu"` remains rejected. The tile-binned
`IRIS_REX3_GPU` prototype is separate and CPU-canonical, not the target
architecture.

Expand Down Expand Up @@ -747,9 +749,10 @@ Partial, test-only: a read-only same-device binding and GFIFO frame marker
order resident fills, direct scanout and a GPU frame consumer. Screenshot,
frame-request, headless and VNC tests capture composed output only. Ordinary
frames after seeding have zero raw-plane upload/readback, CPU-plane access
and CPU fallback. In the presenter follow-up (now on `main`), a test-only `WgpuRenderer`
handoff presents two ordered draws and a resize on a real native window using
the same GPU. An explicit diagnostic reads the presenter's unpacked frame
and CPU fallback. In the presenter follow-up (now on `main`), a test-only
`WgpuRenderer` handoff makes three presentations, including a resize, on a
real native window using the same GPU. An explicit diagnostic reads the
presenter's unpacked frame
texture for pixel parity with the software compositor; it does not inspect
final swapchain or on-screen pixels. This threaded test is available on
Windows and Linux; macOS needs a main-thread window harness. Resident refresh
Expand All @@ -772,14 +775,14 @@ It is deliberately slow and never an automatic fallback. M2 is complete
within this gated test-only scope. Production live integration and final
on-screen validation remain open; `iris-gui` cannot select this mode.

The Windows gate `.\scripts\test-resident-gate.ps1` checks 103 cases: 28
The Windows gate `.\scripts\test-resident-gate.ps1` checks 130 cases: 43
resident CPU, 4 flat-fill, 2 line, 1 shade-DDA, 1 pattern-state, 3 command-ABI
and 3 direct-state tests, 2 HostW walker tests, 1 HostW interpreter/JIT source
oracle, 2 resident HostR port/retirement tests, plus 19 resident GPU and 9
oracle, 2 resident HostR port/retirement tests, plus 24 resident GPU and 10
direct-scanout tests on each of Vulkan and D3D12. It requires the named
backend on an integrated/discrete adapter and a native desktop, and fails
rather than skipping when unavailable; a single-backend run is not the
complete 103-test gate. See
complete 130-test gate. See
`TESTING.md` for commands and prerequisites.

### M3 - Command ABI and complete uber-shader
Expand Down Expand Up @@ -1056,34 +1059,109 @@ resident mode yet.

### M7 - Snapshot, reset and failure lifecycle

- [ ] Define a quiescent GPU snapshot boundary.
- [ ] Serialize full planes and required command/context state.
- [ ] Restore by uploading before command processing resumes.
- [x] Define a quiescent GPU snapshot boundary.
- [x] Serialize full planes and required command/context state.
- [x] Restore by uploading before command processing resumes.
- [x] Define device-loss behavior without CPU-current checkpoints.
- [ ] Re-run Stop/reset/restore/debugger/frontend lifecycle tests.
- [ ] Validate Vulkan and D3D12; unblock Metal only after safe completion and
- [x] Re-run Stop/reset/restore/debugger/frontend lifecycle tests.
- [x] Validate Vulkan and D3D12; unblock Metal only after safe completion and
destruction are demonstrated.

Complete when snapshot round trips are exact and GPU failure cannot return
success with stale or partially recovered framebuffer state.

Device loss is sticky and fatal in the gated resident path, with one machine
notification and no restart from stale CPU planes. Production lifecycle and
snapshot support remain open.
Complete within the gated resident backend. A lifecycle write lock excludes
PIO, DMA and monitor producers while Stop joins the display and GFIFO workers.
The snapshot boundary requires a stopped worker, a fully published empty
FIFO, no active display frame and no incomplete HostRW transfer. It then
captures the complete register/context/display state and one attributed
two-plane `Snapshot` observation under the same lock. GFIFO contents are
deliberately not serialized.

Restore validates and stages the register and full RGB/auxiliary halves
without publishing either one. Only after both planes have been uploaded into
a new resident epoch are the registers committed, old scanout bindings and
captures invalidated, and restart allowed. Invalid, duplicate, missing or
partially written halves leave the board stopped and require a complete retry.
Machine disk snapshots, CI rollback, live debugger checkpoints and a second
Newport head use the same atomic checkpoint. Reset zeros the GPU planes and
registers without reading or writing stale CPU shadows.

CPU/test-double cases cover producer exclusion, Stop/restart, reset, debugger
commands, invalid input and sticky failure. Vulkan and D3D12 cases round-trip
complete GPU-written planes, HostW continuation state and direct/compatibility
display output while protected CPU planes remain untouched. Device loss or a
failed upload remains sticky and cannot return success or restart with
partial state. Metal remains blocked until its completion and destruction
behavior is exercised by an equivalent gate.

### M8 - Optimize only after complete live execution

- [ ] Capture representative live Newport workloads.
- [ ] Record primitive, mode, area and HostRW transfer distributions.
- [ ] Add GFIFO occupancy/backpressure telemetry.
- [ ] Tune tile size, active-tile dispatch and batch limits.
- [ ] Bound batching by both capacity and presentation latency.
- [ ] Compare full-plane and region HOSTR readback only if HOSTR is material.
- [ ] Re-run correctness after every scheduling/layout change.
- [x] Capture a representative, redistributable live Newport workload.
- [x] Record primitive, mode, area and HostRW transfer distributions.
- [x] Add GFIFO occupancy/backpressure telemetry.
- [x] Tune tile size, active-tile dispatch and batch limits.
- [x] Bound batching by both capacity and presentation latency.
- [x] Compare full-plane and region HOSTR readback only if HOSTR is material.
- [x] Re-run correctness after every scheduling/layout change.

Complete when the selected design passes correctness and end-to-end gates on
representative applications, not only synthetic fills.

The gated implementation now records checked, typed aggregate telemetry for
primitive and address kinds, mode features, clipped area and tiles, HostW and
HostR transfer sizes, nonempty batch sizes, flush reasons, command-generation
and submission time, bounded-set waits, GFIFO occupancy/backpressure and
frame-cut/presentation latency. Counter overflow, reset/epoch mismatch and
decreasing snapshots fail closed. Default operation maps no profiling data.
Explicit profiling waits for each nonempty batch and maps one 64-byte metadata
record containing timestamps, busy-tile totals and the GPU-generated indirect
dispatch; it never maps framebuffer data.

Batching now has a 4 ms maximum age in addition to existing state, payload and
tile-list capacity boundaries. The processor checks that age after each GFIFO
command, so it cannot split one architectural operation or preempt a bounded
GPU-set wait. Idle, display, HostR, copy-hazard, observation, restore and exit
boundaries retain their existing ordering. Empty flush checks are not counted
as batches.

A local recording of the embedded SGI PROM command monitor exercised real
guest `hinv`, `printenv`, `help` and `version` redraws without proprietary
installation media. Aggregate-only replay on both Vulkan and D3D12 executed
66,741 records, checked 398 reads with zero differences, accepted 20,987
operations with 206 no-ops and zero unsupported operations, and issued 20,777
GPU commands. It contained 20,781 draws, two HostW and four HostR operations;
12,443 draws used Z pattern, 150 used scissor and 109 used CID testing. It did
not contain copy or line primitives, which remain covered by the independent
mixed-workload hardware gate.

After excluding empty submit checks, the replay formed 43-51 nonempty batches.
The latency guard caused 25-31 flushes under the continuously fed replay,
alongside 13-15 capacity flushes. Eight post-replay direct presentations on
each backend used no raw or composed readback and reported conservative p95
bounds of 2.10 ms for render completion and 0.26 ms for the frame cut. These
are replay/test-path measurements, not guest wall-clock application timing.
The fastest producer drove GFIFO occupancy to 29,329-29,713 entries, but no
reservation was refused as full or contended.

The captured HostR traffic was only four requests among 20,987 accepted
operations. Two generation-keyed selected-plane maps transferred 16 MiB
total, so region readback is not justified by this evidence. Profiling mapped
only 43-51 metadata records (2,752-3,264 bytes total), measured
165,234-167,299 busy tiles and 1,067,889 tile/primitive pairs, and confirmed
that GPU-generated dispatch matched the busy list. Measurements therefore
retain 8 x 8 tiles, GPU-generated active-tile dispatch, 1,024 state slots,
three reusable sets and full selected-plane HostR snapshots.

The exact 130-case Vulkan+D3D12 gate covers the scheduling change and includes
an independent mixed workload with fills, copies, all line families, HostW,
HostR, direct presentation and explicit observation. The M8 implementation
checklist is complete within the gated backend. Its milestone acceptance for
normal use remains open until the production path runs representative IRIX
desktop applications and satisfies the end-to-end throughput, CPU-use and
frame-rate criteria below; the embedded PROM capture does not claim that
coverage.

### M9/M10 - Production activation and frontends

- [ ] Compile the resident path in normal wgpu builds after its prerequisites
Expand Down
6 changes: 3 additions & 3 deletions scripts/test-resident-gate.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ function Invoke-ResidentTests {
}

try {
Invoke-ResidentTests 'resident_' 28 $false
Invoke-ResidentTests 'resident_' 43 $false
Invoke-ResidentTests 'dev::ng1::rex3_flat_fill::tests' 4 $false
Invoke-ResidentTests 'dev::ng1::wgpu::line::tests' 2 $false
Invoke-ResidentTests 'dev::ng1::wgpu::host::tests' 2 $false
Expand All @@ -78,8 +78,8 @@ try {
Invoke-ResidentTests 'direct_ng1_scanout_' 3 $false
foreach ($name in $requestedBackends) {
$env:REX3_RESIDENT_BACKEND = $name
Invoke-ResidentTests 'resident_gpu_' 19 $true
Invoke-ResidentTests 'dev::ng1::wgpu::direct_tests' 9 $true
Invoke-ResidentTests 'resident_gpu_' 24 $true
Invoke-ResidentTests 'dev::ng1::wgpu::direct_tests' 10 $true
}
} finally {
[Environment]::SetEnvironmentVariable('REX3_RESIDENT_BACKEND', $previousBackend, 'Process')
Expand Down
Loading