From a2879e656e0e9cac882a3e3ab332edec9ac87ef4 Mon Sep 17 00:00:00 2001
From: Arthur Hanson Rasmusson <arthur@vgpu.io>
Date: Fri, 9 Oct 2026 14:07:11 -0400
Subject: guest-diag: stream channel CPU-side GPUT on change (#put lines,
 ISSUE-0002 diag)

---
 tools/guest-diag/guest_pin_stream.py | 25 +++++++++++++++++++++++++
 tools/guest-diag/pin_gr_stream.py    |  4 ++++
 2 files changed, 29 insertions(+)

diff --git a/tools/guest-diag/guest_pin_stream.py b/tools/guest-diag/guest_pin_stream.py
index 6c22e62..844d512 100644
--- a/tools/guest-diag/guest_pin_stream.py
+++ b/tools/guest-diag/guest_pin_stream.py
@@ -316,6 +316,7 @@ def resolve_channel_from_sem(kc, sem, out):
         emitted = _emit_ring_pins(kc, v, entries_cpu, entries, out)
         gp_put = kc.read64(pos - 0x50)
         gp_put_va = kc.read64(pos + 0x08)
+        chan_put_note(v, gp_put)
         if is_kern_ptr(gp_put) and gp_put_va and \
                 GR_RING_LO <= gp_put_va < 0x201000000:
             pa = kc.va_to_pa(gp_put)
@@ -359,6 +360,18 @@ GR_RING_LO = 0x200200000
 GR_RING_HI = 0x200400000
 CHAN_INFO_GPFIFO_VA = 0x58
 
+# ISSUE-0002: channel CPU-side GPUT pointers, keyed by ring GPU VA. The main
+# loop emits a "#put <ring_va> <value>" control line when the value changes,
+# so the host can see whether the guest's real put advances while the
+# service's GP_PUT read stays at 1 (no guest agent needed at stall time).
+CHAN_PUTS = {}
+PUT_LAST = {}
+
+
+def chan_put_note(gpu_va, gp_put):
+    if gpu_va and is_kern_ptr(gp_put):
+        CHAN_PUTS[gpu_va] = gp_put
+
 
 def resolve_channel_pins(kc, ch, out):
     """uvm_channel_t kptr -> pin the GPFIFO ring + GPPUT buffers.
@@ -416,6 +429,7 @@ def resolve_channel_pins(kc, ch, out):
             emitted += 1
     gp_put = kc.read64(base + 0x08)
     gp_put_va = kc.read64(base + 0x60)
+    chan_put_note(gpu_va, gp_put)
     if is_kern_ptr(gp_put) and gp_put_va and \
             GR_RING_LO <= gp_put_va < 0x201000000:
         pa = kc.va_to_pa(gp_put)
@@ -842,6 +856,17 @@ def main():
                                    len(resolved_chs), len(seen_chs)))
                 except OSError:
                     pass
+        # ISSUE-0002: stream the channel CPU-side GPUT on change (see
+        # chan_put_note). Emitted here so the value is sent with this
+        # loop's payload even when no new pages appeared.
+        for gv, pp in list(CHAN_PUTS.items()):
+            d = kc.read(pp, 4)
+            if not d:
+                continue
+            pv = struct.unpack("<I", d)[0]
+            if PUT_LAST.get(gv) != pv:
+                PUT_LAST[gv] = pv
+                lines.append("#put 0x%x %u\n" % (gv, pv))
         now = time.time()
         if now - last_log > 1.0:
             last_log = now
diff --git a/tools/guest-diag/pin_gr_stream.py b/tools/guest-diag/pin_gr_stream.py
index aba3912..b864ab5 100644
--- a/tools/guest-diag/pin_gr_stream.py
+++ b/tools/guest-diag/pin_gr_stream.py
@@ -154,6 +154,10 @@ def main():
                 if text.startswith("#pb"):
                     _mirror(text)
                     continue
+                if text.startswith("#put"):
+                    log(text)
+                    _mirror(text)
+                    continue
                 m = re.match(r"^(0x[0-9a-f]+),(0x[0-9a-f]+)(?:,(\d+))?$", text)
                 if m:
                     runs.append((int(m.group(1), 16), int(m.group(2), 16),
-- 
cgit v1.2.3