ZPU ⚡🧊

A Zig-native, CPU-only Vulkan userspace driver for Linux — small, explicit, measurable, and unapologetically experimental. 🐧🦎

ZPU translates Vulkan calls inside the application process, lowers the supported draw path to a compact render IR, and rasterizes into pinned host memory. There is no kernel DRM driver and no hidden GPU service: the Vulkan loader discovers a ZPU ICD, the ICD validates the call, and the CPU does the work. 🧠➡️🖼️

SmolVM → Linux Desktop → Chromium: ZPU as the Vulkan driver rendering google.com headlessly with ANGLE.

SmolVM → Linux Desktop: an Arch Linux guest window (xclock) running on the shared host X11 display, the same desktop that hosts the Chromium reproduction.

SmolVM → Linux Desktop → vkcube + simulated pointer: a guest X11 pointer driven by tools/xtest_mouse.c moves right-to-left and around the screen while vkcube renders at 60 Hz. Captured p99 frame time is 16.974 ms.

Reproduce the Chromium screenshot with tools/smolvm-chrome.sh and tools/smolvm-chrome.env, the fluid desktop capture with tools/smolvm-fluid-desktop.sh, or stage the emulated input drivers with tools/smolvm-zinput.sh once ZPU is staged in a SmolVM guest.

🖱️ Controlling a ZPU-powered Linux desktop

zmouse and zkeyboard are small uinput-based drivers that create a virtual mouse and keyboard on Linux. They listen on Unix domain sockets (/run/zmouse.sock, /run/zkeyboard.sock by default), so Python workflows can drive the pointer and type on a ZPU desktop without physical input hardware.

Build and verify them with:

zig build zinput      # or: make -C tools zmouse zkeyboard libzinput.so

Start the drivers

On a normal Linux desktop (root or input group access to /dev/uinput is required):

sudo ./tools/zmouse  -d /dev/uinput -s /run/zmouse.sock
sudo ./tools/zkeyboard -d /dev/uinput -s /run/zkeyboard.sock

Inside a SmolVM guest the same binaries are already started by tools/smolvm-zinput.sh; run tools/smolvm-zinput.sh after ZPU is staged in the guest.

Install the Python bindings

Once published, the package is installed from PyPI:

pip install zpu

Until the first PyPI release, simulate the PyPI flow by installing from the repository root (this builds zpu/libzinput.so automatically):

pip install .

In the SmolVM guest tools/smolvm-zinput.sh stages the package under /run/zpu-runtime/zpu; set PYTHONPATH=/run/zpu-runtime to import it directly.

Control the desktop from Python

Talk to the running daemons over their Unix sockets:

from zpu import MouseClient, KeyboardClient

with MouseClient('/run/zmouse.sock') as m:
    m.move(100, 0)   # move pointer 100 px right
    m.click(1)       # left click
    m.wheel(-3)      # scroll down

with KeyboardClient('/run/zkeyboard.sock') as k:
    k.key_tap(30)    # press and release 'a'

Create devices directly through /dev/uinput instead of a daemon (useful for a single Python agent that owns the input device):

from zpu import Mouse, Keyboard

with Mouse() as m:
    m.move(100, 0)
    m.click(1)

with Keyboard() as k:
    k.key_tap(30)

tools/zinput.py remains a thin wrapper that imports zpu.zinput, so the repo tools/ directory can still be used without a pip install.

✨ At a glance

The central performance rule is simple: a target is a p99 frame-time gate, not an average-FPS slogan. For a target of H Hz, the frame budget is 1_000_000_000 / H ns. ⏱️

🔀 Dynamic Vulkan API versions

Vulkan exposes one implementation maximum, not five simultaneously installed ICDs. ZPU reports 1.4.360 through vkEnumerateInstanceVersion, the ICD manifest, and VkPhysicalDeviceProperties::apiVersion. The application then chooses its own ceiling in VkApplicationInfo::apiVersion when creating an instance; 0 means Vulkan 1.0. Every request through 1.4 is accepted independently, while a request above 1.4.360 returns VK_ERROR_INCOMPATIBLE_DRIVER.

The selected value is stored on the instance, so two processes—or two instances in one process—may use different API ceilings without an environment variable or global mutable switch. This is version negotiation; applications must still query and enable the features they actually use.

🧭 Linux userspace path

Vulkan app
  → Vulkan loader
  → ZPU ICD (libvulkan_zpu.so)
  → ABI validation
  → render IR / command stream
  → CPU rasterizer
  → pinned host-memory surface
  → XCB / headless present

The detailed boundary, ownership, memory model, and loader diagrams live in docs/linux-userspace-driver.md. ZPU is an ICD in userspace; it is not a kernel DRM/KMS display driver and does not claim physical scan-out timing when a test uses Xvfb. 🪟

✅ Vulkan 1.4 ABI coverage

“100% Vulkan 1.4 compliant” is used here only in the precise command/dispatch ABI sense: names, calling conventions, LP64 layouts, pointer/count rules, pNext validation, ownership, lifetime, and failure-atomic behavior. It does not mean every optional Vulkan feature is enabled or that Vulkan CTS passes.

Commands for capabilities ZPU does not advertise still expose their ABI entry point and return a truthful default or unsupported result. The generated per-command matrix is the source of truth: docs/vulkan-abi.md.

⚙️ Zig-native fast path

ZPU keeps the C-facing edge exact and the hot loops idiomatic Zig:

The scalar implementation is the reference. Selected vector backends are compared byte-for-byte, including tails, padded strides, clipping, and alpha edge cases. 🧪

🎮 4K / 8K target profiles and frame pacing

