Wine-NSPA 11.x Documentation

WIP -- Active research & development. Everything subject to change.

Architecture & Design

• Architecture Overview CORE
  Full NSPA architecture: RT priority mapping, CS-PI, NTSync PI, io_uring, SRW spin, pi_cond requeue-PI, Win32 condvar PI, SIMD optimizations. 9 SVG diagrams.
• Critical Section PI CORE
  FUTEX_LOCK_PI on CRITICAL_SECTION: fast/slow path, PI chain, gating, fallback. 3 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.
• io_uring I/O Architecture CORE
  Phase 1-3 io_uring integration: file I/O bypass, socket I/O via ALERTED-state interception, E2 bitmap, ntsync uring_fd. 3 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, halves server message-handling load in busy Ableton playback. 5 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.
• Shmem IPC Architecture CORE
  Per-thread shared memory IPC: dispatcher model, PI boost protocol, global_lock PI, v2.5 cached sched state. 3 SVG diagrams.
• NTSync PI Kernel Driver CORE
  NTSync driver architecture: upstream vs NSPA, 5 kernel patches, PI boost, uring_fd. 3 SVG diagrams.

Test Results & Validation

• State of The Art LIVE
  At-a-glance health dashboard: all 11 tests with key metrics (v3 → v5 → v6). NTSync driver status, PI chain validation, priority mapping tables.
• Test Suite Comparison (v3 → v5 → v6) DATA
  Full A/B comparison across all test versions. Per-thread metrics, throughput deltas, PI contention measurements, condvar PI latency, socket I/O histograms.

Research & Investigation

• Sync Primitives Research RESEARCH
  SRW spin, CS adaptive spin, condvar/SRW PI design space. Windows semantics, glibc/Linux comparisons, kernel rwsem analysis, librtpi capabilities.
• RT Test Harness DATA
  Test architecture, subcommands, runner script, watchdog, benchmarks.
• Ableton Decoration Loop Investigation DEBUG
  Windowing/nonclient resize feedback loop in Ableton Live 12. Root cause analysis and workaround.

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-04-16