Wine-NSPA RT Test Harness

This page documents the current Wine-NSPA validation harness: the two-layer full-suite boundary, the default PE validation matrix, the native ntsync suite, and the targeted validators that sit outside the archived matrix.

Table of Contents

1. Validation model
2. Current archived boundary
3. Layer 2 default PE matrix
4. Layer 1 native ntsync suite
5. Targeted validators outside the full-suite archive
6. Runners and output
7. Safety
8. Extending the harness
9. Environment and prerequisites

1. Validation model

The current test surface is split into four categories:

• Layer 1 native suite. Small plain-C programs under wine/nspa/tests/test-*.c that talk directly to /dev/ntsync ioctls. These cover kernel invariants the Win32 layer cannot reach directly.
• Layer 2 default PE matrix. nspa_rt_test.exe in baseline and RT modes. This is the archived user-visible full-suite matrix.
• Targeted validators. Focused scripts or workload checks that validate a newer subsystem without redefining the full-suite boundary.
• Opt-in perf tests. Benchmarks such as srw-bench and seqlock-bound. These are useful for measurement, but they are not part of the default validation matrix.

The important maintenance rule is that these categories are not interchangeable. If a carry is validated only by a targeted harness, the public docs should say that explicitly instead of silently folding it into the matrix totals.

2. Current archived boundary

The current archived full-suite snapshot is:

Layer 2 in this archived snapshot covers:

• rapidmutex
• philosophers
• fork-mutex
• cs-contention
• signal-recursion
• large-pages
• ntsync-d4
• ntsync-d8
• ntsync-d12
• socket-io
• condvar-pi
• nt-timer
• wm-timer
• rpc-bypass
• irot-bypass
• dispatcher-burst

Mode definitions:

• baseline = WINEDEBUG=-all with the normal default-on Wine-NSPA stack, but without RT promotion
• rt = WINEDEBUG=-all NSPA_RT_PRIO=80 NSPA_RT_POLICY=FF WINEPRELOADREMAPVDSO=force

One detail worth preserving in the docs: socket-io currently reports an implicit verdict in the suite archive (PASS*) because the test exits 0 without printing an explicit PASS line. The suite still counts it as a pass, but the output format difference is intentional and should stay documented.

The newer subsystem carries that were validated after this archive should be described as targeted validators unless and until another full archived matrix is cut.

3. Layer 2 default PE matrix

The current default PE matrix is driven by nspa/run_rt_tests.sh. It is a validation set, not a “run every possible subcommand” set.

3.1 Default validation tests

3.2 Optional tests outside the default matrix

3.3 Dispatcher-specific PE coverage

dispatcher-burst remains important because most other PE tests do not stress the gamma dispatcher path directly. It is the PE-side oracle for:

• channel_dispatcher
• dispatch_channel_entry
• aggregate-wait receive / reply ownership
• post-dispatch TRY_RECV2 burst drain

Archived v9-validation-default result:

The earlier 2026-04-30 A/B numbers remain useful historically, but the current public fact is that dispatcher coverage is part of the default full-suite boundary rather than a side harness.

4. Layer 1 native ntsync suite

Layer 1 is driven by wine/nspa/tests/run-rt-suite.sh native. These tests exercise kernel-only invariants that the PE layer cannot reach directly.

4.1 Default native tests

Archived v9-validation-default result:

• 3 PASS / 0 FAIL / 0 SKIP
• test-aggregate-wait: 9/9 PASS

4.2 Opt-in native stress tests

These are not part of the default validation boundary:

4.3 SKIPPED_BY_DESIGN

Two tests remain excluded because they assert behavior that is no longer part of the active kernel/userspace contract:

• test-cross-boost
• test-wait-rejects-channel

They are kept as source history and canaries, not as active validation.

5. Targeted validators outside the full-suite archive

These checks matter, but they are not the same thing as the archived matrix.

This separation is what keeps the public numbers honest: the archived full-suite totals stay stable, while newer subsystem carries can still be documented with their own validators.

6. Runners and output

6.1 Two-layer runner

wine/nspa/tests/run-rt-suite.sh drives the public two-layer suite:

wine/nspa/tests/run-rt-suite.sh
wine/nspa/tests/run-rt-suite.sh native
wine/nspa/tests/run-rt-suite.sh wine

It:

• runs Layer 1 native tests
• delegates Layer 2 to nspa/run_rt_tests.sh
• cleans up stale Wine processes
• archives logs
• can auto-compare against a prior archive

6.2 PE runner

nspa/run_rt_tests.sh is the Layer 2 orchestrator. It:

• runs each default test in baseline and rt
• writes one log per run
• resolves verdicts from explicit PASS / FAIL lines or exit code
• prints a summary matrix and totals

Verdict resolution order:

1. timeout -> TIMEOUT
2. explicit PASS line -> PASS
3. explicit FAIL line -> FAIL
4. fallback to exit code -> PASS* / FAIL*

6.3 Build

i686-w64-mingw32-gcc -O2 -static programs/nspa_rt_test/main.c -o nspa_rt_test.exe -lws2_32

Native ntsync tests are built on demand by run-rt-suite.sh.

7. Safety

The harness has two layers of timeout protection:

• inner watchdog inside nspa_rt_test.exe
• outer shell timeout in run_rt_tests.sh

Other safety rules:

• stale nspa_rt_test.exe processes are reaped between runs
• load-thread counts are capped for system survivability
• Ctrl+C sets the global stop flags and exits cleanly
• native stress tests are opt-in, not part of routine validation

These are part of the methodology, not just implementation detail: they keep the validation suite usable on a real development machine.

8. Extending the harness

8.1 Adding a PE validation test

1. Add a new cmd_foo() handler to programs/nspa_rt_test/main.c.
2. Register it in the commands[] table.
3. Decide whether it belongs in:
   • the default validation matrix
   • targeted validation only
   • opt-in perf tests
4. If it belongs in the default matrix, add it to the tests=() array in nspa/run_rt_tests.sh.

8.2 Adding a native test

1. Add test-foo.c under wine/nspa/tests/.
2. Add test-foo to NATIVE_TESTS=() or NATIVE_STRESS_TESTS=().
3. Use exit code 77 for skip.

The important maintenance rule is classification: do not put a perf probe into the default validation matrix unless it is actually validating a contract.

9. Environment and prerequisites

9.1 Common runner variables

9.2 Optional gates

9.3 Prerequisites

For matrix lineage and comparability rules, see nspa-test-comparison.