diff --git a/clanker/plans/GPUTodo.md b/clanker/plans/GPUTodo.md index fc189b923..0cf583f2b 100644 --- a/clanker/plans/GPUTodo.md +++ b/clanker/plans/GPUTodo.md @@ -93,12 +93,11 @@ of copying a stale fork version over upstream changes. 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. + expansion can be parallelized while noting that reduced transfer traffic + may still make it worthwhile. The current shader runs rows in parallel but + decodes runs within each row serially. Follow the DID benchmark and + optimization plan below before claiming a performance win; this 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 @@ -606,6 +605,97 @@ instrumented occupancy over time. A filling GFIFO proves consumer backlog. A mostly empty GFIFO suggests that faster raster alone will not improve throughput. +### DID expansion follow-up (#731) + +The current GPU shader assigns one invocation per row. Each invocation parses +its runs sequentially and scans preceding line-table entries to preserve early +termination. With 1,024 active rows and no earlier terminator, that is up to +523,776 preceding-entry checks in total. Pixel writes also use source-level +masked read/modify/write operations on packed words; actual memory traffic +depends on the compiler and GPU. + +Before claiming a speedup, compare GPU expansion against the prior CPU DID +decoder and changed-map upload in the same resident raster/presenter pipeline, +using identical VC2 input, prior DID history and update cadence. Keep the CPU +path as an explicit benchmark baseline, not a production fallback: + +- Measure GPU expansion with timestamp queries where supported, CPU decode and + upload cost, and end-to-end frame latency including p50/p95. Record the + adapter, backend, resolution, run configuration and sample counts. +- Measure initialization separately from unchanged frames, cursor-only + register and bitmap changes, and actual DID-table changes. Include early + terminators, full-height tables, display enable/disable and retained rows. +- Count expansion dispatches and bytes by upload reason. The previous resident + path uploaded the 2 MiB DID map only when its decoded contents changed; + the GPU path still uploads changed VC2 RAM and expansion parameters. Do not + describe the 2 MiB saving as a per-frame or overall speedup. +- Verify full DID-map and composed-pixel parity with the CPU reference. + Exclude diagnostic readbacks from timed frames and require zero ordinary + raw-plane traffic and CPU raster fallback. + +The maintainer-proposed scheduler experiment was measured on 2026-11-14 on +an NVIDIA RTX 5070. The benchmark compiles both shader variants into the same +process and alternates their order across four rounds. Each round measures 64 +dispatches for a 1,280 x 1,024 map with either one run per row or adjacent +rows alternating among one, two, four and eight runs. Values below are p50 +microseconds; wall time is submit-through-map time amortized per dispatch: + +| Backend | Rows | 64 threads / 16 groups | 1 thread / 1,024 groups | Change | +| --- | --- | ---: | ---: | ---: | +| D3D12 timestamp | uniform | 262.912 | 146.848 | -44% | +| D3D12 timestamp | divergent | 289.184 | 147.264 | -49% | +| D3D12 wall | uniform | 288.886 | 160.044 | -45% | +| D3D12 wall | divergent | 318.438 | 161.169 | -49% | +| Vulkan wall | uniform | 198.870 | 169.878 | -15% | +| Vulkan wall | divergent | 243.495 | 183.703 | -25% | + +Vulkan's in-pass timestamps reported roughly 1 microsecond while the matching +wall measurements were 170-243 microseconds, so those timestamp values are +not credible and are excluded. That experiment selected the one-thread +workgroup as the serial baseline because both D3D12 metrics and Vulkan wall +time favored it. + +A second critical-path experiment on 2026-11-15 compared that baseline with +one 64-lane workgroup per scanline. Lane zero checks the line table and +publishes the row state in workgroup memory; all lanes then resolve their +pixels and write disjoint packed `u32` words, avoiding byte read/modify/write. +The same adapter, workloads, alternating order, rounds and sample count were +used: + +| Backend | Rows | Serial p50 / p95 | Packed p50 / p95 | Change | +| --- | --- | ---: | ---: | ---: | +| D3D12 timestamp | uniform | 145.184 / 218.496 | 89.152 / 90.112 | -39% / -59% | +| D3D12 timestamp | divergent | 145.728 / 234.176 | 95.872 / 97.824 | -34% / -58% | +| D3D12 wall p50 | uniform | 167.464 | 105.053 | -37% | +| D3D12 wall p50 | divergent | 168.086 | 114.334 | -32% | +| Vulkan wall p50 | uniform | 166.347 | 107.412 | -35% | +| Vulkan wall p50 | divergent | 169.342 | 121.675 | -28% | + +The packed cooperative entry remains selected and the 65-test Vulkan+D3D12 +resident gate passes. This is still only a scheduler microbenchmark: it does +not include VC2 uploads, composition, presentation, the CPU decoder baseline +or end-to-end frame latency, and is not evidence that GPU DID expansion is +faster overall. Run the current serial-versus-packed comparison with: + +```powershell +$env:LIBCHDMAN_FORCE_SOURCE = '1' +$env:REX3_RESIDENT_BACKEND = 'dx12' # or vulkan +cargo test --locked -p iris --lib --features wgpu,rex-jit,rexdiag did_expansion_dispatch_latency -- --ignored --nocapture --test-threads=1 +``` + +If measurements justify optimization, investigate DID-specific invalidation +so cursor-only changes do not unnecessarily re-expand the map. VC2 updates +must still reach the compositor and trigger presentation where needed; changes +that might affect DID tables must conservatively invalidate. Test cursor-only +updates, DID pointer/table and geometry changes, early termination, inactive +display controls and preserved DID history. + +Packed-word writes now replace the per-byte update loop. Consider a shared +GPU terminator prepass only if end-to-end measurements show that the remaining +per-row scans matter enough to repay another dispatch on the decode-to-compose +critical path. Preserve untouched bytes and rows, and rerun the full +correctness and no-readback gates after any change. + ## Milestones ### M0 - Rebase the architecture, not the prototype diff --git a/src/dev/ng1/wgpu/did_bench_tests.rs b/src/dev/ng1/wgpu/did_bench_tests.rs new file mode 100644 index 000000000..a5b48f672 --- /dev/null +++ b/src/dev/ng1/wgpu/did_bench_tests.rs @@ -0,0 +1,326 @@ +use std::sync::Arc; +use std::time::Instant; + +use super::direct::DID_EXPAND; +use super::VC2_WORDS; +use crate::disp::{FB_MAX_H, FB_STRIDE}; +use crate::wgpu::{Gpu, GpuOptions, Source}; + +const WIDTH: u32 = 1280; +const HEIGHT: u32 = 1024; +const DID_PTR: usize = 0x100; +const RUNS_PTR: usize = 0x1000; +const SAMPLES: u32 = 64; +const ROUNDS: usize = 4; + +#[repr(C)] +#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)] +struct DidParams { + did_ptr: u32, + scan_len: u32, + width: u32, + height: u32, + enabled: u32, + display_on: u32, + pad: [u32; 2], +} + +#[derive(Default)] +struct Measurements { + timestamp_ns: Vec, + wall_ns: Vec, +} + +#[derive(Clone, Copy)] +struct Variant { + name: &'static str, + entry: &'static str, + threads_per_workgroup: u32, + workgroups: u32, + production: bool, +} + +const VARIANTS: [Variant; 2] = [ + Variant { + name: "serial", + entry: "expand_did_serial", + threads_per_workgroup: 1, + workgroups: HEIGHT, + production: false, + }, + Variant { + name: "packed", + entry: "expand_did", + threads_per_workgroup: 64, + workgroups: HEIGHT, + production: true, + }, +]; + +fn required_gpu() -> Arc { + let backend = std::env::var("REX3_RESIDENT_BACKEND").unwrap_or_else(|_| "auto".into()); + let expected = match backend.as_str() { + "vulkan" => Some(wgpu::Backend::Vulkan), + "dx12" => Some(wgpu::Backend::Dx12), + "metal" => Some(wgpu::Backend::Metal), + "gl" => Some(wgpu::Backend::Gl), + "auto" => None, + _ => panic!("unknown required backend {backend}"), + }; + let gpu = Gpu::new(&GpuOptions { + backend: backend.clone(), + ..GpuOptions::default() + }) + .unwrap_or_else(|error| panic!("required DID benchmark backend {backend}: {error}")); + if let Some(expected) = expected { + assert_eq!( + gpu.caps.backend, expected, + "the requested backend must actually be used" + ); + } + assert!( + matches!( + gpu.caps.device_type, + wgpu::DeviceType::DiscreteGpu | wgpu::DeviceType::IntegratedGpu + ), + "DID benchmark requires a hardware adapter: {}", + gpu.caps, + ); + assert!( + gpu.device + .features() + .contains(wgpu::Features::TIMESTAMP_QUERY), + "DID benchmark requires timestamp queries: {}", + gpu.caps, + ); + eprintln!("DID expansion benchmark adapter: {}", gpu.caps); + gpu +} + +fn did_ram(divergent: bool) -> Vec { + let mut ram = vec![0; VC2_WORDS]; + let run_counts = [1u32, 2, 4, 8]; + let mut pointers = [0u16; 4]; + let mut ptr = RUNS_PTR; + + for (pattern, &runs) in run_counts.iter().enumerate() { + pointers[pattern] = ptr as u16; + ram[ptr] = pattern as u16; + ptr += 1; + for run in 1..runs { + let x = WIDTH * run / runs; + ram[ptr] = ((x << 5) | ((pattern as u32 + run) & 0x1f)) as u16; + ptr += 1; + } + ram[ptr] = 0xffe0; + ptr += 1; + } + + for y in 0..HEIGHT as usize { + ram[DID_PTR + y] = pointers[if divergent { y % pointers.len() } else { 0 }]; + } + ram +} + +fn measure( + gpu: &Gpu, + pipeline: &wgpu::ComputePipeline, + group: &wgpu::BindGroup, + label: &'static str, + variant: Variant, +) -> (Vec, f64) { + let mut warmup = gpu.encoder("DID expansion benchmark warmup"); + { + let mut pass = warmup.begin_compute_pass(&wgpu::ComputePassDescriptor { + label: Some("DID expansion benchmark warmup"), + timestamp_writes: None, + }); + pass.set_pipeline(pipeline); + pass.set_bind_group(0, group, &[]); + pass.dispatch_workgroups(variant.workgroups, 1, 1); + } + let submission = gpu.submit(warmup); + gpu.wait(Some(submission)) + .expect("wait for DID benchmark warmup"); + + let count = 2 * SAMPLES; + let queries = gpu.device.create_query_set(&wgpu::QuerySetDescriptor { + label: Some("DID expansion benchmark timestamps"), + ty: wgpu::QueryType::Timestamp, + count, + }); + let bytes = u64::from(count) * size_of::() as u64; + let resolve = gpu.buffer( + "DID expansion benchmark resolve", + bytes, + wgpu::BufferUsages::QUERY_RESOLVE | wgpu::BufferUsages::COPY_SRC, + ); + let read = gpu.buffer( + "DID expansion benchmark readback", + bytes, + wgpu::BufferUsages::MAP_READ | wgpu::BufferUsages::COPY_DST, + ); + let mut encoder = gpu.encoder("DID expansion benchmark"); + for sample in 0..SAMPLES { + let mut pass = encoder.begin_compute_pass(&wgpu::ComputePassDescriptor { + label: Some(label), + timestamp_writes: Some(wgpu::ComputePassTimestampWrites { + query_set: &queries, + beginning_of_pass_write_index: Some(2 * sample), + end_of_pass_write_index: Some(2 * sample + 1), + }), + }); + pass.set_pipeline(pipeline); + pass.set_bind_group(0, group, &[]); + pass.dispatch_workgroups(variant.workgroups, 1, 1); + } + encoder.resolve_query_set(&queries, 0..count, &resolve, 0); + encoder.copy_buffer_to_buffer(&resolve, 0, &read, 0, bytes); + let started = Instant::now(); + let submission = gpu.submit(encoder); + let slice = read.slice(..); + slice.map_async(wgpu::MapMode::Read, |_| {}); + gpu.wait(Some(submission)).expect("wait for DID benchmark"); + gpu.wait(None).expect("finish DID benchmark mapping"); + let mapped = slice + .get_mapped_range() + .expect("map DID benchmark timestamps"); + let period_ns = f64::from(gpu.queue.get_timestamp_period()); + let mut samples = mapped + .chunks_exact(2 * size_of::()) + .map(|pair| { + let begin = u64::from_le_bytes(pair[..8].try_into().unwrap()); + let end = u64::from_le_bytes(pair[8..16].try_into().unwrap()); + end.saturating_sub(begin) as f64 * period_ns + }) + .collect::>(); + drop(mapped); + read.unmap(); + samples.sort_by(f64::total_cmp); + let wall_ns = started.elapsed().as_secs_f64() * 1_000_000_000.0 / f64::from(SAMPLES); + (samples, wall_ns) +} + +fn report(label: &str, variant: Variant, measurements: &Measurements) { + let mut samples = measurements.timestamp_ns.clone(); + samples.sort_by(f64::total_cmp); + let mut wall = measurements.wall_ns.clone(); + wall.sort_by(f64::total_cmp); + let percentile = |percent: usize| samples[(samples.len() - 1) * percent / 100] / 1_000.0; + eprintln!( + "DID expansion {label} {}: threads/workgroup={} workgroups={} \ + production={} samples={} timestamp \ + min={:.3}us p50={:.3}us p95={:.3}us max={:.3}us wall-p50={:.3}us", + variant.name, + variant.threads_per_workgroup, + variant.workgroups, + variant.production, + samples.len(), + samples[0] / 1_000.0, + percentile(50), + percentile(95), + samples[samples.len() - 1] / 1_000.0, + wall[wall.len() / 2] / 1_000.0, + ); +} + +#[test] +#[ignore = "manual hardware latency benchmark"] +fn did_expansion_dispatch_latency() { + let gpu = required_gpu(); + let entry = |binding, ty| wgpu::BindGroupLayoutEntry { + binding, + visibility: wgpu::ShaderStages::COMPUTE, + ty: wgpu::BindingType::Buffer { + ty, + has_dynamic_offset: false, + min_binding_size: None, + }, + count: None, + }; + let layout = gpu + .device + .create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor { + label: Some("DID expansion benchmark"), + entries: &[ + entry(0, wgpu::BufferBindingType::Storage { read_only: true }), + entry(1, wgpu::BufferBindingType::Storage { read_only: false }), + entry(2, wgpu::BufferBindingType::Uniform), + ], + }); + let pipelines: [wgpu::ComputePipeline; 2] = std::array::from_fn(|index| { + let variant = VARIANTS[index]; + Source::new(&format!("DID expansion benchmark {}", variant.name)) + .body(DID_EXPAND) + .compute_pipeline(&gpu.device, variant.entry, &[&layout]) + .expect("create DID expansion benchmark pipeline") + }); + let vc2 = gpu.buffer( + "DID expansion benchmark VC2 RAM", + (2 * VC2_WORDS) as u64, + wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST, + ); + let did = gpu.buffer( + "DID expansion benchmark map", + (FB_STRIDE * FB_MAX_H) as u64, + wgpu::BufferUsages::STORAGE | wgpu::BufferUsages::COPY_DST, + ); + let params = gpu.buffer( + "DID expansion benchmark parameters", + size_of::() as u64, + wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST, + ); + let group = gpu.device.create_bind_group(&wgpu::BindGroupDescriptor { + label: Some("DID expansion benchmark"), + layout: &layout, + entries: &[ + wgpu::BindGroupEntry { + binding: 0, + resource: vc2.as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 1, + resource: did.as_entire_binding(), + }, + wgpu::BindGroupEntry { + binding: 2, + resource: params.as_entire_binding(), + }, + ], + }); + gpu.write( + ¶ms, + 0, + bytemuck::bytes_of(&DidParams { + did_ptr: DID_PTR as u32, + scan_len: WIDTH, + width: WIDTH, + height: HEIGHT, + enabled: 1, + display_on: 1, + pad: [0; 2], + }), + ); + + let workloads = [("uniform", false), ("divergent", true)]; + let mut results: [[Measurements; 2]; 2] = + std::array::from_fn(|_| std::array::from_fn(|_| Measurements::default())); + for round in 0..ROUNDS { + let order = if round % 2 == 0 { [0, 1] } else { [1, 0] }; + for workload in order { + let (label, divergent) = workloads[workload]; + gpu.write(&vc2, 0, bytemuck::cast_slice(&did_ram(divergent))); + for variant in order { + let (samples, wall_ns) = + measure(&gpu, &pipelines[variant], &group, label, VARIANTS[variant]); + results[workload][variant].timestamp_ns.extend(samples); + results[workload][variant].wall_ns.push(wall_ns); + } + } + } + for (workload, (label, _)) in workloads.iter().enumerate() { + for (variant, config) in VARIANTS.iter().copied().enumerate() { + report(label, config, &results[workload][variant]); + } + } +} diff --git a/src/dev/ng1/wgpu/direct.rs b/src/dev/ng1/wgpu/direct.rs index a7db429c8..b63d7704d 100644 --- a/src/dev/ng1/wgpu/direct.rs +++ b/src/dev/ng1/wgpu/direct.rs @@ -15,7 +15,9 @@ use crate::wgpu::{Fragment, Gpu, Scanout, ScanoutPipeline, ScanoutShaders, Sourc const HEIGHT: usize = REX3_SCREEN_HEIGHT as usize; const DID_BYTES: usize = FB_STRIDE * HEIGHT; const MAX_PIXELS: u32 = (FB_STRIDE * HEIGHT) as u32; -const DID_EXPAND: Fragment = +// Each workgroup owns one scanline; its lanes write disjoint packed words. +pub(super) const DID_WORKGROUPS: u32 = HEIGHT as u32; +pub(super) const DID_EXPAND: Fragment = Fragment::new("ng1_did_expand.wgsl", include_str!("shaders/did_expand.wgsl")); fn scanout_error(error: String) -> ResidentError { @@ -306,7 +308,7 @@ impl Ng1ResidentScanout { }); pass.set_pipeline(&self.did_pipeline); pass.set_bind_group(0, group, &[]); - pass.dispatch_workgroups((HEIGHT as u32).div_ceil(64), 1, 1); + pass.dispatch_workgroups(DID_WORKGROUPS, 1, 1); } gpu.submit(encoder); gpu.check().map_err(scanout_error) diff --git a/src/dev/ng1/wgpu/mod.rs b/src/dev/ng1/wgpu/mod.rs index 07cdfbae6..9036bb75b 100644 --- a/src/dev/ng1/wgpu/mod.rs +++ b/src/dev/ng1/wgpu/mod.rs @@ -31,6 +31,9 @@ pub(crate) mod direct; #[cfg(test)] mod direct_tests; +#[cfg(test)] +mod did_bench_tests; + const SCANOUT: Fragment = Fragment::new("ng1_scanout.wgsl", include_str!("shaders/scanout.wgsl")); const CPU_BINDINGS: Fragment = Fragment::new("ng1_bindings.wgsl", include_str!("shaders/scanout_cpu_bindings.wgsl")); #[cfg(test)] diff --git a/src/dev/ng1/wgpu/shaders/did_expand.wgsl b/src/dev/ng1/wgpu/shaders/did_expand.wgsl index dfb4f3f4f..b7949ebe3 100644 --- a/src/dev/ng1/wgpu/shaders/did_expand.wgsl +++ b/src/dev/ng1/wgpu/shaders/did_expand.wgsl @@ -33,8 +33,8 @@ fn fill_run(y: u32, start: u32, end: u32, value: u32) { } } -@compute @workgroup_size(64) -fn expand_did(@builtin(global_invocation_id) id: vec3) { +@compute @workgroup_size(1) +fn expand_did_serial(@builtin(global_invocation_id) id: vec3) { let y = id.x; if y >= 1024u { return; @@ -111,3 +111,139 @@ fn expand_did(@builtin(global_invocation_id) id: vec3) { } } } + +const DID_ROW_LANES: u32 = 64u; +const MODE_PRESERVE: u32 = 0u; +const MODE_ZERO: u32 = 1u; +const MODE_DECODE: u32 = 2u; + +var row_mode: u32; +var row_line_ptr: u32; +var row_write_len: u32; +var row_ram_words: u32; + +fn store_packed(y: u32, word_x: u32, value: u32, pixels: u32) { + let index = y * 512u + word_x; + if pixels == 4u { + did_map[index] = value; + } else { + let mask = 0xffffffffu >> (32u - pixels * 8u); + did_map[index] = (did_map[index] & ~mask) | (value & mask); + } +} + +fn zero_words(y: u32, len: u32, lane: u32) { + let words = (len + 3u) >> 2u; + var word_x = lane; + while word_x < words { + let start = word_x * 4u; + store_packed(y, word_x, 0u, min(4u, len - start)); + word_x += DID_ROW_LANES; + } +} + +fn did_at(line_ptr: u32, x: u32, effective_len: u32, ram_words: u32) -> u32 { + var ptr = line_ptr; + var current_did = vc2_word(ptr) & 0x1fu; + var current_x = 0u; + ptr += 1u; + + loop { + if ptr >= ram_words { + return current_did; + } + let next = vc2_word(ptr); + let next_x_raw = (next >> 5u) & 0x7ffu; + let next_did = next & 0x1fu; + let eol = next_x_raw == 0x7ffu; + let next_x = select(next_x_raw, effective_len, eol); + let run_end = min(max(next_x, current_x), effective_len); + if x < run_end { + return current_did; + } + current_x = run_end; + current_did = next_did; + ptr += 1u; + if eol || current_x >= effective_len { + return current_did; + } + } + return current_did; +} + +fn decode_words(y: u32, line_ptr: u32, len: u32, ram_words: u32, lane: u32) { + let words = (len + 3u) >> 2u; + var word_x = lane; + while word_x < words { + let start = word_x * 4u; + let pixels = min(4u, len - start); + var packed = 0u; + var pixel = 0u; + while pixel < pixels { + packed |= did_at(line_ptr, start + pixel, len, ram_words) << (pixel * 8u); + pixel += 1u; + } + store_packed(y, word_x, packed, pixels); + word_x += DID_ROW_LANES; + } +} + +@compute @workgroup_size(DID_ROW_LANES) +fn expand_did( + @builtin(workgroup_id) group_id: vec3, + @builtin(local_invocation_id) local_id: vec3, +) { + let y = group_id.x; + let lane = local_id.x; + if lane == 0u { + row_mode = MODE_PRESERVE; + row_line_ptr = 0u; + row_write_len = 0u; + row_ram_words = arrayLength(&vc2_ram) * 2u; + + if y < 1024u && params.display_on != 0u { + if params.enabled == 0u { + row_mode = MODE_ZERO; + row_write_len = 2048u; + } else if y < params.height { + var prior = 0u; + var terminated = false; + while prior < y { + let prior_table = params.did_ptr + prior; + if prior_table >= row_ram_words || vc2_word(prior_table) == 0xffffu { + terminated = true; + break; + } + prior += 1u; + } + + if !terminated { + let table = params.did_ptr + y; + if table < row_ram_words { + let line_ptr = vc2_word(table); + if line_ptr != 0xffffu { + row_write_len = select( + params.width, + params.scan_len, + params.scan_len > 0u && params.scan_len <= 2048u, + ); + if line_ptr >= row_ram_words { + row_mode = MODE_ZERO; + } else { + row_mode = MODE_DECODE; + row_line_ptr = line_ptr; + } + } + } + } + } + } + } + + workgroupBarrier(); + if row_mode == MODE_ZERO { + zero_words(y, row_write_len, lane); + } else if row_mode == MODE_DECODE { + decode_words(y, row_line_ptr, row_write_len, row_ram_words, lane); + } +}