HyperBridge engine 0019

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–0019 on FEX-Emu fd141ed6d, built with fex/build.sh at commit d55632c. 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	3d413809…
engine/fex/aarch64-windows/xtajit.dll	WOW64, 32-bit x86 processes	9bc5810d…
engine/fex/aarch64-unix/libarm64ecfex.so	host library for xtajit64.dll (same as engine 0015)	373e34d2…
engine/fex/aarch64-unix/libwow64fex.so	host library for xtajit.dll (same as engine 0015)	927931f4…

New compared with engine 0015 (the engine of MacRunner 1.0.3)

• 0016 MACRUNNER_FEX_NULL_HOST=1 (default off): a branch to guest address 0 takes the full lookup instead of jumping to host address 0, so the guest gets its own fault
• 0017 MACRUNNER_FEX_DIV_PROVEN_HIGH=1 (default off): DIV/IDIV directly after xor edx,edx, CDQ or CQO is a plain n-bit division
• 0018 with MACRUNNER_FEX_DIV_OVERFLOW_DE=1: Windows programs get STATUS_INTEGER_OVERFLOW (0xC0000095) for a quotient overflow and STATUS_INTEGER_DIVIDE_BY_ZERO (0xC0000094) for a zero divisor, as under Microsoft Prism
• 0019 Darwin: the engine no longer switches the whole process to hardware TSO after a one-thread probe (the macOS mode is per thread); no change at run time without Apple's entitlement

Verification

• HB↔FEX oracle, 72 219 x86-64 cases plus 133 division idioms: 0016 changes one case (push 0; ret now faults at guest 0), 0017 and 0018 change no result.
• Under MacRunner's Wine, a 64-bit probe of 88 DIV/IDIV cases (8–64 bits, register and memory operands): with MACRUNNER_FEX_DIV_OVERFLOW_DE=1 all 88 equal Microsoft Prism — exception code, fault flag and RAX/RDX at the fault.
• xbench (M1 Pro, three alternating runs): cqo; idiv rcx 0.969 ns without gates, 0.783 ns with MACRUNNER_FEX_DIV_PROVEN_HIGH=1 (MacRunner 1.0.2 engine: 0.722 ns); loops without division unchanged.
• Game: Hollow Knight 1.5.12620 reaches the main menu in three of three runs with all gates off, with the same start-up timings as engine 0015 (GAME-CHECK.txt).

Known limits

• 0017 recognizes only the idiom directly before the division; xor edx,edx; mov eax, …; div ecx keeps the slower path.
• The 32-bit probe cannot start under MacRunner's Wine on this Mac (32-bit programs need the low 4 GB, which needs Apple's entitlement); xtajit.dll was built, not run.

Installing into MacRunner 1.0.3

Quit MacRunner, keep a copy of MacRunner.app/Contents/Resources/engine/fex, and copy the four files over the same paths. Then 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. Restore the copy to go back.

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 notices are in the archive. FEX-Emu has not reviewed or endorsed these modifications, and they are not contributions to FEX-Emu.