From 3fc2d5b083200e2d2a5ae9db61ea1eedcc70b1c6 Mon Sep 17 00:00:00 2001
From: Daniel Samson <12231216+daniel-samson@users.noreply.github.com>
Date: Tue, 14 Jul 2026 01:58:18 +0100
Subject: [PATCH] =?UTF-8?q?display:=20finalize=20v1=20=E2=80=94=20docs=20+?=
 =?UTF-8?q?=20plan=20to=20DONE=20(D5)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The three integration cases (display, display-service, display-demo) plus the
pure host tests all pass; the default build is clean. Update docs/display.md's
"Verifying it" to name the real cases, and mark docs/display-plan.md D1-D5 done.

The display service v1 is complete: a framebuffer compositor that owns the
write-combining framebuffer, composites a z-ordered layer stack into a cacheable
back buffer, presents only the damaged region, and is driven over IPC by the
runtime.display client — proven end to end by the display-demo process. Deferred
by design (docs/display.md): runtime mode-setting and true vsync.
---
 docs/display-plan.md | 32 +++++++++++++++++++++-----------
 docs/display.md      | 28 +++++++++++++++++++++-------
 2 files changed, 42 insertions(+), 18 deletions(-)

diff --git a/docs/display-plan.md b/docs/display-plan.md
index 2cfde96..b19a1cc 100644
--- a/docs/display-plan.md
+++ b/docs/display-plan.md
@@ -142,20 +142,30 @@ the demo drives a run of frames of motion through the layer client API and logs
 Regression-checked: `zig build test`, `display` (D1), and `display-service` (D2/D3) all
 still pass, and the default `zig build` is clean.
 
-**Gate:** run `run-efi`; a screenshot (or two, apart in time) shows the wallpaper, the
-cursor, and the rectangle in different positions — motion, from a client, through the
-compositor, on screen.
+## D5 — Test cases + docs ✅
 
-## D5 — Test case + docs
+- [x] The three integration cases exist and pass: `display` (D1 handoff, kernel),
+      `display-service` (D2/D3 compositor + self-check), and `display-demo` (D4 full
+      pipeline: spawn `display` + `display-demo`, match `display-demo: ok`) —
+      [tests.zig](../system/kernel/tests.zig) + [qemu_test.py](../test/qemu_test.py). Plus
+      the pure host tests (`zig build test`).
+- [x] [display.md](display.md) updated to the built state (the "Verifying it" section names
+      the real cases); [README index](README.md) entry present (#19); the `display-track`
+      memory marked DONE with the commits.
 
-- [ ] `test/qemu_test.py display` + `displayTest` in
-      [tests.zig](../system/kernel/tests.zig): boot, spawn `display` + `display-demo`,
-      pass on `display: presented frame {N}` and `display-demo: ok` heartbeats.
-- [ ] Flip [display.md](display.md)'s status notes from "planned/built" as appropriate;
-      confirm the [README index](README.md) entry; update the `display-track` memory to
-      DONE with the commit.
+**Gate (met):** `python3 test/qemu_test.py display display-service display-demo` all pass,
+`zig build test` is green, and the default `zig build` is clean.
 
-**Gate:** `python3 test/qemu_test.py display` passes in CI-equivalent local run.
+---
+
+## v1 status: complete
+
+D1–D5 done. The display service is a working framebuffer compositor: it owns the
+framebuffer (write-combining), composites a z-ordered layer stack into a cacheable back
+buffer, presents only the damaged region, and is driven over IPC by the `runtime.display`
+client — proven end-to-end by a separate demo process. Two limitations are deliberate and
+documented (docs/display.md): no runtime mode-setting (native backend) and no true vsync
+(no vblank on a dumb framebuffer). Next steps are the Deferred items below.
 
 ---
 
diff --git a/docs/display.md b/docs/display.md
index f5b2e5f..3f4fd1b 100644
--- a/docs/display.md
+++ b/docs/display.md
@@ -232,13 +232,27 @@ both are clean additions behind the interfaces v1 establishes.
 
 ## Verifying it
 
-A `display` test case ([tests.zig](../system/kernel/tests.zig), `python3
-test/qemu_test.py display`) boots the kernel, spawns the service and a synthetic
-`display-demo` client (the hardware-free analog of
-[`input-source`](../system/services/input-source/)) that drives layers — a wallpaper, a
-moving rectangle, a cursor. It passes on a serial heartbeat (`display: presented frame N`
-/ `display-demo: ok`), proving a frame travelled client → compositor → screen, exactly
-as the [input test](input.md) proves an event travels source → service → subscriber.
+Three QEMU test cases ([tests.zig](../system/kernel/tests.zig), `python3
+test/qemu_test.py <case>`), each layering on the last:
+
+- **`display`** — the kernel handoff: the seeded `display` device is shaped correctly and
+  the claim → `mmio_map` leaf is genuinely **write-combining** (PAT entry 4), asserted at
+  the page-table level.
+- **`display-service`** — the compositor comes up: it claims the framebuffer, allocates
+  the cacheable back buffer, presents a cleared frame through the double-buffer path
+  (`display: online … / presented frame 0`), and a startup **self-check** composites two
+  overlapping layers on the real framebuffer and reads them back — overlap = the top
+  layer — logging `display: compositor self-check ok`.
+- **`display-demo`** — the full pipeline from a separate process: the hardware-free
+  [`display-demo`](../system/services/display-demo/) client (the
+  [`input-source`](../system/services/input-source/) analog) drives layers — a wallpaper, a
+  sliding rectangle, a cursor — through the layer client API and heartbeats
+  `display-demo: ok`, proving a frame travelled client → compositor → screen, exactly as
+  the [input test](input.md) proves an event travels source → service → subscriber. The
+  visible motion itself is a screenshot away via `zig build run-x86-64`.
+
+The compositor's pixel math (rectangle clipping, fill, composite, tile blit) and colour
+packing are additionally covered by pure host unit tests under `zig build test`.
 
 ## See also