Wine-NSPA 11.x Documentation

WIP -- Active research & development. Everything subject to change. Last updated 2026-05-01.

Architecture & Design

• Aggregate-Wait and Async Completion CORE
  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 directly on this foundation. 4 SVG diagrams.
• Architecture Overview CORE
  Master system map: client / wineserver / kernel layering, shipped bypass surfaces, residual wineserver floor, and links into the dedicated subsystem docs. 9 SVG diagrams.
• Audio Stack CORE
  winejack.drv (WASAPI + MIDI on JACK) and nspaASIO bridge: same-period bufferSwitch inside JACK RT callback, futex-synced zero-latency path, unified MIDI handling.
• Critical Section PI CORE
  FUTEX_LOCK_PI on CRITICAL_SECTION: fast/slow path, PI chain, gating, fallback. 3 SVG diagrams.
• Gamma Channel Dispatcher CORE
  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 after each dispatch.
• Hook Cache CORE
  Tier 1 + Tier 2 hook caching for SetWindowsHookEx / WH_* dispatch. Drains the per-call get_hook_info round-trip; validated server_dispatch=0 on Ableton 165s session.
• io_uring I/O Architecture CORE
  Phase 1-4 io_uring integration: file I/O bypass, dispatcher-owned async `CreateFile`, socket I/O via ALERTED-state interception, E2 bitmap, ntsync uring_fd. 3 SVG diagrams.
• Local-File Bypass Architecture CORE
  NtCreateFile bypass for read-only regular files: client-private handle range, per-process table, shared inode-aggregation shmem for cross-process sharing arbitration, lazy server-handle promotion on server-requiring APIs. 21+ NT-API intercept sites; ~28,500 file opens offloaded per Ableton startup. 2 SVG diagrams.
• Message Ring Architecture CORE
  Same-process cross-thread PostMessage / SendMessage via per-queue memfd rings. Removes wineserver round-trip from hot message path; v2 audit fix-pack (MR1 reply-slot ABA, MR2 cross-process futex, MR4 POST wake-loss CAS rollback). 5 SVG diagrams.
• NT Local Stubs CORE
  Client-side intercepts for cheap NT APIs that don't need a server round-trip: query/info paths handled locally with cached state. Catalog of stub sites and their server-equivalence guarantees.
• NTSync PI Kernel Driver CORE
  NTSync driver architecture: upstream vs NSPA, patches 1003-1011, PI boost, channel transport, aggregate-wait, and `CHANNEL_TRY_RECV2`. 4 SVG diagrams.
• Win32 Condvar PI (Requeue-PI) CORE
  FUTEX_WAIT_REQUEUE_PI for RtlSleepConditionVariableCS. Condvar-to-mutex mapping table, 3 new syscalls, zero-gap PI from condvar wake to CS reacquire. 2 SVG diagrams.
• Wineserver Decomposition Plan PLAN
  Roadmap for splitting wineserver into NTSync-extension paths plus a thinner request handler. Aggregate-wait kernel/userspace slice is now landed; timer/fd-poll decomposition remains ahead.

Test Results & Validation

• State of The Art LIVE
  Current shipped-state board: defaults, exact validation totals, performance deltas, remaining gates, and open work across ntsync, gamma, and Phase 4.
• Test Suite Comparison (v3 → v8) DATA
  Current v8 snapshot plus preserved historical reports: Layer 1 native suite, 24/24 PE matrix, dispatcher-burst A/B, and older cross-version latency / throughput data.
• RT Test Harness DATA
  Two-layer validation harness: native ntsync suite plus the PE matrix, now including `dispatcher-burst` for gamma / TRY_RECV2 coverage.

Latest Highlights (2026-05-01)

• three new default-on user features shipped — NSPA_FLUSH_THROTTLE_MS=8, NSPA_ENABLE_ASYNC_CREATE_FILE=1, and NSPA_TRY_RECV2=1. State of The Art →
• ntsync production module advanced again — current prod srcversion is 10124FB81FDC76797EF1F91, carrying 1003-1011 with NTSYNC_IOC_CHANNEL_TRY_RECV2.
• dispatcher tuning landed a major busy-workload win — channel_dispatcher dropped 14.51% → 0.70%, and system-wide samples fell 38,588 → 19,415 per 30s. Gamma Channel Dispatcher →
• follow-on dispatcher hot-path tuning also landed — gating allocator poison / valgrind stubs reclaims the full 1.34pp debug-allocator cost, and inlining read_request_shm removes another ~1pp from the dispatcher path.
• dispatcher-burst joined the PE matrix — the new harness finally covers the gamma hot path and shows TRY_RECV2 burst mode at 841,765 ops/sec vs 555,567 with the feature disabled. RT Test Harness →
• flush throttle recovered MainThread CPU — x11drv_surface_flush went 8.23% → 4.74%, copy_rect_32 memmove 4.38% → 2.49%, for ~5.4 percentage points of recovered MainThread CPU.
• winex11 AVX2 follow-on shipped — the alpha-bit OR loop inside x11drv_surface_flush dropped 6.72% → 2.39% (-4.33pp / -64%), and total winex11.so dropped 6.76% → 2.43%, with bit-identical output.
• Tier 1 compatibility / log cleanup shipped — the dominant stub noise sources fell from ~565 prints per Ableton run to ~5 first-time prints, and ShutdownBlockReasonCreate/Destroy now succeed silently instead of failing with ERROR_CALL_NOT_IMPLEMENTED.

v7 Highlights (2026-04-28)

• msg-ring v2 audit fix-pack — MR1 reply-slot ABA, MR2 cross-process futex, MR4 POST wake-loss CAS rollback. Message Ring Architecture →
• Gamma channel dispatcher — kernel-mediated single-per-process IPC, replaces legacy per-thread shmem-pthread. T1 + T2 + T3 thread-token shipped default-on. Gamma Channel Dispatcher →
• 2× clean Ableton runs — paint-cache OFF and paint-cache=1 both held past the historical 5-minute lockup threshold.

v6 Highlights (2026-04-16)

• Win32 condvar PI — FUTEX_WAIT_REQUEUE_PI for RtlSleepConditionVariableCS. Kernel atomically requeues waiters from condvar onto CS PI mutex — zero gap. Details →
• 4th PI coverage path — CS-PI, NTSync PI, pi_cond, and now Win32 condvar PI. Only SRW remains without PI (unsolved in Linux kernel too).
• condvar-pi max wait: -42% — worst-case tail latency 263→152µs under RT load (500 iterations, 4 load threads)
• 22/22 RT test suite — condvar-pi test added, no regressions across all existing tests

v5 Highlights (2026-04-15)

• pi_cond requeue-PI — FUTEX_WAIT_REQUEUE_PI closes the last PI gap across all unix-side condvar consumers (ntdll, audio drivers, gstreamer)
• SRW lock spin phase — 256-iteration spin before parking, matching Windows behavior. RT threads skip spinning.
• msvcrt SIMD — AVX memcpy/memmove, SSE2 memchr/strlen/memcmp with runtime CPU dispatch
• NTSync d8 PI: -52% wait time — deep transitive PI chains now 2x faster
• rapidmutex: +4.7% throughput, RT max wait 46→36µs

Wine-NSPA by Jordan Johnston — github.com/nine7nine/Wine-NSPA
Kernel: Linux-NSPA 6.19.11-rt1-1 (PREEMPT_RT) | Wine 11.6 | 2026-05-01