docs/uvm: describe the push-execution fallbacks and the semaphore-VA flap pitfall

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/03-architecture/04-uvm.md b/docs/03-architecture/04-uvm.md
index 05ec80b..b879572 100644
--- a/docs/03-architecture/04-uvm.md
+++ b/docs/03-architecture/04-uvm.md
@@ -106,6 +106,28 @@ sequence) decodes as:
 So: **the emulation's job for this push is to write `payload` to the memory at
 the semaphore's GPU VA.** Which requires a GPU-VA → guest-PA translation.
 
+How the host performs it: while the channel's GPFIFO has pending entries the
+service reads each push through the learned VA→PA map, decodes the method
+stream and runs the pushed work (page-table memsets, copies, semaphore
+releases). Whenever a push page cannot be resolved - or a channel consumes
+entries without any release landing, which means the translation pointed at a
+stale page - the service falls back to content: guest RAM is scanned page by
+page for release groups (`SET_SEMAPHORE_A/B` + `LAUNCH_DMA` with
+`SEMAPHORE_TYPE=RELEASE_ONE_WORD`) and the pending payloads are applied
+forward-only. A rolling 32 MB/pass sweep runs in parallel; a stalled channel
+additionally triggers a faster sliced full-RAM pass (256 MB per service pass)
+so a client wait clears in seconds instead of waiting for the rolling sweep to
+come around. A release is applied only when `payload > current`, so recycled
+push buffers and stale copies are harmless.
+
+One pitfall observed live: the learned map is rebuilt from a content scan, and
+a semaphore-page VA can flap between two physical pages across rebuilds (a
+freed allocation's record competing with the live one). Releases then land on
+a page the client never reads and its tracker wait stops advancing even though
+the emulation "applied" the value. When a wait stalls while the applied
+counter climbs, check that the semaphore VA resolves to a stable PA; pinning
+the validated translation fixes it.
+
 ## 5. The memory model UVM assumes (and what we learned)
 
 * UVM's semaphore pool is **system memory** (`pool->aperture = UVM_APERTURE_SYS`),