Skip to content
Open
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
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,8 @@ hashes are given where a change is easiest to understand by reading the commit.

### Display

- Display buffers now start smaller and grow only for taller video modes; Newport-only
planes and debug overlays are allocated on demand. All machines use less host RAM.
- VPro (Octane, Fuel, Tezro): 16-bit colour-index images put by the X
server now appear, on the CPU raster and the GPU raster unit; LightWave
Modeler's viewports showed no grid, labels or model.
Expand Down
7 changes: 7 additions & 0 deletions HACKING.md
Original file line number Diff line number Diff line change
Expand Up @@ -1298,6 +1298,13 @@ separate CPU cache before using the ordinary renderer.
`wait_fresh_frame` says whether the board composed a new frame in time, so a
caller can tell a fresh screenshot from a repeat of the last one.

The shared frame and readback buffers start at 1024 rows and grow to the
highest active mode, up to `FB_MAX_H`. Newport's auxiliary and DID planes are
allocated only by a Newport display-state refresh. Software compositors and
debug overlays likewise allocate for their active frame height instead of
reserving 2048 rows up front. A producer that writes `fb_rgb`, or a renderer
that fills `rgba`, must first ensure the corresponding row count.

Nothing downstream looks inside the drawing code. The VNC server
(`src/vnc/`) finds damage by comparing frames in 64x64 tiles, so every board
is served the same way and drawing paths carry no bookkeeping.
Expand Down
1 change: 1 addition & 0 deletions clanker/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -429,6 +429,7 @@ Host performance: idle parking, thread parking, GFIFO, benchmarks.
| Note | Kind | Title |
|---|---|---|
| [decode-cache-conflicts-vary-by-boot.md](perf/decode-cache-conflicts-vary-by-boot.md) | measure | The shadow cache's 64-page decode cache conflicts differently on every boot: up to 25% interpreter variance per boot, gone with 256 pages; compare builds over several boots |
| [display-buffers-grow-on-demand.md](perf/display-buffers-grow-on-demand.md) | rule | Display frame, readback, software-compositor and debug-overlay buffers grow to the active height; Newport-only planes are allocated on demand, and every direct writer must ensure its rows first |
| [bench-first-numbers.md](perf/bench-first-numbers.md) | history | First benchmark matrix — 2026-08-21 |
| [guest-compiler-changes-the-benchmark.md](perf/guest-compiler-changes-the-benchmark.md) | measure | The guest compiler is part of the benchmark: GCC 14.2 against 16.2.1 changes Dhrystone and rotate90 by 37% in guest instructions, and the pin that fixes it |
| [gfifo-backend-experiment.md](perf/gfifo-backend-experiment.md) | history | GFIFO backend: swappable ring for benchmarking — 2026-09-14 |
Expand Down
17 changes: 17 additions & 0 deletions clanker/perf/display-buffers-grow-on-demand.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Display buffers grow on demand

`Rex3Screen` used to reserve four 2048-row planes per head: RGB, auxiliary,
DID and composed readback (about 52 MiB). Newport's physical planes are only
1024 rows, and most other boards never use Newport's auxiliary or DID planes.
The software compositor and debug overlay also reserved 2048-row buffers.

The shared RGB/readback buffers now start at 1024 rows. Newport allocates its
auxiliary and DID planes on its first display-state refresh. IMPACT, VPro,
InfiniteReality and O2 grow the composed frame buffer before writing taller
modes. Readback and presentation paths grow `rgba` before writing it. The
software compositor, iris-gui GL capture buffer and debug overlay allocate to
the active height.

Buffers only grow, so a mode change does not repeatedly reallocate them. Any
new direct writer must call `ensure_fb_rows` or `ensure_rgba_rows` first; do
not reintroduce a fixed 2048-row allocation to avoid that call.
5 changes: 3 additions & 2 deletions iris-gui/src/framebuffer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -323,14 +323,14 @@ impl Renderer for GlCaptureRenderer {
return;
}

