diff --git a/HACKING.md b/HACKING.md index 952ed2b6e..a98760be2 100644 --- a/HACKING.md +++ b/HACKING.md @@ -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 diff --git a/TESTING.md b/TESTING.md index 6b1b9c0e5..ce1221c63 100644 --- a/TESTING.md +++ b/TESTING.md @@ -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 @@ -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 diff --git a/clanker/plans/GPUTodo.md b/clanker/plans/GPUTodo.md index eb6d275d0..fc189b923 100644 --- a/clanker/plans/GPUTodo.md +++ b/clanker/plans/GPUTodo.md @@ -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. @@ -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 @@ -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 @@ -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. @@ -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 @@ -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 diff --git a/scripts/test-resident-gate.ps1 b/scripts/test-resident-gate.ps1 index bc1d84845..5b05491e6 100644 --- a/scripts/test-resident-gate.ps1 +++ b/scripts/test-resident-gate.ps1 @@ -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') diff --git a/src/dev/ng1/rex3.rs b/src/dev/ng1/rex3.rs index 4cd32f152..b1b52a95a 100644 --- a/src/dev/ng1/rex3.rs +++ b/src/dev/ng1/rex3.rs @@ -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 { None } + + #[cfg(all(test, feature = "wgpu"))] + fn resident_presented_texture(&self) -> Option<&wgpu::Texture> { None } } pub const REX3_SIZE: u32 = 0x2000; // 8KB diff --git a/src/dev/ng1/wgpu/direct_tests.rs b/src/dev/ng1/wgpu/direct_tests.rs index 93fc445ec..24dcf6b4b 100644 --- a/src/dev/ng1/wgpu/direct_tests.rs +++ b/src/dev/ng1/wgpu/direct_tests.rs @@ -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 { + 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 = 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() { diff --git a/src/ui.rs b/src/ui.rs index 9b8a29db2..0760c8a9b 100644 --- a/src/ui.rs +++ b/src/ui.rs @@ -953,6 +953,16 @@ impl Renderer for WgpuRenderer { crate::disp::FB_STRIDE, ) } + + #[cfg(test)] + fn resident_presented_frames(&self) -> Option { + Some(self.presenter.frames) + } + + #[cfg(test)] + fn resident_presented_texture(&self) -> Option<&wgpu::Texture> { + Some(self.presenter.frame_texture_for_test()) + } } struct MouseDelta { @@ -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, + event_loop: &EventLoop<()>, + attrs: WindowAttributes, +) -> Result, 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, diff --git a/src/wgpu/present.rs b/src/wgpu/present.rs index 06425eab3..4aa2d6f84 100644 --- a/src/wgpu/present.rs +++ b/src/wgpu/present.rs @@ -208,6 +208,8 @@ impl Presenter { let mut usage = wgpu::TextureUsages::TEXTURE_BINDING | wgpu::TextureUsages::COPY_DST; if storage { usage |= wgpu::TextureUsages::STORAGE_BINDING; + #[cfg(test)] + { usage |= wgpu::TextureUsages::COPY_SRC; } } let texture = device.create_texture(&wgpu::TextureDescriptor { label: Some(label), @@ -292,6 +294,11 @@ impl Presenter { &self.gpu } + #[cfg(test)] + pub(crate) fn frame_texture_for_test(&self) -> &wgpu::Texture { + &self.frame.texture + } + /// The window's new size in pixels. pub fn resize(&mut self, width: u32, height: u32) { let (w, h) = (width.max(1), height.max(1));