This repository documents the ongoing research, implementation, and validation work for Wine-NSPA 11.x -- a real-time capable, priority-inheritance-aware build of Wine targeting PREEMPT_RT broadly, with professional audio workloads as a leading test case.
Wine-NSPA 11.x is a work in progress built on top of upstream Wine 11.6. Everything here is subject to change -- designs may be revised, features may be reworked or dropped, and nothing should be considered stable or final. This documentation tracks the evolving design decisions, test results, and research as the work progresses.
| Document | Description |
|---|---|
| Aggregate-Wait and Async Completion | Landed kernel 1010 + dispatcher Phase 2/3 architecture: NTSYNC_IOC_AGGREGATE_WAIT, per-process dispatcher-owned io_uring, and same-thread CQE drain / reply. The 2026-04-30 Phase 4 / 1011 follow-ons build on this base. |
| Architecture Overview | Master system map: client / wineserver / kernel layering, shipped bypass surfaces, residual wineserver floor, and links into the dedicated subsystem docs below. |
| Audio Stack | winejack.drv (WASAPI + MIDI via JACK), nspaASIO bridge (ASIO -> WASAPI exclusive -> winejack -> JACK), Phase F zero-latency bufferSwitch inside the JACK callback. |
| Critical Section PI | FUTEX_LOCK_PI on CRITICAL_SECTION: fast / slow path, PI chain, gating, fallback. v2.3 stable. |
| Gamma Channel Dispatcher | Hybrid ntsync + wineserver request plane: single per-process channel transport, aggregate-wait over channel + uring eventfd + shutdown eventfd, and post-1011 TRY_RECV2 burst drain. |
| Hook Cache | Two-tier Win32 hook chain cache. Tier 1 server-side count rebuild + Tier 2 full chain snapshot in queue_shm; clients walk the chain locally without RPC. |
| io_uring I/O Architecture | Phase 1 file I/O bypass and Phase 4 dispatcher-owned async CreateFile are shipped. Phase 2 sockets and Phase 3 pipes / named events remain queued. ntsync uring_fd integration. |
| Local-File Bypass Architecture | NtCreateFile bypass for read-only regular files: client-private handle range, per-process table, shared inode-aggregation shmem with seqlock + PSHARED PI mutex bucket lock. ~28,500 file opens offloaded per Ableton startup. |
| Message Ring Architecture | Cross-thread PostMessage / SendMessage via per-queue memfd rings. Includes Phase A redraw-window push ring, Phase B1.0 paint-cache fastpath, Phase C get_message bypass (paused), and the MR1 / MR2 / MR4 audit fix-pack. |
| NT Local Stubs | The architectural pattern of client-side stubs that satisfy NT-API calls without crossing into wineserver. Currently shipped: nspa_local_file, nspa_local_timer, nspa_local_wm_timer. |
| NTSync PI Kernel Driver | Patch series 1003-1011: PI primitives, channel object, thread-token pass-through, RT alloc-hoist, hardening fixes, NTSYNC_IOC_AGGREGATE_WAIT, and NTSYNC_IOC_CHANNEL_TRY_RECV2. |
| Win32 Condvar PI (Requeue-PI) | FUTEX_WAIT_REQUEUE_PI for RtlSleepConditionVariableCS: condvar-to-mutex mapping, three new syscalls, zero-gap PI. |
| Wineserver Decomposition Plan | Long-horizon plan to decompose wineserver after enough state migrates out via the bypass trajectories. Phases 1-2 shipped; aggregate-wait kernel/userspace slice landed; timer/fd-poll remainder still queued. |
| Document | Description |
|---|---|
| State of The Art | Current shipped-state board: defaults, kernel + module versions, exact validation totals, performance deltas, remaining gates, and open work. |
| RT Test Harness | Layer 1 native ntsync stress suite + Layer 2 PE matrix, now including dispatcher-burst for gamma / TRY_RECV2 coverage. |
| Test Suite Comparison | v3 -> v8 timeline. Current Layer 1 / Layer 2 totals, dispatcher-burst A/B, and preserved historical latency / throughput reports. |
| 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. |
WIP. The 11.x tree passes its validation suite (Layer 1 native ntsync 3 PASS / 0 FAIL + Layer 2 PE matrix 24 PASS / 0 FAIL / 0 TIMEOUT) and is used for day-to-day development. The 2026-04-30 session added three default-on user-facing features: NSPA_FLUSH_THROTTLE_MS=8, NSPA_ENABLE_ASYNC_CREATE_FILE=1, and NSPA_TRY_RECV2=1.
Immediate follow-on dispatcher tuning also landed on top of that shipped base: ACQ_REL fences, inlined dispatcher helpers, allocator debug poison / valgrind stubs gated out of production builds, and inlined read_request_shm on the gamma hot path.
The 2026-05-01 shipped follow-ons worth carrying in public docs are smaller but real: the winex11.drv alpha-bit flush loop is now AVX2-vectorized (x11drv_surface_flush 6.72% -> 2.39%, total winex11.so 6.76% -> 2.43%, bit-identical output), and the top Tier 1 compatibility/log-noise cleanup landed (~565 stub prints per Ableton run -> ~5 first-time prints, plus ShutdownBlockReasonCreate/Destroy now succeed silently instead of failing with ERROR_CALL_NOT_IMPLEMENTED).
This is an active research branch -- code is not released and the architecture is still evolving.
Key areas under active work:
- 5 PI coverage paths: CS-PI, NTSync PI, pi_cond requeue-PI, Win32 condvar PI, kernel-atomic IPC PI via gamma channels
- Bypass trajectories: most shipped default-on; paint-cache validating; Phase C
get_messagebypass paused mid-development; sechost device-IRP poll and io_uring socket/pipe follow-on queued - NTSync kernel driver: patch series 1003-1011 in production; current module
10124FB81FDC76797EF1F91 - Wineserver decomposition: long-horizon plan with bypass-trajectories-as-prereqs; Phases 1-2 shipped, aggregate-wait slice landed, timer/fd-poll remainder queued
- Application compatibility: Ableton Live 12 + VST hosts; PE-only Wine-NSPA build matrix (x86_64 + Wow64 i386)
- Linux-NSPA Kernel -- Custom PREEMPT_RT kernel with NTSync PI patches
- librtpi -- PI mutex / condvar library (vendored into Wine-NSPA with a recursive
pi_mutexextension forvirtual_mutexre-entrance) - Wine-NSPA Wiki -- Installation and configuration (8.x)