Wine-NSPA – Memory, Sections, Large Pages, and Working-Set Support

This page documents Wine-NSPA’s memory surface: local sections, large-page mappings, RT-keyed page locking and hugetlb, working-set support, and shared-memory backing choices.

Table of Contents

1. Overview
2. Coverage
3. Client-side sections
4. Large-page allocation and mapping
5. Working-set reporting and quota semantics
6. Shared-memory backing choices
7. Validation and observed effect
8. Implementation map
9. Related docs

1. Overview

Wine-NSPA’s memory work is not just large-page syscall support and it is not just memfd everywhere.

Five distinct pieces are active:

• client-side file-backed sections built on top of local-file handles
• large-page support for anonymous and section-backed mappings
• RT-keyed page locking and automatic hugetlb promotion for the hot anonymous-memory path
• hugetlb safety and fallback rules so transparent promotion stays honest under pool pressure, partial operations, and JIT RWX allocation
• working-set reporting plus working-set quota bookkeeping
• selective shared-memory backing choices for bypass state

The important design point is that these pieces solve different problems. Client-side sections reduce mapping RPC traffic on same-process file-backed mapping workloads. Large pages reduce TLB pressure on hot mappings. Working-set reporting makes the Windows-visible memory surface honest enough for tools and tests. Dedicated shared-memory backends keep bypass subsystems off the wineserver hot path without forcing every shared region through one mechanism.

2. Coverage

3. Client-side sections

The new client-side section path sits between local-file handles and the traditional wineserver mapping-object path.

Eligible unnamed file-backed sections on local-file handles can:

• allocate a client-private section handle
• duplicate the backing unix fd at section creation time
• map, unmap, query, and close the section locally in the same process
• publish FILE_MAPPING_* bits back into the local-file aggregate so later share checks and end-of-file changes still see active mappings

This is a memory feature as much as a file feature. It changes how Windows section objects are represented, how views are installed, and how file-mapping state is reflected back into the rest of the process.

The main boundary is still the same one the local-file path already uses: cross-process or namespace-visible semantics remain on the server side. Same-process mapping is the fast path. Cross-process duplication is not guessed at.

For the full lifecycle and ownership rules, see Local Section Bypass.

4. Large-page allocation and mapping

Large-page support has three allocation shapes: explicit Windows large-page APIs, RT-keyed anonymous-memory promotion, and heap-arena backing that rides on that same anonymous path. Section-backed mappings remain the one large-page shape that still crosses wineserver once for backing creation.

The large-page contract is:

• expose the real large-page minimum when the host has one
• reject invalid alignment and privilege shapes instead of silently inventing a fake success path
• preserve enough view metadata that QueryWorkingSetEx() can later report LargePage=1

That last point matters. The feature is not just about getting mmap() flags accepted. It is about keeping the Windows-visible memory story coherent from allocation to reporting.

4.1 Automatic hugetlb promotion safety rules

Transparent promotion is an optimization, not a new Windows API. That means the fast path also needs a clear “stay honest” rule set:

• if the free hugetlb pool drops below 10%, stop auto-promoting and leave the reserve for explicit large-page callers
• if an auto-promoted allocation hits pool exhaustion anyway, fall back to regular pages and succeed instead of failing the ordinary allocation
• if an app later performs a sub-hugepage partial operation on an auto-promoted view, demote that view back to regular pages first so MEM_DECOMMIT, MEM_RELEASE, and VirtualProtect retain NT semantics
• if MEM_RESET runs under mlockall(), unlock before MADV_DONTNEED so the kernel can actually reclaim the pages

5. Working-set reporting and quota semantics

Working-set support is deliberately split into two levels:

• reporting: current-process QueryWorkingSetEx() tells tools and tests what is resident and whether a page is large-page-backed
• quota bookkeeping: GetProcessWorkingSetSize(Ex) and SetProcessWorkingSetSize(Ex) store and return Windows-visible quota values

What is not part of this surface is a Linux-side working-set trimmer that enforces those quota values by reclaiming or emptying the process working set.

That division is intentional. Reporting should be correct. Quota APIs should behave coherently. RT-keyed mlockall() improves residency behavior for the actual process, but the docs should not imply that Wine-NSPA has grown a full Windows-style working-set manager or a quota-enforcing trimmer. It has not.

6. Shared-memory backing choices

The tree uses several shared-memory backends, and they are chosen per subsystem instead of by one global rule.

This is why a single “memfd page” would be misleading. memfd is important, but it is not the whole story:

• some NSPA state lives in shared payload windows
• some lives in queue-local memfd regions
• some lives in shared memfd tables
• large pages are a different memory feature again

The docs should keep those roles separate, because the correctness rules and performance goals are different.

7. Validation and observed effect

The public large-pages PE harness covers more than one call shape:

• VirtualAlloc(MEM_LARGE_PAGES)
• QueryWorkingSetEx() LargePage reporting on the resulting view
• CreateFileMapping(SEC_LARGE_PAGES)
• privilege-negative SEC_LARGE_PAGES behavior
• 1 GiB huge-page request shape when the host is configured for it

That means the public test surface validates both the allocation path and the Windows-visible reporting path. Local sections are currently validated through the workload path rather than a dedicated PE harness: CreateFile -> CreateFileMapping -> CloseHandle(file) -> MapViewOfFile is clean on the local path and materially reduces mapping RPC traffic.

The relevant public harness documentation lives on nspa-rt-test.gen.html.

The newer RT-keyed memory work was validated separately on real workloads and targeted shell harnesses:

• mlockall() under NSPA_RT_PRIO cut perf page faults from 561/s to 451/s, cut bpf page faults from 869/s to 629/s, and tightened max futex wait from 94us to 49us, with VmLck around 300848kB.
• automatic hugetlb promotion stayed conservative and is keyed only off NSPA_RT_PRIO; the cleanup pass ended with test-huge-auto.sh 3/3 PASS.
• the demote / fallback / reclaim follow-ons are also on the active path: test-huge-decommit.sh validates zero-on-recommit after partial decommit, test-huge-rwx.sh validates RWX JIT-style promotion, and pool-pressure cases fall back instead of failing an ordinary allocation
• heap arena hugetlb backing increased hugepage regions from 3 or 6 to 104, reduced dTLB miss / insn to 0.071%, reduced mmap rate from 33-61/s to 0.13/s, reduced mprotect rate from 56-90/s to 0.03/s, and reduced page-faults from 753-869/s to 2.8/s.
• after the gate cleanup, the public shell checks finished at test-mlock-ws.sh 4/4, test-huge-auto.sh 3/3, and test-heap-hugepage.sh 3/3.

8. Implementation map

9. Related docs

• Local Section Bypass
• Architecture Overview
• RT Test Harness
• Message Ring Architecture
• NT Local Stubs
• Local-File Bypass Architecture