Wine-NSPA – Local Section Bypass

This page documents the client-side section path built on top of local-file handles.

Table of Contents

1. Overview
2. Coverage
3. Eligibility and fallback
4. Handle range and section table
5. Section lifecycle
6. DuplicateHandle and ownership boundaries
7. Sharing arbitration and mapping bits
8. Validation and observed effect
9. Implementation map
10. Related docs

1. Overview

Wine-NSPA no longer has to mint a wineserver section object for every eligible CreateFileMapping on a local-file handle. The client process can keep a bounded section table of its own, duplicate the unix fd at section-creation time, and service the common same-process view lifecycle without a server round-trip.

The feature sits on top of the local-file bypass rather than replacing it. A local file handle still owns pathname resolution, open semantics, and the cross-process sharing aggregate. The local section path reuses that file handle state to build an unnamed file-backed section, then publishes mapping bits back into the same aggregate so later file operations still see correct STATUS_USER_MAPPED_FILE and sharing behavior.

The current boundary is intentionally narrow:

• file-backed sections only
• unnamed sections only
• same-process mapping / query / close lifecycle only
• same-process DuplicateHandle is supported by promoting to a server section
• cross-process duplication still falls back cleanly instead of guessing

That is enough to retire a large volume of mapping RPC traffic from the common case while leaving the hard cross-process edge cases on the authoritative server path.

2. Coverage

This path is the default for eligible unnamed file-backed sections.

3. Eligibility and fallback

The local section path is deliberately smaller than the full NT section surface. A section stays local only when all of the following are true:

• the backing handle is a local-file handle
• the section is file-backed
• the section is unnamed
• the section is not SEC_IMAGE
• the section is not SEC_LARGE_PAGES
• the later map/query/close operations stay in the same process

Anything outside that envelope falls back to the normal server path. That keeps the feature easy to reason about and avoids pretending that cross-process namespace or image-loader semantics can be reconstructed client-side.

4. Handle range and section table

Local section handles live in their own client-private range:

• local sections: [0x7FFF8000, 0x7FFFC000)
• local files: [0x7FFFC000, 0x80000000)

That split matters because later APIs can distinguish a local section from a local file with a cheap range check before they decide which local table to consult.

Each local section entry keeps:

• the local section handle returned to the app
• the duplicated unix fd that outlives the original file handle
• the original local-file handle and backing (dev, inode) identity
• current mapping bits published into the local-file aggregate
• the cached promoted server handle, if same-process duplication already crossed the server boundary
• the list of active local views so NtUnmapViewOfSectionEx and NtClose can tear them down coherently

The table is process-local and protected by its own PI mutex. Cross-process coordination is not done through the section table itself; only the mapping effects are published into the shared local-file aggregate.

5. Section lifecycle

The local section lifecycle is a same-process fast path from creation to final close. The main change versus the older path is that the unix fd is duplicated at section creation time, so the mapping can survive a later CloseHandle() on the original file handle.

Two points are worth calling out:

• CloseHandle(file) no longer invalidates the later map path for an eligible local section, because the section owns its own duplicated unix fd.
• mapping and unmapping stay client-side, but they still update shared mapping state so later file operations do not silently violate Windows semantics.

6. DuplicateHandle and ownership boundaries

The local section path is same-process first. That is deliberate.

When NtDuplicateObject() sees a local section handle and both the source and destination process are the current process, it promotes the section once to a server section, caches that promoted handle on the local entry, and then lets the duplicate proceed through the normal server machinery.

When the duplicate crosses a process boundary, the client-side section handle stops being a valid abstraction. The server does not have access to the remote process’s private section table, so the current behavior is to fall through cleanly rather than invent cross-process state. That produces the right failure instead of a confusing partially-working handle.

This is one of the key differences between a local optimization and a fake object namespace. The local section handle is a process-local implementation detail until the call explicitly crosses into server-owned handle semantics.

7. Sharing arbitration and mapping bits

The local section path stays correct by feeding its mapping state back into the same shared aggregate that local-file already uses for open and sharing arbitration.

When a local section is created:

• the client identifies the backing (dev, inode) from the local-file entry
• the section publishes FILE_MAPPING_WRITE, FILE_MAPPING_IMAGE, or FILE_MAPPING_ACCESS bits into the shared aggregate, matching the mapping shape
• the section keeps those bits live until the last local view and the section itself are gone

That shared publication matters for two reasons:

• later opens and share checks still see mapping state even though the section never became a wineserver object in the common case
• FileEndOfFileInformation can still reject a shrink with STATUS_USER_MAPPED_FILE when a mapped section is active

This is the architectural seam between the file path and the section path: the file table owns the cross-process aggregate, and the section table reuses it instead of inventing a second source of truth.

8. Validation and observed effect

The local section path was validated on the real workload that exposed the old cost: repeated file mapping and view traffic during app startup and UI initialization.

Key observed results from the landed implementation:

• DirectWrite-style shape is clean: CreateFile -> CreateFileMapping -> CloseHandle(file) -> MapViewOfFile
• nspa_create_mapping_from_unix_fd count dropped from 2,664 to ~800 (-70%)
• get_mapping_info and unmap_view dropped out of the top sampled symbols
• total wineserver handler time moved from 1,991 ms to 1,077 ms on the cleanest run of that comparison
• same-process duplicate is handled correctly
• cross-process duplicate returns a clean STATUS_INVALID_HANDLE instead of an inconsistent handle state

The companion local-file follow-ons matter here too. Because mapping bits are published into the shared aggregate, later file-side changes like local FileEndOfFileInformation handling can preserve the same mapped-file boundary without reintroducing a mandatory section RPC.

9. Implementation map

The design intentionally stays inside existing Wine layers:

• sync.c decides whether section creation can stay local
• virtual.c owns view installation and teardown
• server.c remains the place where an explicit server-handle boundary is crossed

That keeps the patch understandable and reduces the number of call sites that need to know about the feature.

10. Related docs

• Local-File Bypass Architecture
• Memory, Sections, Large Pages, and Working-Set Support
• NT Local Stubs
• Architecture Overview
• State of The Art