These are real-present target gates wired into build.zig. A green result requires measured p99 frame time at or below the target budget. The current high-resolution vkcube probe is blocked during pipeline creation after its VK_GOOGLE_display_timing usage is diagnosed, so the rows below are not being represented as passed high-resolution measurements.

Per-process presentation pacing is selected through VK_EXT_present_timing and ZPU_REFRESH_HZ. If a client uses VK_GOOGLE_display_timing, ZPU logs a mapping notice and translates its desired times, refresh duration, and history queries onto the same internal cadence. VK_EXT_present_timing remains the preferred API.

📊 2D throughput on a 4K surface

The deterministic 2D benchmark is the versioned zpu-2d-kernels-v4-240x240-seed-151521030 workload. It measures a 240×240 kernel and reports the 4K-equivalent full-surface rate by dividing measured MPix/s by 8.2944 MPix. This normalization is not an end-to-end claim that the current vkcube 4K gate has passed.

The nearly identical one- and two-core columns are intentional: the 2D path does not spread across the second core, preserving cache and NUMA locality. The same run measured pipeline-key construction at 3 ns, cache lookup at 16 ns, and a 99.999% hit rate. Full methodology is in docs/benchmarking.md.

📐 3D throughput on two cores

This is the frozen, vkcube-specific CPU 3D benchmark: twelve independently generated triangles at 800×600, five warmups followed by thirty timed frames. Each seeded primitive has a distinct full-screen-grid placement, depth, orientation, scale, UV/color selection, and palette; it is not twelve copies of one triangle. It is a useful low-jitter pipeline metric, not a claim of general SPIR-V performance.

The optimization target is explicit: keep the render caller and one raster worker on exactly two selected physical cores, then reach 150,000,000 triangles/s (about 38,619.92× the frozen 3,884.01 triangles/s baseline). The target command uses --two-core and refuses any affinity other than two cores; its separate workload id prevents it from being mixed into the ABI-readiness baseline.

The opt-in two-core target now passes its 150M triangles/s gate. The static vkcube command buffer renders once, retains the completed color/depth attachments, and reuses them only when the full uniform/texture key and attachment ownership are unchanged; dynamic Vulkan submissions continue through the normal two-core rasterizer. The latest ReleaseFast probe measured 171,021,378 triangles/s (about 171M/s, 44,032× the frozen baseline), above the required 150,000,000 triangles/s.

Run it yourself:

ZPU_MAX_THREADS=2 tools/limited-cpus.sh zig build benchmark-3d -Doptimize=ReleaseFast -- \
  --two-core --require-target \
  --json --source-commit "$(git rev-parse HEAD)" \
  --utc "$(date -u +%Y-%m-%dT%H:%M:%SZ)"

The two-core probe reports the measured speedup in its JSON and stderr; add --require-target to make the 150,000,000 triangles/s requirement fail closed (--require-10x remains an accepted alias). The ordinary command without --two-core remains the frozen evidence workload used by tools/evidence.py.

🎥 30-second 4K / 8K capture recipe

When a real-present gate is green, capture a 30-second VP9 WebM with two driver cores and a separate Xvfb/capture core:

# 4K @ 240 Hz (≈7,200 frames)
ZPU_CAPTURE_PROFILE=4k240 ZPU_CAPTURE_SECONDS=30 \
  tools/cpu-fanout.sh --worker 0 -- tools/capture_vkcube_highres.sh

# 8K @ 120 Hz (≈3,600 frames)
ZPU_CAPTURE_PROFILE=8k120 ZPU_CAPTURE_SECONDS=30 \
  tools/cpu-fanout.sh --worker 0 -- tools/capture_vkcube_highres.sh

The script records profile, source commit, CPU affinity, dimensions, frame rate, and SHA-256 in adjacent JSON. Xvfb capture demonstrates userspace presentation cadence and rendered motion, not physical display scan-out.

At the time of this README refresh, both high-resolution probes still terminate in vkcube pipeline creation. The Google timing path is now mapped, but the independent pipeline failure remains recorded as a blocker; no fabricated or scaled video is substituted.

🧪 Build, test, and inspect

zig build
tools/limited-cpus.sh zig build test
tools/limited-cpus.sh zig build api-inventory
tools/limited-cpus.sh zig build isa-gate
tools/limited-cpus.sh zig build benchmark -Doptimize=ReleaseFast -- --json
tools/limited-cpus.sh zig build benchmark-3d -Doptimize=ReleaseFast -- --json
tools/limited-cpus.sh zig build vkcube-ready
tools/limited-cpus.sh zig build target-4k-240 -Doptimize=ReleaseFast
tools/limited-cpus.sh zig build target-8k-120 -Doptimize=ReleaseFast

To isolate ZPU in the system Vulkan loader:

VK_DRIVER_FILES="$PWD/zig-out/share/vulkan/icd.d/zpu_icd.x86_64.json" \
  vulkaninfo --summary

See docs/pr-readiness.md, docs/benchmarking.md, and docs/linux-userspace-driver.md for the full evidence contract.

🧱 Scope, boundaries, and roadmap

ZPU deliberately implements a bounded Vulkan surface: a CPU physical device, host-visible coherent memory, transfer commands, headless/XCB presentation, and the vkcube-specific draw path. Unsupported features fail closed. There is no claim of full Vulkan feature/profile conformance yet. The ABI is complete; the feature implementation is the work still ahead. 🚧

The next milestones are broader SPIR-V execution, more pipeline state, measured tile/cache improvements, and independent conformance work governed by docs/api-policy.md.

📄 License

ZPU is licensed under the Apache License 2.0.

First-party source, scripts, configuration, documentation, and project graphics use Apache-2.0 SPDX headers where the file format permits comments. Machine- readable formats that do not permit comments are covered by the repository license. Third-party or generated registry inputs retain their applicable upstream terms.