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
6 changes: 6 additions & 0 deletions HACKING.md
Original file line number Diff line number Diff line change
Expand Up @@ -630,6 +630,12 @@ cut defers the frame rather than forcing fence progress or presenting stale
state. GL and presenters using another device are rejected. Screenshot,
frame request, VNC and headless test capture read the composed output only,
and publish pixels and complete requests only after a successful copy/map.
An ignored hardware test also sends ordered draws and a resize through the
common wgpu presenter on a native window using the same device. It compares
the presenter's unpacked frame texture with the software compositor using an
explicit test-only readback. This exercises surface submission but does not
inspect the final swapchain or on-screen pixels. The threaded window test is
available on Windows and Linux; macOS requires a main-thread window harness.
After the initial seed, ordinary resident frames and idle/fence processing
perform no raw-plane transfer, CPU-plane access or CPU raster fallback.
Raw-plane observations explicitly select RGB, auxiliary or both, and return
Expand Down
15 changes: 12 additions & 3 deletions TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -290,7 +290,14 @@ including a full GFIFO and a full ordinary machine event queue. They require
a single first-fault notification and reject restart.
These tests opt in to the test-only display worker; they do not enable resident
raster in the emulator. They do not complete board-level HOSTR, snapshot or
other raw consumers, full opcode/lifecycle coverage, or live-window validation.
other raw consumers, full opcode/lifecycle coverage, or production guest
validation. On Windows and Linux, an additional hardware test sends two
ordered draws and a resize through the common wgpu presenter on a native
window. It explicitly reads the presenter's unpacked frame texture, including
padded rows after the resize, and compares it pixel-for-pixel with the software
compositor. This diagnostic readback is not part of ordinary presentation and
does not inspect the final swapchain or on-screen pixels. The window test is
excluded on macOS, where a separate main-thread harness is not yet provided.
Resident refresh skips CPU DID decoding. A GPU kernel expands changed VC2 DID
tables before scanout, and traffic assertions require zero decoded-map uploads
and less than 128 KiB for the complete initial display-state transfer. The
Expand Down Expand Up @@ -328,8 +335,10 @@ Remove-Item Env:\IRIS_NO_JIT -ErrorAction SilentlyContinue
```

The script requires 25 `resident_` CPU tests, three flat-fill tests and three
direct-state tests, then **10 resident GPU tests and six direct
scanout tests on each backend**. It checks each libtest pass count, rejects
direct-state tests, then **10 resident GPU tests and seven direct
scanout tests on each backend**: 65 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
Expand Down
60 changes: 45 additions & 15 deletions clanker/plans/GPUTodo.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,10 @@

Status: upstream integration in progress 2026-11-13. Upstream
[#569](https://github.com/techomancer/iris/pull/569) merged M0, the gated
test-only M1 resident slice and a minimum M2 scanout slice. The remaining
M2-M10 work exists in an unmerged candidate stack, not in upstream `main`.
test-only M1 resident slice and a minimum M2 scanout slice.
[#731](https://github.com/techomancer/iris/pull/731) merged the test-only
GPU DID expansion and retained-history handling. The remaining M2-M10 work
exists in an unmerged candidate stack, not in upstream `main`.
No production GPU-authoritative Newport mode has landed. The tile-binned
`IRIS_REX3_GPU` prototype is separate and CPU-canonical, not the target
architecture.
Expand All @@ -30,9 +32,9 @@ without fallback or routine readback.

Build new, reviewable PRs against upstream `main` on top of the foundation
that has already merged; do not start a second implementation or replay the
old foundation commits. As of 2026-11-13, the baseline is `1c9d16ad`, which
contains the squash merge `bbbe5de0` of #569. Refresh the baseline before
preparing each PR.
old foundation commits. After #731 merged, the baseline is `49210388`, which
also contains the squash merge `bbbe5de0` of #569. Refresh the baseline
before preparing each PR.

The local `feature/gpu-m2-display-state` through
`feature/gpu-m10-frontend` branches contain the rebased candidate work. The
Expand Down Expand Up @@ -82,6 +84,27 @@ the updated `main`; use an unmerged PR as a base only if the maintainer agrees
to that review arrangement. Reconcile shared code and documentation instead
of copying a stale fork version over upstream changes.

### Next follow-up and review feedback

- #731 has merged. Prepare the presenter follow-up on the latest upstream
`main` using only the presenter and subsequent follow-up commits; #731's
commits were recreated when it landed and must not be replayed. Before
submission, refresh upstream, verify its `main` is an ancestor, and re-run
the resident gate and core/GUI checks on the rebased branch.
- Revisit new maintainer comments on #731, #698 and subsequent GPU PRs before
filing or updating follow-ups. The #731 maintainer questioned how much DID
expansion can be parallelized while noting that reduced transfer traffic may
still make it worthwhile. Before claiming a performance win, measure GPU
expansion and end-to-end frame costs against CPU decoding and decoded-map
upload for changed and unchanged display state. Preserve exact DID history
and the no-routine-readback contract if optimizing. This measurement need
not block the presenter follow-up unless review requires it.
- #698 remains a draft, not a prerequisite. Its maintainer feedback favors
invalidating composition after processed raster commands or display-register
updates rather than counting every framebuffer write. If that discussion or
PR changes the shared presenter, review the final design and reconcile the
Newport follow-up; do not assume the draft behavior has landed.

### Pending upstream PRs to coordinate with

- [#698](https://github.com/techomancer/iris/pull/698) is an open draft for
Expand Down Expand Up @@ -636,7 +659,8 @@ consumers; the legacy `rex-gpu` replay/live prototype remains CPU-canonical.

- [x] Add a REX3 scanout kernel over the authoritative GPU planes.
- [x] Upload only small display state/tables needed for each changed frame.
- [ ] Present through the common wgpu presenter on the same device.
- [ ] Present in a running emulator through the common wgpu presenter on the
same device.
- [x] Add CPU-raster plus wgpu-compositor uploads.
- [x] Add an eframe wgpu path or explicitly keep proper GPU mode unavailable in
`iris-gui` until one exists.
Expand All @@ -649,10 +673,14 @@ 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. The `WgpuRenderer` has a test-only common-presenter handoff,
but the marker/presentation tests use a same-device test presenter, not a
real live window. Resident refresh no longer decodes DID on the CPU. Changed
VC2 state uploads at most the 64 KiB VC2 RAM and a 32-byte parameter block,
and CPU fallback. In the local presenter follow-up, 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
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
no longer decodes DID on the CPU. Changed VC2 state uploads at most the 64 KiB
VC2 RAM and a 32-byte parameter block,
then a GPU kernel expands DID before scanout; the 2 MiB decoded map is never
uploaded. The complete initial display-state transfer is below 128 KiB.
CPU-oracle parity covers disabled DID, malformed pointers, line-table
Expand All @@ -663,14 +691,16 @@ contents. The initial resident frame explicitly rejects nonzero retained CPU
DID history outside the area reconstructed by the current VC2 state. Before
production activation, define how a CPU-to-GPU transition or device
replacement preserves that history without violating the transfer contract.
Live integration and the labeled readback compositor mode remain open.
Production live integration, final on-screen validation and the labeled
readback compositor mode remain open.
`iris-gui` cannot select this mode.

The Windows gate `.\scripts\test-resident-gate.ps1` checks 25 resident CPU,
3 flat-fill and 3 direct-state tests, plus 10 resident GPU and 6
direct-scanout tests on each of Vulkan and D3D12. It requires the named
backend on an integrated/discrete adapter and fails rather than skipping
when unavailable; a single-backend run is not the complete gate. See
3 flat-fill and 3 direct-state tests, plus 10 resident GPU and 7
direct-scanout tests on each of Vulkan and D3D12, for 65 tests total. 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 gate. See
`TESTING.md` for commands and prerequisites.

### M3 - Command ABI and complete uber-shader
Expand Down
2 changes: 1 addition & 1 deletion scripts/test-resident-gate.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ try {
foreach ($name in $requestedBackends) {
$env:REX3_RESIDENT_BACKEND = $name
Invoke-ResidentTests 'resident_gpu_' 10 $true
Invoke-ResidentTests 'dev::ng1::wgpu::direct_tests' 6 $true
Invoke-ResidentTests 'dev::ng1::wgpu::direct_tests' 7 $true
}
} finally {
[Environment]::SetEnvironmentVariable('REX3_RESIDENT_BACKEND', $previousBackend, 'Process')
Expand Down
6 changes: 6 additions & 0 deletions src/dev/ng1/rex3.rs
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,12 @@ pub trait Renderer: Send {
) -> Result<(), String> {
Err("renderer does not support resident GPU frames".into())
}

#[cfg(all(test, feature = "wgpu"))]
fn resident_presented_frames(&self) -> Option<u64> { None }

#[cfg(all(test, feature = "wgpu"))]
fn resident_presented_texture(&self) -> Option<&wgpu::Texture> { None }
}

pub const REX3_SIZE: u32 = 0x2000; // 8KB
Expand Down
185 changes: 185 additions & 0 deletions src/dev/ng1/wgpu/direct_tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1422,6 +1422,191 @@ impl Drop for SharedTestBoard {
fn drop(&mut self) { self.0.stop(); }
}

#[cfg(any(windows, target_os = "linux"))]
fn read_presenter_texture(board: &Rex3, gpu: &Gpu, width: u32, height: u32) -> Vec<u32> {
let pitch = (width * 4).next_multiple_of(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT);
let size = u64::from(pitch) * u64::from(height);
let buffer = gpu.buffer(
"resident presenter test readback",
size,
wgpu::BufferUsages::COPY_SRC | wgpu::BufferUsages::COPY_DST,
);
let renderer = board.renderer.lock();
let texture = renderer.as_deref().unwrap().resident_presented_texture()
.expect("common presenter frame texture");
let mut encoder = gpu.encoder("resident presenter test readback");
encoder.copy_texture_to_buffer(
wgpu::TexelCopyTextureInfo {
texture,
mip_level: 0,
origin: wgpu::Origin3d::ZERO,
aspect: wgpu::TextureAspect::All,
},
wgpu::TexelCopyBufferInfo {
buffer: &buffer,
layout: wgpu::TexelCopyBufferLayout {
offset: 0,
bytes_per_row: Some(pitch),
rows_per_image: Some(height),
},
},
wgpu::Extent3d { width, height, depth_or_array_layers: 1 },
);
gpu.submit(encoder);
drop(renderer);
let bytes = Staging::default().read(gpu, &buffer, &[(0, size)])
.expect("presenter frame texture readback");
let mut pixels = Vec::with_capacity(width as usize * height as usize);
for row in bytes.chunks_exact(pitch as usize) {
pixels.extend(
row[..width as usize * 4].chunks_exact(4)
.map(|pixel| u32::from_le_bytes(pixel.try_into().unwrap())),
);
}
assert_eq!(pixels.len(), width as usize * height as usize);
pixels
}

#[cfg(any(windows, target_os = "linux"))]
fn run_common_presenter_window_test() {
use winit::platform::pump_events::EventLoopExtPumpEvents;

struct Pump;
impl winit::application::ApplicationHandler for Pump {
fn resumed(&mut self, _event_loop: &winit::event_loop::ActiveEventLoop) {}

fn window_event(
&mut self,
_event_loop: &winit::event_loop::ActiveEventLoop,
_window_id: winit::window::WindowId,
_event: winit::event::WindowEvent,
) {}
}

let gpu = required_gpu();
let (rgb, aux) = seed_planes();
let mut expected_rgb = rgb.clone();
let mut expected_aux = aux.clone();
let mut rex = Box::new(Rex3::new(crate::disp::StatusSource::detached()));
rex.fb_rgb.get_mut().copy_from_slice(&rgb);
rex.fb_aux.get_mut().copy_from_slice(&aux);
rex.fb_rgb.get_mut().isolate().unwrap();
rex.fb_aux.get_mut().isolate().unwrap();
configure_board_display(&rex);
rex.activate_resident_gpu(Arc::clone(&gpu)).unwrap();
rex.fb_rgb.get_mut().reset_access_counts();
rex.fb_aux.get_mut().reset_access_counts();
let rgb_guard = unsafe { (&*rex.fb_rgb.get()).protect() }.unwrap();
let aux_guard = unsafe { (&*rex.fb_aux.get()).protect() }.unwrap();
let board = SharedTestBoard(Arc::from(rex));

let mut builder = winit::event_loop::EventLoop::builder();
#[cfg(windows)]
{
use winit::platform::windows::EventLoopBuilderExtWindows;
builder.with_any_thread(true);
}
#[cfg(target_os = "linux")]
{
use winit::platform::x11::EventLoopBuilderExtX11;
builder.with_any_thread(true);
}
let mut event_loop = builder.build().expect("create common-presenter event loop");
let gfx: Arc<dyn GfxDisplay> = board.0.clone();
let attrs = winit::window::Window::default_attributes()
.with_title("IRIS resident presenter gate")
.with_inner_size(winit::dpi::PhysicalSize::new(320, 256));
let window = crate::ui::install_test_wgpu_renderer(&gfx, &event_loop, attrs)
.expect("install common wgpu presenter");
let mut pump = Pump;
event_loop.pump_app_events(Some(std::time::Duration::ZERO), &mut pump);
assert!(board.0.renderer.lock().as_deref().unwrap().takes_gpu_frames());

board.0.start();
let mut display = ResidentDisplay::new(&board.0, &gpu).expect("bind common presenter");
let mut fill = fill_context();
fill.drawmode0.0 |= 1 << 5;
draw_reference(fill.clone(), &mut expected_rgb, &mut expected_aux);
enqueue_fill(&board.0, &fill);
let stamp = display.render(&board.0, std::time::Duration::from_secs(5), |_| {})
.expect("present resident frame to the window");
event_loop.pump_app_events(Some(std::time::Duration::ZERO), &mut pump);

assert_eq!((stamp.width as usize, stamp.height as usize), (WIDTH, HEIGHT));
assert_eq!(board.0.renderer.lock().as_deref().unwrap().resident_presented_frames(), Some(1));
let first = software_frame(&board.0, &expected_rgb, &expected_aux);
assert!(first != software_frame(&board.0, &rgb, &aux), "resident fill must change the frame");
assert_pixels_eq(
"presenter texture after first draw",
&read_presenter_texture(&board.0, &gpu, WIDTH as u32, HEIGHT as u32),
&first,
);

let mut later = fill.clone();
later.colorred = 0xd0 << 11;
later.colorgrn = 0x15 << 11;
later.colorblue = 0x41 << 11;
draw_reference(later.clone(), &mut expected_rgb, &mut expected_aux);
enqueue_fill(&board.0, &later);
let next = display.render(&board.0, std::time::Duration::from_secs(5), |_| {})
.expect("present the later resident draw");
event_loop.pump_app_events(Some(std::time::Duration::ZERO), &mut pump);
assert_ne!(next.position, stamp.position);
let second = software_frame(&board.0, &expected_rgb, &expected_aux);
assert!(second != first, "later draw must change the presented pixels");
assert_pixels_eq(
"presenter texture after later draw",
&read_presenter_texture(&board.0, &gpu, WIDTH as u32, HEIGHT as u32),
&second,
);

{
let mut vc2 = board.0.vc2.lock();
vc2.ram[0x200] = 0x8000 | (((WIDTH - 16) as u16 / 2) << 8);
vc2.dirty = true;
}
let resized = display.render(&board.0, std::time::Duration::from_secs(5), |_| {})
.expect("present the resized resident frame");
event_loop.pump_app_events(Some(std::time::Duration::ZERO), &mut pump);
assert_eq!((resized.width as usize, resized.height as usize), (WIDTH - 16, HEIGHT));
assert_eq!(resized.position, next.position);
let resized_expected = software_frame(&board.0, &expected_rgb, &expected_aux);
assert_pixels_eq(
"presenter texture after resize",
&read_presenter_texture(&board.0, &gpu, resized.width, resized.height),
&resized_expected,
);

assert_eq!(board.0.renderer.lock().as_deref().unwrap().resident_presented_frames(), Some(3));
assert_eq!(display.traffic().composed_readbacks.attempts, 0);
assert_no_plane_traffic(display.traffic());
let status = board.0.resident_status().unwrap();
assert_eq!(status.observations, ObservationCounters::default());
assert_eq!(status.raw_plane_map_attempts, 0);
assert_no_cpu_plane_access(&board.0);

board.0.stop();
drop(board.0.renderer.lock().take());
drop(window);
drop(gfx);
drop(event_loop);
drop(aux_guard);
drop(rgb_guard);
}

#[cfg(any(windows, target_os = "linux"))]
#[test]
#[ignore = "requires the requested conformant hardware GPU backend"]
fn resident_frame_gpu_common_presenter_pixels_without_routine_readback() {
std::thread::Builder::new()
.name("resident-common-presenter".into())
.stack_size(64 * 1024 * 1024)
.spawn(run_common_presenter_window_test)
.expect("spawn common presenter test")
.join()
.unwrap_or_else(|panic| std::panic::resume_unwind(panic));
}

#[test]
#[ignore = "requires the requested conformant hardware GPU backend"]
fn resident_frame_gpu_headless_screenshot_png_matches_cpu() {
Expand Down
19 changes: 19 additions & 0 deletions src/ui.rs
Original file line number Diff line number Diff line change
Expand Up @@ -953,6 +953,16 @@ impl Renderer for WgpuRenderer {
crate::disp::FB_STRIDE,
)
}

#[cfg(test)]
fn resident_presented_frames(&self) -> Option<u64> {
Some(self.presenter.frames)
}

#[cfg(test)]
fn resident_presented_texture(&self) -> Option<&wgpu::Texture> {
Some(self.presenter.frame_texture_for_test())
}
}

struct MouseDelta {
Expand Down Expand Up @@ -1419,6 +1429,15 @@ impl Ui {
}
}

#[cfg(all(test, feature = "wgpu", any(windows, target_os = "linux")))]
pub(crate) fn install_test_wgpu_renderer(
display: &Arc<dyn GfxDisplay>,
event_loop: &EventLoop<()>,
attrs: WindowAttributes,
) -> Result<Arc<Window>, String> {
Ui::new_wgpu(display, event_loop, attrs, 1).map(|(window, _, _, _)| window)
}

/// `Ui::run`'s event-loop state: `run_app` takes the old closure's captures as a struct.
struct UiApp {
ps2: Arc<Ps2Controller>,
Expand Down
Loading
Loading