tools/lg + docs: guest frame producer path (CUDA -> ivshmem -> host) and the Looking Glass status

- tools/cuda-ab/frame_producer.cu: renders an animated Julia frame on the
  guest GPU and publishes it into the ivshmem BAR (the kvmfr 128 MiB window)
  with a small header + RGBA payload.
- tools/lg/frame_reader.py: host-side reader of /dev/shm/kvmfr-<uuid> that
  saves each published frame as a PPM (the transport half of the frame path).
- tools/guest-diag/egl_frame.c: EGL probe (device/surfaceless/default
  platforms) - live result: eglQueryDevicesEXT sees the NVIDIA device and
  eglInitialize succeeds, but eglMakeCurrent fails EGL_BAD_ALLOC (0x3003),
  the same VASpace-allocation wall as Xorg's 'Failed to allocate VASpace
  object'.
- docs/05-operations/06: the state, the blockers and the exact remaining
  pieces (guest GL VASpace allocation; LGMP session producer).

1 files changed, 76 insertions, 0 deletions

diff --git a/tools/lg/frame_reader.py b/tools/lg/frame_reader.py
new file mode 100644
index 0000000..5598667
--- /dev/null
+++ b/tools/lg/frame_reader.py
@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: BSD-3-Clause
+# frame_reader.py - read the GPU-rendered frames the guest publishes into the
+# kvmfr ivshmem BAR (see tools/cuda-ab/frame_producer.cu) and save them on the
+# host as PPM/PNG. This is the host half of the guest frame-producer path:
+# the QEMU ivshmem-plain device is backed by /dev/shm/kvmfr-<uuid>, which the
+# guest maps through /sys/bus/pci/devices/0000:00:03.0/resource2.
+#
+# Usage: frame_reader.py [--shm /dev/shm/kvmfr-<uuid>] [--frames N] [--out DIR]
+import argparse
+import mmap
+import os
+import struct
+import sys
+import time
+
+MAGIC = 0x4B564D46
+FRAME_OFFSET = 0x100000
+# magic, version, width, height, stride, format, seq, reserved, timestamp_ns
+HDR = struct.Struct("<IIIIIIIIQ")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--shm", default=None)
+    ap.add_argument("--frames", type=int, default=5)
+    ap.add_argument("--out", default="/tmp/opencode/frames")
+    ap.add_argument("--timeout", type=float, default=120.0)
+    args = ap.parse_args()
+
+    if not args.shm:
+        import glob
+        cands = sorted(glob.glob("/dev/shm/kvmfr-*"))
+        if not cands:
+            print("NO_SHM_FILE", file=sys.stderr)
+            return 1
+        args.shm = cands[0]
+    os.makedirs(args.out, exist_ok=True)
+    print("SHM %s" % args.shm)
+
+    fd = os.open(args.shm, os.O_RDWR)
+    size = os.fstat(fd).st_size
+    mm = mmap.mmap(fd, size, mmap.MAP_SHARED,
+                   mmap.PROT_READ | mmap.PROT_WRITE)
+
+    deadline = time.time() + args.timeout
+    saved = 0
+    last_seq = 0
+    while saved < args.frames and time.time() < deadline:
+        mm.seek(FRAME_OFFSET)
+        magic, ver, w, h, stride, fmt, seq, _res, ts = HDR.unpack(
+            mm.read(HDR.size))
+        if magic != MAGIC or seq == 0 or seq == last_seq or w == 0:
+            time.sleep(0.05)
+            continue
+        fb = mm.read(w * h * 4)
+        last_seq = seq
+        path = os.path.join(args.out, "frame-%04d.ppm" % seq)
+        with open(path, "wb") as f:
+            f.write(b"P6\n%d %d\n255\n" % (w, h))
+            # RGBA -> RGB
+            rgb = bytearray(w * h * 3)
+            rgb[0::3] = fb[0::4]
+            rgb[1::3] = fb[1::4]
+            rgb[2::3] = fb[2::4]
+            f.write(bytes(rgb))
+        saved += 1
+        print("SAVED seq=%d %dx%d fmt=%d -> %s" % (seq, w, h, fmt, path))
+    mm.close()
+    os.close(fd)
+    print("READER_DONE saved=%d last_seq=%d" % (saved, last_seq))
+    return 0 if saved else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())