Compare commits

...
Author SHA1 Message Date
poli0981andClaude Fable 5.2 4a14330059 fix(overlay): the patch registry refuses a patch it cannot record and records a patch before it can run - a full table no longer leaves a live patch the stop does not know, and a stop that arrives while a hook goes in can no longer miss it (beta.42 PR-2)
fl_patch_registry.h: slots Free -> Claimed -> Live -> Retired and one sequence, fl::patch::Install - claim, create, enable, commit, re-read the flag - against a stop that clears the flag and then walks the committed slots, both sequentially consistent. PatchTarget, the loader detour and the three DXGI patches go through it; a patch that did not go in is logged once (PATCH_FAILED); the capacity is asserted against the inventory's row count; READY is written only over INIT and init's failure path stores nothing, so neither overwrites a stop's reason. No hook body changed.

ctest fl_unhook_inline drives the shipped sequence against real MinHook patches (+3 cases).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 08:05:34 +07:00
6 changed files with 580 additions and 75 deletions

No files matched your search

+7
View File
@@ -37,6 +37,13 @@ numeric core and does not move; the heading is the full version — corrected 20
### Fixed
- **The part inside the game can no longer leave a hook in after it has stopped.** Two gaps in how the Overlay keeps
track of its own patches, found by reading the code and not by a failure: a patch made while the table of patches
was full would have been made anyway and never taken out, and a stop that arrived at the exact moment a hook was
going in could miss it. A patch now takes its place in the table before it is made — no place, no patch — and is
recorded before it can run, so the stop either removes it or the installer does. A patch that could not be made
is written to the Overlay's log with the reason, where it used to be silent. No hook's own code changed.
- **A session that saw two upscalers is named after the one it ran, with that one's quality and render size.** The
session's upscaler used to be the first one FrameLedger saw named, while the quality mode and the render size
came from whichever frames carried them. A game that evaluated DLSS briefly and then ran FSR was stored as "DLSS"
+30 -2
View File
@@ -714,6 +714,33 @@ Every hook body is wrapped:
> foreign one in ctest `fl_unhook_inline` (the vtable form stays in `fl_unhook_preserves_foreign`), and
> against the injected Overlay in ctest `fl_guard` `[log]`, where every patch reads `UNHOOK_RESTORED`
> because the harness is alone in its process.
>
> **The registry refuses what it cannot hold, and a patch is registered before it can run (0.1.0-beta.42,
> `fl_patch_registry.h`).** The registry was an array and a counter, and two things were wrong with it — found by
> reading the code for the plan of the next two hooks, not by a failure. **Full meant silent:** `RegisterPatch`
> wrote its entry only while it fitted, after `PatchTarget` had already enabled the hook, so a 49th patch would
> have been live and unknown to the stop, with no line anywhere. (Twenty patch sites exist; the rule no longer
> depends on that count being right, and a `static_assert` now checks the capacity against the inventory's own row
> count plus the seven sites that are not rows.) **Enabled before registered:** `PatchTarget` enabled the hook,
> re-read `g_observing`, and registered last; a stop between the re-read and the registration walked a table
> that did not hold the patch yet, and the patch stayed in after "stopped". The DXGI three and the loader detour
> registered after enabling too, with no re-read at all.
>
> One sequence now, `fl::patch::Install`: **take a slot — no slot, no patch, nothing created — create, enable,
> commit the slot, then re-read the flag.** The stop clears the flag and then walks the committed slots. Each side
> writes and then reads what the other wrote, sequentially consistent, so at least one sees the other: the walk
> restores the patch, or the installer finds the flag clear and takes its own patch out (and retires the slot,
> so the walk does not report it as somebody else's). A slot whose patch failed is free again; one that was ever
> live is never reused — the walk reads it without a lock. Nothing is created once observing is off. A patch
> that did not go in is logged once per target and reason, `PATCH_FAILED a=<reason>` (`2` stopped, `3` registry
> full, `4` create failed, `5` enable failed, `6` the stop arrived meanwhile); until now every such failure was
> silent. The three DXGI patches are still enabled together and keep the same rules by hand; when any step of
> theirs fails, whatever a partial enable left in is taken out — it used to stay, unregistered, with init
> reporting failure. And two stores that could overwrite a stop's reason no longer do: `READY` is written only
> over `INIT`, and init's failure path stores nothing. No hook body changed. ctest `fl_unhook_inline` drives
> the shipped sequence against real MinHook patches: a full registry leaves the target's bytes untouched and
> MinHook unasked; a stop arranged between the enable and the re-read ends with the function unpatched; a failed
> patch gives its slot back; a slot is invisible to the walk until committed.
~~`FlRequestUnhook()` (or the control flag) ⇒ `MH_DisableHook(MH_ALL_HOOKS)`, restore vtable entries **only where they are still ours**, flush the ring, set status.~~ *(Corrected 2026-10-04: both reach `StopObserving` — compare-and-restore per patch as the note above says, then the status; there is no `MH_ALL_HOOKS`, no vtable entry and no ring flush. The watchdog flushes the native log on its way out.)* **The DLL is not `FreeLibrary`'d from the live process** — a thread could still be inside a trampoline. It goes dormant and unloads with the process. This is deliberate and documented.
@@ -758,8 +785,9 @@ No logging in hook bodies. A small fixed-size in-memory ring of structured event
> `__func__` — never from a hook body. Codes: `RING_CREATED`, `PRESENT_HOOKS`, `HOOK_INSTALLED` (one per
> patch, with the target address), `SYMBOL_MISSING` (once per pair, and only when the module IS mapped),
> `FAULT`, `STOP` (the reason), `UNHOOK_RESTORED` / `UNHOOK_DECLINED` (one per patch), `LOADER_DETOUR`,
> `SUPERVISION_LOST`, and since beta.24 `STOP_FLUSHED` (the last line after a stop: `a=1` when the stop had finished
> writing). **Three flush points, none on a present path:** the end of `InitThread` (so the
> `SUPERVISION_LOST`, since beta.24 `STOP_FLUSHED` (the last line after a stop: `a=1` when the stop had finished
> writing), and since beta.42 `PATCH_FAILED` (a patch that did not go in, once per target and reason — §Unhooking).
> **Three flush points, none on a present path:** the end of `InitThread` (so the
> file exists from the start of the session and a crash mid-session still leaves it), the watchdog when
> `FlControlBlock.logFlushRequested` changes (a counter the Agent bumps at session end; nothing clears it),
> and the watchdog on its way out after any stop. Appended, never recreated; events overwritten before a
@@ -376,6 +376,13 @@ inline int FfxLeafOf(const wchar_t* moduleName) noexcept {
X(L"amd_fidelityfx_loader_dx12.dll", "ffxQuery", fl::inventory::kFamilyFfxQuery) \
X(L"ffx_fsr3_x64.dll", "ffxFsr3ContextDispatchUpscale", fl::inventory::kFamilyFsr3Host)
// How many rows the table has: one inline patch each at most. dllmain's patch registry is sized against it, so a
// row added here cannot outgrow the registry without a compile error (0.1.0-beta.42).
#define FL_COUNT_ROW(mod, sym, family) +1u
inline constexpr uint32_t kRowCount = 0u FL_HOOK_INVENTORY(FL_COUNT_ROW);
#undef FL_COUNT_ROW
static_assert(kRowCount == 13u, "a row was added or removed: say so here, and in 17_HOOK_ENGINE §Hook inventory");
// The FSR 3.0 host module and the one symbol dllmain's ffx arm keys on for it. Named
// constants HERE, for the reason kModuleSlInterposer gives below, and bound to the
// table so the row and the arm cannot drift apart.
@@ -0,0 +1,181 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
// The patch registry (17_HOOK_ENGINE §Unhooking): every inline patch the Overlay
// makes, so that the stop can take each one out again -- and the ONE sequence a
// patch goes in by, so that a patch the stop cannot see is never made.
//
// WHAT THIS REPLACES, AND WHY (0.1.0-beta.42, found by reviewing the plan for the
// next two hooks against the code). The registry was an array and a counter:
//
// 1. FULL MEANT SILENT. RegisterPatch advanced the counter and wrote the entry
// only while it fitted; PatchTarget had already created and enabled the
// hook. A 49th patch would have been live and unknown to the stop -- "the
// part inside the game stops" (legal/DISCLAIMER.md §2) with one patch left
// in, and no line anywhere saying so. Unreachable with the 20 patch sites
// of today; the rule now does not depend on counting them right.
// 2. ENABLED BEFORE REGISTERED. PatchTarget enabled the hook, re-read
// g_observing, and registered last. A stop that ran between the re-read and
// the registration walked a table that did not hold the patch yet.
//
// THE SEQUENCE NOW (Install below): take a slot -- no slot, no patch -- create,
// enable, COMMIT the slot, and only then re-read the flag. The stop clears the
// flag and only then walks the committed slots. Both are a write followed by a
// read of what the other wrote, in the one total order sequentially consistent
// operations have, so at least one of the two sees the other: either the walk
// finds the committed slot and restores it, or the installer finds the flag
// clear and takes its own patch out. There is no interleaving in which neither
// does. (On x86-64 the only instruction this costs is the commit's XCHG, on an
// install path that runs a handful of times per process.)
//
// A SLOT IS Free -> Claimed -> Live, and from Live only to Retired. A claimed slot
// whose patch failed goes back to Free -- the walk never saw it. A slot that was
// ever Live is never handed out again: the walk reads a Live slot's three fields
// without a lock, and a slot refilled under it would be a target paired with
// another patch's detour. Retiring costs a slot only for a patch that raced the
// stop, and after the stop nothing is installed at all.
//
// Header-only, MinHook-free and allocation-free: the Overlay passes MinHook in as
// the `hooker`, and ctest fl_unhook_inline drives this same sequence against real
// MinHook patches -- the shipped sequence, not a copy of it.
#ifndef FRAMELEDGER_FL_PATCH_REGISTRY_H
#define FRAMELEDGER_FL_PATCH_REGISTRY_H
#include <atomic>
#include <cstdint>
namespace fl::patch {
// Why Install did or did not patch. The values are written to the native log (PATCH_FAILED a=<value>), so they
// are fixed: append, never renumber.
enum class InstallResult : std::uint32_t {
Installed = 0,
NoTarget = 1, // nothing to patch
Stopped = 2, // observing was already off: nothing was created
Full = 3, // every slot is taken: nothing was created
CreateFailed =
4, // the hooker could not create the hook (MinHook: already created, unsupported prologue, memory)
EnableFailed = 5, // created, not enabled: no patch at the target
StoppedDuring = 6, // the stop ran while this patch went in; the installer took it out again
};
template <std::uint32_t Capacity>
class Registry {
public:
// A free slot for a patch that does not exist yet, or -1: the caller must not patch.
int Claim(void* target, void* detour, const char* name) noexcept {
for (std::uint32_t i = 0; i < Capacity; ++i) {
std::uint32_t expected = kFree;
if (slots_[i].state.compare_exchange_strong(expected, kClaimed, std::memory_order_acq_rel,
std::memory_order_relaxed)) {
slots_[i].target = target;
slots_[i].detour = detour;
slots_[i].name = name;
return static_cast<int>(i);
}
}
return -1;
}
// The patch is enabled; the stop's walk restores it from here on. Sequentially consistent ON PURPOSE: it is the
// write of the write-then-read pair described at the top of this file.
void Commit(int slot) noexcept {
if (Valid(slot)) {
slots_[static_cast<std::uint32_t>(slot)].state.store(kLive, std::memory_order_seq_cst);
}
}
// The patch was never made. Only for a slot that was claimed and not committed.
void Release(int slot) noexcept {
if (Valid(slot)) {
std::uint32_t expected = kClaimed;
slots_[static_cast<std::uint32_t>(slot)].state.compare_exchange_strong(
expected, kFree, std::memory_order_acq_rel, std::memory_order_relaxed);
}
}
// The installer took a committed patch out itself. The slot is never handed out again.
void Retire(int slot) noexcept {
if (Valid(slot)) {
slots_[static_cast<std::uint32_t>(slot)].state.store(kRetired, std::memory_order_seq_cst);
}
}
// Every committed patch: visit(target, detour, name). The read of the write-then-read pair, on the stop's side.
template <class Visit>
void ForEachLive(Visit&& visit) const noexcept {
for (std::uint32_t i = 0; i < Capacity; ++i) {
if (slots_[i].state.load(std::memory_order_seq_cst) == kLive) {
visit(slots_[i].target, slots_[i].detour, slots_[i].name);
}
}
}
std::uint32_t LiveCount() const noexcept {
std::uint32_t n = 0;
ForEachLive([&n](void*, void*, const char*) noexcept { ++n; });
return n;
}
static constexpr std::uint32_t kCapacity = Capacity;
private:
static constexpr std::uint32_t kFree = 0;
static constexpr std::uint32_t kClaimed = 1;
static constexpr std::uint32_t kLive = 2;
static constexpr std::uint32_t kRetired = 3;
static bool Valid(int slot) noexcept { return slot >= 0 && static_cast<std::uint32_t>(slot) < Capacity; }
struct Slot {
std::atomic<std::uint32_t> state{kFree};
void* target = nullptr;
void* detour = nullptr;
const char* name = nullptr;
};
Slot slots_[Capacity]{};
};
// Patch ONE address, registered before it can run and never left in after a stop.
//
// `hooker` is the inline-hook engine: Create(target, detour, original) -> bool, Enable(target) -> bool,
// Disable(target). The Overlay passes MinHook; so does the test.
//
// A hook that was created and could not be enabled stays created in the engine, as it always has: a later attempt
// then fails at Create, and nothing is at the target either way.
template <std::uint32_t Capacity, class Hooker>
InstallResult Install(Registry<Capacity>& registry, const std::atomic<std::uint32_t>& observing, Hooker&& hooker,
void* target, void* detour, void** original, const char* name) noexcept {
if (target == nullptr) {
return InstallResult::NoTarget;
}
if (observing.load(std::memory_order_seq_cst) == 0u) {
return InstallResult::Stopped;
}
const int slot = registry.Claim(target, detour, name);
if (slot < 0) {
return InstallResult::Full;
}
if (!hooker.Create(target, detour, original)) {
registry.Release(slot);
return InstallResult::CreateFailed;
}
if (!hooker.Enable(target)) {
registry.Release(slot);
return InstallResult::EnableFailed;
}
registry.Commit(slot);
if (observing.load(std::memory_order_seq_cst) == 0u) {
// The stop ran while the patch went in. Its walk either saw the committed slot and restored the patch -- then
// this disable finds it disabled already -- or it had passed the slot, and this is what takes the patch out.
hooker.Disable(target);
registry.Retire(slot);
return InstallResult::StoppedDuring;
}
return InstallResult::Installed;
}
} // namespace fl::patch
#endif // FRAMELEDGER_FL_PATCH_REGISTRY_H
+148 -73
View File
@@ -52,6 +52,7 @@
#include <fl_dxgi_vtable.h>
#include <fl_hook_inventory.h>
#include <fl_patch_check.h>
#include <fl_patch_registry.h>
#include <fl_ring.h>
#include <fl_rt_accum.h>
#include <fl_shm.h>
@@ -147,6 +148,7 @@ enum FlLogCode : uint32_t {
kLogSupervisionLost,
kLogTolerance,
kLogStopFlushed,
kLogPatchFailed,
};
const char* LogCodeName(uint32_t code) noexcept {
@@ -175,6 +177,8 @@ const char* LogCodeName(uint32_t code) noexcept {
return "TOLERANCE";
case kLogStopFlushed:
return "STOP_FLUSHED";
case kLogPatchFailed:
return "PATCH_FAILED";
default:
return "?";
}
@@ -334,23 +338,55 @@ void FlushLog(bool lastFlush = false) noexcept {
// patch this DLL installs is recorded here so the stop can ask, per patch,
// whether the bytes at the target are still OUR jump before writing the saved
// prologue back -- the inline-patch form of §H7's compare-and-restore.
//
// fl_patch_registry.h since 0.1.0-beta.42: a patch takes its slot BEFORE it is
// created -- no slot, no patch -- and is committed before the flag is re-read,
// so no patch can be live and unknown to the stop. The header says what the
// array and counter this replaces let through.
//
// THE CAPACITY IS CHECKED AGAINST WHAT CAN BE INSTALLED: every inventory row,
// counted by the table itself, and the seven sites that are not rows -- DXGI's
// Present, Present1 and ResizeBuffers, kernelbase!LoadLibraryExW,
// opengl32!wglSwapBuffers, and the two ray-tracing command-list methods. A site
// added without raising kPatchSitesOutsideTheInventory is not caught here; it is
// caught at run time, where a full registry refuses the patch and says so.
// ---------------------------------------------------------------------------
struct PatchEntry {
void* target = nullptr;
void* detour = nullptr;
const char* name = nullptr;
};
constexpr uint32_t kMaxPatches = 48;
PatchEntry g_patches[kMaxPatches]{};
std::atomic<uint32_t> g_patchCount{0};
constexpr uint32_t kMaxPatches = 48;
constexpr uint32_t kPatchSitesOutsideTheInventory = 7;
static_assert(fl::inventory::kRowCount + kPatchSitesOutsideTheInventory <= kMaxPatches,
"the patch registry cannot hold every patch this DLL may install -- raise kMaxPatches with the table");
fl::patch::Registry<kMaxPatches> g_patches;
void RegisterPatch(void* target, void* detour, const char* name) noexcept {
const uint32_t i = g_patchCount.fetch_add(1u, std::memory_order_acq_rel);
if (i < kMaxPatches) {
g_patches[i].target = target;
g_patches[i].detour = detour;
g_patches[i].name = name;
LogNote(kLogHookInstalled, name, 0, reinterpret_cast<uint64_t>(target));
// MinHook, as the engine fl::patch::Install drives.
struct MinHookEngine {
static bool Create(void* target, void* detour, void** original) noexcept {
return MH_CreateHook(target, detour, original) == MH_OK;
}
static bool Enable(void* target) noexcept { return MH_EnableHook(target) == MH_OK; }
static void Disable(void* target) noexcept { MH_DisableHook(target); }
};
// A patch that did not go in, said ONCE per target and reason: the lazy installers retry every second, and a line a
// second would push everything else out of a 256-event ring. Init and watchdog threads only, which never install at
// the same time (the watchdog starts after the init thread's last install), so a plain table.
struct PatchFailure {
const void* target = nullptr;
uint32_t result = 0;
};
PatchFailure g_patchFailuresSeen[16]{};
void NotePatchFailedOnce(const void* target, fl::patch::InstallResult result, const char* name) noexcept {
const auto code = static_cast<uint32_t>(result);
for (PatchFailure& seen : g_patchFailuresSeen) {
if (seen.target == target && seen.result == code) {
return;
}
if (seen.target == nullptr) {
seen.target = target;
seen.result = code;
LogNote(kLogPatchFailed, name, code, reinterpret_cast<uint64_t>(target));
return;
}
}
}
@@ -850,8 +886,11 @@ void StopObserving(uint32_t reason) noexcept {
// reason wins -- a self-disable already in flight is not overwritten by a
// safety stop that arrives a millisecond later, or the record of WHY we
// stopped would depend on thread scheduling.
//
// Sequentially consistent, and the walk below reads the registry the same way: this write and that read are one
// half of the pair fl_patch_registry.h describes, and an installer's commit and re-read are the other.
uint32_t expected = 1;
if (!g_observing.compare_exchange_strong(expected, 0, std::memory_order_acq_rel, std::memory_order_acquire)) {
if (!g_observing.compare_exchange_strong(expected, 0, std::memory_order_seq_cst, std::memory_order_seq_cst)) {
return;
}
LogNote(kLogStop, "observing stopped", reason);
@@ -862,16 +901,14 @@ void StopObserving(uint32_t reason) noexcept {
// is restored only while the bytes at its target are still the jump MinHook
// wrote for us; otherwise it is left in place and our detour stays in the
// other overlay's chain doing nothing -- g_observing is 0, every body forwards.
const uint32_t n = g_patchCount.load(std::memory_order_acquire);
for (uint32_t i = 0; i < n && i < kMaxPatches; ++i) {
const PatchEntry& p = g_patches[i];
if (fl::patch::StillOurs(p.target, p.detour)) {
const bool ok = MH_DisableHook(p.target) == MH_OK;
LogNote(kLogUnhookRestored, p.name, ok ? 1u : 0u, reinterpret_cast<uint64_t>(p.target));
g_patches.ForEachLive([](void* target, void* detour, const char* name) noexcept {
if (fl::patch::StillOurs(target, detour)) {
const bool ok = MH_DisableHook(target) == MH_OK;
LogNote(kLogUnhookRestored, name, ok ? 1u : 0u, reinterpret_cast<uint64_t>(target));
} else {
LogNote(kLogUnhookDeclined, p.name, 0u, reinterpret_cast<uint64_t>(p.target));
LogNote(kLogUnhookDeclined, name, 0u, reinterpret_cast<uint64_t>(target));
}
}
});
if (g_state != nullptr) {
std::atomic_ref<uint32_t> status{g_state->status};
status.store(reason, std::memory_order_release);
@@ -882,6 +919,35 @@ void StopObserving(uint32_t reason) noexcept {
WakeWatchdog();
}
// Patch ONE address, and close the install-after-stop window.
//
// STOPPING IS ONE-WAY, and fl::patch::Install is what keeps it so. StopObserving can
// run between a caller's g_observing check and the patch, and its walk would then
// have run BEFORE this hook existed -- leaving a hook patched in after we promised
// the Agent there were none. Nothing false would be recorded (every body consults
// MayObserve), but legal/DISCLAIMER.md §2 promises the part inside the game stops,
// and a hook installed after the stop is not that. So the patch is registered
// before the flag is re-read, and a full registry refuses it (fl_patch_registry.h).
//
// ONE FUNCTION ON PURPOSE, and the reason has now happened three times. It was first
// inline in the single installer, so a second lazy installer that forgot it would
// reopen the window silently; the ray-tracing installer WAS that second one, and it
// cannot reuse InstallRow because its targets come from a VTABLE rather than from a
// name; the LoadLibrary detour was the third, and until 0.1.0-beta.42 it carried a
// copy of the sequence with the re-check left out.
bool PatchTarget(void* target, void* detour, void** original, const char* name = "hook") noexcept {
const fl::patch::InstallResult result =
fl::patch::Install(g_patches, g_observing, MinHookEngine{}, target, detour, original, name);
if (result == fl::patch::InstallResult::Installed) {
LogNote(kLogHookInstalled, name, 0, reinterpret_cast<uint64_t>(target));
return true;
}
if (result != fl::patch::InstallResult::NoTarget) {
NotePatchFailedOnce(target, result, name);
}
return false;
}
// Returns false when we must not record this present.
//
// The supervision deadline is NOT here any more -- it is the watchdog's, which
@@ -1522,13 +1588,11 @@ bool InstallLoaderHook() noexcept {
if (target == nullptr) {
return false;
}
if (MH_CreateHook(target, reinterpret_cast<void*>(&Hook_LoadLibraryExW),
reinterpret_cast<void**>(&g_origLoadLibraryExW)) != MH_OK ||
MH_EnableHook(target) != MH_OK) {
if (!PatchTarget(target, reinterpret_cast<void*>(&Hook_LoadLibraryExW),
reinterpret_cast<void**>(&g_origLoadLibraryExW), "kernelbase!LoadLibraryExW")) {
LogNote(kLogLoaderDetour, "kernelbase!LoadLibraryExW", 0);
return false;
}
RegisterPatch(target, reinterpret_cast<void*>(&Hook_LoadLibraryExW), "kernelbase!LoadLibraryExW");
g_loaderSignals.fetch_or(kLoaderInstalledBit, std::memory_order_release);
LogNote(kLogLoaderDetour, "kernelbase!LoadLibraryExW", 1);
return true;
@@ -2141,36 +2205,6 @@ void STDMETHODCALLTYPE Hook_BuildRtAs(ID3D12GraphicsCommandList4*
// slSetTag would have been detoured by the slEvaluateFeature body, which reads
// argument 1 as a feature id. Same class of defect as the SL1 ABI break (#71),
// reached from the other direction.
// Patch ONE address, and close the install-after-stop window.
//
// STOPPING IS ONE-WAY, and the check below is what keeps it so. StopObserving can
// run between a caller's g_observing check and here, and MH_DisableHook(MH_ALL_HOOKS)
// would then have run BEFORE this hook existed -- leaving a hook patched in after
// we promised the Agent there were none. Nothing false would be recorded (every
// body consults MayObserve), but legal/DISCLAIMER.md §2 promises the part inside
// the game stops, and a hook installed after the stop is not that.
//
// FACTORED OUT OF InstallRow ON PURPOSE, and the reason has now happened twice.
// It was first inline in the single installer, so a second lazy installer that
// forgot it would reopen the window silently; the ray-tracing installer IS that
// second one, and it cannot reuse InstallRow because its targets come from a
// VTABLE rather than from a name. Sharing this is what keeps the window closed in
// one place rather than in two that can drift.
bool PatchTarget(void* target, void* detour, void** original, const char* name = "hook") noexcept {
if (target == nullptr) {
return false;
}
if (MH_CreateHook(target, detour, original) != MH_OK || MH_EnableHook(target) != MH_OK) {
return false;
}
if (g_observing.load(std::memory_order_acquire) == 0) {
MH_DisableHook(target);
return false;
}
RegisterPatch(target, detour, name);
return true;
}
// Publish the family bit and latch. Separate from PatchTarget because a hook that
// spans several targets must not claim its family until every one of them is in.
void PublishHookFamily(uint32_t family, std::atomic<uint32_t>& live) noexcept {
@@ -3544,20 +3578,55 @@ bool InstallPresentHooks() noexcept {
// so ctest fl_vtable_indices proved a fact about dxgi.dll rather
// than about this DLL: changing an 8 here left it green
// (20_OPEN_QUESTIONS §S29(b)).
ok = MH_CreateHook(vtbl[fl::dxgi::kPresentIndex], reinterpret_cast<void*>(&Hook_Present),
reinterpret_cast<void**>(&g_origPresent)) == MH_OK &&
MH_CreateHook(vtbl[fl::dxgi::kResizeBuffersIndex], reinterpret_cast<void*>(&Hook_ResizeBuffers),
reinterpret_cast<void**>(&g_origResizeBuffers)) == MH_OK &&
MH_CreateHook(vtbl[fl::dxgi::kPresent1Index], reinterpret_cast<void*>(&Hook_Present1),
reinterpret_cast<void**>(&g_origPresent1)) == MH_OK &&
MH_EnableHook(MH_ALL_HOOKS) == MH_OK;
//
// THREE PATCHES, ENABLED TOGETHER -- one pass over the process's threads rather than three, and no
// moment in which Present is hooked and ResizeBuffers is not -- so they do not go through PatchTarget,
// and keep its rules by hand: a slot each BEFORE anything is created, committed before the flag is
// re-read, and nothing left enabled when any step fails (a partial MH_EnableHook(MH_ALL_HOOKS) used to
// leave what it had enabled in place, unregistered, with init reporting failure).
struct PresentPatch {
void* target;
void* detour;
void** original;
const char* name;
int slot;
};
PresentPatch patches[] = {
{vtbl[fl::dxgi::kPresentIndex], reinterpret_cast<void*>(&Hook_Present),
reinterpret_cast<void**>(&g_origPresent), "dxgi!IDXGISwapChain::Present", -1},
{vtbl[fl::dxgi::kResizeBuffersIndex], reinterpret_cast<void*>(&Hook_ResizeBuffers),
reinterpret_cast<void**>(&g_origResizeBuffers), "dxgi!IDXGISwapChain::ResizeBuffers", -1},
{vtbl[fl::dxgi::kPresent1Index], reinterpret_cast<void*>(&Hook_Present1),
reinterpret_cast<void**>(&g_origPresent1), "dxgi!IDXGISwapChain1::Present1", -1},
};
ok = true;
for (PresentPatch& p : patches) {
p.slot = g_patches.Claim(p.target, p.detour, p.name);
ok = ok && p.slot >= 0;
}
for (const PresentPatch& p : patches) {
ok = ok && MH_CreateHook(p.target, p.detour, p.original) == MH_OK;
}
ok = ok && MH_EnableHook(MH_ALL_HOOKS) == MH_OK;
if (ok) {
RegisterPatch(vtbl[fl::dxgi::kPresentIndex], reinterpret_cast<void*>(&Hook_Present),
"dxgi!IDXGISwapChain::Present");
RegisterPatch(vtbl[fl::dxgi::kResizeBuffersIndex], reinterpret_cast<void*>(&Hook_ResizeBuffers),
"dxgi!IDXGISwapChain::ResizeBuffers");
RegisterPatch(vtbl[fl::dxgi::kPresent1Index], reinterpret_cast<void*>(&Hook_Present1),
"dxgi!IDXGISwapChain1::Present1");
for (const PresentPatch& p : patches) {
g_patches.Commit(p.slot);
LogNote(kLogHookInstalled, p.name, 0, reinterpret_cast<uint64_t>(p.target));
}
if (g_observing.load(std::memory_order_seq_cst) == 0u) {
// A stop arrived while they went in (FlRequestUnhook, or a present that read the Agent's
// request): out again, here, whether or not its walk saw them.
for (const PresentPatch& p : patches) {
MH_DisableHook(p.target);
g_patches.Retire(p.slot);
}
ok = false;
}
} else {
for (const PresentPatch& p : patches) {
MH_DisableHook(p.target); // a no-op for one never created or never enabled
g_patches.Release(p.slot);
}
}
}
}
@@ -3628,8 +3697,10 @@ DWORD WINAPI InitThread(LPVOID) noexcept {
// Hooking failed, so nothing will ever be recorded. Staying at INIT says
// exactly that; READY would be a claim about a capture side that does not
// exist, and the Agent's degradation path is what should run instead.
//
// NOTHING IS STORED: the status is INIT already -- unless a stop arrived while the present hooks went in, and
// then it holds the stop's reason, which a store of INIT here would overwrite (0.1.0-beta.42).
LogNote(kLogPresentHooks, "MinHook init or the DXGI present hooks FAILED", 0);
status.store(FL_STATUS_INIT, std::memory_order_release);
FlushLog();
return 1;
}
@@ -3658,7 +3729,11 @@ DWORD WINAPI InitThread(LPVOID) noexcept {
// for one that maps it later.
InstallOpenGlHook();
status.store(FL_STATUS_READY, std::memory_order_release);
// INIT -> READY and nothing else -> READY. The present hooks are live from InstallPresentHooks on, so a stop can
// already have written its reason here (a present that read the Agent's request, FlRequestUnhook); a plain
// store would put READY over it, and the Agent would read a capture side with no hook in as ready.
uint32_t stillInit = FL_STATUS_INIT;
status.compare_exchange_strong(stillInit, FL_STATUS_READY, std::memory_order_acq_rel, std::memory_order_acquire);
// AFTER the hooks, deliberately. The watchdog's only job is to take them out
// again, so starting it earlier would create a window in which it could
+207
View File
@@ -17,10 +17,12 @@
#include <windows.h>
#include <atomic>
#include <catch2/catch_test_macros.hpp>
#include <cstdint>
#include <cstring>
#include <fl_patch_check.h>
#include <fl_patch_registry.h>
#include <MinHook.h>
namespace {
@@ -93,6 +95,92 @@ void RepointJump(void* target, const void* relay, std::int32_t* savedRel) {
FlushInstructionCache(GetCurrentProcess(), p, 5);
}
// --- the registry's cases (0.1.0-beta.42) ---------------------------------------------------------------------------
// Three more real functions, each with a body of its own so the linker cannot fold them into one address.
__declspec(noinline) int First(int x) {
volatile int acc = x;
for (int i = 0; i < 3; ++i) {
acc = acc * 5 + i;
}
return acc;
}
__declspec(noinline) int Second(int x) {
volatile int acc = x;
for (int i = 0; i < 4; ++i) {
acc = acc * 7 - i;
}
return acc;
}
__declspec(noinline) int Third(int x) {
volatile int acc = x;
for (int i = 0; i < 5; ++i) {
acc = acc * 11 + 2 * i;
}
return acc;
}
TargetFn g_origFirst = nullptr;
TargetFn g_origSecond = nullptr;
TargetFn g_origThird = nullptr;
int DetourFirst(int x) {
return g_origFirst(x) + 1000000;
}
int DetourSecond(int x) {
return g_origSecond(x) + 2000000;
}
int DetourThird(int x) {
return g_origThird(x) + 3000000;
}
// MinHook, exactly as the Overlay hands it to fl::patch::Install (dllmain.cpp's MinHookEngine).
struct RealMinHook {
static bool Create(void* target, void* detour, void** original) noexcept {
return MH_CreateHook(target, detour, original) == MH_OK;
}
static bool Enable(void* target) noexcept { return MH_EnableHook(target) == MH_OK; }
static void Disable(void* target) noexcept { MH_DisableHook(target); }
};
// The same engine with one thing arranged: a stop that arrives between the enable and the installer's re-read.
struct StopArrivesWhileEnabling {
std::atomic<std::uint32_t>* observing;
static bool Create(void* target, void* detour, void** original) noexcept {
return RealMinHook::Create(target, detour, original);
}
bool Enable(void* target) const noexcept {
const bool ok = RealMinHook::Enable(target);
observing->store(0u);
return ok;
}
static void Disable(void* target) noexcept { RealMinHook::Disable(target); }
};
// An engine that fails at a chosen step and counts what it was asked: nothing may be created once a patch is refused.
struct FailingEngine {
bool createOk;
bool enableOk;
int* created;
bool Create(void*, void*, void**) const noexcept {
++*created;
return createOk;
}
bool Enable(void*) const noexcept { return enableOk; }
static void Disable(void*) noexcept {}
};
// The stop's walk, as StopObserving writes it: restore each patch that is still ours.
template <std::uint32_t N>
int RestoreEveryLivePatch(const fl::patch::Registry<N>& registry) {
int restored = 0;
registry.ForEachLive([&restored](void* target, void* detour, const char*) noexcept {
if (fl::patch::StillOurs(target, detour) && MH_DisableHook(target) == MH_OK) {
++restored;
}
});
return restored;
}
void RestoreJump(void* target, std::int32_t savedRel) {
auto* p = static_cast<std::uint8_t*>(target);
DWORD old = 0;
@@ -160,3 +248,122 @@ TEST_CASE("garbage at the target is 'not ours', never a fault", "[unhook][inline
CHECK_FALSE(fl::patch::StillOurs(page, nullptr));
VirtualFree(page, 0, MEM_RELEASE);
}
TEST_CASE("a full registry refuses the patch: nothing is created and the target's bytes are untouched",
"[unhook][registry]") {
using fl::patch::InstallResult;
fl::patch::Registry<2> registry;
std::atomic<std::uint32_t> observing{1u};
void* first = reinterpret_cast<void*>(&First);
void* second = reinterpret_cast<void*>(&Second);
void* third = reinterpret_cast<void*>(&Third);
const int firstPlain = First(3);
const int secondPlain = Second(3);
const int thirdPlain = Third(3);
std::uint8_t before[16]{};
std::memcpy(before, third, sizeof(before));
REQUIRE(MH_Initialize() == MH_OK);
CHECK(fl::patch::Install(registry, observing, RealMinHook{}, first, reinterpret_cast<void*>(&DetourFirst),
reinterpret_cast<void**>(&g_origFirst), "first") == InstallResult::Installed);
CHECK(fl::patch::Install(registry, observing, RealMinHook{}, second, reinterpret_cast<void*>(&DetourSecond),
reinterpret_cast<void**>(&g_origSecond), "second") == InstallResult::Installed);
CHECK(First(3) == firstPlain + 1000000);
CHECK(Second(3) == secondPlain + 2000000);
CHECK(registry.LiveCount() == 2u);
// The third has no slot. The array and counter this replaced patched it anyway and forgot it.
g_origThird = nullptr;
CHECK(fl::patch::Install(registry, observing, RealMinHook{}, third, reinterpret_cast<void*>(&DetourThird),
reinterpret_cast<void**>(&g_origThird), "third") == InstallResult::Full);
CHECK(std::memcmp(before, third, sizeof(before)) == 0);
CHECK(Third(3) == thirdPlain);
CHECK(g_origThird == nullptr); // MinHook was never asked: no trampoline exists for it
CHECK(MH_EnableHook(third) == MH_ERROR_NOT_CREATED);
CHECK(registry.LiveCount() == 2u);
// And the stop takes out every patch that did go in -- which is now every patch there is.
observing.store(0u);
CHECK(RestoreEveryLivePatch(registry) == 2);
CHECK(First(3) == firstPlain);
CHECK(Second(3) == secondPlain);
// Stopping is one-way: after it, nothing is created at all.
CHECK(fl::patch::Install(registry, observing, RealMinHook{}, third, reinterpret_cast<void*>(&DetourThird),
reinterpret_cast<void**>(&g_origThird), "third") == InstallResult::Stopped);
CHECK(MH_EnableHook(third) == MH_ERROR_NOT_CREATED);
MH_Uninitialize();
}
TEST_CASE("a patch that goes in while the stop runs is taken out by its installer, and its slot is never reused",
"[unhook][registry]") {
using fl::patch::InstallResult;
fl::patch::Registry<1> registry;
std::atomic<std::uint32_t> observing{1u};
void* first = reinterpret_cast<void*>(&First);
const int firstPlain = First(4);
REQUIRE(MH_Initialize() == MH_OK);
// The window the old order left open: the flag read 1, the stop ran -- its walk found nothing, the patch was not
// registered yet -- and the patch was then enabled and registered, live after "stopped".
CHECK(fl::patch::Install(registry, observing, StopArrivesWhileEnabling{&observing}, first,
reinterpret_cast<void*>(&DetourFirst), reinterpret_cast<void**>(&g_origFirst),
"first") == InstallResult::StoppedDuring);
CHECK(First(4) == firstPlain); // not left in
CHECK_FALSE(fl::patch::StillOurs(first, reinterpret_cast<void*>(&DetourFirst)));
CHECK(registry.LiveCount() == 0u); // and not left for a walk to report as somebody else's
CHECK(registry.Claim(first, first, "again") == -1);
MH_Uninitialize();
}
TEST_CASE("a patch that failed gives its slot back, and a slot is not seen by the walk until it is committed",
"[unhook][registry]") {
using fl::patch::InstallResult;
fl::patch::Registry<1> registry;
std::atomic<std::uint32_t> observing{1u};
int target = 0;
int detour = 0;
void* original = nullptr;
int created = 0;
CHECK(fl::patch::Install(registry, observing, FailingEngine{false, true, &created}, &target, &detour, &original,
"x") == InstallResult::CreateFailed);
CHECK(fl::patch::Install(registry, observing, FailingEngine{true, false, &created}, &target, &detour, &original,
"x") == InstallResult::EnableFailed);
CHECK(created == 2);
CHECK(registry.LiveCount() == 0u);
CHECK(fl::patch::Install(registry, observing, FailingEngine{true, true, &created}, nullptr, &detour, &original,
"x") == InstallResult::NoTarget);
CHECK(created == 2);
// Both failures gave the one slot back, so it can still be claimed -- and a claimed slot is nobody's yet.
const int slot = registry.Claim(&target, &detour, "x");
REQUIRE(slot == 0);
CHECK(registry.LiveCount() == 0u);
CHECK(registry.Claim(&target, &detour, "y") == -1);
CHECK(fl::patch::Install(registry, observing, FailingEngine{true, true, &created}, &target, &detour, &original,
"x") == InstallResult::Full);
CHECK(created == 2); // refused before the engine was asked for anything
registry.Commit(slot);
const void* seenTarget = nullptr;
const char* seenName = nullptr;
registry.ForEachLive([&seenTarget, &seenName](void* t, void*, const char* name) noexcept {
seenTarget = t;
seenName = name;
});
CHECK(seenTarget == &target);
CHECK(seenName != nullptr);
CHECK(registry.LiveCount() == 1u);
// Release is for a slot that was never committed: on a live one it changes nothing.
registry.Release(slot);
CHECK(registry.LiveCount() == 1u);
registry.Retire(slot);
CHECK(registry.LiveCount() == 0u);
registry.Commit(-1);
registry.Release(7);
registry.Retire(-3);
CHECK(registry.LiveCount() == 0u);
}