Development:ARM64EC

Building

These instructions expect you to be building on an ARM64 host.

Toolchain

Scripts and instructions to build an ARM64EC toolchain can be found here, with prebuilt binaries for ARM64/x86 hosts on the releases page. Once built/downloaded, add it to your environment with

export PATH="<path to toolchain>/bin:$PATH"

note the toolchain must come before all other path entries as it needs to override the host ar binary.

• Make sure to grab the tar.gz aarch64 files when compiling on Linux. The zip files are for a Windows toolchain which doesn't work for these instructions.

Wine

Upstream wine has various things missing for full FEX/ARM64EC support, while it can be used, my fork will give the best results for now. Make sure to install the deps listed here before building with the ARM64EC toolchain.

 ./configure --enable-archs=arm64ec,aarch64,i386 --prefix=/usr --with-mingw=clang --disable-tests
 make -j$(nproc)
 sudo --preserve-env=PATH make install -j$(nproc)

FEX

FEX must be built twice, once for the x86 (WOW64) emulation module and once for x86_64 emulation module (ARM64EC)

FEX's official Ubuntu PPA now provides a fex-emu-wine package of the latest release. This package can be downloaded and the DLL files can be extracted if compiling isn't desired.

Build directions

mkdir build-arm64ec
cd build-arm64ec
cmake -GNinja -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=../Data/CMake/toolchain_mingw.cmake -DCMAKE_INSTALL_LIBDIR=/usr/lib/wine/aarch64-windows -DENABLE_LTO=False -DMINGW_TRIPLE=arm64ec-w64-mingw32 -DBUILD_TESTS=False -DENABLE_JEMALLOC_GLIBC_ALLOC=False -DCMAKE_INSTALL_PREFIX=/usr ..
ninja
sudo ninja install
cd ..
mkdir build-wow64
cd build-wow64
cmake -GNinja -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=../Data/CMake/toolchain_mingw.cmake -DCMAKE_INSTALL_LIBDIR=/usr/lib/wine/aarch64-windows -DENABLE_LTO=False -DMINGW_TRIPLE=aarch64-w64-mingw32 -DBUILD_TESTS=False -DENABLE_JEMALLOC_GLIBC_ALLOC=False -DCMAKE_INSTALL_PREFIX=/usr ..
ninja
sudo ninja install
cd ..

dxvk/vkd3d-proton

Both can be built and installed as instructed on their respective github pages, except that a path to the following cross file should be passed to meson with --cross-file:

[binaries]
ar = 'arm64ec-w64-mingw32-ar'
c = 'arm64ec-w64-mingw32-gcc'
cpp = 'arm64ec-w64-mingw32-g++'
ld = 'arm64ec-w64-mingw32-ld'
windres = 'arm64ec-w64-mingw32-windres'
strip = 'strip'
widl = 'arm64ec-w64-mingw32-widl'
pkgconfig = 'aarch64-linux-gnu-pkg-config'
[host_machine]
system = 'windows'
cpu_family = 'aarch64'
cpu = 'aarch64'
endian = 'little'

Windows

ARM64EC FEX is usable as a drop-in replacement for xtajit64 on native WOA, build FEX with -DUSE_PDB_DEBUGINFO=True and copy the libarm64ecfex.{dll,pdb} binaries into C:/Windows/System32. To actually use FEX create an empty registry key at HKLM\\Software\\Microsoft\\Wow64\\amd64 and set its value to libarm64ecfex.dll, all subsequently launched programs will then use FEX. Logs/configuration is stored in %localappdata%.

Info

Unlike Linux FEX, the Windows FEX modules purely handle CPU emulation, with syscall translation being done on either the wine side (WOW64) or ABI (ARM64EC). This is similarly the case for wine's unixcalls and as a result native ARM64 variants can be used for all .so libraries (Vulkan, wine, etc.) dropping the need for an x86 rootfs and FEX-side thunking.

WOW64 (Windows 32-bit On Windows 64-bit) is the mechanism to run 32-bit applications on 64-bit platforms: All system libraries are built as x86 and emulated. Any 32-bit syscalls they use are adapted on-the-fly to 64-bit equivalents by injecting thunks.

ARM64EC (Emulation Compatible) on the other hand deals with 64-bit applications and avoids emulation overhead by using a dedicated set of system libraries compiled for ARM64 with the custom ARM64EC ABI. This ABI is designed to be callable from recompiled x86_64 code in order to allow a mix-and-match of native and emulated code. To avoid needing both a set of ARM64EC and ARM64 system libraries, ARM64X is introduced: It uses linker relocations to combine ARM64EC code and regular ARM64 code in a single binary file, which can be used both by standard Windows-on-Arm applications and emulated x86_64 ones.

The following pages serve as a good reference:

https://learn.microsoft.com/en-us/windows/arm/arm64ec

https://learn.microsoft.com/en-us/windows/arm/arm64ec-abi

https://gitlab.winehq.org/wine/wine/-/wikis/ARM64EC-Toolchain

Of note is the fact that FEX needs to run in a very reduced Windows environment - due to how early it is loaded it can only depend on ntdll and not say the system CRT. This is worked around by implementing/stubbing the subset of the CRT/Windows APIs necessary for FEX to run/link purely ontop of ntdll (see Common/Windows/{WinAPI,CRT}).

Building problems

`bytes of instructions in range, but .seh directives corresponding to`

This is seemingly caused by the `-mcpu` tune option, pass to cmake `-DTUNE_CPU=none`