Wine-NSPA 11.x

Architecture, Implementation, and Validation

This repository publishes the public design, architecture, and validation documentation for Wine-NSPA 11.x -- a PREEMPT_RT-focused fork of Wine 11.8 with end-to-end priority inheritance, kernel-mediated IPC, client-side NT surfaces, and RT-oriented memory and I/O work.

View Documentation

---

Documentation

Architecture & Design

Document	Description
Aggregate-Wait and Async Completion	Aggregate-wait, same-thread CQE drain, and async completion ownership.
Architecture Overview	System map for the current client, wineserver, and kernel layers.
Audio Stack	winejack, nspaASIO, and the RT callback audio path.
Client Scheduler Architecture	wine-sched, wine-sched-rt, close queue, and sched-hosted timers.
Critical Section PI	Priority inheritance for CRITICAL_SECTION.
Gamma Channel Dispatcher	Kernel-mediated wineserver IPC, aggregate-wait, and burst drain.
Hook Cache	Tier 1 + Tier 2 Win32 hook-chain caching.
Hot-Path Optimizations	TEB state, cache layout, SIMD string/Unicode loops, and other cost trims.
io_uring I/O Architecture	File, socket, and async CreateFile use of io_uring.
librtpi (PI mutex / condvar)	Wine’s internal PI mutex and condvar shim.
Local-File Bypass Architecture	Local regular-file and explicit-directory handling.
Local Section Bypass	Client-side unnamed file-backed sections on local-file handles.
Message Ring Architecture	Message rings, redraw push, paint cache, and empty-poll caching.
Memory, Sections, Large Pages, and Working-Set Support	Sections, large pages, working-set support, and shared-memory backing.
NT Local Stubs	The NT-local stub pattern and the active stub surfaces.
NTSync PI Kernel	Kernel-side ntsync overlay, PI, channels, and aggregate-wait.
NTSync Userspace Sync	Wine-side ntsync cache, wait/signal path, and zero-time waits.
Thread and Process Shared-State Bypass	Published thread/process snapshots and zero-time waits.
NSPA X11 Embed Protocol	Atomic X11 embedding for Winelib hosts with Wine HWND children.
NSPA Wayland Embed Protocol	Native Wayland embedding for Winelib hosts with Wine HWND children.
Win32 Condvar PI (Requeue-PI)	Priority inheritance for Win32 condition variables.
Wineserver Decomposition	Residual wineserver scope and decomposition path.

Applications

Document	Description
Lulada	Linux Digital Audio Workstation with recording, sequencing, JACK routing, and in-process Windows plugins.
JUCE-NSPA	Framework fork for Linux winelib hosting and native plugin embedding.
Yabridge-NSPA	Linux VST bridge fork aligned to Wine-NSPA RT and PI rules.

Test Results & Validation

Document	Description
RT Test Harness	Native ntsync tests, PE matrix, and targeted follow-on validators.
State of The Art	Current defaults, validation totals, and measured results.
Test Suite Comparison	Archived suite snapshots, per-test deltas, and targeted A/Bs.

Historical / Superseded

Document	Description
Shmem IPC (legacy)	The v1.5 / v2.4 per-thread pthread + userspace sched_setscheduler boost dispatcher. Superseded by the gamma channel dispatcher; retained for historical context.
Decoration Loop Investigation	Ableton Live 12 windowing debug (WineHQ bug 57955). X11 fixed, Wayland untested. Investigation complete.
Sync Primitives Research	Background research on SRW spin, condvar PI, adaptive CS across Windows / glibc / Linux kernel. Research archive.

---

Status

The current archived full-suite boundary is Layer 1 native ntsync 3 PASS / 0 FAIL / 0 SKIP plus Layer 2 PE matrix 32 PASS / 0 FAIL / 0 TIMEOUT (v9-validation-default). Newer work is documented as targeted follow-on validation on top of that baseline.

Current highlights:

• client scheduler hosts, local events, local timers, and socket io_uring send/recv are on the normal path
• widened local-file coverage and local sections keep more file and mapping work client-side
• thread/process shared-state readers also power zero-time process and thread waits
• msg-ring, empty-poll caching, x86_64 TEB hot state, cacheline-shaped userspace sync, and AVX2 string/Unicode loops further reduce hot-path overhead
• RT memory follow-ons include mlockall(), automatic hugetlb promotion, heap hugepage backing, and the safety/fallback fixes around them
• winelib hosts can embed Wine HWND-backed plugin editors through X11 or Wayland-specific Wine-NSPA protocols

---

Related

• Linux-NSPA Kernel -- Custom PREEMPT_RT kernel with NTSync PI patches
• librtpi -- upstream-tracking PI mutex / condvar library. Wine-NSPA carries a Wine-internal header-only re-implementation of the same public API at libs/librtpi/rtpi.h, plus the NSPA_RTPI_MUTEX_RECURSIVE extension required by virtual_mutex and a few other recursive sites. See the librtpi documentation page for details.
• Wine-NSPA Wiki -- Installation and configuration (8.x)