Win16 (Windows 3.x) compatibility layer

MayteraOS can run real, unmodified 16-bit Windows 3.x (“NE”) executables: a user-supplied copy of Microsoft Word 6.0, and a set of Windows Entertainment Pack games. This is not a userland Windows emulator process, and it is not a Win32/Win64 subsystem; it is an in-kernel interpreter: a clean-room 16-bit x86 CPU emulator with a protected-mode/LDT selector model, a from-scratch KERNEL/USER/GDI/MMSYSTEM API translation layer, an OLE2/COM runtime with software x87 support, and an NE (New Executable) loader. All third-party Windows 3.x software named on this page was supplied by the user for compatibility testing; MayteraOS does not include or distribute any third-party commercial software.

Architecture

Three source files carry the whole layer:

• kernel/exec/x86_16.c: the 16-bit CPU emulator, covering real-mode and protected-mode execution, an LDT (Local Descriptor Table) selector/arena model backing every protected-mode segment, and a small software x87 FPU (the kernel itself builds with SSE/x87 disabled, so floating point used by a Win16 app is emulated in software, not delegated to hardware state the kernel never saves).
• kernel/exec/ne.c: the NE loader, which parses the NE header, segment table, per-segment relocations, and the imported-name/entry tables, then loads all segments into the emulated address space and resolves imports to the API dispatcher below.
• kernel/exec/win16api.c: the KERNEL/USER/GDI/MMSYSTEM/SHELL/OLESVR API surface (see the generated tables below), the window/message/DC plumbing that maps a Win16 HWND onto a real composited MayteraOS window, the WINE-style drive-letter filesystem shim (/WINDIR/DRIVE_C/... ↔ C:\...), and the WIN16PM.RUN boot autolauncher.

WIN16PM.RUN is a single-line boot config (/CONFIG/WIN16PM.RUN): an executable path plus an optional pm/realmode flag, read once at boot to launch one Win16 application automatically. It is not a Program Manager. Separately, the compositor's Start Menu (userland/apps/compositor/startmenu.c) can surface Win16 “program groups” as nested Start-menu folders if a simple pipe-delimited /WIN16GRP.CFG file exists (GROUP|name / ITEM|name|path records), and that reader is live in the current source, but nothing in the current interpreter parses a real PROGMAN.INI or generates WIN16GRP.CFG from a Windows 3.x SETUP run; there is no committed PROGMAN.INI parser in ne.c or win16api.c. Treat Win16 program-group surfacing as a config format the compositor can render, not an installer feature that populates it today.

Verified applications

“Verified” below means: booted on a MayteraOS VM, screenshotted or serial-traced, and (for the games) checked for byte-identical regression across later interpreter changes; FreeCell in particular has served as the standing regression gate for hundreds of interpreter passes. This list is a snapshot from the project's own engineering log (CHANGELOG.md), not a promise that every build behaves identically; re-verify after any interpreter change.

Known limitations, stated plainly

• The interpreter runs with full kernel privilege. A Win16 (or DOS) guest executes as a PRIV_KERNEL thread (proc/process.c:424), so it bypasses every perms_check() call site and capability bit that gates a normal userland process, and writes files directly via fat_write_file(). None of win16api.c, x86_16.c, or ne.c contain inline assembly or a privileged instruction, so nothing about the interpreter actually requires Ring 0; this is an assessed, currently-real security gap (tracked internally), not a hypothetical one, and there is no committed plan yet to move it to userland.
• An unimplemented API call can desync the emulated stack. The 16-bit calling convention (Pascal: callee pops its own arguments) means the interpreter must know exactly how many argument bytes to discard on return. A call that lands on neither the implemented table nor the stub table is logged (MISS/UNIMPL) and can only pop the far-return frame, not the app's pushed arguments, leaving stray bytes on the 16-bit stack that corrupt the very next POP or RET the app executes. This has been a real, repeatedly-hit failure mode during bring-up; see “Ordinal discovery” below for how it is found and fixed per application.
• Coverage is discovery-driven, not exhaustive. The tables below are exactly the ordinals and names the interpreter's tables recognize today. A new application will very likely need ordinals neither table has; that is expected, not a bug report waiting to happen, and the fix path is the same one used throughout this file's history (add a real handler, or at minimum a correctly-argbyte'd stub).
• A stub is not an implementation. g_stub_table entries exist purely to keep the calling stack consistent; they return a fixed value and do nothing else. Any claim of “X APIs supported” that does not separate implemented from stubbed is overstating coverage, which is exactly why this page's tables keep the two counts apart.
• This is Win16 only. There is no Win32 or Win64 support in this layer, and none is implied by anything above: 32-bit PE binaries (including Win32s modules referenced by some of the 16-bit launchers above) are out of scope here and belong to a separate, future PE subsystem.

Coverage by module

Implemented = a real C handler in g_api_table runs and does the work. Stubbed = g_stub_table supplies the exact Pascal argbyte count so the caller's stack does not desync, and a canned return value, but no real behaviour happens. A stub that returns a plausible value is not an implemented API. Everything outside both tables is unimplemented and is discovered per-application at runtime; see “Ordinal discovery” below.

3 (module, ordinal) pair(s) appear in both tables. The real handler always wins at dispatch (find_handler() is checked before find_stub()), so these are stale, unreachable stub entries left behind after a real handler was added later: GDI.38, USER.61, USER.319.

Ordinal discovery

Coverage above is closed: it is exactly the two tables in kernel/exec/win16api.c. What an untested application needs is not closed, and this generator does not guess at it. The interpreter itself is the discovery tool: win16_api_dispatch() looks up every call an app makes against g_api_table then g_stub_table, in that order.

• Found in g_api_table: real handler runs, logged ok (first occurrence only, to /WIN16LOG.TXT).
• Found in g_stub_table only: stack is popped with the exact recorded argbytes and the canned retval is returned, logged ok as well (the trace line does not distinguish real from stubbed; the generated tables below do).
• Found in neither: logged MISS on first occurrence, then UNIMPL <module>.<ordinal-or-name> (args unknown). Because the true argbyte count is unknown, the dispatcher can only pop the far-call return frame, not the caller's pushed arguments, and returns AX=0.

This is a real, previously-hit failure mode: an unimplemented import desyncs the emulated Pascal stack by exactly the number of bytes the app expected popped, corrupting whatever the next POP or RET reads. The fix pattern used throughout this file's history is always the same: find the correct argbyte count (from a WINE .spec file, or by reading the caller's own push sequence) and add either a real handler or, at minimum, a g_stub_table entry, so the stack stays consistent even before real behaviour is implemented.

Practical effect: run the target application, then read /WIN16LOG.TXT (or /BOOTLOG.TXT for boot-time/autolaunch traces) for MISS/UNIMPL lines naming exactly what that application needs next.

Implemented API table

Grouped by module, sorted by ordinal. “(by name)” means this entry is matched by the import's name string only, because the source Win3.1 DLL for this function has no fixed ordinal for it (or none is recorded here); an app importing it by ordinal instead would not match this row.

Stubbed ordinal table

These ordinals are recognized (the loader will not desync the caller's stack) but return a fixed value with no real behaviour. argbytes is the exact number of bytes the Pascal calling convention pops off the 16-bit stack; retval is 0 (a “no object”/handle-shaped failure) or 1 (a BOOL success) per the source's own convention.