open-iov.git/docs/03-architecture, branch cs-share

docs: add the GR compute-launch frontier page and align execution status across the tree

2026-10-06T19:18:39+00:00

New page docs/04-implementation/03-execution-frontier.md describes the chain that must fire for a guest CUDA launch (guest push -> GPFIFO/front-end -> inline launch-descriptor install -> engine read/dispatch -> completion), where the leading edge is (the descriptor install path), how we know (front-end vs engine-authored observables and their limits), what is exonerated (context validity at dispatch, destination window mapping, fetch alignment, shared-buffer rule, parenting), the ranked issues (verbatim prelude targets, missing descriptor-virtualization control, sentinel hygiene), live investigation lines and labelled theories. Align every page that still said GR execution is blocked on engine-context validity to the current frontier, and add the new page to the README reading order (row 15, later rows renumbered). Docs only; no code.

docs: draw the physical-backend lifecycle (init, work, completion, teardown) on one page

2026-10-06T00:08:06+00:00

vgsp: never run work for a slot consumed without it (epoch mark + content-hash once gate)

2026-10-05T00:54:03+00:00

The grace-expiry fake path consumed a held CE entry without marking its GPFIFO slot as consumed for the put epoch, and the replay guard only ran while the channel was not deferring. A later pin-batch rewind then re-read the slot, found no recorded identity, and executed the push's copies against a staging buffer the client had refilled after the faked release - a deterministic vadd input shift (a[k] == h_a[k + 2 MB]). - grace-fake consume path now calls svc_replay_note() before advancing; - the svc_replay_seen() replay skip is evaluated unconditionally: a slot consumed in the current epoch is skipped on every replay, deferral or not, until a put wrap clears the mark; - the once-only identity gate gains a content witness (FNV-1a hash of the recorded push bytes): the same entry words with different push content is a new push (clients rewrite push buffers in place) and runs its ops with a cleared done bitmap; suppression requires identical content; - snapshot write-back persists the hash array; new drain counter reident= counts content-mismatch cancellations; - the grace window stays at 8 s: a faked entry's work is never run, so the hold is that work's only chance (a 2.5 s experiment made red-class runs complete with corrupt data instead of timing out). Verified: module 8e90fc7e..., three consecutive end-to-end acceptance runs (MAIL + VADD bad=0 checksum=392344090.500000 + STATUS OK).

docs: note live verification of the per-op once gate

2026-10-04T23:13:16+00:00

A later supervised cycle reproduced the held-entry retry over a refilled staging buffer, the completed operation was skipped, and the end-to-end transfer verified byte-for-byte (bad=0, expected checksum).

vgsp: once-only op execution per entry identity, per-op done bitmap

2026-10-04T22:54:35+00:00

