FEX(1)

📦
version 2608 · 2 versions
, in nixpkgs unstable

💅 FEX — the FEX / FEXBash manual page, bestie edition ✨

Okay so like — this is the manual page for FEX, a.k.a. FEXBash, from the LOCAL section. Yes the man page name goes up there, we're not copy-pasting the header line, we're being cute about it. Let's GO 🚀

🌸 NAME 🌸

FEX, FEXBash — Fast x86-64 and x86 emulation. That's it, that's the whole vibe. 🦋

✨ SYNOPSIS ✨

FEX <args> ...

FEXBash <args> ...

Literally just: throw the binary at it, then whatever args you want. Periodt. 💅

💖 DESCRIPTION 💖

So FEX lets you run x86 and x86-64 binaries on an AArch64 host — yes, same energy as qemu-user and box86, but it's giving its own whole thing. 👑

It has native support for a rootfs overlay, so you do not need to chroot — thank u, next 🙏 — plus it's got these thunklibs so it can forward stuff like GL through to the host. Iconic behaviour honestly.

Also, FEX presents a Linux 5.0 interface to the guest, and it supports both AArch64 and x86-64 as hosts. 🌈

⚠️ Real talk: FEX is very much work in progress. Expect things to change. Like, literally expect it. Ngl it's part of the charm. 😭

🎀 ENVIRONMENT 🎀

Every one of these is a little environment variable you can vibe with. The JSON key is what it's called in the config file, and default is... the default. Obvi. 💁‍♀️

FEX_MULTIBLOCK

Controls multiblock code compilation.

Heads up though — this can cause long JIT compilation times and stutter. 😬

  • JSON key: 'Multiblock'
  • default: true

FEX_MAXINST

Maximum number of instruction to store in a block.

  • JSON key: 'MaxInst'
  • default: 5000

FEX_ENABLECODECACHINGWIP

