Skip to content

series: honor ExtendedVolatileMetadata ranges and whole-module entries (0013) - #13

Draft
utkarshdalal wants to merge 3 commits into
gamenativefrom
volatile-metadata-option-ranges
Draft

utkarshdalal wants to merge 3 commits into
gamenativefrom
volatile-metadata-option-ranges

Conversation

@utkarshdalal

@utkarshdalal utkarshdalal commented Nov 20, 2026 •

Copy link
Copy Markdown

Adds patch 0013. SERIES_VERSION 8.

Problem

On current builds a FEX_EXTENDEDVOLATILEMETADATA range or whole-module entry does nothing. Since FEX-2608 (852e93a) GenerateIR relaxes a block only when the block lies in a metadata range and a listed instruction lies inside the block; every other block keeps full TSO. That fits PE volatile metadata, where the listed instructions are the ones the compiler marked. Option entries such as UnityPlayer.dll;<begin>-<end> or a bare UnityPlayer.dll list no instructions, so no block qualifies. On 2605 they only worked through a past-the-end read of the instruction set, and only for the module mapped at the highest address.

Turning the condition off everywhere would also relax every module that ships PE volatile metadata, which is what 0005 (Counter-Strike 2) had to deal with.

Change

  • Ranges and whole-module entries from the option go into their own list in the context (AddTSODisabledRanges). PE metadata still goes only into the existing list.
  • A block that lies entirely inside an option range, at any load address, is translated without TSO for its integer loads and stores. Instructions listed in the entry and the Unity ring-buffer accesses (FLAG_FORCE_TSO) keep TSO, and 0005's dmb ishld still goes in front of them when a plain load comes first. Vector accesses follow VectorTSOEnabled as before. rep movs/stos and x87 read the context setting directly and are not affected.
  • A block that crosses a range boundary keeps TSO. Ranges are end exclusive. A range that does not fit in the module is dropped with an INFO line.
  • A block that already qualifies through PE metadata (a listed instruction inside it) takes the existing path unchanged. A module with no option entry behaves as before.
  • Unmapping a module removes its option ranges.
  • The Linux frontend is unchanged.

Identity guard

Matching by file name alone means a game update that ships a different DLL under the same name would get the old entry. Upstream 3c0410e (2607) already accepts a module's image ID as a key: <lowercase file name>-<16 hex digits>, where the digits are XXH3_64(lowercase name) ^ (SizeOfImage << 32 | TimeDateStamp), the same ID the code cache uses and the Load module log line prints. The patch uses that key rather than adding new syntax. It also adds:

  • When a module loads whose ID differs from an ID-keyed entry for the same file name, the entry is not applied and one INFO line names both IDs.
  • An applied entry logs one INFO line: key, module and base address.

Example, Unity 2022.3.62f2 (TimeDateStamp 0x68d678af, SizeOfImage 0x1e65000):

FEX_EXTENDEDVOLATILEMETADATA=unityplayer.dll-5695747efd732d16;<begin>-<end>,<begin>-<end>

Entries without an ID keep their current meaning. The name-only lookup stays case sensitive against the loaded path, as upstream has it. The config description documents both forms.

Environment size

On arm64ec and WoW64, LoadConfig reads the option from the CRT _environ into a fextl::string and parses it with string views. No fixed-size buffer sits on this path. A few ranges come to about 150 characters, far below the 32,767-character Windows variable limit.

Tested

  • New Catch2 cases in unittests/APITests/ExtendedVolatileMetadata.cpp: ID-key parse, another build of the same module (IsOtherImageIdOfModule), RVA-to-address mapping, a straddling block not covered, a range past the module end dropped, a whole-module entry, and listed instructions still reaching the PE-metadata lists. The existing grammar cases are unchanged. All 14 cases pass when compiled locally with clang against this tree. CI here does not build tests (BUILD_TESTING=False).
  • The series applies with plain git am on fresh FEX-2611 and FEX-2611.1 checkouts. CI now picks FEX-2611.1, the newest tag; it changed the volatile-metadata block in ImageTracker.cpp (0ec72ac gates it on VolatileMetadata). The new ImageTracker hunk sits where both tags agree and checks the same option.
  • CI builds both DLLs on both bases with no errors: the PR run (FEX-2611.1) and a manual workflow_dispatch run with upstream_ref=FEX-2611. The FEX-2611 artifact differs from the shipped 2611-gn-7 only by this patch.

Not run on a device yet. The device check: confirm the applied line, then count ordered and plain accesses in one translated block inside a configured range, with and without the env var.

Device result

AYN Odin 3 (Snapdragon 8 Elite), arm64ec Proton, manual CI build FEXCore-2611-gn8-e18178c-0 (FEX-2611 + this series, so it differs from 2611-gn-7 by this patch only), installed as a FEX package, one Unity 2022.3 game, 3 minutes of gameplay with a controller.

  • Entry keyed to the image id, two ranges: the log shows ExtendedVolatileMetadata: applied unityplayer.dll-5695747efd732d16 to UnityPlayer.dll at 5FFA7F0000.
  • Translated code: the two exempted functions have 0 ordered memory accesses (262 and 16 plain); three functions of the same DLL that were not listed keep theirs (61, 150 and 135 ordered).
  • Same worker load and frame rate as stock FEX 2605 with the same two ranges, where the option happened to work: job workers 206 % of a core against 207 %, and about 280 % with no entry.
  • No crash, input and rendering normal.
  • Not run: an entry whose image id does not match the loaded module (the skip path), whole-module entries, x86_64/WoW64.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant