From 74b6fa4bb0912e310c24dbeefd58eadfc938f9b2 Mon Sep 17 00:00:00 2001
From: Arthur Hanson Rasmusson <arthur@vgpu.io>
Date: Sat, 24 Oct 2026 13:24:02 -0400
Subject: tools r624: tracker_walk.py + pool_page.py - guest-side (kcore) walks
 for the first-wait class: read a UVM tracker's semaphore object and expected
 payload, and dump the semaphore-pool page's applied values; together with the
 host pool-wr/sema-sw logs they compare what the driver waits for against what
 the host wrote

---
 tools/guest-diag/pool_page.py    | 28 ++++++++++++++++++++++
 tools/guest-diag/tracker_walk.py | 50 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78 insertions(+)
 create mode 100755 tools/guest-diag/pool_page.py
 create mode 100755 tools/guest-diag/tracker_walk.py

(limited to 'tools/guest-diag')

diff --git a/tools/guest-diag/pool_page.py b/tools/guest-diag/pool_page.py
new file mode 100755
index 0000000..a9f7b15
--- /dev/null
+++ b/tools/guest-diag/pool_page.py
@@ -0,0 +1,28 @@
+#!/usr/bin/env python3
+# pool_page.py <pa-hex> - dump the UVM semaphore-pool page's u32 slots via
+# /proc/kcore (guest root). The pool VA 0x121000000 maps to the PA the
+# scanner+host pinned; nonzero slots are the applied release values. Compare
+# against the tracker's expected payload (tracker_walk.py) and the driver's
+# uvsv wait value to find write-target divergence / starvation.
+import sys
+import struct
+
+pa = int(sys.argv[1], 16) if len(sys.argv) > 1 else 0x107fd8000
+sys.argv = ["pool_page"]
+sys.path.insert(0, "/tmp")
+import guest_pin_stream as g  # noqa: E402
+
+kc = g.Kcore()
+if not kc.load():
+    print("KCORE LOAD FAILED")
+    sys.exit(1)
+
+nz = []
+for off in range(0, 0x1000, 4):
+    d = kc.read(kc.page_offset_base + pa + off, 4)
+    v = struct.unpack("<I", d)[0] if d else 0
+    if v:
+        nz.append((off, v))
+print("pa=0x%x nonzero slots=%d" % (pa, len(nz)))
+for off, v in nz[:64]:
+    print("off=0x%x val=%u" % (off, v))
diff --git a/tools/guest-diag/tracker_walk.py b/tools/guest-diag/tracker_walk.py
new file mode 100755
index 0000000..3846fa1
--- /dev/null
+++ b/tools/guest-diag/tracker_walk.py
@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+# tracker_walk.py - read a UVM tracking semaphore's expected payload and walk
+# its semaphore object via /proc/kcore (run in the guest as root).
+#
+# Use with a live stuck client: the udvt/uvtw kprobes or the scanner's #sem
+# lines give the tracker kptr (e.g. 0xffff899a885b5480); this prints
+#   tracker+0x0  = semaphore kptr
+#   tracker+0x28 = expected payload (the value the client waits to observe)
+#   semaphore+0.. = its pointers (rm_mem/page) and candidate value words
+# Pair it with the host's pool-wr/deferred-release logs and a pool page dump
+# (pool_page.py) to compare what the driver expects vs what the host wrote.
+import sys
+import struct
+
+sys.argv = ["tracker_walk"]
+sys.path.insert(0, "/tmp")
+import guest_pin_stream as g  # noqa: E402
+
+kc = g.Kcore()
+if not kc.load():
+    print("KCORE LOAD FAILED")
+    sys.exit(1)
+
+
+def r64(a):
+    d = kc.read(a, 8)
+    return struct.unpack("<Q", d)[0] if d else None
+
+
+def r32(a):
+    d = kc.read(a, 4)
+    return struct.unpack("<I", d)[0] if d else None
+
+
+for arg in sys.argv[1:] or ["0xffff899a885b5480"]:
+    SEM = int(arg, 16)
+    print("tracker 0x%x:" % SEM)
+    for off in range(0, 0x40, 8):
+        print("  +0x%x = 0x%x" % (off, r64(SEM + off) or 0))
+    sp = r64(SEM)
+    print("semaphore=0x%x" % (sp or 0))
+    if sp and g.is_kern_ptr(sp):
+        for off in range(0, 0x80, 8):
+            v = r64(sp + off)
+            print("  sem+0x%x = 0x%x" % (off, v or 0))
+        for off in range(0, 0x80, 8):
+            v = r64(sp + off)
+            if v and g.is_kern_ptr(v):
+                w = r32(v)
+                print("  *sem+0x%x -> dword=0x%x (%u)" % (off, w or 0, w or 0))
-- 
cgit v1.2.3