let needed = FB_STRIDE * iris::disp::FB_MAX_H;
let needed = FB_STRIDE * height;
if self.rgba.len() < needed {
self.rgba.resize(needed, 0);
}
if screen.prebuilt {
// GR2 hands over a finished frame (stride 2048, RGBA bytes):
// no GPU round trip needed.
self.rgba.copy_from_slice(&screen.fb_rgb[..needed]);
self.rgba[..needed].copy_from_slice(&screen.fb_rgb[..needed]);
} else {
let src = screen.compositor_source_from(live_fb_rgb, live_fb_aux);
let gl = &self.headless.gl;
Expand Down Expand Up @@ -427,6 +427,7 @@ fn mirror_band(
dirty_y: u32,
dirty_h: u32,
) {
screen.ensure_rgba_rows(height);
let first = dirty_y as usize;
let last = (first + dirty_h as usize).min(height);
for y in first..last {
Expand Down
28 changes: 26 additions & 2 deletions src/compositor.rs
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ pub trait Compositor: Send {
/// Pure-CPU compositor. Runs the per-pixel loop into a `Vec<u32>`, uploads to
/// a GL texture via `glTexSubImage2D`, and returns that texture.
pub struct SwCompositor {
/// CPU pixel buffer: stride 2048, `FB_MAX_H` rows.
/// CPU pixel buffer: stride 2048, grown to the tallest frame composed.
buf: Vec<u32>,
/// GL texture that holds the last uploaded frame.
tex: Option<glow::Texture>,
Expand All @@ -115,7 +115,7 @@ pub struct SwCompositor {
impl SwCompositor {
pub fn new() -> Self {
Self {
buf: vec![0u32; crate::disp::FB_STRIDE * crate::disp::FB_MAX_H],
buf: Vec::new(),
tex: None,
picture_current: false,
current_size: (0, 0),
Expand Down Expand Up @@ -157,6 +157,10 @@ impl SwCompositor {

let width = src.width;
let height = src.height;
let needed = crate::disp::FB_STRIDE * height.min(crate::disp::FB_MAX_H);
if self.buf.len() < needed {
self.buf.resize(needed, 0);
}

if let Some(frame) = src.prebuilt {
for y in 0..height {
Expand Down Expand Up @@ -393,4 +397,24 @@ mod tests {
// Another size: the texture holds a picture of another size.
assert!(!holds_current_picture(&src, true, (1280, 768)));
}

#[test]
fn the_pixel_buffer_tracks_the_tallest_active_frame() {
let tall = vec![0xff12_3456; crate::disp::FB_STRIDE * 1200];
let mut comp = SwCompositor::new();
comp.compose_pixels(&CompositorSource {
prebuilt: Some(&tall),
..source(1600, 1200, false)
});
assert_eq!(comp.pixels().len(), crate::disp::FB_STRIDE * 1200);
assert_eq!(comp.pixels()[1199 * crate::disp::FB_STRIDE], 0xff12_3456);

let small = vec![0xff65_4321; crate::disp::FB_STRIDE * 768];
comp.compose_pixels(&CompositorSource {
prebuilt: Some(&small),
..source(1280, 768, false)
});
assert_eq!(comp.pixels().len(), crate::disp::FB_STRIDE * 1200);
assert_eq!(comp.pixels()[0], 0xff65_4321);
}
}
9 changes: 7 additions & 2 deletions src/debug_overlay.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ pub struct SeenMode {
/// Debug overlay: renders CMAP swatches, DID/XMAP mode info, and draw-record
/// annotations into a GL texture that is alpha-blended over the compositor output.
pub struct DebugOverlay {
/// CPU pixel buffer for the overlay (transparent=0 where inactive), stride 2048.
/// CPU pixel buffer for the overlay (transparent=0 where inactive), stride
/// 2048. Empty until an overlay is drawn, then grown to the tallest frame.
buf: Vec<u32>,
/// GL texture backing the overlay.
tex: Option<glow::Texture>,
Expand All @@ -58,7 +59,7 @@ pub struct DebugOverlay {
impl DebugOverlay {
pub fn new() -> Self {
Self {
buf: vec![0u32; crate::disp::FB_STRIDE * crate::disp::FB_MAX_H],
buf: Vec::new(),
tex: None,
font: crate::vga_font::SCREEN_8X16.to_vec(),
show_cmap: false,
Expand Down Expand Up @@ -118,6 +119,10 @@ impl DebugOverlay {
pub fn render_pixels(&mut self, src: &OverlaySource<'_>) -> &[u32] {
let width = src.width;
let height = src.height;
let needed = crate::disp::FB_STRIDE * height.min(crate::disp::FB_MAX_H);
if self.buf.len() < needed {
self.buf.resize(needed, 0);
}

let display_ctrl = src.vc2_regs[VC2_REG_DISPLAY_CONTROL as usize];
let cursor_en = (display_ctrl & VC2_CTRL_CURSOR_EN) != 0;
Expand Down
1 change: 1 addition & 0 deletions src/dev/gr2/gr2disp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ impl Head for Gr2 {
/// There is nothing smaller to take than the composed frame.
fn capture(&self, screen: &mut Rex3Screen, _want: Want) -> bool {
let r = self.regs();
screen.ensure_fb_rows(FB_H);
gr2comp::compose(self.vram(), &r.vc1, &r.xmap, &r.dac, &mut screen.fb_rgb);
self.presentation_frames.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
self.presentation_host_read_pixels
Expand Down
1 change: 1 addition & 0 deletions src/dev/kona/back/display/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -282,6 +282,7 @@ impl Compositor {
let (w, h) = (self.store.width() as usize, self.store.height() as usize);
let tables = self.tables.lock().snapshot();
compose(&self.store, self.word, &map, &tables, &mut self.frame, w);
screen.ensure_fb_rows(h);
let stride = crate::disp::FB_STRIDE;
let width = w.min(stride);
let height = h.min(screen.fb_rgb.len() / stride);
Expand Down
4 changes: 4 additions & 0 deletions src/dev/mgras/disp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -392,6 +392,8 @@ impl crate::display::Head for Mgras {
return false;
}
if matches!(scan.taken, Taken::None) {
let (_, rows) = frame::display_size(&self.front_view().dcb);
screen.ensure_fb_rows(rows);
scan.taken = match self.compose_gpu_into(rss, &mut screen.fb_rgb) {
Some((w, h)) => Taken::Read(w, h),
None if self.gpu_failed() => {
Expand Down Expand Up @@ -458,6 +460,8 @@ impl crate::display::Head for Mgras {
// SAFETY: a read-only view of the framebuffer, read while
// the engines draw, as the board's scan-out reads it.
let rss = unsafe { &*self.rss.get() };
let (_, rows) = frame::display_size(&self.front_view().dcb);
screen.ensure_fb_rows(rows);
(screen.width, screen.height) = frame::compose_direct(rss, &self.front_view().dcb, &mut screen.fb_rgb);
Composed::Frame
}
Expand Down
2 changes: 2 additions & 0 deletions src/dev/ng1/rex3_frame.rs
Original file line number Diff line number Diff line change
Expand Up @@ -602,6 +602,7 @@ impl ResidentCompatibilityDisplay {
if matches!(fault, Some(CaptureFault::AfterStaging)) {
return Err(ResidentError::Failed("injected composed capture failure after staging".into()));
}
screen.ensure_rgba_rows(height);
for y in 0..height {
let row = y * FB_STRIDE;
screen.rgba[row..row + width]
Expand Down Expand Up @@ -734,6 +735,7 @@ impl ResidentDirectDisplay {
let after = self.scanout.traffic().composed_readbacks;
rex.resident_frame.capture_delta(ResidentDisplayMode::DirectWgpu, before, after)?;
result?;
screen.ensure_rgba_rows(height);
for y in 0..height {
let row = y * FB_STRIDE;
for (dst, &src) in screen.rgba[row..row + width]
Expand Down
8 changes: 6 additions & 2 deletions src/dev/o2gfx.rs
Original file line number Diff line number Diff line change
Expand Up @@ -646,7 +646,7 @@ impl Gbe {
///
/// Returns the size and whether any of `out` was written, or None when
/// the display is off or does not fit.
pub fn render_direct(&self, ram: &mut crate::dev::crime_mem::RamWindow, out: &mut [u32], stride: usize, memo: &mut ScanMemo) -> Option<(u32, u32, bool)> {
pub fn render_direct(&self, ram: &mut crate::dev::crime_mem::RamWindow, out: &mut Vec<u32>, stride: usize, memo: &mut ScanMemo) -> Option<(u32, u32, bool)> {
// The registers the scan reads, copied under the lock: the guest
// polls the beam through the same lock while the frame is made.
let (ctl, wids, crs) = {
Expand All @@ -664,9 +664,13 @@ impl Gbe {
};
let [hcmap, vcmap, ctrlstat, dotclock, vt_xy, vt_flags, tile, frm_pixel, frm, ovr, ovr_tile, did, crs_ctl, crs_pos] = ctl;
let (w, h) = (((hcmap >> 12) & 0xfff) as usize, ((vcmap >> 12) & 0xfff) as usize);
if (ctrlstat >> 28) & 3 != 3 || dotclock & DOTCLOCK_RUN == 0 || vt_xy & VT_FREEZE != 0 || w == 0 || h == 0 || vt_flags & 0xa == 0xa || w > stride || h * stride > out.len() {
if (ctrlstat >> 28) & 3 != 3 || dotclock & DOTCLOCK_RUN == 0 || vt_xy & VT_FREEZE != 0 || w == 0 || h == 0 || vt_flags & 0xa == 0xa || w > stride || h > crate::disp::FB_MAX_H {
return None;
}
let needed = h * stride;
if out.len() < needed {
out.resize(needed, 0);
}
ram.begin();
let ram = &*ram;
// Everything but the cursor's place, which only the bands under
Expand Down
2 changes: 2 additions & 0 deletions src/dev/odyssey/display.rs
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,8 @@ impl Display {
self.verify.lock().before(screen);
}
reader.force = verify;
reader.sync(shared);
screen.ensure_fb_rows(reader.frame_height as usize);
let composed = reader.update_to(Some((&mut screen.fb_rgb, FB_STRIDE)));
if shared.gpu_fault.lock().is_some() {
return Composed::NotReady;
Expand Down
2 changes: 1 addition & 1 deletion src/dev/odyssey/reader.rs
Original file line number Diff line number Diff line change
Expand Up @@ -606,7 +606,7 @@ impl ScanoutReader {
}

/// Take a new mode and retrace restart the front end published.
fn sync(&mut self, shared: &DisplayShared) {
pub fn sync(&mut self, shared: &DisplayShared) {
let cell = &shared.mode;
let (gen, restart) = (cell.gen.load(Acquire), cell.restart.load(Acquire));
let mode = ScanoutMode {
Expand Down
78 changes: 73 additions & 5 deletions src/disp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,10 @@ pub const FB_STRIDE: usize = 2048;
/// board can hand over (Newport and GR2 use the first 1024; IMPACT's
/// 1600x1200 modes need more).
pub const FB_MAX_H: usize = 2048;
/// Rows in Newport's physical framebuffer planes. This is also the initial
/// height of the shared frame/readback buffers; taller boards grow them on
/// demand.
const BASE_FB_ROWS: usize = 1024;

/// Independent revisions of the cached Newport display state. The source
/// identifies the screen that issued them, so replacing a screen cannot make
Expand Down Expand Up @@ -83,7 +87,9 @@ pub struct Rex3Screen {
pub width: usize,
pub height: usize,

// Framebuffer snapshots (copied from Rex3::fb_rgb / fb_aux each frame)
// Framebuffer snapshots (copied from Rex3::fb_rgb / fb_aux each frame).
// The shared RGB plane starts at 1024 rows and grows for taller boards;
// the Newport-only auxiliary plane is allocated on its first refresh.
pub fb_rgb: Vec<u32>,
pub fb_aux: Vec<u32>,
#[cfg(feature = "rex-dirty-upload")]
Expand Down Expand Up @@ -155,8 +161,11 @@ impl Rex3Screen {
Self {
width: 0,
height: 0,
fb_rgb: vec![0u32; FB_STRIDE * FB_MAX_H],
fb_aux: vec![0u32; FB_STRIDE * FB_MAX_H],
fb_rgb: vec![0u32; FB_STRIDE * BASE_FB_ROWS],
// Newport's auxiliary plane and decoded window IDs are allocated
// only when Newport display state is refreshed. Other boards
// compose straight into fb_rgb and never use either plane.
fb_aux: Vec::new(),
#[cfg(feature = "rex-dirty-upload")]
fb_rgb_damage: Vec::new(),
#[cfg(feature = "rex-dirty-upload")]
Expand All @@ -165,8 +174,8 @@ impl Rex3Screen {
fb_rgb_tiles: 0,
#[cfg(feature = "rex-dirty-upload")]
fb_aux_tiles: 0,
did: vec![0u8; FB_STRIDE * FB_MAX_H],
rgba: vec![0u32; FB_STRIDE * FB_MAX_H],
did: Vec::new(),
rgba: vec![0u32; FB_STRIDE * BASE_FB_ROWS],
vc2_ram: vec![0u16; 32768],
vc2_regs: [0u16; 32],
cmap: [0u32; 8192],
Expand All @@ -192,6 +201,39 @@ impl Rex3Screen {
}
}

/// Ensure the composed-frame buffer has `rows` rows. Buffers only grow:
/// a later, smaller mode reuses the allocation instead of reallocating.
pub fn ensure_fb_rows(&mut self, rows: usize) {
let words = FB_STRIDE * rows.min(FB_MAX_H);
if self.fb_rgb.len() < words {
self.fb_rgb.resize(words, 0);
}
}

/// Ensure the CPU readback buffer has `rows` rows. Readback is uncommon
/// (screenshots, VNC and CI), so taller modes do not grow it here.
pub fn ensure_rgba_rows(&mut self, rows: usize) {
let words = FB_STRIDE * rows.min(FB_MAX_H);
if self.rgba.len() < words {
self.rgba.resize(words, 0);
}
}

/// Newport's planes have a fixed 2048x1024 physical size, independent of
/// the visible mode. Allocate them together on the first Newport refresh.
fn ensure_newport_planes(&mut self) {
let words = FB_STRIDE * BASE_FB_ROWS;
if self.fb_rgb.len() < words {
self.fb_rgb.resize(words, 0);
}
if self.fb_aux.len() < words {
self.fb_aux.resize(words, 0);
}
if self.did.len() < words {
self.did.resize(words, 0);
}
}

fn decode_did_into(
vc2_regs: &[u16; 32],
vc2_ram: &[u16],
Expand Down Expand Up @@ -329,6 +371,7 @@ impl Rex3Screen {
bt445: &Mutex<Bt445>,
diag: &AtomicU64,
) -> bool {
self.ensure_newport_planes();
#[cfg(feature = "rex-dirty-upload")]
{
fb_damage.rectangles_into(DamagePlane::Rgb, &mut self.fb_rgb_damage);
Expand Down Expand Up @@ -484,6 +527,7 @@ impl Rex3Screen {
}

if decode_did {
self.ensure_newport_planes();
diag.fetch_or(Rex3::DIAG_LOOP_DECODE_DID, Ordering::Relaxed);
let did_changed = self.decode_did();
#[cfg(feature = "wgpu")]
Expand Down Expand Up @@ -626,6 +670,30 @@ impl Rex3Screen {
}
}

#[cfg(test)]
mod buffer_tests {
use super::*;

#[test]
fn display_buffers_start_small_and_only_grow() {
let mut screen = Rex3Screen::new();
let base = FB_STRIDE * BASE_FB_ROWS;
assert_eq!((screen.fb_rgb.len(), screen.rgba.len()), (base, base));
assert!(screen.fb_aux.is_empty() && screen.did.is_empty());

screen.ensure_fb_rows(1200);
screen.ensure_rgba_rows(1200);
assert_eq!((screen.fb_rgb.len(), screen.rgba.len()), (FB_STRIDE * 1200, FB_STRIDE * 1200));
screen.ensure_fb_rows(768);
screen.ensure_rgba_rows(768);
assert_eq!((screen.fb_rgb.len(), screen.rgba.len()), (FB_STRIDE * 1200, FB_STRIDE * 1200));
assert!(screen.fb_aux.is_empty() && screen.did.is_empty());

screen.ensure_newport_planes();
assert_eq!((screen.fb_aux.len(), screen.did.len()), (base, base));
}
}

/// What a VC2 or VC3 timing generator's tables add up to.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Vc2Totals {
Expand Down
3 changes: 3 additions & 0 deletions src/display/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -980,6 +980,9 @@ impl Slot {
// A finished frame is copied for its readers here; display state
// (Newport) is read back by the renderer that composes it.
let fill = readback && !self.rgba_current && self.cpu_frame;
if fill {
screen.ensure_rgba_rows(size.1);
}
if !(new_frame || fill || heartbeat) {
// A head that asks every frame and had nothing new.
return;
Expand Down
Loading