wiicompiled/runtime/src/guest_flat_memory.cpp

#include "guest_flat_memory.h"

#include <algorithm>
#include <atomic>
#include <chrono>
#include <cstdio>
#include <cstdlib>
#include <cstring>
#include <iomanip>
#include <iostream>
#include <mutex>
#include <sstream>
#include <stdexcept>
#include <unordered_map>

#include "memory.h"
#include "ppc_runtime.h"
#include "recomp_mod_loader.h"
#include "runtime_log.h"
#include "system_bridge.h"

#ifndef NOMINMAX
#define NOMINMAX
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <windows.h>

namespace GuestFlat {
namespace {

// Placeholder / view constants. Declared here so the build does not depend on
// the exact Windows SDK version that first shipped them.
constexpr DWORD kMemReplacePlaceholder = 0x00004000;
constexpr DWORD kMemReservePlaceholder = 0x00040000;
constexpr DWORD kMemPreservePlaceholder = 0x00000002;
constexpr size_t kAllocationGranularity = 0x10000;  // 64 KiB
constexpr size_t kHostPageSize = 0x1000;

using VirtualAlloc2Fn = PVOID(WINAPI*)(HANDLE, PVOID, SIZE_T, ULONG, ULONG, void*, ULONG);
using MapViewOfFile3Fn = PVOID(WINAPI*)(HANDLE, HANDLE, PVOID, ULONG64, SIZE_T, ULONG, ULONG, void*, ULONG);

VirtualAlloc2Fn g_virtualAlloc2 = nullptr;
MapViewOfFile3Fn g_mapViewOfFile3 = nullptr;

uint8_t* g_base = nullptr;
bool g_initialized = false;
std::vector<RegionRequest> g_activeRegions;
PVOID g_vectoredHandle = nullptr;

std::mutex& StateMutex() {
    static std::mutex mutex;
    return mutex;
}

struct SectionKey {
    Backing backing = Backing::Owned;
    uint32_t ownedBase = 0;