Enable the code caching subsystem. (WIP in the name = it's a work in progress, iykyk 🧚)

  • JSON key: 'EnableCodeCachingWIP'
  • default: false

FEX_ENABLELAZYCODECACHINGWIP

Enable lazy loading of chunks in code caches.

  • JSON key: 'EnableLazyCodeCachingWIP'
  • default: false

FEX_ENABLECODECACHEVALIDATION

Enable expensive validation when loading code caches. Like, expensive expensive. 💸

  • JSON key: 'EnableCodeCacheValidation'
  • default: false

FEX_HOSTFEATURES

This one lets you control the CPU features in the JIT. Big main-character energy. Here's the menu:

  • off: Default CPU features queried from CPU features
  • {enable,disable}sve: Will force enable or disable sve even if the host doesn't support it
  • {enable,disable}avx: Will force enable or disable avx even if the host doesn't support it
  • {enable,disable}afp: Will force enable or disable afp even if the host doesn't support it
  • {enable,disable}lrcpc: Will force enable or disable lrcpc even if the host doesn't support it
  • {enable,disable}lrcpc2: Will force enable or disable lrcpc2 even if the host doesn't support it
  • {enable,disable}cssc: Will force enable or disable cssc even if the host doesn't support it
  • {enable,disable}pmull128: Will force enable or disable pmull128 even if the host doesn't support it
  • {enable,disable}rng: Will force enable or disable rng even if the host doesn't support it
  • {enable,disable}clzero: Will force enable or disable clzero even if the host doesn't support it
  • {enable,disable}atomics: Will force enable or disable ARMv8.1 LSE atomics even if the host doesn't support it
  • {enable,disable}fcma: Will force enable or disable fcma even if the host doesn't support it
  • {enable,disable}flagm: Will force enable or disable flagm even if the host doesn't support it
  • {enable,disable}flagm2: Will force enable or disable flagm2 even if the host doesn't support it
  • {enable,disable}crypto: Will force enable or disable crypto extensions even if the host doesn't support it
  • {enable,disable}rpres: Will force enable or disable rpres even if the host doesn't support it
  • {enable,disable}svebitperm: Will force enable or disable svebitperm even if the host doesn't support it
  • {enable,disable}preserveallabi: Will force enable or disable preserve_all abi even if the host doesn't support it
  • {enable,disable}wfxt: Will force enable or disable wfxt even if the host doesn't support it
  • {enable,disable}3dnow: Will force enable or disable 3DNow! even if the host doesn't support it
  • {enable,disable}sse4a: Will force enable or disable SSE4a even if the host doesn't support it
  • {enable,disable}mops: Will force enable or disable FEAT_MOPS even if the host doesn't support it
  • JSON key: 'HostFeatures'
  • default: 'FEXCore::Config::HostFeatures::OFF'
  • Available Options: enablesve, disablesve, enableavx, disableavx, enableafp, disableafp, enablelrcpc, disablelrcpc, enablelrcpc2, disablelrcpc2, enablecssc, disablecssc, enablepmull128, disablepmull128, enablerng, disablerng, enableclzero, disableclzero, enableatomics, disableatomics, enablefcma, disablefcma, enableflagm, disableflagm, enableflagm2, disableflagm2, enablefrintts, disablefrintts, enablecrypto, disablecrypto, enablerpres, disablerpres, enablesvebitperm, disablesvebitperm, enablepreserveallabi, disablepreserveallabi, enablewfxt, disablewfxt, enable3dnow, disable3dnow, enablesse4a, disablesse4a, enablemops, disablemops
🫶 Friendly lil note: yes, enablefrintts / disablefrintts show up in the Available Options list. It's in the list, so we list it. Slay.

FEX_SMALLTSCSCALE

Scales the cycle counter on systems that have low frequencies. 🐌➡️⚡

  • JSON key: 'SmallTSCScale'
  • default: true

FEX_HIDEHYBRID

Hides hybrid CPU core arrangement. Shhh, they don't need to know 🤫

  • JSON key: 'HideHybrid'
  • default: true

FEX_CPUFEATUREREGISTERS

Allows overriding cpu feature flags for manual testing. Testing girlies rise 🧪

  • JSON key: 'CPUFeatureRegisters'
  • default: ''

FEX_ROOTFS

Which Root filesystem prefix to use.

This can be a filesystem path:

  • eg: ~/RootFS/Debian_x86_64

Or this can be a name of a rootfs. If the named rootfs exists in the FEX data folder then it will use that one:

  • eg: $XDG_DATA_HOME/fex-emu/RootFS/<RootFS name>/

If XDG_DATA_HOME is unset, ~/.local/share will be used in its place:

  • eg: $HOME/.local/share/fex-emu/RootFS/<RootFS name>/
  • JSON key: 'RootFS'
  • default: ''

FEX_UNUSEDTHUNKHOSTLIBS

Folder to find the host-side thunking libraries.

  • JSON key: 'UnusedThunkHostLibs'
  • default: '/nix/store/pw7d9fiig8dawpi8brg6918rq3s269g3-fex-2608/lib/fex-emu/HostThunks'

FEX_UNUSEDTHUNKGUESTLIBS

Folder to find the guest-side thunking libraries.

  • JSON key: 'UnusedThunkGuestLibs'
  • default: '/nix/store/pw7d9fiig8dawpi8brg6918rq3s269g3-fex-2608/share/fex-emu/GuestThunks'

FEX_THUNKCONFIG

A json file specifying where to overlay the thunks.

This can be a filesystem path:

  • eg: ~/MyThunkConfig.json

Or this can be a named of a Thunk config file. If the named config file exists in the FEX data folder folder the it will use that one (yes, "folder folder", we're keeping it 💀):

  • eg: $XDG_DATA_HOME/fex-emu/ThunkConfigs/<ThunkConfig name>

If XDG_DATA_HOME is unset, ~/.local/share will be used in its place:

  • eg: $HOME/.local/share/fex-emu/ThunkConfigs/<ThunkConfig name>
  • JSON key: 'ThunkConfig'
  • default: ''

FEX_ENV

Adds an environment variable to the emulated environment.

  • JSON key: 'Env'
  • default: ''

FEX_HOSTENV

Adds an environment variable to the host environment.

This can be useful for setting environment variables that thunks can pick up. 👀

Typically isn't necessary since the guest libc isn't thunked. But is possible. 💫

  • JSON key: 'HostEnv'
  • default: ''

FEX_ADDITIONALARGUMENTS

Allows the user to pass additional arguments to the application.

  • JSON key: 'AdditionalArguments'
  • default: ''

FEX_DISABLEL2CACHE

Disables FEXCore's JIT L2 cache lookup. Saving memory. 🧠✨

Can potentially introduce more stutters.

  • JSON key: 'DisableL2Cache'
  • default: true

FEX_DYNAMICL1CACHE

Switches FEXCore's JIT L1 cache to be dynamically sized. Saving memory. 🫧

Can potentially introduce more stutters.

  • JSON key: 'DynamicL1Cache'
  • default: true

FEX_DYNAMICL1CACHEINCREASECOUNTHEURISTIC

Threshold of lookups per second that the L1 dynamic cache should increase its size.

Lower numbers means more aggressive scaling upward to the maximum size.

Higher numbers means more conservative scaling, using less memory.

Can potentially introduce stutters, more likely the higher the number.

🚨 Don't have this number smaller than the decrease count!
  • JSON key: 'DynamicL1CacheIncreaseCountHeuristic'
  • default: 250

FEX_DYNAMICL1CACHEDECREASECOUNTHEURISTIC

Threshold of lookups per second that the L1 dynamic cache should decrease its size.

The higher the number, the more aggressively it reduces the L1 cache size.

Lower numbers means more conservative memory savings.

Can potentially introduce stutters, more likely the higher the number.

🚨 Don't have this number larger than the increase count!
  • JSON key: 'DynamicL1CacheDecreaseCountHeuristic'
  • default: 50

FEX_SINGLESTEP

Single stepping configuration.

  • JSON key: 'SingleStep'
  • default: false

FEX_GDBSERVER

Enables the GDB server. 🐛 bestie is watching

  • JSON key: 'GdbServer'
  • default: false

FEX_DUMPIR

Folder to dump the IR in to.

[no, stdout, stderr, server, <Folder>]

  • JSON key: 'DumpIR'
  • default: 'no'

FEX_PASSMANAGERDUMPIR

Allows controlling when FEX dumps its IR. Timing is everything, babes ⏰

  • off: IR dumping will be disabled
  • beforeopt: Dump IR before any optimizations
  • afteropt: Dump IR after all optimizations
  • beforepass: Dump IR before every optimization pass
  • afterpass: Dump IR after every optimization pass
  • JSON key: 'PassManagerDumpIR'
  • default: 'FEXCore::Config::PassManagerDumpIR::OFF'
  • Available Options: beforeopt, afteropt, beforepass, afterpass

FEX_DUMPGPRS

When the test harness ends, print the GPR state. Little end-of-run report card 🗒️

  • JSON key: 'DumpGPRs'
  • default: false

FEX_O0

Disables optimizations passes for debugging. (Yes, "optimizations passes". We keep the words. 💜)

  • JSON key: 'O0'
  • default: false

FEX_GLOBALJITNAMING

Uses JITSymbols to name all JIT state as one symbol.

Useful for querying how much time is spent inside of the JIT.

Profiling tools will show JIT time as FEXJIT ✨

  • JSON key: 'GlobalJITNaming'
  • default: false

FEX_LIBRARYJITNAMING

Uses JITSymbols to name JIT symbols grouped by library.

Useful for querying how much time is spent in each guest library.

Can be used to help guide thunk generation. 🧵

  • JSON key: 'LibraryJITNaming'
  • default: false

FEX_BLOCKJITNAMING

Uses JITSymbols to name JIT symbols.

Useful for determining hot blocks of code. 🔥

Has some file writing overhead per JIT block. (overhead = the tax we pay 💸)

  • JSON key: 'BlockJITNaming'
  • default: false

FEX_GDBSYMBOLS

Integrates with GDB using the JIT interface.

Needs the fex jit loader in GDB, which can be loaded via jit-reader-load libFEXGDBReader.so.

Also needs x86_64-linux-gnu-objdump in PATH.

💀 Can be very slow. Like, go-make-a-snack slow.
  • JSON key: 'GDBSymbols'
  • default: false

FEX_INJECTLIBSEGFAULT

Sets the environment variable LD_PRELOAD=libSegFault.so

This allows the user to very easily enable libSegFault without dealing with environment variables. 🎉

Very useful for applications that have launch scripts that set the variable to nothing at launch.

Set this in an application configuration for injecting in to only specific applications.

🙈 Note: If x86/x86_64 libSegFault.so isn't installed then this option won't work.
  • JSON key: 'InjectLibSegFault'
  • default: false

FEX_DISASSEMBLE

Allows controlling of the vixl disassembler for generated ARM code. 🔍

  • off: No disassembly will be output
  • dispatcher: Will enable disassembly of the JIT dispatcher loop

no sign-off bestie, there's more page coming 🫶

  • blocks — turns on disassembly of the translated instruction code blocks 🧩
  • stats — prints stats while it's disassembling the code 📊
    • JSON key: 'Disassemble'
    • default: 'FEXCore::Config::Disassemble::OFF'
    • Available Options: dispatcher, blocks, stats
  • FEX_X86DISASSEMBLE — bestie this one gives you x86/x86-64 guest disassembly output for compiled blocks 💅 lowkey only works if FEX was built with -DENABLE_ZYDIS=TRUE, so like… check that first, no cap.
    • JSON key: 'X86Disassemble'
    • default: false
  • FEX_FORCESVEWIDTH — lets you override the SVE width in the vixl simulator. it's giving debugging-feature energy, fr fr 🔧
    • JSON key: 'ForceSVEWidth'
    • default: 0
  • FEX_DISABLETELEMETRY — kills telemetry at runtime. mostly useful for CI instcountCI, iykyk 🙈
    • JSON key: 'DisableTelemetry'
    • default: false
  • FEX_SILENTLOG — disables logging 🤫
    • JSON key: 'SilentLog'
    • default: true
  • FEX_OUTPUTLOG — the file FEX writes its output to. options are stderr, server, or a <Filename> 📝
    • JSON key: 'OutputLog'
    • default: 'server'
  • FEX_TELEMETRYDIRECTORY — redirects the telemetry folder FEX usually writes to. by default your telemetry data lives in {$FEX_APP_DATA_LOCATION,{$XDG_DATA_HOME,$HOME}/fex-emu/Telemetry/} 🗂️
    • JSON key: 'TelemetryDirectory'
    • default: ''
  • FEX_PROFILESTATS — turns on FEX's low-overhead sampling profile statistics ✨ requires a supported version of Mangohud to actually see the results, so don't come for me if it's invisible.
    • JSON key: 'ProfileStats'
    • default: false
  • FEX_ENABLEGPUVISPROFILING — enables profiling when FEX was built with the gpuvis profiler backend 🔥
    • JSON key: 'EnableGpuvisProfiling'
    • default: false
  • FEX_SMCCHECKS — checks code for modification before execution. the options are:
    • none — no checks, live your truth 🙈
    • mtrack — page tracking based invalidation, and this is the default 👑
    • full — validate code before every run, which is slow 🐌
    • JSON key: 'SMCChecks'
    • default: mtrack
  • FEX_TSOENABLED — controls TSO IR ops. bestie, it is highly likely to break any multithreaded application if you disable it 💀 like, seriously, don't.
    • JSON key: 'TSOEnabled'
    • default: true
  • FEX_VECTORTSOENABLED — when TSO emulation is enabled, this controls whether vector loadstores should also be atomic 💜
    • JSON key: 'VectorTSOEnabled'
    • default: false
  • FEX_MEMCPYSETTSOENABLED — when TSO emulation is enabled, controls whether memcpy and memset should also be atomic. only affects REP MOVS and REP STOS instructions, fyi 🫶
    • JSON key: 'MemcpySetTSOEnabled'
    • default: false
  • FEX_HALFBARRIERTSOENABLED — when TSO emulation is enabled, controls whether unaligned loads and stores get backpatched to half-barrier atomics. ⚠️ can be dangerous, because aligned loadstores going through the same code now become non-atomic. so like… careful, okay?
    • JSON key: 'HalfBarrierTSOEnabled'
    • default: true
  • FEX_STRICTINPROCESSSPLITLOCKS — strict global lock when handling an unaligned atomic that crosses a 16-byte or cacheline granularity. this is required to ensure a split-lock doesn't tear inside the process 🔒
    • JSON key: 'StrictInProcessSplitLocks'
    • default: false
  • FEX_KERNELUNALIGNEDATOMICBACKPATCHING — when the kernel unaligned atomic handler is enabled, use backpatching to reduce kernel context switches ⚡
    • JSON key: 'KernelUnalignedAtomicBackpatching'
    • default: true
  • FEX_VOLATILEMETADATA — use volatile metadata in PE files to inform TSO instructions when it's available. when metadata isn't available it falls back to the currently enabled TSO options 🦋
    • JSON key: 'VolatileMetadata'
    • default: true
  • FEX_X87REDUCEDPRECISION — emulates X87 floating point using 64-bit precision. this reduces emulation accuracy and may result in rendering bugs 😭 so yeah, know what you're getting into.
    • JSON key: 'X87ReducedPrecision'
    • default: false
  • FEX_STALLPROCESS — forces a process to stall out on initialization. useful for a process that keeps restarting and just doesn't work 🫠
    • JSON key: 'StallProcess'
    • default: false
  • FEX_HIDEHYPERVISORBIT — hides the hypervisor CPUID bit when set. should only be used for applications that have issues with this being set 🙈
    • JSON key: 'HideHypervisorBit'
    • default: false
  • FEX_STARTUPSLEEP — sleeps the process at startup for a duration in seconds 😴 useful if an application crashes too quickly to attach a debugger.
    • JSON key: 'StartupSleep'
    • default: 0
  • FEX_STARTUPSLEEPPROCNAME — constrains the startup sleep so it only applies to processes matching this name 🎯
    • JSON key: 'StartupSleepProcName'
    • default: ''
  • FEX_MONOHACKS — permits a hook-based SMC approach and smaller JIT blocks when mono is detected 🐒
    • JSON key: 'MonoHacks'
    • default: true
  • FEX_SERVERSOCKETPATH — override for a FEXServer socket path. only useful for chroots, ngl 🔌
    • JSON key: 'ServerSocketPath'
    • default: ''
  • FEX_NEEDSSECCOMP — disables inline syscalls in order to support seccomp handling 🛡️
    • JSON key: 'NeedsSeccomp'
    • default: false
  • FEX_EXTENDEDVOLATILEMETADATA — configuration-provided volatile metadata. only implemented for WoW64/arm64ec. limited in its use but can be handy ✨ it extends on top of what Microsoft has for volatile metadata, but it's also supported for WoW64.

the format goes: colon delimited modules, then semi-colon delimited instructions, then comma delimited ranges. by default it disables TSO in the module, unless instructions overlap the range 💅

<module>;<offset begin>-<offset-end>,...;<instruction offset to force TSO>,...:<another>

the examples, bestie, are iconic:

  • Disable TSO for a full module: just provide the module name: hl2_linux
  • Disable TSO for a part of the module: hl2_linux;<offset begin>-<offset-end>
  • Disable TSO for a part of the module, but enable TSO for some instructions within the module: hl2_linux;<offset begin>-<offset-end>;<instruction offset>,<instruction offset>
  • Disable TSO for multiple modules: hl2_linux:libsdl2.so
  • JSON key: 'ExtendedVolatileMetadata'
  • default: ''
  • FEX_APP_CONFIG_LOCATION — lets you override where FEX looks for configuration files 🗃️ by default FEX looks in ${XDG_CONFIG_HOME, $HOME/.config}/fex-emu/. this overrides the full path. if FEX_PORTABLE is declared then relative paths are also supported:
    • For FEX: relative to the FEX binary
    • For WINE: relative to %LOCALAPPDATA%
    • default: ''
  • FEX_APP_CONFIG — lets you override where FEX looks for only the application config file 📄 by default FEX looks in ${XDG_CONFIG_HOME, $HOME/.config}/fex-emu/Config.json, and this overrides that file location.
one must be careful with this option, bestie, because it will override any applications that load with execve as well 😬 if you need to support applications that execve then use FEX_APP_CONFIG_LOCATION instead!!

if FEX_PORTABLE is declared then relative paths are also supported:

  • For FEX: relative to the FEX binary
  • For WINE: relative to %LOCALAPPDATA%
  • default: ''
  • FEX_APP_DATA_LOCATION — lets you override where FEX looks for data files 🗂️ by default FEX looks in {$XDG_DATA_HOME, $HOME/.local/share}/fex-emu/. this overrides the full path. this is also the folder where FEX stores generated files like IR cache 💾
    • default: ''
  • FEX_PORTABLE — lets FEX run without installation 🧳 global locations for configuration and binfmt_misc are ignored.
    • For FEX on Linux: these files are instead read from <FEXPath>/fex-emu/ by default.
    • For Arm64ec/Wow64 WINE builds: these files are instead read from $LOCALAPPDATA/fex-emu/ by default.

for further customization, see FEX_APP_CONFIG_LOCATION and FEX_APP_DATA_LOCATION 🫶

  • default: ''
  • FEX_APP_CACHE_LOCATION — lets you override where FEX stores and loads cache files 🌸 by default FEX looks in ${XDG_CACHE_HOME, $HOME/.cache}/fex-emu/. this overrides the full path, and a trailing forward-slash is expected to exist 👀
    • default: ''

🎀 FILES 🎀

  • $XDG_CONFIG_DIR/fex-emu — the default FEX user configuration directory 💖
  • $prefix/share/fex-emu/AppConfig — system level application configuration files 🗂️
  • $prefix/share/fex-emu/GuestThunks — guest-side thunk data libraries 🧚
  • $prefix/lib/fex-emu/HostThunks — host-side thunks for guest communication 📡

and that's the whole page, bestie, you made it 🎉 this one's from the Linux source, version FEX(), dated UNDATED — so like, timeless icon behaviour honestly 👑💅 go forth and configure, periodt. 🦋✨

📦 where this page comes from