Skip to content

LordOS — a free, fast and secure GNU/Linux distribution based on Debian, with its own desktop environment: display server and Wayland compositor in C, a React UI engine on QuickJS, and private native apps.

tools/diag: keylag.sh (2-minute typing delay check) and the key latency harness

Federico Pereira683f33a59ee9
diff --git a/tools/diag/keylag-client.c b/tools/diag/keylag-client.c
new file mode 100644
index 0000000..5b17db5
--- /dev/null
+++ b/tools/diag/keylag-client.c
@@ -0,0 +1,143 @@
+/* keylag-client.c — a minimal Wayland client for the key latency harness (docs/TROUBLESHOOTING.md).
+ *
+ * A 320x200 window that repaints itself in a new colour on every key press and asks for
+ * presentation feedback for that frame. It prints, in CLOCK_MONOTONIC ms:
+ *
+ * client key t=81234.901 wl_keyboard.key (press) arrived
+ * client shown t=81251.300 the frame drawn for it was presented
+ *
+ * (no key identity is printed, like the compositor's trace)
+ *
+ * Build (libwayland-dev and wayland-protocols; the two protocol headers come from wayland-scanner):
+ * P=/usr/share/wayland-protocols
+ * wayland-scanner client-header $P/stable/xdg-shell/xdg-shell.xml xdg-shell-client-protocol.h
+ * wayland-scanner private-code $P/stable/xdg-shell/xdg-shell.xml xdg-shell-protocol.c
+ * wayland-scanner client-header $P/stable/presentation-time/presentation-time.xml presentation-time-client-protocol.h
+ * wayland-scanner private-code $P/stable/presentation-time/presentation-time.xml presentation-time-protocol.c
+ * cc -O2 -I. -o keylag-client keylag-client.c xdg-shell-protocol.c presentation-time-protocol.c -lwayland-client
+ * Run inside a LordOS session: XDG_RUNTIME_DIR=/run/user/$(id -u) WAYLAND_DISPLAY=wayland-0 ./keylag-client */
+#define _GNU_SOURCE
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/mman.h>
+#include <time.h>
+#include <unistd.h>
+#include <wayland-client.h>
+
+#include "xdg-shell-client-protocol.h"
+#include "presentation-time-client-protocol.h"
+
+#define W 320
+#define H 200
+
+static struct wl_compositor *comp;
+static struct wl_shm *shm;
+static struct xdg_wm_base *wm;
+static struct wl_seat *seat;
+static struct wp_presentation *pres;
+static struct wl_surface *surf;
+static struct wl_buffer *buf[2];
+static uint32_t *px[2];
+static int cur, configured;
+
+static double mono_ms(void) {
+ struct timespec t;
+ clock_gettime(CLOCK_MONOTONIC, &t);
+ return t.tv_sec * 1e3 + t.tv_nsec / 1e6;
+}
+
+static void fb_sync(void *d, struct wp_presentation_feedback *f, struct wl_output *o) { (void)d; (void)f; (void)o; }
+static void fb_presented(void *d, struct wp_presentation_feedback *f, uint32_t hi, uint32_t lo, uint32_t ns, uint32_t refresh,
+ uint32_t shi, uint32_t slo, uint32_t flags) {
+ (void)refresh; (void)shi; (void)slo; (void)flags;
+ double t = ((double)(((uint64_t)hi << 32) | lo)) * 1e3 + ns / 1e6;
+ (void)d;
+ printf("client shown t=%.3f\n", t);
+ fflush(stdout);
+ wp_presentation_feedback_destroy(f);
+}
+static void fb_discarded(void *d, struct wp_presentation_feedback *f) {
+ (void)d;
+ printf("client discarded t=%.3f\n", mono_ms());
+ fflush(stdout);
+ wp_presentation_feedback_destroy(f);
+}
+static const struct wp_presentation_feedback_listener fb_l = { fb_sync, fb_presented, fb_discarded };
+
+static void draw(int code) {
+ cur ^= 1;
+ uint32_t c = 0xff000000u | ((uint32_t)(code * 2654435761u) & 0x00ffffffu);
+ for (int i = 0; i < W * H; i++) px[cur][i] = c;
+ wl_surface_attach(surf, buf[cur], 0, 0);
+ wl_surface_damage(surf, 0, 0, W, H);
+ if (pres) wp_presentation_feedback_add_listener(wp_presentation_feedback(pres, surf), &fb_l, (void *)(intptr_t)code);
+ wl_surface_commit(surf);
+}
+
+static void kb_keymap(void *d, struct wl_keyboard *k, uint32_t f, int fd, uint32_t s) { (void)d; (void)k; (void)f; (void)s; close(fd); }
+static void kb_enter(void *d, struct wl_keyboard *k, uint32_t s, struct wl_surface *sf, struct wl_array *a) { (void)d; (void)k; (void)s; (void)sf; (void)a; fprintf(stderr, "keylag-client: keyboard focus\n"); }
+static void kb_leave(void *d, struct wl_keyboard *k, uint32_t s, struct wl_surface *sf) { (void)d; (void)k; (void)s; (void)sf; }
+static void kb_key(void *d, struct wl_keyboard *k, uint32_t serial, uint32_t time, uint32_t key, uint32_t state) {
+ (void)d; (void)k; (void)serial; (void)time;
+ if (state != WL_KEYBOARD_KEY_STATE_PRESSED) return;
+ printf("client key t=%.3f\n", mono_ms());
+ fflush(stdout);
+ draw((int)key);
+}
+static void kb_mods(void *d, struct wl_keyboard *k, uint32_t s, uint32_t a, uint32_t b, uint32_t c, uint32_t g) { (void)d; (void)k; (void)s; (void)a; (void)b; (void)c; (void)g; }
+static void kb_repeat(void *d, struct wl_keyboard *k, int32_t r, int32_t dl) { (void)d; (void)k; (void)r; (void)dl; }
+static const struct wl_keyboard_listener kb_l = { kb_keymap, kb_enter, kb_leave, kb_key, kb_mods, kb_repeat };
+
+static void wm_ping(void *d, struct xdg_wm_base *w, uint32_t s) { (void)d; xdg_wm_base_pong(w, s); }
+static const struct xdg_wm_base_listener wm_l = { wm_ping };
+static void xs_configure(void *d, struct xdg_surface *x, uint32_t s) {
+ (void)d;
+ xdg_surface_ack_configure(x, s);
+ if (!configured) { configured = 1; draw(0); }
+}
+static const struct xdg_surface_listener xs_l = { xs_configure };
+static void top_configure(void *d, struct xdg_toplevel *t, int32_t w, int32_t h, struct wl_array *s) { (void)d; (void)t; (void)w; (void)h; (void)s; }
+static void top_close(void *d, struct xdg_toplevel *t) { (void)d; (void)t; exit(0); }
+static const struct xdg_toplevel_listener top_l = { top_configure, top_close, NULL, NULL };
+
+static void reg_global(void *d, struct wl_registry *r, uint32_t name, const char *iface, uint32_t ver) {
+ (void)d;
+ if (!strcmp(iface, wl_compositor_interface.name)) comp = wl_registry_bind(r, name, &wl_compositor_interface, 4);
+ else if (!strcmp(iface, wl_shm_interface.name)) shm = wl_registry_bind(r, name, &wl_shm_interface, 1);
+ else if (!strcmp(iface, xdg_wm_base_interface.name)) { wm = wl_registry_bind(r, name, &xdg_wm_base_interface, 1); xdg_wm_base_add_listener(wm, &wm_l, NULL); }
+ else if (!strcmp(iface, wl_seat_interface.name)) seat = wl_registry_bind(r, name, &wl_seat_interface, ver < 5 ? ver : 5);
+ else if (!strcmp(iface, wp_presentation_interface.name)) pres = wl_registry_bind(r, name, &wp_presentation_interface, 1);
+}
+static void reg_remove(void *d, struct wl_registry *r, uint32_t n) { (void)d; (void)r; (void)n; }
+static const struct wl_registry_listener reg_l = { reg_global, reg_remove };
+
+int main(void) {
+ struct wl_display *dpy = wl_display_connect(NULL);
+ if (!dpy) { fprintf(stderr, "keylag-client: no Wayland display\n"); return 1; }
+ wl_registry_add_listener(wl_display_get_registry(dpy), &reg_l, NULL);
+ wl_display_roundtrip(dpy);
+ if (!comp || !shm || !wm || !seat) { fprintf(stderr, "keylag-client: missing globals\n"); return 1; }
+ if (!pres) fprintf(stderr, "keylag-client: no wp_presentation (no 'shown' lines)\n");
+ int fd = memfd_create("keylag", MFD_CLOEXEC);
+ size_t one = (size_t)W * H * 4;
+ if (fd < 0 || ftruncate(fd, (off_t)(one * 2))) return 1;
+ uint32_t *map = mmap(NULL, one * 2, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
+ if (map == MAP_FAILED) return 1;
+ struct wl_shm_pool *pool = wl_shm_create_pool(shm, fd, (int32_t)(one * 2));
+ for (int i = 0; i < 2; i++) {
+ px[i] = map + (size_t)i * W * H;
+ buf[i] = wl_shm_pool_create_buffer(pool, (int32_t)(i * one), W, H, W * 4, WL_SHM_FORMAT_XRGB8888);
+ }
+ wl_keyboard_add_listener(wl_seat_get_keyboard(seat), &kb_l, NULL);
+ surf = wl_compositor_create_surface(comp);
+ struct xdg_surface *xs = xdg_wm_base_get_xdg_surface(wm, surf);
+ xdg_surface_add_listener(xs, &xs_l, NULL);
+ struct xdg_toplevel *top = xdg_surface_get_toplevel(xs);
+ xdg_toplevel_add_listener(top, &top_l, NULL);
+ xdg_toplevel_set_title(top, "keylag");
+ wl_surface_commit(surf);
+ while (wl_display_dispatch(dpy) >= 0) {}
+ return 0;
+}
diff --git a/tools/diag/keylag-inject.py b/tools/diag/keylag-inject.py
new file mode 100755
index 0000000..ed8f0cf
--- /dev/null
+++ b/tools/diag/keylag-inject.py
@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+"""keylag-inject.py: types through a virtual uinput keyboard at known times (the latency harness,
+docs/TROUBLESHOOTING.md). Needs write access to /dev/uinput (root).
+
+ sudo python3 tools/diag/keylag-inject.py [count] [interval_ms]
+
+Each press is printed as "inject t=<CLOCK_MONOTONIC ms>" right after the write; the key is
+released 60 ms later. Keys cycle over a..z so a text field shows them.
+"""
+import fcntl
+import os
+import random
+import struct
+import sys
+import time
+
+UI_SET_EVBIT = 0x40045564
+UI_SET_KEYBIT = 0x40045565
+UI_DEV_CREATE = 0x5501
+UI_DEV_DESTROY = 0x5502
+EV_SYN, EV_KEY = 0, 1
+LETTERS = [30, 48, 46, 32, 18, 33, 34, 35, 23, 36, 37, 38, 50, 49, 24, 25, 16, 19, 31, 20, 22, 47, 17, 45, 21, 44]
+
+
+def ev(fd, etype, code, value):
+ t = time.time()
+ os.write(fd, struct.pack("llHHi", int(t), int((t % 1) * 1e6), etype, code, value))
+
+
+def main():
+ count = int(sys.argv[1]) if len(sys.argv) > 1 else 100
+ interval = float(sys.argv[2]) if len(sys.argv) > 2 else 180.0
+ fd = os.open("/dev/uinput", os.O_WRONLY | os.O_NONBLOCK)
+ fcntl.ioctl(fd, UI_SET_EVBIT, EV_KEY)
+ for code in range(1, 128):
+ fcntl.ioctl(fd, UI_SET_KEYBIT, code)
+ # struct uinput_user_dev: name[80], input_id (4 x u16), ff_effects_max, absmax/min/fuzz/flat [64] each
+ dev = struct.pack("80sHHHHi", b"keylag virtual keyboard", 3, 0x1234, 0x5678, 1, 0) + b"\0" * (4 * 64 * 4)
+ os.write(fd, dev)
+ fcntl.ioctl(fd, UI_DEV_CREATE)
+ time.sleep(2.0) # lord-sessiond sees it (inotify) and lends it to the session
+ try:
+ for i in range(count):
+ code = LETTERS[i % len(LETTERS)]
+ ev(fd, EV_KEY, code, 1)
+ ev(fd, EV_SYN, 0, 0)
+ print("inject t=%.3f" % (time.clock_gettime(time.CLOCK_MONOTONIC) * 1e3), flush=True)
+ time.sleep(0.06)
+ ev(fd, EV_KEY, code, 0)
+ ev(fd, EV_SYN, 0, 0)
+ time.sleep(max(0.0, (interval + random.uniform(-40, 40)) / 1e3 - 0.06))
+ finally:
+ time.sleep(0.5)
+ fcntl.ioctl(fd, UI_DEV_DESTROY)
+ os.close(fd)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tools/diag/keylag.sh b/tools/diag/keylag.sh
new file mode 100755
index 0000000..608be49
--- /dev/null
+++ b/tools/diag/keylag.sh
@@ -0,0 +1,123 @@
+#!/bin/sh
+# keylag.sh — where does the typing delay come from? (docs/TROUBLESHOOTING.md, "Typing feels slow")
+#
+# Run it as the logged-in user, in the LordOS Terminal (keys typed there are never traced):
+#
+# sh keylag.sh [seconds] (default 30)
+#
+# 1. It prints what matters for input latency: version, GPU or CPU composition, virtual machine,
+# guest tools, the boot flags, and whether Chromium has complained about the compositor.
+# 2. If the session was started with the key latency trace (boot menu: add lordos.inputdebug=1 to
+# the kernel line, LordOS 0.8.1 or later), it asks you to type in the slow app for a few
+# seconds and prints, per stage, p50/p95/max in ms after the kernel's evdev timestamp:
+# lord-server read it (rx), the app got it (flush), the app answered (commit) and the frame with
+# it was on screen (shown). The trace has timings only: no key, character or modifier.
+# 3. It says which stage is slow and what to try.
+set -u
+export LC_ALL=C # decimal points in awk and printf
+SECS=${1:-30}
+RT=${XDG_RUNTIME_DIR:-/run/user/$(id -u)}
+TRACE=$RT/lordos-keylag.log
+LOGDIR=$HOME/.cache/lordos
+SLOG=$LOGDIR/session.log
+ALOG=$LOGDIR/apps.log
+
+say() { printf '%s\n' "$*"; }
+
+say "== LordOS key latency check"
+ver=$(dpkg-query -W -f '${Version}' lordos 2>/dev/null || echo "?")
+virt=$(systemd-detect-virt 2>/dev/null || echo "?")
+cmd=$(cat /proc/cmdline)
+comp="unknown"
+if [ -r "$SLOG" ]; then
+ if grep -q "gpu: GPU composition" "$SLOG"; then comp="GPU ($(grep -m1 'gpu: GPU composition' "$SLOG" | sed 's/.*composition (\([^,]*\).*/\1/'))"
+ elif grep -q "gpu:" "$SLOG"; then comp="CPU"; fi
+fi
+tools="not installed"
+if command -v vmtoolsd >/dev/null 2>&1; then
+ tools="installed, $(systemctl is-active open-vm-tools 2>/dev/null)"
+ ts=$(vmware-toolbox-cmd timesync status 2>/dev/null) && tools="$tools, host time sync $ts"
+fi
+say "version: $ver"
+say "virtualization: $virt"
+say "composition: $comp"
+say "guest tools: $tools"
+case " $cmd " in *" lordos.gpu=0 "*) say "boot flag: lordos.gpu=0 (CPU composition forced)";; esac
+case " $cmd " in *" lordos.inputdebug=1 "*) say "boot flag: lordos.inputdebug=1 (key latency trace)";; esac
+buggy=0
+[ -r "$ALOG" ] && buggy=$(grep -c "buggy presentation feedback" "$ALOG" 2>/dev/null)
+say "Chromium: \"buggy presentation feedback\" $buggy time(s) in this session's app log"
+say ""
+
+if ! grep -q "keylag: key latency trace on" "$SLOG" 2>/dev/null; then
+ say "No key latency trace in this session."
+ if [ "$buggy" -gt 0 ] && [ "${comp#GPU}" != "$comp" ]; then
+ say "-> Chromium's warning on the GPU path is the presentation bug fixed in LordOS 0.8.1: a Linux"
+ say " app's new frame was only shown when something else on the screen changed (up to ~1 s late)."
+ say " To confirm on this build in 2 minutes: reboot, press 'e' in the boot menu, add lordos.gpu=0"
+ say " at the end of the 'linux' line, Ctrl+X, then type in Chromium. If the delay is gone, that was it."
+ fi
+ say "With LordOS 0.8.1 or later: add lordos.inputdebug=1 the same way (one boot only) and run this again."
+ exit 0
+fi
+
+before=0
+[ -f "$TRACE" ] && before=$(wc -l < "$TRACE")
+say "Click the slow app (Chromium, Firefox...) and type normally for $SECS seconds, starting now."
+say "(The trace stops by itself 120 s after the first traced key; log out and in for a new one.)"
+i=$SECS
+while [ "$i" -gt 0 ]; do printf '\r%3d s ' "$i"; sleep 1; i=$((i - 1)); done
+printf '\r \n'
+if [ ! -f "$TRACE" ]; then
+ say "Nothing was traced: no key reached a Linux app (keys for LordOS's own apps are never traced)."
+ exit 1
+fi
+tail -n +"$((before + 1))" "$TRACE" | grep '^keylag n=' | grep ' press ' > "$RT/keylag-run.txt"
+n=$(wc -l < "$RT/keylag-run.txt")
+grep -q '^keylag stop' "$TRACE" && say "note: $(grep -m1 '^keylag stop' "$TRACE")"
+if [ "$n" -lt 5 ]; then say "Only $n key presses traced: type a bit more and run it again."; exit 1; fi
+
+# p50 / p95 / max of one field (rx=, flush=...), values of -1 left out
+stats() {
+ sed -n "s/.* $1=\([-0-9.]*\).*/\1/p" "$RT/keylag-run.txt" | awk '$1 >= 0' | sort -n | awk '
+ { v[NR] = $1 }
+ END { if (!NR) { print " - - -"; exit }
+ i50 = int((NR - 1) * 0.50) + 1; i95 = int((NR - 1) * 0.95) + 1
+ printf "%7.1f %7.1f %7.1f\n", v[i50], v[i95], v[NR] }'
+}
+say ""
+say "$n key presses (ms after the kernel event) p50 p95 max"
+for f in rx flush commit shown; do
+ case $f in
+ rx) label="lord-server read the key (rx)";;
+ flush) label="the app received it (flush)";;
+ commit) label="the app drew its answer (commit)";;
+ shown) label="that frame was on screen (shown)";;
+ esac
+ printf '%-44s %s\n' "$label" "$(stats $f)"
+done
+p95() { stats "$1" | awk '{print int($2)}'; }
+rx=$(p95 rx); fl=$(p95 flush); co=$(p95 commit); sh=$(p95 shown)
+# keys arriving in clumps (< 15 ms apart): they were held back before the guest's kernel
+clump=$(sed -n 's/.* ev=\([0-9.]*\) .*/\1/p' "$RT/keylag-run.txt" | awk 'NR > 1 && $1 - p < 15 { c++ } { p = $1 } END { printf "%d", 100 * c / (NR > 1 ? NR - 1 : 1) }')
+say ""
+say "key presses arriving less than 15 ms after the previous one: $clump %"
+say ""
+if [ "$rx" -gt 30 ]; then
+ say "-> lord-server is slow to read keys (busy main loop). Note what is open and report it with this output."
+elif [ "$((co - fl))" -gt 50 ]; then
+ say "-> The app itself is slow to answer (commit - flush). Try it with fewer tabs or without the video."
+elif [ "$((sh - co))" -gt 50 ]; then
+ say "-> Frames reach the screen late (shown - commit): compositor presentation. Report it with this output;"
+ say " meanwhile boot with lordos.gpu=0 (CPU composition)."
+elif [ "$sh" -le 40 ] && [ "$clump" -ge 20 ]; then
+ say "-> Inside the guest every stage is fast, but keys arrive in clumps: the delay is before the guest"
+ say " kernel, in the hypervisor. On VMware try: 'Accelerate 3D graphics' off, fewer vCPUs, or in the"
+ say " .vmx keyboard.vusb.enable = \"TRUE\" (docs/TROUBLESHOOTING.md)."
+elif [ "$sh" -le 40 ]; then
+ say "-> Every stage inside the guest is fast (p95 under 40 ms). If typing still feels slow, the delay is"
+ say " before the guest kernel (the hypervisor or the host): see docs/TROUBLESHOOTING.md."
+else
+ say "-> Mixed result: keep this output and report it."
+fi
+rm -f "$RT/keylag-run.txt"