The pump's operand-targeted-scan hold decodes a push, runs every op that translates, then leaves the entry pending for a retry. The retry re-decoded the whole push and re-ran the operations that had already completed. A CE copy reads a client staging buffer the client refills per chunk, so the retry overwrote a finished chunk with the following chunk's data (observed: the bridge's vadd input half replaced by the next 1 MB chunk, first half of the device buffer byte-identical to the source shifted by exactly 2 MB; the same 1 MB copy logged twice with different staging contents). The service now records, per GPFIFO slot, the entry identity plus a bitmap of the decoded operation indexes whose work has executed for that identity, and a complete flag for a pass that ended with no operand pending. svc_run_ops skips already-executed ops on a retry and marks the rest as they succeed; the pump stores the record immediately after decode, before any hold path can break, so the pending path can no longer lose it. A replay of a complete identity suppresses all ops; a partial identity retries only what is owed. Also carries the ops_once diagnostic counter in the service snapshot line and documents the operation-granularity rule in the architecture doc.

vgsp: end-to-end CUDA acceptance in the guest

2026-10-04T20:19:31+00:00

The no-claim emulation path now runs a stock CUDA program end to end: device properties, cudaMalloc, a GPU-authored string kernel read back byte-for-byte, two 4 MB host-to-device copies, a 1 M-element vectorAdd executed on the physical GPU through the host bridge, and the device-to-host copy-back verified element by element. Three consecutive supervised cycles report MAIL + VADD bad=0 checksum=392344090.500000 + STATUS OK with identical input/output hashes. Two data-path correctness fixes make the transfers sound: - Once-only op execution per GPFIFO entry. The pump replays recently consumed ring entries when translation batches are injected so missed releases can land; re-executing a CE copy is not idempotent because its source is a client staging buffer that may have been refilled. Slots now record their raw entry words and a replayed entry matching that identity suppresses operations while still processing releases. - Per-page translation of virtual operands. svc_copy resolved only the first page of a VA range and walked the PA linearly; client staging ranges are frequently split (observed 195 + 61 pages), so the tail of alternating chunks was read from unrelated memory. Multi-page copies now re-resolve each 4 KB page through the trusted resolver. Also carries the earlier uncommitted emulation fixes that got the client to the launch (QMD address-window gate, counter registration persistence, 512 MiB emulated FB, bridge slot hygiene) and bounded diagnostics (sema-bigop, sema-bigcopy, bridge-in/out hashes, daemon INCHECK/OUTCHECK/dumps).

kernel: GR context-promote bisection modes 4-17 and server-managed-ctxbuf registry variant; complete vgsp rename; docs/tooling refresh

2026-10-02T19:13:06+00:00

- gsp_phys_booter: GR promote bisection modes 4-17 (two-phase zero-field VA, batched entries, hVirtMemory, bare VA, KMD SKIP_CTXBUFFER_ALLOC channel, old-interface GPU_INITIALIZE_CTX, FBMEM context buffer, UVM-faithful PA-only, PATCH/PM auxiliary promotes, server-managed no-promote path); PATCH/PM geometry queries and buffers; pre-boot SET_REGISTRY profile selection - gsp_phys_gpu: gsp_phys_rmcall_gr_promote clamp 0..17 and gsp_phys_srv_ctxbuf parameter; registry image variant with RMSetClientRMAllocatedCtxBuffer=0 - vgsp rename across kernel, scripts, tools and docs (module vgsp.ko, /sys/kernel/debug/vgsp/, vgsp-: log prefixes) - risc-v-gsp-rm-debugger user-facing rename and docs/CI refresh; guest-diag tool updates; README/SBOM/install/Makefile sync Live status: CE ladder and P6 guest-copy forwarding green; GR engine context commit still open (all promote shapes accepted or cleanly refused; the channel stays CTXNOTVALID) - see Handoff-vGPU-IO.md Addendum 21 (local).

docs: engineering-operations playbook and project-wide status accuracy pass

2026-10-02T15:28:49+00:00

- docs/eng-ops.md gains Part II, live physical-backend engineering operations: hard rules, the full module-parameter matrix, the routine supervised cycle and clean-release checklist, the debugfs inventory, how to read gsp-phys-state, a debugging scenario catalogue (CTXNOTVALID/promote wedge, fail-safe WPR2, unload hangs, guest wedges, MMU/PTE and PBDMA faults, relay symptoms), a hazard register (crash causes and debugging side effects), the physical-backend OODA loop, and the work-context map with porting flows - architecture, implementation, operations, orientation, getting-started, portability, ecosystem and reference docs corrected to the current state: CUDA driver-API smoke green, CE-class work forwarding and engine-authored releases plus fault relay in place (default off), GR execution blocked on engine-context validity, the promote wedge and designed locked fail-safe, and P5 wave-2 subsumed - internal-reference cleanup in tracked docs (no analysis-source or local-archive references); historical architecture document bannered - README reading list and STATE-CURRENT frontier refreshed; new pages (runbook, green-eye user guide, porting sequence, porting/packaging notes) linked from the tree Link check: scripts/check-docs-links.py passes (56 files, no broken links).

gsp-phys: P6b waves 1.5 and 2 - deferred release and hardware-authored guest copies

2026-10-02T10:55:42+00:00

- new default-off gsp_phys_work_defer_release: a forwarded guest push's releases are recorded and its GPFIFO entry is held (no consume, no GP_GET write, no counter publish/stall) until the work item publishes completion; the service thread then delivers the releases, with a fallback on failure/timeout (500 ms cap enforced every pump pass)/ pause/quiesce/channel-delete - new default-off gsp_phys_work_hw_primary: the software copy is skipped for forwarded ops, so the physical engine authors the data; a once-only software copy runs before the releases on any hardware failure or when the request cannot be queued - release-apply helpers extracted; exactly-once latches; channel-delete and teardown handling; counters and a work_guard state line - live: deferred-release run engaged=75 applied=75 timeouts=0 with the full smoke green; hardware-primary run req=100 ok=100 verify_ok=100 fallback=0 copy_skipped=119 copy_fail=0, smoke ALL OK 64/64 (guest read data the engine authored), with 19 fail-closed inline software fallbacks under single-inflight contention; a range-unregistered run proved the fallback (121 skipped copies, all recovered, smoke green) - defaults off; the software path and all existing guards unchanged

gsp-phys: P6b wave 1 - shadow-forward guest CE copies to the physical engine

2026-10-02T09:04:44+00:00

- the sema service captures the first eligible copy per push from the software resolver's own operands (the real push shape mixes guest RAM with emulated-VRAM shadow addresses, including physical destinations) - HPA resolution: guest RAM through the shared guest-RAM file page cache, emulated VRAM through the mapping of its kernel shadow - new scratch page-table pool: 16 zeroed page-table pages with their page-directory entries built before any engine access, handing out one whole 128-byte GMMU PTE fetch line per copy pair (16 PTEs, 512 pairs per boot, never reused; a PTE written into an already-fetched line is not observed and there is no invalidate path) - the backend submits the copy on the module-owned channel and verifies the result host-side; every miss falls back to the ladder shadow copy, and the software pump remains authoritative - live (full smoke, both parameters on): req=42 ok=42 verify_ok=42 verify_fail=0 fallback=0, guest payload roundtrip ALL OK 64/64, clean latched release; defaults stay off