    bool operator==(const SectionKey& other) const {
        return backing == other.backing && ownedBase == other.ownedBase;
    }
};

struct SectionKeyHash {
    size_t operator()(const SectionKey& key) const {
        return (static_cast<size_t>(key.ownedBase) << 3) ^ static_cast<size_t>(key.backing);
    }
};

struct Section {
    HANDLE handle = nullptr;
    uint64_t size = 0;
    uint8_t* hostView = nullptr;
};

std::unordered_map<SectionKey, Section, SectionKeyHash>& Sections() {
    static std::unordered_map<SectionKey, Section, SectionKeyHash> sections;
    return sections;
}

struct MappedRegion {
    uint32_t guestBase = 0;
    uint64_t guestSize = 0;      // requested size (page-table authority)
    uint64_t mappedSize = 0;     // rounded to allocation granularity
    uint64_t sectionOffset = 0;
    uint8_t* hostView = nullptr; // section host view base
};

std::vector<MappedRegion>& MappedRegions() {
    static std::vector<MappedRegion> regions;
    return regions;
}

struct GuardedRange {
    uint32_t start = 0;
    uint32_t end = 0;
};

std::vector<GuardedRange>& ExecutableRanges() {
    static std::vector<GuardedRange> ranges;
    return ranges;
}

// 4 KiB guest pages currently PAGE_READONLY for the executable-write guard.
std::vector<uint8_t>& ExecutableProtectedPages() {
    static std::vector<uint8_t> pages(1u << 20, 0);  // 2^32 / 4 KiB
    return pages;
}

std::vector<GuardedRange>& DeferredRanges() {
    static std::vector<GuardedRange> ranges;
    return ranges;
}

std::atomic<uint32_t> g_countMmio{0};
std::atomic<uint32_t> g_countEfb{0};
std::atomic<uint32_t> g_countXGuard{0};
std::atomic<uint32_t> g_countUnmapped{0};
std::atomic<uint32_t> g_countUnmappedRegions{0};

// Full register dumps for the first few committed regions. The one-line record
// below is emitted for every region regardless; the dump is what the historical
// checked path produced for an unmapped access, and it stays useful only while
// the log is still readable - a pointer that walks a large stride would
// otherwise bury the run in 65536 dumps.
constexpr uint32_t kUnmappedCpuDumpLimit = 16;

uint64_t RoundUp(uint64_t value, uint64_t alignment) {
    return (value + alignment - 1u) & ~(alignment - 1u);
}

std::string LastErrorText(const char* what) {
    std::ostringstream oss;
    oss << what << " failed (GetLastError=" << GetLastError() << ")";
    return oss.str();
}

void ResolvePlacementApi() {
    if (g_virtualAlloc2 != nullptr && g_mapViewOfFile3 != nullptr) return;
    HMODULE kernelBase = GetModuleHandleW(L"kernelbase.dll");
    if (kernelBase == nullptr) kernelBase = LoadLibraryW(L"kernelbase.dll");
    if (kernelBase != nullptr) {
        g_virtualAlloc2 =
            reinterpret_cast<VirtualAlloc2Fn>(GetProcAddress(kernelBase, "VirtualAlloc2"));
        g_mapViewOfFile3 =
            reinterpret_cast<MapViewOfFile3Fn>(GetProcAddress(kernelBase, "MapViewOfFile3"));
    }
    if (g_virtualAlloc2 == nullptr || g_mapViewOfFile3 == nullptr) {
        throw std::runtime_error(
            "Flat guest memory requires Windows 10 1803 or newer (VirtualAlloc2/MapViewOfFile3 "
            "are unavailable on this system).");
    }
}

void EnsureReservation() {
    if (g_base != nullptr) return;
    ResolvePlacementApi();

    void* requested = reinterpret_cast<void*>(kFixedFlatGuestBase);

    // One extra granule stays an uncommitted placeholder so an access that
    // straddles 0xFFFFFFFF faults instead of corrupting whatever the allocator
    // happened to place directly after the reservation.
    void* reserved = g_virtualAlloc2(GetCurrentProcess(), requested,
                                     static_cast<SIZE_T>(kGuestSpaceSize + kAllocationGranularity),
                                     MEM_RESERVE | kMemReservePlaceholder, PAGE_NOACCESS,
                                     nullptr, 0);
    if (reserved == nullptr) {
        std::ostringstream oss;
        oss << "Unable to reserve the 4 GiB flat guest address space at 0x" << std::hex
            << reinterpret_cast<uintptr_t>(requested) << std::dec
            << " (GetLastError=" << GetLastError()
            << "). The translated code addresses guest memory through this fixed base, so it "
               "cannot fall back to another one. Something else in this process reserved the "
               "16 TiB region first - an injected DLL, an overlay or a debugging tool is the "
               "usual cause.";
        throw std::runtime_error(oss.str());
    }

    if (reserved != requested) {
        throw std::runtime_error(
            "The flat guest reservation did not land on the fixed base the translated code was "
            "compiled against.");
    }
    g_base = static_cast<uint8_t*>(reserved);
}

// Carves `size` bytes out of the enclosing placeholder so a view or a private
// commit can replace it. Splitting an exact-size placeholder is a no-op that
// reports ERROR_INVALID_PARAMETER; the caller validates the replacement.
void SplitPlaceholder(uint8_t* address, uint64_t size) {
    VirtualFree(address, static_cast<SIZE_T>(size), MEM_RELEASE | kMemPreservePlaceholder);
}

void MapGuestView(const Section& section, uint64_t sectionOffset, uint32_t guestBase,
                  uint64_t mappedSize) {
    uint8_t* target = g_base + guestBase;
    SplitPlaceholder(target, mappedSize);
    void* view = g_mapViewOfFile3(section.handle, GetCurrentProcess(), target, sectionOffset,
                                  static_cast<SIZE_T>(mappedSize), kMemReplacePlaceholder,
                                  PAGE_READWRITE, nullptr, 0);
    if (view == nullptr) {
        std::ostringstream oss;
        oss << "Unable to map guest region 0x" << std::hex << guestBase << " (+0x" << mappedSize
            << ") into the flat reservation" << std::dec << " (GetLastError=" << GetLastError()
            << ")";
        throw std::runtime_error(oss.str());
    }
}

// Replaces a placeholder with private committed memory. Used for the MMIO
// window (read-only zeros) and for on-demand commits of stray guest pages.
bool CommitPlaceholder(uint8_t* address, uint64_t size, DWORD protection) {
    SplitPlaceholder(address, size);
    void* result = g_virtualAlloc2(GetCurrentProcess(), address, static_cast<SIZE_T>(size),
                                   MEM_RESERVE | MEM_COMMIT | kMemReplacePlaceholder, protection,
                                   nullptr, 0);
    return result != nullptr;
}

// One definition of the two windows lives in memory_access.h; these are the
// names the fault handler below reads.
bool IsMmio(uint32_t address) { return MemoryInline::IsMmioAddress(address); }
bool IsGpuFifo(uint32_t address) { return MemoryInline::IsGpuFifoAddress(address); }

void ApplyExecutableProtectionLocked() {
    if (g_base == nullptr) return;
    auto& protectedPages = ExecutableProtectedPages();
    for (const auto& range : ExecutableRanges()) {
        // Only pages fully inside the range are protected: edge pages often share a page with data
        // (MKW's THP buffers do), so guarding them would fault legitimate stores; their writes still go through the checked path.
        const uint64_t first = RoundUp(range.start, kHostPageSize);
        const uint64_t last = static_cast<uint64_t>(range.end) & ~(kHostPageSize - 1u);
        if (last <= first) continue;
        for (uint64_t page = first; page < last; page += kHostPageSize) {
            const uint32_t pageIndex = static_cast<uint32_t>(page >> 12);
            if (protectedPages[pageIndex] != 0) continue;
            DWORD previous = 0;
            if (VirtualProtect(g_base + page, kHostPageSize, PAGE_READONLY, &previous) != FALSE) {
                protectedPages[pageIndex] = 1;
            }
        }
    }
}

bool SameLayout(const std::vector<RegionRequest>& lhs, const std::vector<RegionRequest>& rhs) {
    if (lhs.size() != rhs.size()) return false;
    for (size_t index = 0; index < lhs.size(); ++index) {
        if (lhs[index].base != rhs[index].base || lhs[index].size != rhs[index].size ||
            lhs[index].backing != rhs[index].backing) {
            return false;
        }
    }
    return true;
}

uint64_t SectionOffsetFor(const RegionRequest& region) {
    switch (region.backing) {
    case Backing::Mem1:
        return region.base & 0x01FFFFFFu;  // 32 MiB MEM1 window
    case Backing::Mem2:
        return region.base & 0x0FFFFFFFu;  // 256 MiB MEM2 window
    case Backing::Owned:
    default:
        return 0;
    }
}

SectionKey KeyFor(const RegionRequest& region) {
    SectionKey key;
    key.backing = region.backing;
    key.ownedBase = region.backing == Backing::Owned ? region.base : 0;
    return key;
}

void ZeroMappedStorage() {
    for (auto& [key, section] : Sections()) {
        (void)key;
        if (section.hostView != nullptr && section.size != 0) {
            std::memset(section.hostView, 0, static_cast<size_t>(section.size));
        }
    }
}

LONG CALLBACK FlatGuestVectoredHandler(EXCEPTION_POINTERS* info) {
    if (HandleAccessViolation(info)) {
        return EXCEPTION_CONTINUE_EXECUTION;
    }
    return EXCEPTION_CONTINUE_SEARCH;
}

void InstallVectoredHandler() {
    if (g_vectoredHandle != nullptr) return;
    g_vectoredHandle = AddVectoredExceptionHandler(1, FlatGuestVectoredHandler);
    if (g_vectoredHandle == nullptr) {
        throw std::runtime_error(LastErrorText("AddVectoredExceptionHandler"));
    }
}

void ReportFatalGuestFault(const char* category, uint32_t guestAddress, bool isWrite,
                           const char* detail) {
    RT_LOG(RT_TAG_MEMORY) << "FATAL " << category << std::endl;
    std::cerr << "  guest address: 0x" << std::hex << std::uppercase << std::setw(8)
              << std::setfill('0') << guestAddress << std::dec << std::setfill(' ') << std::endl;
    std::cerr << "  access:        " << (isWrite ? "write" : "read") << std::endl;
    // The fault record carries the faulting address but not the width of the
    // access, so the size is genuinely unavailable on this path. The checked
    // path (runtime/src/memory.cpp) reports the exact length instead.
    std::cerr << "  access size:   unknown (not recoverable from the fault record)" << std::endl;
    std::cerr << "  active func:   0x" << std::hex << std::uppercase
              << RecompMod::CurrentTranslatedExecutionAddress() << std::dec << std::nouppercase
              << std::endl;
    std::cerr << "  detail:        " << detail << std::endl;
    if (auto* cpu = TryGetCpuContext()) {
        std::cerr << "  guest pc:      0x" << std::hex << cpu->pc << " lr=0x" << cpu->lr << std::dec
                  << std::endl;
        SystemBridge::DumpCpuState(cpu);
    }
    std::cerr.flush();
    std::ostringstream message;
    message << "The game stopped because translated code performed a forbidden guest memory "
               "access at 0x"
            << std::hex << std::uppercase << guestAddress << ".\n\n"
            << detail;
    ShowRuntimeFatalPopup(category, message.str());
    std::abort();
}

// Logged once per newly committed 64 KiB block since a silent commit would hide a wild guest pointer bug.
// Called with StateMutex() released so the register dump (which reads guest memory) can't deadlock against it.
void ReportUnmappedCommit(uint32_t guestAddress, uint64_t blockBase, bool isWrite,
                          uint32_t regionOrdinal) {
    RT_LOG(RT_TAG_MEMORY) << "WARNING unmapped guest touch: no mapped region for 0x" << std::hex
              << std::uppercase << std::setw(8) << std::setfill('0') << guestAddress
              << std::setfill(' ') << " (" << (isWrite ? "write" : "read")
              << "); committed zero-filled block 0x" << blockBase << "-0x"
              << (blockBase + kAllocationGranularity) << " active=0x"
              << RecompMod::CurrentTranslatedExecutionAddress();
    if (auto* cpu = TryGetCpuContext()) {
        std::cerr << " pc=0x" << cpu->pc << " lr=0x" << cpu->lr << " r1=0x" << cpu->gpr[1];
    }
    std::cerr << std::dec << std::nouppercase << " region#" << regionOrdinal << std::endl;

    if (regionOrdinal <= kUnmappedCpuDumpLimit) {
        if (auto* cpu = TryGetCpuContext()) {
            RT_LOG(RT_TAG_MEMORY) << "===== DUMPING CPU STATE (unmapped touch) =====" << std::endl;
            SystemBridge::DumpCpuState(cpu);
        }
        if (regionOrdinal == kUnmappedCpuDumpLimit) {
            RT_LOG(RT_TAG_MEMORY) << "further unmapped commits log the one-line record only; the "
                         "shutdown summary reports the totals."
                      << std::endl;
        }
    }
    std::cerr.flush();
}

} // namespace

bool IsActive() {
    return g_initialized;
}

void Initialize(const std::vector<RegionRequest>& regions) {
    std::lock_guard<std::mutex> lock(StateMutex());

    if (g_initialized) {
        if (!SameLayout(g_activeRegions, regions)) {
            throw std::runtime_error(
                "The flat guest address space is mapped once per process; a second Memory::Init "
                "requested a different region layout. Restart the process instead of remapping.");
        }
        // Re-init keeps the mapping and restores the pristine interception
        // state: deferred ranges are gone, executable pages stay protected.
        for (const auto& range : DeferredRanges()) {
            const uint64_t first = static_cast<uint64_t>(range.start) & ~(kHostPageSize - 1u);
            const uint64_t last = RoundUp(range.end, kHostPageSize);
            DWORD previous = 0;
            VirtualProtect(g_base + first, static_cast<SIZE_T>(last - first), PAGE_READWRITE,
                           &previous);
        }
        DeferredRanges().clear();
        ZeroMappedStorage();
        ApplyExecutableProtectionLocked();
        return;
    }

    EnsureReservation();

    // Size every section from the highest byte any of its regions reaches.
    std::unordered_map<SectionKey, uint64_t, SectionKeyHash> sizes;
    for (const auto& region : regions) {
        if (region.size == 0) continue;
        if ((region.base % kAllocationGranularity) != 0) {
            std::ostringstream oss;
            oss << "Guest region base 0x" << std::hex << region.base
                << " is not 64 KiB aligned; the flat mapping cannot place it.";
            throw std::runtime_error(oss.str());
        }
        const uint64_t end = SectionOffsetFor(region) + region.size;
        auto& current = sizes[KeyFor(region)];
        current = std::max(current, end);
    }

    for (auto& [key, size] : sizes) {
        const uint64_t rounded = RoundUp(size, kAllocationGranularity);
        Section section;
        section.size = rounded;
        section.handle = CreateFileMappingW(INVALID_HANDLE_VALUE, nullptr, PAGE_READWRITE,
                                            static_cast<DWORD>(rounded >> 32),
                                            static_cast<DWORD>(rounded & 0xFFFFFFFFu), nullptr);
        if (section.handle == nullptr) {
            throw std::runtime_error(LastErrorText("CreateFileMapping for guest RAM"));
        }
        section.hostView = static_cast<uint8_t*>(
            MapViewOfFile(section.handle, FILE_MAP_ALL_ACCESS, 0, 0, static_cast<SIZE_T>(rounded)));
        if (section.hostView == nullptr) {
            throw std::runtime_error(LastErrorText("MapViewOfFile for the host guest-RAM alias"));
        }
        Sections()[key] = section;
    }

    for (const auto& region : regions) {
        if (region.size == 0) continue;
        const auto& section = Sections()[KeyFor(region)];
        const uint64_t offset = SectionOffsetFor(region);
        const uint64_t mappedSize =
            std::min<uint64_t>(RoundUp(region.size, kAllocationGranularity), section.size - offset);
        MapGuestView(section, offset, region.base, mappedSize);
        MappedRegions().push_back(
            MappedRegion{region.base, region.size, mappedSize, offset, section.hostView});
    }

    // MMIO stays inaccessible in both directions so the vectored handler can report missing HLE; the old
    // PAGE_READONLY read window that returned zero turned missing devices into silent hangs instead.
    if (!CommitPlaceholder(g_base + 0xCC000000u, 0x02000000u, PAGE_NOACCESS)) {
        throw std::runtime_error(LastErrorText("committing the no-access MMIO window"));
    }

    ApplyExecutableProtectionLocked();
    InstallVectoredHandler();

    // Freshly created section objects are demand-zero, so no explicit clear is
    // needed on the first mapping (that would fault in all 152 MiB at startup).
    g_activeRegions = regions;
    g_initialized = true;

    RT_LOG(RT_TAG_MEMORY) << "guest address space reserved at 0x" << std::hex
              << reinterpret_cast<uintptr_t>(g_base) << std::dec << " (" << MappedRegions().size()
              << " regions, " << Sections().size() << " backing stores)" << std::endl;
}

uint8_t* HostPointer(uint32_t guestAddress) {
    if (!g_initialized) return nullptr;
    for (const auto& region : MappedRegions()) {
        if (guestAddress < region.guestBase) continue;
        const uint64_t offset = static_cast<uint64_t>(guestAddress) - region.guestBase;
        if (offset >= region.guestSize) continue;
        return region.hostView + region.sectionOffset + offset;
    }
    return nullptr;
}

void ProtectDeferredRange(uint32_t address, size_t length) {
    if (!g_initialized || length == 0) return;
    const uint64_t end = static_cast<uint64_t>(address) + length;
    if (end > kGuestSpaceSize) return;
    std::lock_guard<std::mutex> lock(StateMutex());
    const uint64_t first = static_cast<uint64_t>(address) & ~(kHostPageSize - 1u);
    const uint64_t last = RoundUp(end, kHostPageSize);
    DWORD previous = 0;
    if (VirtualProtect(g_base + first, static_cast<SIZE_T>(last - first), PAGE_NOACCESS,
                       &previous) == FALSE) {
        // An unmapped destination cannot be trapped; the checked path still
        // clears the readable bias, so nothing silently reads stale bytes.
        return;
    }
    DeferredRanges().push_back(GuardedRange{address, static_cast<uint32_t>(end)});
}

void UnprotectDeferredRange(uint32_t address, size_t length) {
    if (!g_initialized || length == 0) return;
    std::lock_guard<std::mutex> lock(StateMutex());
    auto& ranges = DeferredRanges();
    const uint64_t end = static_cast<uint64_t>(address) + length;
    const auto it = std::find_if(ranges.begin(), ranges.end(), [&](const GuardedRange& range) {
        return range.start == address && range.end == static_cast<uint32_t>(end);
    });
    if (it == ranges.end()) return;
    ranges.erase(it);
    const uint64_t first = static_cast<uint64_t>(address) & ~(kHostPageSize - 1u);
    const uint64_t last = RoundUp(end, kHostPageSize);
    DWORD previous = 0;
    VirtualProtect(g_base + first, static_cast<SIZE_T>(last - first), PAGE_READWRITE, &previous);
}

void RegisterExecutableRange(uint32_t start, uint32_t end) {
    if (end <= start) return;
    std::lock_guard<std::mutex> lock(StateMutex());
    auto& ranges = ExecutableRanges();
    if (std::any_of(ranges.begin(), ranges.end(), [&](const GuardedRange& range) {
            return range.start == start && range.end == end;
        })) {
        return;
    }
    ranges.push_back(GuardedRange{start, end});
    ApplyExecutableProtectionLocked();
}

FaultCounters Counters() {
    FaultCounters counters;
    counters.mmio = g_countMmio.load(std::memory_order_relaxed);
    counters.efb = g_countEfb.load(std::memory_order_relaxed);
    counters.xguard = g_countXGuard.load(std::memory_order_relaxed);
    counters.unmapped = g_countUnmapped.load(std::memory_order_relaxed);
    counters.unmappedRegions = g_countUnmappedRegions.load(std::memory_order_relaxed);
    return counters;
}

void LogFaultSummary() noexcept {
    static std::atomic<bool> reported{false};
    if (reported.exchange(true, std::memory_order_relaxed)) return;
    const FaultCounters counters = Counters();
    if (counters.unmapped == 0) {
        RT_LOG(RT_TAG_MEMORY) << "shutdown summary: no unmapped guest touches (efb="
                  << counters.efb << " xguard=" << counters.xguard << " mmio=" << counters.mmio
                  << ")" << std::endl;
        std::cerr.flush();
        return;
    }
    RT_LOG(RT_TAG_MEMORY) << "WARNING shutdown summary: " << counters.unmapped
              << " unmapped guest touches across " << counters.unmappedRegions
              << " distinct 64 KiB regions were absorbed by on-demand commits. Each one is a "
                 "guest pointer that addressed nothing; search the log for "
                 "'[" RT_TAG_MEMORY "] WARNING unmapped guest touch' for the faulting addresses."
              << std::endl;
    RT_LOG(RT_TAG_MEMORY) << "shutdown summary: efb=" << counters.efb
              << " xguard=" << counters.xguard << " mmio=" << counters.mmio << std::endl;
    std::cerr.flush();
}

bool HandleAccessViolation(void* exceptionPointers) noexcept {
    if (!g_initialized || exceptionPointers == nullptr) return false;
    auto* info = static_cast<EXCEPTION_POINTERS*>(exceptionPointers);
    const auto* record = info->ExceptionRecord;
    if (record == nullptr || record->ExceptionCode != EXCEPTION_ACCESS_VIOLATION ||
        record->NumberParameters < 2) {
        return false;
    }

    const uintptr_t fault = static_cast<uintptr_t>(record->ExceptionInformation[1]);
    const uintptr_t base = reinterpret_cast<uintptr_t>(g_base);
    if (fault < base || fault - base >= kGuestSpaceSize) return false;

    const uint32_t guestAddress = static_cast<uint32_t>(fault - base);
    const bool isWrite = record->ExceptionInformation[0] != 0;

    // 1) Deferred (EFB) read: materialize the pending copy and drop the trap for the whole 4 KiB page span,
    //    not just the registered range, since protection is page-granular. Leaving a range registered but
    //    unprotected would serve stale bytes without ever faulting again.
    {
        bool covered = false;
        uint32_t rangeStart = 0;
        uint32_t rangeEnd = 0;
        uint64_t spanFirst = 0;
        uint64_t spanLast = 0;
        {
            std::lock_guard<std::mutex> lock(StateMutex());
            auto& ranges = DeferredRanges();
            const auto it = std::find_if(ranges.begin(), ranges.end(), [&](const GuardedRange& r) {
                const uint64_t first = static_cast<uint64_t>(r.start) & ~(kHostPageSize - 1u);
                const uint64_t last = RoundUp(r.end, kHostPageSize);
                return guestAddress >= first && guestAddress < last;
            });
            if (it != ranges.end()) {
                covered = true;
                rangeStart = it->start;
                rangeEnd = it->end;
                ranges.erase(it);
                spanFirst = static_cast<uint64_t>(rangeStart) & ~(kHostPageSize - 1u);
                spanLast = RoundUp(rangeEnd, kHostPageSize);
                DWORD previous = 0;
                VirtualProtect(g_base + spanFirst, static_cast<SIZE_T>(spanLast - spanFirst),
                               PAGE_READWRITE, &previous);
            }
        }
        if (covered) {
            g_countEfb.fetch_add(1, std::memory_order_relaxed);
            try {
                MemoryInline::ResolveDeferredReads(
                    static_cast<uint32_t>(spanFirst), static_cast<size_t>(spanLast - spanFirst));
            } catch (const std::exception& error) {
                ReportFatalGuestFault("deferred read materialization failed", guestAddress, isWrite,
                                      error.what());
            }
            return true;
        }
    }

    // 2) Executable-write guard. Only writes trap (the pages are PAGE_READONLY),
    //    so a fault here is exactly the event the guard exists to report.
    {
        const uint32_t pageIndex = guestAddress >> 12;
        bool guarded = false;
        {
            std::lock_guard<std::mutex> lock(StateMutex());
            guarded = ExecutableProtectedPages()[pageIndex] != 0;
        }
        if (guarded) {
            g_countXGuard.fetch_add(1, std::memory_order_relaxed);
            // Aborts inside CheckExecutableWrite for an unsupported patch; the
            // width and value are not recoverable from the fault record, so the
            // report carries the exact address instead.
            if (!RecompMod::HandleExecutableWrite(guestAddress, 1, 0)) {
                // A permitted write (the REL loader relocating its own text).
                // Those arrive in bulk, so the page is opened permanently
                // rather than trapping every relocation.
                std::lock_guard<std::mutex> lock(StateMutex());
                DWORD previous = 0;
                if (VirtualProtect(g_base + (static_cast<uint64_t>(pageIndex) << 12), kHostPageSize,
                                   PAGE_READWRITE, &previous) != FALSE) {
                    ExecutableProtectedPages()[pageIndex] = 0;
                }
            }
            return true;
        }
    }

    // 3) MMIO. PAGE_NOACCESS makes both directions faults: a write has no backing device (including a GPU
    //    FIFO store the translator failed to lower), and a read would have to invent a register value;
    //    answering zero would turn a missing device into a silent hang, so both are reported instead.
    if (IsMmio(guestAddress)) {
        g_countMmio.fetch_add(1, std::memory_order_relaxed);
        if (IsGpuFifo(guestAddress)) {
            if (isWrite) {
                ReportFatalGuestFault(
                    "GPU FIFO write reached the flat memory path", guestAddress, isWrite,
                    "Gather-pipe stores must be lowered to GX_HLE_FIFO_Write*; the written value "
                    "cannot be recovered from a fault. Fix the translator lowering for this "
                    "store.");
            }
            ReportFatalGuestFault(
                "GPU FIFO read blocked", guestAddress, isWrite,
                "The gather pipe is write-only; nothing can be read back from it. The guest code "
                "that issued this load needs GX HLE, not a memory access.");
        }
        if (isWrite) {
            ReportFatalGuestFault("MMIO write blocked (non-GPU)", guestAddress, isWrite,
                                  "Hardware registers have no backing store. Add HLE for this "
                                  "device instead of letting the write land.");
        }
        ReportFatalGuestFault("MMIO read blocked (non-GPU)", guestAddress, isWrite,
                              "Hardware registers have no backing store. Answering zero would "
                              "hang the caller in a status poll instead of reporting the gap; "
                              "add HLE for this device.");
        return true;
    }

    // 4) Unmapped address: commit the block on demand (reproducing the old zero-fill sparse-map behavior)
    //    and report it, since a commit here means a wild guest pointer that would otherwise walk over silently.
    const uint64_t blockBase = static_cast<uint64_t>(guestAddress) & ~(kAllocationGranularity - 1u);
    g_countUnmapped.fetch_add(1, std::memory_order_relaxed);
    bool committed = false;
    {
        std::lock_guard<std::mutex> lock(StateMutex());
        MEMORY_BASIC_INFORMATION mbi{};
        if (VirtualQuery(g_base + blockBase, &mbi, sizeof(mbi)) == 0) return false;
        if (mbi.State == MEM_COMMIT) {
            // Another thread already committed this block: re-running the
            // access succeeds. Any other committed-but-inaccessible state is
            // not ours to fix - resuming would fault forever, so hand the
            // exception to the crash reporter instead.
            const bool writable = (mbi.Protect & (PAGE_READWRITE | PAGE_WRITECOPY |
                                                  PAGE_EXECUTE_READWRITE | PAGE_EXECUTE_WRITECOPY)) != 0;
            const bool readable = writable || (mbi.Protect & (PAGE_READONLY | PAGE_EXECUTE_READ |
                                                              PAGE_EXECUTE)) != 0;
            return isWrite ? writable : readable;
        }
        if (!CommitPlaceholder(g_base + blockBase, kAllocationGranularity, PAGE_READWRITE)) {
            return false;
        }
        committed = true;
    }
    if (committed) {
        const uint32_t ordinal = g_countUnmappedRegions.fetch_add(1, std::memory_order_relaxed) + 1u;
        ReportUnmappedCommit(guestAddress, blockBase, isWrite, ordinal);
    }
    return true;
}

} // namespace GuestFlat