tools/guest-diag: guest frame capture + input driving for the two-VM GZDoom video (Xvfb XGetImage capture, SDL present shim, window resize, XTEST input, QGA range fetch)

5 files changed, 550 insertions, 0 deletions

diff --git a/tools/guest-diag/qga_snip.py b/tools/guest-diag/qga_snip.py
new file mode 100644
index 0000000..cd3b992
--- /dev/null
+++ b/tools/guest-diag/qga_snip.py
@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# Fetch a byte range from a guest file via the QEMU guest agent.
+# Usage: qga_snip.py <guest_path> <offset> <length> <host_out>
+import base64
+import json
+import socket
+import sys
+
+GUEST, OFF, LEN, HOST = sys.argv[1], int(sys.argv[2]), int(sys.argv[3]), sys.argv[4]
+import os
+SOCK = os.environ.get("QGA_SOCK", "/tmp/qemu-guest-agent.sock")
+
+
+def recv_line(s):
+    buf = b""
+    while b"\n" not in buf:
+        c = s.recv(65536)
+        if not c:
+            break
+        buf += c
+    return buf.split(b"\n", 1)[0]
+
+
+def cmd(s, obj):
+    s.sendall((json.dumps(obj) + "\r\n").encode())
+    return json.loads(recv_line(s))
+
+
+s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+s.settimeout(30.0)
+s.connect(SOCK)
+h = cmd(s, {"execute": "guest-file-open",
+            "arguments": {"path": GUEST, "mode": "r"}})["return"]
+cmd(s, {"execute": "guest-file-seek",
+        "arguments": {"handle": h, "offset": OFF, "whence": 0}})
+r = cmd(s, {"execute": "guest-file-read",
+            "arguments": {"handle": h, "count": LEN}})
+data = base64.b64decode(r["return"].get("buf-b64", ""))
+open(HOST, "wb").write(data)
+cmd(s, {"execute": "guest-file-close", "arguments": {"handle": h}})
+print(f"GOT {len(data)} bytes @ {OFF} -> {HOST}")
diff --git a/tools/guest-diag/sdl_cap.c b/tools/guest-diag/sdl_cap.c
new file mode 100644
index 0000000..23c83ab
--- /dev/null
+++ b/tools/guest-diag/sdl_cap.c
@@ -0,0 +1,229 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// sdl_cap.c - LD_PRELOAD capture shim: records every frame GZDoom presents
+// through SDL into an append-only file, so the host can harvest the guest's
+// real rendered frames without any X/driver readback path.
+//
+// Hooks:
+//   SDL_RenderPresent(SDL_Renderer*)      -> SDL_RenderReadPixels(ARGB8888)
+//   SDL_UpdateWindowSurface(SDL_Window*)  -> SDL_GetWindowSurface pixels
+// Both forward to the real SDL after capturing.
+//
+// File layout (little endian):
+//   [0]   8B  magic "GZCAPV01"  (+ 4088 B reserved zero)
+//   [4096] frame records:
+//         4B "GZF2" | u32 w | u32 h | u32 stride | u32 bpp
+//         u64 ts_ns (CLOCK_MONOTONIC) | u64 seq | stride*h bytes (top-down)
+//   A trailing record with seq = 0xFFFFFFFFFFFFFFFF marks clean stop.
+//
+// Env: GZCAP (path, default /dev/shm/gzframes.bin), GZCAP_MAXF (0=unlimited)
+#define _GNU_SOURCE
+#include <dlfcn.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <unistd.h>
+
+#define ARGB8888 0x16362004u
+
+typedef struct SDL_Renderer SDL_Renderer;
+typedef struct SDL_Window SDL_Window;
+
+typedef struct SDL_Surface {
+    uint32_t flags;
+    void *format;
+    int w, h;
+    int pitch;
+    void *pixels;
+    void *userdata;
+    int locked;
+    void *list_blitmap;
+    struct { int x, y, w, h; } clip_rect;
+    void *map;
+    int refcount;
+} SDL_Surface;
+
+static int (*real_RenderReadPixels)(SDL_Renderer *, const void *, uint32_t,
+                                    void *, int);
+static int (*real_RenderPresent)(SDL_Renderer *);
+static SDL_Surface *(*real_GetWindowSurface)(SDL_Window *);
+static int (*real_UpdateWindowSurface)(SDL_Window *);
+static int (*real_GetRendererOutputSize)(SDL_Renderer *, int *, int *);
+static void (*real_GL_SwapWindow)(SDL_Window *);
+static int (*real_GL_GetDrawableSize)(SDL_Window *, int *, int *);
+static void (*real_glReadPixels)(int, int, int, int, unsigned, unsigned, void *);
+
+static FILE *cap_fp;
+static unsigned long long cap_count, cap_max = 0;
+static int cap_stop;
+
+__attribute__((constructor)) static void cap_init(void)
+{
+    const char *p = getenv("GZCAP");
+    const char *m = getenv("GZCAP_MAXF");
+    char hdr[4096];
+
+    if (m)
+        cap_max = strtoull(m, NULL, 0);
+    if (!p)
+        p = "/dev/shm/gzframes.bin";
+    real_RenderReadPixels = dlsym(RTLD_NEXT, "SDL_RenderReadPixels");
+    real_RenderPresent = dlsym(RTLD_NEXT, "SDL_RenderPresent");
+    real_GetWindowSurface = dlsym(RTLD_NEXT, "SDL_GetWindowSurface");
+    real_UpdateWindowSurface = dlsym(RTLD_NEXT, "SDL_UpdateWindowSurface");
+    real_GetRendererOutputSize =
+        dlsym(RTLD_NEXT, "SDL_GetRendererOutputSize");
+    real_GL_SwapWindow = dlsym(RTLD_NEXT, "SDL_GL_SwapWindow");
+    real_GL_GetDrawableSize = dlsym(RTLD_NEXT, "SDL_GL_GetDrawableSize");
+    real_glReadPixels = dlsym(RTLD_NEXT, "glReadPixels");
+    if (!real_glReadPixels)
+        real_glReadPixels = dlsym(RTLD_DEFAULT, "glReadPixels");
+    if (!real_glReadPixels) {
+        void *h = dlopen("libGL.so.1", RTLD_NOW | RTLD_GLOBAL);
+
+        if (!h)
+            h = dlopen("libGLESv2.so.2", RTLD_NOW | RTLD_GLOBAL);
+        if (h)
+            real_glReadPixels = dlsym(h, "glReadPixels");
+    }
+    fprintf(stderr, "[gzcap] init path=%s present=%p updwin=%p swap=%p read=%p gros=%p\n",
+            p, (void *)real_RenderPresent, (void *)real_UpdateWindowSurface,
+            (void *)real_GL_SwapWindow, (void *)real_RenderReadPixels,
+            (void *)real_GetRendererOutputSize, (void *)real_glReadPixels);
+    cap_fp = fopen(p, "wb");
+    if (!cap_fp)
+        return;
+    memset(hdr, 0, sizeof(hdr));
+    memcpy(hdr, "GZCAPV01", 8);
+    fwrite(hdr, 1, sizeof(hdr), cap_fp);
+    fflush(cap_fp);
+}
+
+static void cap_record(const void *px, int w, int h, int stride, int bpp)
+{
+    struct timespec ts;
+    uint64_t tns, seq;
+    uint32_t rh[4];
+    char m[4] = { 'G', 'Z', 'F', '2' };
+
+    if (!cap_fp || cap_stop)
+        return;
+    if (cap_max && cap_count >= cap_max) {
+        uint64_t endseq = 0xFFFFFFFFFFFFFFFFull;
+
+        fwrite(m, 1, 4, cap_fp);
+        fwrite(&endseq, 8, 1, cap_fp);
+        fflush(cap_fp);
+        cap_stop = 1;
+        return;
+    }
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    tns = (uint64_t)ts.tv_sec * 1000000000ull + (uint64_t)ts.tv_nsec;
+    seq = cap_count;
+    rh[0] = (uint32_t)w;
+    rh[1] = (uint32_t)h;
+    rh[2] = (uint32_t)stride;
+    rh[3] = (uint32_t)bpp;
+    fwrite(m, 1, 4, cap_fp);
+    fwrite(rh, 4, 4, cap_fp);
+    fwrite(&tns, 8, 1, cap_fp);
+    fwrite(&seq, 8, 1, cap_fp);
+    fwrite(px, 1, (size_t)stride * h, cap_fp);
+    fflush(cap_fp);
+    cap_count++;
+    if ((cap_count & 31) == 0)
+        fprintf(stderr, "[gzcap] frames=%llu\n", cap_count);
+}
+
+int SDL_RenderPresent(SDL_Renderer *r)
+{
+    static int hit;
+
+    if (!hit++)
+        fprintf(stderr, "[gzcap] hook RenderPresent\n");
+    if (cap_fp && !cap_stop && real_RenderReadPixels &&
+        real_GetRendererOutputSize) {
+        int w = 0, h = 0;
+
+        if (real_GetRendererOutputSize(r, &w, &h) == 0 && w > 0 && h > 0 &&
+            w <= 4096 && h <= 4096) {
+            static unsigned char *buf;
+            static size_t bufsz;
+            size_t need = (size_t)w * 4 * h;
+
+            if (bufsz < need) {
+                free(buf);
+                buf = malloc(need);
+                bufsz = buf ? need : 0;
+            }
+            if (buf && real_RenderReadPixels(r, NULL, ARGB8888, buf,
+                                             w * 4) == 0)
+                cap_record(buf, w, h, w * 4, 32);
+        }
+    }
+    if (real_RenderPresent)
+        return real_RenderPresent(r);
+    return 0;
+}
+
+int SDL_UpdateWindowSurface(SDL_Window *win)
+{
+    static int hit;
+
+    if (!hit++)
+        fprintf(stderr, "[gzcap] hook UpdateWindowSurface\n");
+    if (cap_fp && !cap_stop && real_GetWindowSurface) {
+        SDL_Surface *s = real_GetWindowSurface(win);
+
+        if (s && s->pixels && s->w > 0 && s->h > 0 && s->pitch > 0 &&
+            s->w <= 4096 && s->h <= 4096)
+            cap_record(s->pixels, s->w, s->h, s->pitch, 32);
+    }
+    if (real_UpdateWindowSurface)
+        return real_UpdateWindowSurface(win);
+    return 0;
+}
+
+void SDL_GL_SwapWindow(SDL_Window *win)
+{
+    static int hit;
+    static unsigned char *gbuf;
+    static size_t gbufsz;
+
+    if (!hit++)
+        fprintf(stderr, "[gzcap] hook GLSwapWindow\n");
+    if (cap_fp && !cap_stop && real_glReadPixels && real_GL_GetDrawableSize) {
+        int w = 0, h = 0;
+
+        if (real_GL_GetDrawableSize(win, &w, &h) == 0 && w > 0 && h > 0 &&
+            w <= 4096 && h <= 4096) {
+            size_t need = (size_t)w * 4 * h;
+
+            if (gbufsz < need) {
+                free(gbuf);
+                gbuf = malloc(need);
+                gbufsz = gbuf ? need : 0;
+            }
+            if (gbuf) {
+                real_glReadPixels(0, 0, w, h, 0x1908, 0x1401, gbuf);
+                /* GL rows are bottom-up: flip into a scratch record */
+                {
+                    unsigned char *tmp = malloc(need);
+                    int y;
+
+                    if (tmp) {
+                        for (y = 0; y < h; y++)
+                            memcpy(tmp + (size_t)y * w * 4,
+                                   gbuf + (size_t)(h - 1 - y) * w * 4,
+                                   (size_t)w * 4);
+                        cap_record(tmp, w, h, w * 4, 32);
+                        free(tmp);
+                    }
+                }
+            }
+        }
+    }
+    if (real_GL_SwapWindow)
+        real_GL_SwapWindow(win);
+}
diff --git a/tools/guest-diag/xgrab.c b/tools/guest-diag/xgrab.c
new file mode 100644
index 0000000..3f4ec76
--- /dev/null
+++ b/tools/guest-diag/xgrab.c
@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// xgrab.c - capture the X screen (root window) into an append-only frame file.
+// Pure client-side XGetImage on a software X server (Xvfb): no GL, no driver,
+// no present-path hooks. Same record format as sdl_cap.c:
+//   [0]   8B "GZCAPV01" + zero pad to 4096
+//   [4096..] records: 4B "GZF2" | u32 w | u32 h | u32 stride | u32 bpp |
+//                     u64 ts_ns | u64 seq | stride*h bytes (top-down BGRA)
+// Trailing record seq=0xFFFFFFFFFFFFFFFF on clean stop.
+// Usage: xgrab <display> <out> <maxframes|0> <pace_us|0>
+#include <X11/Xlib.h>
+#include <X11/Xutil.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include <unistd.h>
+
+int main(int argc, char **argv)
+{
+    const char *dpy = argc > 1 ? argv[1] : ":1";
+    const char *out = argc > 2 ? argv[2] : "/dev/shm/gzframes.bin";
+    long maxf = argc > 3 ? atol(argv[3]) : 0;
+    long pace = argc > 4 ? atol(argv[4]) : 0;
+    Display *d;
+    Window root;
+    XWindowAttributes wa;
+    FILE *f;
+    char hdr[4096];
+    uint64_t seq = 0;
+
+    d = XOpenDisplay(dpy);
+    if (!d) {
+        fprintf(stderr, "xgrab: cannot open display %s\n", dpy);
+        return 1;
+    }
+    root = DefaultRootWindow(d);
+    if (!XGetWindowAttributes(d, root, &wa)) {
+        fprintf(stderr, "xgrab: no root attrs\n");
+        return 1;
+    }
+    fprintf(stderr, "xgrab: root %dx%d depth=%d\n", wa.width, wa.height,
+            wa.depth);
+    f = fopen(out, "wb");
+    if (!f) {
+        perror("xgrab: open out");
+        return 1;
+    }
+    memset(hdr, 0, sizeof(hdr));
+    memcpy(hdr, "GZCAPV01", 8);
+    fwrite(hdr, 1, sizeof(hdr), f);
+    fflush(f);
+
+    while (!maxf || (long)seq < maxf) {
+        XImage *im = XGetImage(d, root, 0, 0, wa.width, wa.height,
+                               AllPlanes, ZPixmap);
+        struct timespec ts;
+        uint64_t tns;
+        uint32_t rh[4];
+        char m[4] = { 'G', 'Z', 'F', '2' };
+        int y;
+
+        if (!im) {
+            usleep(10000);
+            continue;
+        }
+        if (im->bits_per_pixel != 32) {
+            fprintf(stderr, "xgrab: unexpected bpp %d\n",
+                    im->bits_per_pixel);
+            XDestroyImage(im);
+            break;
+        }
+        clock_gettime(CLOCK_MONOTONIC, &ts);
+        tns = (uint64_t)ts.tv_sec * 1000000000ull + (uint64_t)ts.tv_nsec;
+        rh[0] = (uint32_t)wa.width;
+        rh[1] = (uint32_t)wa.height;
+        rh[2] = (uint32_t)wa.width * 4;
+        rh[3] = 32;
+        fwrite(m, 1, 4, f);
+        fwrite(rh, 4, 4, f);
+        fwrite(&tns, 8, 1, f);
+        fwrite(&seq, 8, 1, f);
+        for (y = 0; y < wa.height; y++)
+            fwrite(im->data + (size_t)y * im->bytes_per_line, 1,
+                   (size_t)wa.width * 4, f);
+        fflush(f);
+        seq++;
+        XDestroyImage(im);
+        if (pace)
+            usleep(pace);
+        if ((seq & 63) == 0)
+            fprintf(stderr, "xgrab: frames=%llu\n",
+                    (unsigned long long)seq);
+    }
+    {
+        char m[4] = { 'G', 'Z', 'F', '2' };
+        uint64_t end = 0xFFFFFFFFFFFFFFFFull;
+
+        fwrite(m, 1, 4, f);
+        fwrite(&end, 8, 1, f);
+        fflush(f);
+    }
+    fclose(f);
+    XCloseDisplay(d);
+    fprintf(stderr, "xgrab: done frames=%llu\n", (unsigned long long)seq);
+    return 0;
+}
diff --git a/tools/guest-diag/xresize.c b/tools/guest-diag/xresize.c
new file mode 100644
index 0000000..877f0e9
--- /dev/null
+++ b/tools/guest-diag/xresize.c
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// xresize.c - find a window by name substring and resize/move it (Xvfb has
+// no WM, so a client-side XMoveResizeWindow is the only way to force the
+// game window onto the screen).
+// Usage: xresize <display> <name-substr> <w> <h> <x> <y>
+#include <X11/Xlib.h>
+#include <X11/Xutil.h>
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+
+static Window find_named(Display *d, Window root, const char *sub)
+{
+    Window r, parent, *kids = NULL;
+    unsigned int nkids = 0;
+
+    if (!XQueryTree(d, root, &r, &parent, &kids, &nkids))
+        return 0;
+    for (unsigned int i = 0; i < nkids; i++) {
+        char *name = NULL;
+
+        if (XFetchName(d, kids[i], &name) && name) {
+            int hit = strstr(name, sub) != NULL;
+
+            XFree(name);
+            if (hit) {
+                Window w = kids[i];
+
+                if (kids)
+                    XFree(kids);
+                return w;
+            }
+        }
+    }
+    if (kids)
+        XFree(kids);
+    return 0;
+}
+
+int main(int argc, char **argv)
+{
+    Display *d;
+    Window w;
+
+    if (argc < 6) {
+        fprintf(stderr, "usage: xresize <display> <name> <w> <h> <x> <y>\n");
+        return 2;
+    }
+    d = XOpenDisplay(argv[1]);
+    if (!d) {
+        fprintf(stderr, "no display\n");
+        return 1;
+    }
+    w = find_named(d, DefaultRootWindow(d), argv[2]);
+    if (!w) {
+        fprintf(stderr, "window '%s' not found\n", argv[2]);
+        return 1;
+    }
+    XMoveResizeWindow(d, w, atoi(argv[5]), atoi(argv[6]), atoi(argv[3]),
+                      atoi(argv[4]));
+    XFlush(d);
+    printf("resized 0x%lx to %sx%s at %s,%s\n", w, argv[3], argv[4],
+           argv[5], argv[6]);
+    XCloseDisplay(d);
+    return 0;
+}
diff --git a/tools/guest-diag/xtest_move.c b/tools/guest-diag/xtest_move.c
new file mode 100644
index 0000000..a156bf8
--- /dev/null
+++ b/tools/guest-diag/xtest_move.c
@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: BSD-3-Clause
+// xtest_move.c - drive the game with XTEST: hold forward + fire and tap
+// left/right periodically so the captured footage has constant motion.
+// Usage: xtest_move <display> <seconds>
+#include <X11/Xlib.h>
+#include <X11/keysym.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <string.h>
+
+extern int XTestFakeKeyEvent(Display *, unsigned int, int, unsigned long);
+
+int main(int argc, char **argv)
+{
+    Display *d = XOpenDisplay(argc > 1 ? argv[1] : ":1");
+    int secs = argc > 2 ? atoi(argv[2]) : 12;
+    KeyCode kFwd, kFire, kLeft, kRight;
+    int t;
+
+    if (!d) {
+        fprintf(stderr, "xtest_move: no display\n");
+        return 1;
+    }
+    /* No WM on Xvfb: give the game window input focus ourselves. */
+    {
+        Window r, parent, *kids = NULL;
+        unsigned int nk = 0;
+
+        if (XQueryTree(d, DefaultRootWindow(d), &r, &parent, &kids, &nk)) {
+            unsigned int i;
+
+            for (i = 0; i < nk; i++) {
+                char *nm = NULL;
+
+                if (XFetchName(d, kids[i], &nm) && nm) {
+                    int hit = strstr(nm, "Freedoom") || strstr(nm, "Doom") ||
+                              strstr(nm, "gzdoom") || strstr(nm, "Outer");
+
+                    XFree(nm);
+                    if (hit) {
+                        XSetInputFocus(d, kids[i], RevertToParent, CurrentTime);
+                        fprintf(stderr, "xtest_move: focused 0x%lx\n",
+                                (unsigned long)kids[i]);
+                        break;
+                    }
+                }
+            }
+            if (kids)
+                XFree(kids);
+        }
+    }
+    kFwd = XKeysymToKeycode(d, XK_Up);
+    kFire = XKeysymToKeycode(d, XK_space);
+    kLeft = XKeysymToKeycode(d, XK_Left);
+    kRight = XKeysymToKeycode(d, XK_Right);
+    fprintf(stderr, "xtest_move: fwd=%d fire=%d left=%d right=%d\n",
+            kFwd, kFire, kLeft, kRight);
+    XTestFakeKeyEvent(d, kFwd, 1, 0);
+    XTestFakeKeyEvent(d, kFire, 1, 0);
+    XFlush(d);
+    /* Continuous motion: rotate steadily (hold a turn key ~0.8 s, then
+     * the other) while forward+fire stay held - every frame changes. */
+    for (t = 0; t < secs * 10; t++) {
+        KeyCode turn = (t & 8) ? kLeft : kRight;
+        Window wr, wpar, *wk = NULL;
+        unsigned int wnk = 0;
+
+        /* Re-assert focus every tick: Xvfb has no WM, and any new X client
+         * (the capture tool) can leave the game unfocused - GZDoom pauses
+         * the game the moment SDL reports focus loss. */
+        if (XQueryTree(d, DefaultRootWindow(d), &wr, &wpar, &wk, &wnk)) {
+            unsigned int i;
+
+            for (i = 0; i < wnk; i++) {
+                char *nm = NULL;
+
+                if (XFetchName(d, wk[i], &nm) && nm) {
+                    int hit = strstr(nm, "Freedoom") || strstr(nm, "Outer") ||
+                              strstr(nm, "Doom");
+
+                    XFree(nm);
+                    if (hit) {
+                        XSetInputFocus(d, wk[i], RevertToParent,
+                                       CurrentTime);
+                        break;
+                    }
+                }
+            }
+            if (wk)
+                XFree(wk);
+        }
+        XTestFakeKeyEvent(d, kLeft, 0, 0);
+        XTestFakeKeyEvent(d, kRight, 0, 0);
+        XTestFakeKeyEvent(d, turn, 1, 0);
+        XFlush(d);
+        usleep(100000);
+    }
+    XTestFakeKeyEvent(d, kLeft, 0, 0);
+    XTestFakeKeyEvent(d, kRight, 0, 0);
+    XTestFakeKeyEvent(d, kFwd, 0, 0);
+    XTestFakeKeyEvent(d, kFire, 0, 0);
+    XFlush(d);
+    XCloseDisplay(d);
+    fprintf(stderr, "xtest_move: done\n");
+    return 0;
+}