HyperBridge engine 0015

HyperBridge is MacRunner's CPU engine for running Windows x86-64 and x86 programs on Apple Silicon through ARM64 Wine. It is built on FEX-Emu (MIT) and carries MacRunner's own patch series, kept in fex/ of this repository.

This build: patches 0001–0015 on FEX-Emu fd141ed6d, built with fex/build.sh at commit 9930c30. Two clean builds in different directories are byte-identical; the hashes are in fex/MANIFEST.json and in SHA256SUMS.

File in the archive	Role	SHA-256
engine/fex/aarch64-windows/xtajit64.dll	ARM64EC, 64-bit x86 processes	c5f82c55…
engine/fex/aarch64-windows/xtajit.dll	WOW64, 32-bit x86 processes	f998d84e…
engine/fex/aarch64-unix/libarm64ecfex.so	host library for xtajit64.dll	373e34d2…
engine/fex/aarch64-unix/libwow64fex.so	host library for xtajit.dll	927931f4…

New compared with the engine in MacRunner 1.0.2 (patches 0001–0007)

• 0008 stale block links are not published; full parity at block entry points
• 0009 Elden Ring work: JIT statistics, writable-code validation modes, ARM64EC TLS
• 0010 MACRUNNER_FEX_PROT_KEEP, MACRUNNER_FEX_REVIVE, MACRUNNER_FEX_CODEBUF_MAX (default off)
• 0011 x87 division by zero raises the exception, SF in the x87 status word; DIV/IDIV raise #DE for a zero divisor
• 0012 JIT map on Windows for profiling (MACRUNNER_FEX_JITMAP_DIR)
• 0013 fixes a deadlock between DLL loading and heap growth (black-screen hang in Elden Ring)
• 0014 MACRUNNER_FEX_DIV_OVERFLOW_DE=1 (default off): DIV/IDIV raise #DE on quotient overflow as x86 does
• 0015 MACRUNNER_FEX_SHLD16_CF=1 (default off): SHLD r/m16 with a count of 16 sets CF (upstream FEX 6646a5cc)

Verification

• HB↔FEX oracle, 72 219 x86-64 cases, one binary for all arms: 0014 turns 26 of 26 quotient-overflow cases x86-correct, 0015 3 of 3 SHLD cases; no other result changes.
• MacRunner-like environment (xtajit64.dll of this build under MacRunner's Wine, 15-case DIV probe): gates off — #DE for a zero divisor; MACRUNNER_FEX_DIV_OVERFLOW_DE=1 — 15 of 15, every #DE at the dividing instruction.
• Game: Hollow Knight 1.5.12620 (Windows build, Unity 6) with MacRunner 1.0.2 Wine/DXMT and this engine, King's Pass from a save, V-Sync on, 120 Hz display: 110 FPS average at the limit (median frame 8.33 ms), 14.7 ms of CPU per frame, main menu 44 s after launch. The native macOS build of the same game version: 113 FPS, 6.7 ms of CPU per frame, main menu at 16 s. One run each (details in GAME-CHECK.txt; its gameplay start times are not comparable, because the native run entered the game by hand). Comparison with Prism and CrossOver Preview: HyperBridge compared.

Known limits

• A quotient-overflow #DE is reported as STATUS_INTEGER_DIVIDE_BY_ZERO; Windows reports STATUS_INTEGER_OVERFLOW. Addressed by patch 0018, which goes into the next build.
• Division-heavy loops are 15–35 % slower than with the 1.0.2 engine (0011 defeats the cqo; idiv fold). Addressed by patch 0017 (MACRUNNER_FEX_DIV_PROVEN_HIGH), which goes into the next build.

Installing into MacRunner 1.0.2

Quit MacRunner, keep a copy of MacRunner.app/Contents/Resources/engine/fex, and copy the four files over the same paths. If macOS then refuses to open the app, re-sign only the outer bundle, keeping the signatures and entitlements of the Wine loader inside it: codesign --force --sign - --preserve-metadata=identifier,entitlements,requirements,flags,runtime /Applications/MacRunner.app. Do not use --deep: it re-signs the nested Wine loader without its entitlements, and Wine can then no longer run translated code. Restore the copy to go back. (Corrected on 29 Sep 2026; an earlier version of this note suggested --deep.)

Licenses

FEX-Emu with MacRunner's modifications, MIT. The binaries statically link {fmt}, xxHash, unordered_dense, range-v3, rpmalloc, tiny-json, cpp-optparse, Cephes and SoftFloat 3e from the FEX-Emu source tree; their license texts are in licenses/ inside the archive and in THIRD_PARTY_NOTICES.md. FEX-Emu has not reviewed or endorsed these modifications, and they are not contributions to FEX-Emu — please report problems to MacRunner.