Performance Research G04 Ordered Vertex Upload Rings

Ordered vertex staging and timeline-managed ring buffers

G04 — Implementation and validation notes

Field	Value
Evidence state	Existing research; lifetime, capacity and memory visibility need qualification
Inspected source	322986f4c5502b3fa887a9605ac8cd88e9b2c579
First experiment	Bounded upload allocation with explicit last-reader retirement
Scope	Addendum dated September 15, 2026; not a current-main benchmark or implementation status

Unproven performance research · Performance research — common test protocol · Performance research — reproducible checks

Evidence and implementation reasoning

Evidence and direction. The repository retains vertex-staging research with explicit capacity, overlap, reset, and rendered-output gates. A bounded upload ring with per-range retirement tokens can decouple producer writes from GPU consumption without repeatedly forcing broad completion. Research history, timeline precedent.

Implementation contract. Each allocation records offset, length, generation, and last GPU reader/completion token. Reuse is permitted only after that use retires. A full ring must wait for the oldest conflicting live allocation or take a safe bounded fallback; it must not overwrite pending draw data.

Host-visible memory introduces an independent obligation: noncoherent writes must be flushed for the populated range, respecting allocation/atom alignment. Coherent memory on one device does not establish portability. The repository's later tracker split includes #110 specifically for mapped draw staging flushes. Tracker clarification.

Expected gain. Fewer forced upload synchronization points and better overlap, but potentially no gain if the next report/readback immediately forces the same completion. Measure ring pressure and total waits, not merely submission count.

Acceptance. Force tiny capacity, wrap, overlapping vertex updates, noncoherent memory where supported, reset with outstanding work, allocation failures, and renderer recreation.

First patch boundary

Track range, generation and last reader. Handle noncoherent flush requirements separately from resource-lifetime rules.

allocate live range -> upload/flush -> submit reader -> retire token -> reuse only after completion

Locate the inspected seam before editing; names or ownership may have changed since the pinned review:

git grep -n -E 'vertex|staging|finish|flush' -- hw/xbox/nv2a/pgraph/vk

Proposed focused tests

These are implementation gates to add or exercise, not claims that production tests already exist or passed. Retained standalone checks are on the checks page.

Test ID	Setup / deliberate control	Required oracle
G04.01	Artificially tiny ring with wrap and delayed GPU readers; update overlapping and disjoint guest ranges.	Pending draw data is never overwritten; only conflicting live allocations constrain reuse.
G04.02	Noncoherent host memory with writes at flush-alignment boundaries.	Required host writes become visible using valid flush ranges; coherent-only testing is insufficient.
G04.03	Allocation failure, renderer reset and snapshot while allocations are live.	Bounded fallback and lifecycle drain preserve every resource owner.

Counters and rejection criteria

Collect: ring_allocations, live_bytes, wrap_count, conflicting_wait_ns, broad_wait_ns, staged_bytes, flush_ranges, gpu_ns. Keep exact counts separate from sampled durations; use an uninstrumented build for performance qualification.

Reject or hold: Reject a lifetime/visibility error even with no VUID. Compare total waiting and memory footprint, not the disappearance of one finish reason.

Follow the common protocol for source identities, previous-main/fixed-baseline controls, raw results, confidence and retail/XISO qualification. No gain becomes proven from a model, cache hit, local operation count, or shifted wait label alone.