1 files changed, 75 insertions, 0 deletions
diff --git a/tools/guest-diag/wall2/README-session77.md b/tools/guest-diag/wall2/README-session77.md
new file mode 100644
index 0000000..cf2450e
--- /dev/null
+++ b/tools/guest-diag/wall2/README-session77.md
@@ -0,0 +1,75 @@
+# session 77 (r683/r684) — vkCreateDevice PASSES: the 0x7E event validation and the readiness-word completion
+
+## The two-part unblock
+
+1. **r682 fix validated** (`e3c1cdc5`, loaded on r683/r684): the
+   nvkms/Vulkan path allocates its completion event as
+   NV01_EVENT_KERNEL_CALLBACK_EX (class 0x7E); the emulation now
+   registers it alongside 0x79. Live proof (r683, sema_dbg=1):
+
+       GSP_RM_ALLOC class=0x7e paramsSize=24 hClient=0xc1e00011
+           hParent=0xcaf00001 hObject=0xcaf00003
+       event registered hEvent=0xcaf00003 hSrc=0x0
+           notifyIndex=1006632972 (off 8, slot 13)
+           params=1100e0c1000000007e0000000c00003c0000000000000000
+       EVPOST all ev[13] cl=0xc1e00011 ev=0xcaf00003 nidx=0x3c00000c rc=0
+
+   (notifyIndex 0x3c00000c = subdevice 0x3c, index 0xc =
+   NV2080_NOTIFIERS_GRAPHICS). The guest consumes the records
+   (`guest_read == our_write` in the rmstate dump), but the guest's
+   event dispatch does NOT write the event's notification word — the
+   residual delivery gap.
+
+2. **The completion word found and driven (the actual unblock)**. The
+   main-thread vkCreateDevice wait (eglcore 0xdceb80, session 76) reads
+   a u32 readiness word: `should-wait = (word != 1)`; the word lives at
+   `+0x80` of a **16 KB rw-s /dev/nvidiactl mapping** (the event
+   notification buffer; holder chain sub -> obj2 -> holder, resolved
+   live by t79.py). The host can write it directly in the guest RAM
+   file:
+
+       PA = pagemap PFN << 12  (+0x80);  file offset = PA - 0x80000000
+       (above-4G RAM; below-4G would be PA itself per the cycle's
+       guest-RAM registration: gpa 0x0/0x100000000 -> off 0x0/0x80000000)
+
+   Writing 1 flipped the wait and **vkCreateDevice returned success**
+   (`VKDEVICE ok family=0`) — reproduced three times:
+   * r683: manual write after a t79 probe;
+   * r684: nudger (all 16 KB mapping words) + slotfill restart;
+   * r684d: probe -> single-word write (the reliable recipe).
+
+## The reliable recipe (per run)
+
+1. r682+ module; `sema_dbg=1 gsp_rm_ev_log=300` optional.
+2. Launch `vk_frame` + `slotfill2.sh` (EGL completion-slot fills; the
+   slots re-arm, so re-run slotfill if the client is stuck in the
+   sched_yield spin before the word-wait).
+3. Wait for the main thread in `do_poll` (the word-wait).
+4. `t79.py` (gdb) -> `WAIT word=0x...`; guest pagemap -> PFN -> PA;
+   host write `01 00 00 00` at `PA-0x80000000`.
+5. `VKDEVICE ok` follows within ~10 s. The client then proceeds to
+   image/memory/pipeline setup; its next wait is NOT the same word
+   (the word stays 1) — next session: probe the follow-on state
+   (attach fails while the client spins in the post-device phase;
+   use the /proc-only checks + a longer observation window).
+
+## Cautions learned
+
+* Writing ALL 16 KB mapping words (the multi-page nudger) can trip the
+  -4 give-up path (an RM error flag word gets written): restrict nudges
+  to the single probed word.
+* Attaching gdb to the client while it is in the tight post-device spin
+  can hang the attach (leave a `timeout`-wrapped gdb, then kill that
+  gdb by PID and `kill -CONT` the client — the pending SIGSTOP from a
+  dead tracer otherwise wedges it).
+* zsh truncates 64-bit hex literals in `$(( ))`: compute PFN/PA in
+  python, not zsh.
+
+## Tools
+
+* `t79.py` — resolves the wait chain (sub -> obj2 -> holder -> word VA)
+  and prints the client's nvidiactl rw-s mapping sizes.
+* `guest_words.sh` — prints VA/PA of the +0x80 word for every 16 KB
+  nvidiactl mapping (pagemap; run in the guest as root).
+* `nudge.sh` — host-side loop: poll guest_words.sh and write 1 to any
+  zero word (multi-page variant; prefer the single-word recipe).