From 06d70d0dfafb7a8a684877d0f5854f62c0930fce Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 08:19:31 +0300 Subject: [PATCH 01/16] Report host registers, code bytes and memory at a crash The crash report named the lifted function and printed the guest registers, but the lifted code keeps guest registers in host locals and writes them back only at calls, so the dump showed stale values and the faulting instruction stayed unknown. Logs from #1005, #967 and #998 could not be traced further than the function. The report now adds the x86 registers of the faulting thread (Windows and Linux), 64 bytes of machine code around rip with the offset into the lifted function, so the instruction can be found in a local build of the same version, 64 bytes of memory around every register value that points at readable memory, and the first 128 bytes of the guest stack. --probe-kernel checks the new lines with a child that faults with known values in rbx and x19. Co-Authored-By: Claude Opus 5.5 --- runtime/kernel_probe.c | 48 ++++++++++++++++++++ runtime/main.c | 88 ++++++++++++++++++++++++++++++++++--- runtime/platform/linux.c | 4 ++ runtime/platform/platform.h | 4 ++ runtime/platform/win32.c | 10 +++++ 5 files changed, 149 insertions(+), 5 deletions(-) diff --git a/runtime/kernel_probe.c b/runtime/kernel_probe.c index 191a1c28..6ee32e2b 100644 --- a/runtime/kernel_probe.c +++ b/runtime/kernel_probe.c @@ -719,6 +719,47 @@ static void test_platform(void) { CHECK(over[N / 2] < 500000, "plat_sleep_ns(1 ms) median overshoot %.3f ms (want < 0.5)", over[N / 2] / 1e6); } +// ---- crash report (main.c crash_handler): a child faults on a guest thread with known values in rbx and x19; the +// report must hold the host registers, the faulting instruction's bytes and the memory both values point at. +#define CRASH_CHILD_ENV "TOTK_PROBE_KERNEL_CRASH_CHILD" +static uint64_t crash_host_words[6] = {0, 0, 0x5ca1ab1e0c0de001ull, 0, 0, 0}; +static uint64_t crash_guest_words[6] = {0, 0, 0x5ca1ab1e0c0de002ull, 0, 0, 0}; + +static void crash_child_main(Cpu *c) { + c->x[19] = (uint64_t)(uintptr_t)&crash_guest_words[2]; + c->sp -= 0x100; // a frame on the guest stack, as a crashing function has + __asm__ volatile("movq %0, %%rbx\n\tmovq 0x10, %%rax" : : "r"(&crash_host_words[2]) : "rax", "rbx", "memory"); +} + +// The report line that holds needle, NULL when none does +static const char *report_line(const char *out, const char *needle, char *line, size_t cap) { + const char *p = strstr(out, needle); + if (!p) return NULL; + while (p > out && p[-1] != '\n') p--; + size_t n = strcspn(p, "\r\n"); + snprintf(line, cap, "%.*s", (int)(n < cap ? n : cap - 1), p); + return line; +} + +static void test_crash_report(void) { + static char out[65536]; + char line[512], want[64]; + int code = plat_run_self(CRASH_CHILD_ENV, "1", out, sizeof out, 30000); + CHECK(code == 71 && strstr(out, "FATAL: access violation") && strstr(out, "reading address 0x10"), + "crash child: exit code %d, no access violation at 0x10 reported", code); + snprintf(want, sizeof want, "rbx %016llx", (unsigned long long)(uintptr_t)&crash_host_words[2]); + CHECK(strstr(out, want), "crash report: no host register line with %s", want); + CHECK(report_line(out, "host code at rip-", line, sizeof line) && strstr(line, "| 48 8b 04 25 10 00 00 00"), + "crash report: the faulting instruction's bytes are missing"); + const char *h = report_line(out, "*5ca1ab1e0c0de001", line, sizeof line); + CHECK(h && strstr(h, "rbx"), "crash report: no memory line for rbx (%s)", h ? h : "none"); + const char *g = report_line(out, "*5ca1ab1e0c0de002", line, sizeof line); + CHECK(g && strstr(g, "x19"), "crash report: no memory line for x19 (%s)", g ? g : "none"); + CHECK(strstr(out, "guest stack sp+0x00:"), "crash report: no guest stack words"); + printf("crash report: exit code %d, host registers, code bytes, memory at rbx and x19, guest stack %s\n", code, + failures ? "checked with failures" : "present"); +} + int probe_kernel(void) { a_lock_waiter = hostfn_register("probe-kernel lock waiter", lock_waiter); a_cv_waiter = hostfn_register("probe-kernel condvar waiter", cv_waiter); @@ -742,7 +783,14 @@ int probe_kernel(void) { printf("probe-kernel: FAILED (no PLT stub for %s in main)\n", TICK_SYMBOL); return 1; } + const char *child = getenv(CRASH_CHILD_ENV); + if (child && *child) { + kern_run_on_guest_main(crash_child_main); + printf("crash child: returned without a fault\n"); + return 1; + } test_platform(); + test_crash_report(); kern_run_on_guest_main(probe_main); RtStats s = rt_stats(); printf("stats: %llu SVCs, %llu threads, %llu host calls\n", (unsigned long long)s.svcs, diff --git a/runtime/main.c b/runtime/main.c index cba26ccf..b8ff1132 100644 --- a/runtime/main.c +++ b/runtime/main.c @@ -21,7 +21,8 @@ // // Also here: the runtime services the generated code calls besides rt_dispatch and rt_svc (rt_brk, rt_udf, // rt_ticks, the function profiler hook), logging, SHA-256, and the crash reporter (a vectored exception handler that -// names the lifted function, the guest registers and the guest frame-pointer chain). +// names the lifted function, the host and guest registers, the machine code around the fault, the guest frame-pointer +// chain and the memory the registers point at). #include #include #include @@ -188,8 +189,8 @@ static int by_host(const void *a, const void *b) { } // The lifted function that contains a host code address, by the nearest function start below it; 0 outside the lifted -// code. -static uint64_t lifted_function(uintptr_t rip) { +// code. *host, when given, gets the function's host start. +static uint64_t lifted_function_at(uintptr_t rip, uintptr_t *host) { if (!fn_rev) { static RtModule mods[MAX_MODULES]; int n = rt_linked_modules(mods, MAX_MODULES); @@ -211,11 +212,78 @@ static uint64_t lifted_function(uintptr_t rip) { if (fn_rev[mid].host <= rip) lo = mid + 1; else hi = mid; } + if (lo && host) *host = fn_rev[lo - 1].host; return lo ? fn_rev[lo - 1].guest : 0; } +static uint64_t lifted_function(uintptr_t rip) { return lifted_function_at(rip, NULL); } + static int readable(uint64_t a, uint64_t n) { return plat_mem_readable(a, n); } +// The machine code around the faulting instruction: 32 bytes before rip, then 32 from rip. The user's totk.exe is built +// on their machine, so its offsets need not match ours; these bytes and the offset into the lifted function find the +// same instruction in a local build of that version, and with it the guest instruction and the operands' registers. +static void crash_code_bytes(uintptr_t rip) { + uint8_t b[64]; + int before = 32; + if (!plat_mem_read(rip - 32, b, sizeof b)) { + before = 0; // rip near the start of a mapping: the bytes from rip only + if (!plat_mem_read(rip, b + 32, 32)) return; + } + rt_logf(" host code at rip-%d:", before); + for (int i = 32 - before; i < 64; i++) rt_logf("%s%02x", i == 32 ? " | " : " ", b[i]); + rt_log_raw("\n", 1); +} + +// 64 bytes around each register value that points at readable memory, as 8-byte words from 16 bytes below the value, +// the word holding the value marked with *. Host and guest registers that land on the same window share a line. A +// guest pointer is a host address here (the guest address space is mapped one to one), so both kinds are read alike. +// The guest registers come from the Cpu, which the lifted code writes back only at calls and returns, so the host +// registers carry the faulting function's live values. +typedef struct { uint64_t start; char names[56]; uint64_t w[8]; } CrashWin; + +static void crash_win_add(CrashWin *wins, int *n, int cap, const char *name, uint64_t v) { + if (v < 0x10000 || v > 0x00007fffffffffffull) return; // small integers and non-canonical values + uint64_t start = (v & ~7ull) - 16; + for (int i = 0; i < *n; i++) + if (wins[i].start == start) { + size_t len = strlen(wins[i].names); + if (len + strlen(name) + 2 < sizeof wins[i].names) + snprintf(wins[i].names + len, sizeof wins[i].names - len, " %s", name); + return; + } + if (*n == cap || !plat_mem_read(start, wins[*n].w, sizeof wins[*n].w)) return; + wins[*n].start = start; + snprintf(wins[*n].names, sizeof wins[*n].names, "%s", name); + (*n)++; +} + +static void crash_memory(const PlatCrash *x, const Cpu *c) { + static CrashWin wins[64]; // the crash handler runs once (busy flag), so static storage needs no allocation + static const char *const gpr_names[16] = PLAT_GPR_NAMES; + int n = 0; + char name[8]; + if (x->has_regs) + for (int i = 0; i < 16; i++) crash_win_add(wins, &n, 64, gpr_names[i], x->gpr[i]); + if (c) { + for (int i = 0; i < 31; i++) snprintf(name, sizeof name, "x%d", i), crash_win_add(wins, &n, 64, name, c->x[i]); + crash_win_add(wins, &n, 64, "sp", c->sp); + } + if (!n) return; + rt_logf(" memory at the register values (8-byte words from value-16, * the value's word):\n"); + for (int i = 0; i < n; i++) { + rt_logf(" %016llx %-12s", (unsigned long long)wins[i].start, wins[i].names); + for (int k = 0; k < 8; k++) rt_logf(" %s%016llx", k == 2 ? "*" : "", (unsigned long long)wins[i].w[k]); + rt_log_raw("\n", 1); + } + // The guest stack above sp: the crashing function's spills and locals, and the callers' saved registers + uint64_t s[16]; + if (c && plat_mem_read(c->sp, s, sizeof s)) + for (int i = 0; i < 16; i += 4) + rt_logf(" guest stack sp+0x%02x: %016llx %016llx %016llx %016llx\n", i * 8, (unsigned long long)s[i], + (unsigned long long)s[i + 1], (unsigned long long)s[i + 2], (unsigned long long)s[i + 3]); +} + static void crash_handler(const PlatCrash *x) { static volatile int32_t busy; if (plat_xchg32(&busy, 1)) plat_exit(71); @@ -230,8 +298,17 @@ static void crash_handler(const PlatCrash *x) { rt_log_raw("\n", 1); if (x->cxx_type) rt_logf(" C++ type %s%s%s\n", x->cxx_type, x->cxx_what ? ", what(): " : "", x->cxx_what ? x->cxx_what : ""); - uint64_t f = x->module ? 0 : lifted_function(rip); - if (f) rt_logf(" in lifted function f_%llx = %s\n", (unsigned long long)f, ldr_describe(f, d, sizeof d)); + uintptr_t fstart = 0; + uint64_t f = x->module ? 0 : lifted_function_at(rip, &fstart); + if (f) + rt_logf(" in lifted function f_%llx = %s, host +%#llx into it\n", (unsigned long long)f, + ldr_describe(f, d, sizeof d), (unsigned long long)(rip - fstart)); + if (x->has_regs) { + static const char *const gpr_names[16] = PLAT_GPR_NAMES; + for (int i = 0; i < 16; i++) + rt_logf(" %-3s %016llx%s", gpr_names[i], (unsigned long long)x->gpr[i], i % 4 == 3 ? "\n" : ""); + crash_code_bytes(rip); + } // abort and invalid parameter: where the host code called it; a fault in another module: the driver code and the // host calls that led into it uintptr_t exe = plat_exe_base(); @@ -266,6 +343,7 @@ static void crash_handler(const PlatCrash *x) { } else { rt_logf(" not on a guest thread\n"); } + crash_memory(x, c); kern_free_cores_note(); fflush(stderr); plat_exit(71); diff --git a/runtime/platform/linux.c b/runtime/platform/linux.c index fcb88d77..24512abb 100644 --- a/runtime/platform/linux.c +++ b/runtime/platform/linux.c @@ -957,6 +957,10 @@ static void fault_handler(int sig, siginfo_t *si, void *uc) { } if (sig == SIGSEGV || sig == SIGBUS) c.access = (err & 16) ? 8 : (err & 2) ? 1 : 0, c.addr = (uint64_t)(uintptr_t)si->si_addr; + static const int gr[16] = {REG_RAX, REG_RCX, REG_RDX, REG_RBX, REG_RSP, REG_RBP, REG_RSI, REG_RDI, + REG_R8, REG_R9, REG_R10, REG_R11, REG_R12, REG_R13, REG_R14, REG_R15}; + for (int i = 0; i < 16; i++) c.gpr[i] = (uint64_t)u->uc_mcontext.gregs[gr[i]]; + c.has_regs = 1; crash_fn(&c); } signal(sig, SIG_DFL); // returns into the faulting instruction, which faults again with the default action diff --git a/runtime/platform/platform.h b/runtime/platform/platform.h index 78873ced..0ddeaa78 100644 --- a/runtime/platform/platform.h +++ b/runtime/platform/platform.h @@ -249,7 +249,11 @@ typedef struct { const char *module; // the module holding rip: NULL for this executable, "" for none (a jump to address 0) const char *cxx_type; // a C++ exception from MSVC-built code: the thrown type's decorated name (.?AV...@@) const char *cxx_what; // and what() when the type derives from std::exception; NULL when unknown + int has_regs; // gpr holds the faulting thread's registers (a fault; not abort or invalid parameter) + uint64_t gpr[16]; // rax rcx rdx rbx rsp rbp rsi rdi r8..r15, in the x86 encoding order } PlatCrash; +#define PLAT_GPR_NAMES {"rax", "rcx", "rdx", "rbx", "rsp", "rbp", "rsi", "rdi", \ + "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15"} void plat_crash_hook(void (*fn)(const PlatCrash *c)); int plat_mem_read(uint64_t addr, void *out, size_t n); // copies n bytes, 0 instead of faulting on unmapped memory int plat_screen_size(int *w, int *h); // the primary display's current mode in pixels; 0 unknown diff --git a/runtime/platform/win32.c b/runtime/platform/win32.c index 83518517..e753b313 100644 --- a/runtime/platform/win32.c +++ b/runtime/platform/win32.c @@ -736,6 +736,14 @@ void plat_mem_fault_hook(int (*fn)(uint64_t addr)) { static void (*crash_fn)(const PlatCrash *c); +// The faulting thread's general registers, for the report to tie the faulting instruction to its operands. +static void regs_of(const CONTEXT *x, PlatCrash *c) { + const DWORD64 r[16] = {x->Rax, x->Rcx, x->Rdx, x->Rbx, x->Rsp, x->Rbp, x->Rsi, x->Rdi, + x->R8, x->R9, x->R10, x->R11, x->R12, x->R13, x->R14, x->R15}; + for (int i = 0; i < 16; i++) c->gpr[i] = r[i]; + c->has_regs = 1; +} + static LONG WINAPI crash_filter(EXCEPTION_POINTERS *ep); static LONG CALLBACK crash_veh(EXCEPTION_POINTERS *ep) { @@ -758,6 +766,7 @@ static LONG CALLBACK crash_veh(EXCEPTION_POINTERS *ep) { PlatCrash c = {what, (uint32_t)code, rip, rip - (uintptr_t)mi.lpBaseOfDll, -1, 0}; if (code == EXCEPTION_ACCESS_VIOLATION && ep->ExceptionRecord->NumberParameters >= 2) c.access = (int)ep->ExceptionRecord->ExceptionInformation[0], c.addr = ep->ExceptionRecord->ExceptionInformation[1]; + regs_of(ep->ContextRecord, &c); crash_fn(&c); return EXCEPTION_CONTINUE_SEARCH; } @@ -895,6 +904,7 @@ static LONG WINAPI crash_filter(EXCEPTION_POINTERS *ep) { (uint32_t)code, rip, 0, -1, 0}; if (code == EXCEPTION_ACCESS_VIOLATION && er->NumberParameters >= 2) c.access = (int)er->ExceptionInformation[0], c.addr = er->ExceptionInformation[1]; + regs_of(ep->ContextRecord, &c); void *base = NULL; RtlPcToFileHeader((void *)rip, &base); uintptr_t exe = (uintptr_t)GetModuleHandleW(NULL); From 6e9ca1ebfd1332cb5ab7c0db28322e05977fa849 Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 08:53:57 +0300 Subject: [PATCH 02/16] Log the process commit in crash reports and in the memory census A driver that runs out of memory faults or throws std::bad_alloc instead of returning an error: #285's log shows bad_alloc inside amdvlk64.dll under gpl_link, and nothing in the report told that apart from a driver bug. The crash report now prints the process and system commit, as rt_fatal does for our own failed allocations; --probe-kernel checks the line. The census at frames 600 and 1800 logs the commit as a baseline and, per heap, VMA's blocks and allocations beside the driver's usage and budget, so a report shows whose memory grew. Co-Authored-By: Claude Opus 5.5 --- runtime/kernel_probe.c | 4 +++- runtime/main.c | 5 +++++ runtime/vk_memory.c | 17 +++++++++++++++++ 3 files changed, 25 insertions(+), 1 deletion(-) diff --git a/runtime/kernel_probe.c b/runtime/kernel_probe.c index 6ee32e2b..cbbc9297 100644 --- a/runtime/kernel_probe.c +++ b/runtime/kernel_probe.c @@ -756,7 +756,9 @@ static void test_crash_report(void) { const char *g = report_line(out, "*5ca1ab1e0c0de002", line, sizeof line); CHECK(g && strstr(g, "x19"), "crash report: no memory line for x19 (%s)", g ? g : "none"); CHECK(strstr(out, "guest stack sp+0x00:"), "crash report: no guest stack words"); - printf("crash report: exit code %d, host registers, code bytes, memory at rbx and x19, guest stack %s\n", code, + CHECK(report_line(out, " memory commit: this process ", line, sizeof line) && !strstr(line, "process -1 MB"), + "crash report: no memory commit line"); + printf("crash report: exit code %d, host registers, code bytes, memory at rbx and x19, guest stack, commit %s\n", code, failures ? "checked with failures" : "present"); } diff --git a/runtime/main.c b/runtime/main.c index b8ff1132..a0e05c80 100644 --- a/runtime/main.c +++ b/runtime/main.c @@ -298,6 +298,11 @@ static void crash_handler(const PlatCrash *x) { rt_log_raw("\n", 1); if (x->cxx_type) rt_logf(" C++ type %s%s%s\n", x->cxx_type, x->cxx_what ? ", what(): " : "", x->cxx_what ? x->cxx_what : ""); + // A driver that runs out of memory faults or throws (std::bad_alloc) instead of returning an error: the commit + // tells that apart from a driver bug, as rt_fatal's line does for our own failed allocations. + double proc, used, limit; + plat_commit_info(&proc, &used, &limit); + rt_logf(" memory commit: this process %.0f MB, the system %.0f of %.0f MB\n", proc, used, limit); uintptr_t fstart = 0; uint64_t f = x->module ? 0 : lifted_function_at(rip, &fstart); if (f) diff --git a/runtime/vk_memory.c b/runtime/vk_memory.c index 98f0aefc..34e3df56 100644 --- a/runtime/vk_memory.c +++ b/runtime/vk_memory.c @@ -571,6 +571,23 @@ void vk_mem_census(uint64_t frame) { n_import_failures, (unsigned long long)count[POOL_PHYS], total[POOL_PHYS] / 1048576.0, (unsigned long long)count[POOL_VIRT], total[POOL_VIRT] / 1048576.0, (unsigned long long)__atomic_load_n(&n_cross_defer, __ATOMIC_RELAXED)); + // The baseline for the commit a crash report prints: a crash far above it points at growth during play. + double proc, used, limit; + plat_commit_info(&proc, &used, &limit); + rt_log("mem: commit at frame %llu: this process %.0f MB, the system %.0f of %.0f MB", (unsigned long long)frame, proc, + used, limit); + // Per heap, what VMA holds (blocks, and the allocations inside them) beside what the driver counts for the process: + // usage above VMA's blocks is the driver's own memory (pipelines, command buffers, descriptor pools). + VkCtx *vc = vk_ctx(); + if (vc && vc->vma) { + VmaBudget vb[VK_MAX_MEMORY_HEAPS]; + vmaGetHeapBudgets(vc->vma, vb); + for (uint32_t h = 0; h < vc->mem_props.memoryHeapCount && h < VK_MAX_MEMORY_HEAPS; h++) + rt_log("mem: heap %u (flags %#x) at frame %llu: vma %u blocks %.0f MiB, %u allocations %.0f MiB; driver usage " + "%.0f of %.0f MiB", h, vc->mem_props.memoryHeaps[h].flags, (unsigned long long)frame, + vb[h].statistics.blockCount, vb[h].statistics.blockBytes / 1048576.0, vb[h].statistics.allocationCount, + vb[h].statistics.allocationBytes / 1048576.0, vb[h].usage / 1048576.0, vb[h].budget / 1048576.0); + } static const char *const kinds[] = {"", "import", "physical", "virtual"}; for (int j = 0; j < ng; j++) { char f[160]; From c838d9692f3133baa58b7e160f4c642d3ef921fd Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 09:02:36 +0300 Subject: [PATCH 03/16] Count system memory in the device-local budget where device memory takes host memory The paths that give memory back under pressure (headroom's spare block, released textures, pool mirrors) watched the Vulkan heap budget only. On a UMA GPU that budget is gigabytes of the same RAM the game runs in, and on Windows the AMD driver charges device-local allocations to the process commit one to one (RX 9070: VRAM use and private bytes grew by the same 1164, 256 and 256 MiB). Crash logs show the result: the process at 4.4-10.5 GB of commit, 16 GB machines at 80-94% RAM, std::bad_alloc inside amdvlk64.dll (#285), allocation failures on Intel UHD. vk_mem_host_room (vk_memory.c) is what the system can still give beyond a reserve (TOTK_MEM_RESERVE_MIB, 1536): commit, and on a UMA GPU physical memory too; Linux overcommits, so there only a UMA GPU's available memory counts. NVIDIA is left out, not measured. vk_mem_vram caps the budget at use plus that room, and headroom keeps its spare block only while four blocks fit in it. RX 9070, field save, 60 s with the room near zero from the start (TOTK_MEM_RESERVE_MIB=21000): commit 7124 MB instead of 8965, VRAM 2631 MiB instead of 3781, released textures 153 instead of 1866; mirrors refused for 423 MiB of pools, GPU 4.45 ms a frame instead of 3.34 ms, 60 fps either way. Without pressure nothing changes. The census logs the room, the device class line the mode. Co-Authored-By: Claude Opus 5.5 --- runtime/cfg.c | 2 +- runtime/platform/linux.c | 11 ++++++++ runtime/platform/platform.h | 3 +++ runtime/platform/win32.c | 6 +++++ runtime/vk.h | 6 ++++- runtime/vk_headroom.c | 7 ++++-- runtime/vk_memory.c | 50 +++++++++++++++++++++++++++++++++++-- 7 files changed, 79 insertions(+), 6 deletions(-) diff --git a/runtime/cfg.c b/runtime/cfg.c index bc395ce6..2d79b5fc 100644 --- a/runtime/cfg.c +++ b/runtime/cfg.c @@ -47,7 +47,7 @@ static const char *const known[] = { "FULLSCREEN", "FXAA", "GPL", "GPL_DRAW_BUILD", "GPU", "GPU_INDEX", "GPU_NAME", "HDR", "HDR_GAME_NITS", "HDR_HUE", "HDR_PEAK_NITS", "HDR_UI_NITS", "HIGHFPS_FIX", "INPUT", "INPUT_RECORD", "INPUT_SCRIPT", "KSPIN_US", "LANG", "LIB_PREBUILD", "LIB_PREBUILD_KEEP", "LIB_PREBUILD_THREADS", "LOCALE", "LOD_GUARD", "LSTICK_DEADZONE", "MEMORY", "MENU_LANG", "MENU_TEST", - "MENU_CURSOR", "MENU_CURSOR_LOG", "MENU_TEST_DIR", "MENU_TEST_SET", "MINIMAL_LAYOUT", "MIRROR_GAP", "MODS_DIR", "MODS_DISABLED", "MODS_ORDER", "MODS_REBUILD", "MOTION", "MOUSE_AIM_SCALE", "MOUSE_MODE", "MOUSE_DIRECT_PATCH", "MOUSE_SENS", "MOVIE_ASPECT", "MOVIE_HOST", "MOVIE_PACE", + "MEM_RESERVE_MIB", "MENU_CURSOR", "MENU_CURSOR_LOG", "MENU_TEST_DIR", "MENU_TEST_SET", "MINIMAL_LAYOUT", "MIRROR_GAP", "MODS_DIR", "MODS_DISABLED", "MODS_ORDER", "MODS_REBUILD", "MOTION", "MOUSE_AIM_SCALE", "MOUSE_MODE", "MOUSE_DIRECT_PATCH", "MOUSE_SENS", "MOVIE_ASPECT", "MOVIE_HOST", "MOVIE_PACE", "MVOBJ_ALL", "MVOBJ_BANKS", "MVOBJ_EQUAL", "MVOBJ_EXACT", "MVOBJ_EXEC", "MVOBJ_NOC4", "MVOBJ_ONLY", "MVOBJ_TIMES", "MVPREV_CHECK", "MVPREV_GROW", "MVPREV_SKIP", "MVPREV_TRUST", "MV_CHECK", "MV_SURVEY", "ONE_PER_CORE", "OPERATION_MODE", "OUTPUT_RES", "PAD_LAYOUT", "PASS_CRUMBS", "PATCH_OUTPUT", "PATCH_SCENE", "PCORE", "PCSS", "PCSS_K", "PERF_OVERLAY", "PERF_SLOW_MS", "PIPELINE_CACHE", "PIPE_MEMO", "PIPE_PREBUILD", "PIPE_SKIP", "PIPE_SYNC", "PIPE_WAIT", diff --git a/runtime/platform/linux.c b/runtime/platform/linux.c index 24512abb..24a0f0b1 100644 --- a/runtime/platform/linux.c +++ b/runtime/platform/linux.c @@ -1673,6 +1673,17 @@ void plat_commit_info(double *proc_mb, double *used_mb, double *limit_mb) { if (private_bytes) *proc_mb = (double)(private_bytes >> 20); } +void plat_mem_room(uint64_t *commit_room, uint64_t *phys_room) { + *commit_room = *phys_room = UINT64_MAX; + char line[128]; + unsigned long long k; + FILE *f = fopen("/proc/meminfo", "r"); + if (!f) return; + while (fgets(line, sizeof line, f)) + if (sscanf(line, "MemAvailable: %llu kB", &k) == 1) *phys_room = (uint64_t)k << 10; + fclose(f); +} + // ---- child processes struct PlatChild { diff --git a/runtime/platform/platform.h b/runtime/platform/platform.h index 0ddeaa78..1f67f661 100644 --- a/runtime/platform/platform.h +++ b/runtime/platform/platform.h @@ -433,6 +433,9 @@ void plat_mem_info(float *used_mb, float *total_mb, float *proc_mb); // Commit charge in MB: this process's private bytes, the system's commit in use and its limit (RAM plus page files). // An allocation fails when the system's reaches the limit, however much physical memory is free. -1 when unknown. void plat_commit_info(double *proc_mb, double *used_mb, double *limit_mb); +// What the system can still give, in bytes: commit (Windows: limit minus charge; Linux, which overcommits: UINT64_MAX) +// and physical memory available without paging. UINT64_MAX when unknown. +void plat_mem_room(uint64_t *commit_room, uint64_t *phys_room); // This process's memory in bytes: resident (the working set) and private (Windows: committed private bytes; Linux: the // resident anonymous pages). 0 when unknown. void plat_process_memory(uint64_t *resident, uint64_t *private_bytes); diff --git a/runtime/platform/win32.c b/runtime/platform/win32.c index e753b313..6a291b81 100644 --- a/runtime/platform/win32.c +++ b/runtime/platform/win32.c @@ -1784,6 +1784,12 @@ void plat_commit_info(double *proc_mb, double *used_mb, double *limit_mb) { *proc_mb = (double)(pmc.PrivateUsage >> 20); } +void plat_mem_room(uint64_t *commit_room, uint64_t *phys_room) { + *commit_room = *phys_room = UINT64_MAX; + MEMORYSTATUSEX ms = {.dwLength = sizeof ms}; + if (GlobalMemoryStatusEx(&ms)) *commit_room = ms.ullAvailPageFile, *phys_room = ms.ullAvailPhys; +} + void plat_process_memory(uint64_t *resident, uint64_t *private_bytes) { PROCESS_MEMORY_COUNTERS_EX pm = {.cb = sizeof pm}; *resident = *private_bytes = 0; diff --git a/runtime/vk.h b/runtime/vk.h index a9c88f12..955937ac 100644 --- a/runtime/vk.h +++ b/runtime/vk.h @@ -300,8 +300,12 @@ int vk_mem_class_of(uint64_t addr); // VK_MCLS_* of the pool at ad void vk_mem_census(uint64_t frame); // at each present: pool census and traffic, logged at frame 1800 and, // with TOTK_TRACE=perf, every 1800 frames // VRAM in use and its budget, summed over the DEVICE_LOCAL heaps. exact 1: VK_EXT_memory_budget (the whole process), -// 0: this allocator's own allocations against the heap sizes. 0 when unknown. +// 0: this allocator's own allocations against the heap sizes. 0 when unknown. Where device memory takes host memory +// (vk_mem_host_room) the budget is at most the use plus that room. int vk_mem_vram(uint64_t *used, uint64_t *budget, int *exact); +// Bytes the system can still give device memory beyond a reserve (TOTK_MEM_RESERVE_MIB) where device memory takes host +// memory: a UMA GPU (commit and physical memory), or a discrete non-NVIDIA GPU on Windows (commit). UINT64_MAX elsewhere. +uint64_t vk_mem_host_room(void); // VRAM headroom (vk_headroom.c): the VMA callbacks that see new device memory, and the thread that allocates the next // block of each memory type in use ahead of the render thread. const VmaDeviceMemoryCallbacks *vk_headroom_callbacks(void); diff --git a/runtime/vk_headroom.c b/runtime/vk_headroom.c index 0d5871cd..e25ceb21 100644 --- a/runtime/vk_headroom.c +++ b/runtime/vk_headroom.c @@ -12,7 +12,7 @@ // a block per memory type is held back. // Under VRAM pressure no headroom is kept: the spare block counts against the budget that decides whether a pool gets // its VRAM mirror (vk_memory.c), so while use plus two blocks passes 85% of the budget the anchor goes and nothing new -// is allocated. +// is allocated. The same holds when the system runs short of memory (room). // TOTK_VRAM_HEADROOM=0 turns it off. #include "cfg.h" @@ -58,11 +58,14 @@ static VkDeviceSize block_size(const VkCtx *c, uint32_t type) { return heap <= HR_SMALL_HEAP ? heap / 8 : 256ull << 20; // VMA's default preferredLargeHeapBlockSize } +// The spare block is memory the game does not use yet; where device memory takes host memory it is kept only while the +// system has four blocks to spare beyond the reserve (vk_mem_host_room). On the RX 9070 the spare blocks held 1.4 GB +// of commit. static int room(const VkCtx *c, uint32_t type, VkDeviceSize block) { VmaBudget b[VK_MAX_MEMORY_HEAPS]; vmaGetHeapBudgets(c->vma, b); const VmaBudget *h = &b[c->mem_props.memoryTypes[type].heapIndex]; - return h->budget && h->usage + 2 * block <= h->budget / 100 * 85; + return h->budget && h->usage + 2 * block <= h->budget / 100 * 85 && vk_mem_host_room() >= 4 * block; } static void drop_anchor(const VkCtx *c, uint32_t type) { diff --git a/runtime/vk_memory.c b/runtime/vk_memory.c index 34e3df56..653ac3ec 100644 --- a/runtime/vk_memory.c +++ b/runtime/vk_memory.c @@ -574,8 +574,10 @@ void vk_mem_census(uint64_t frame) { // The baseline for the commit a crash report prints: a crash far above it points at growth during play. double proc, used, limit; plat_commit_info(&proc, &used, &limit); - rt_log("mem: commit at frame %llu: this process %.0f MB, the system %.0f of %.0f MB", (unsigned long long)frame, proc, - used, limit); + uint64_t room = vk_mem_host_room(); + rt_log("mem: commit at frame %llu: this process %.0f MB, the system %.0f of %.0f MB; room for device memory %s%.0f MiB", + (unsigned long long)frame, proc, used, limit, room == UINT64_MAX ? "not counted " : "", + room == UINT64_MAX ? 0.0 : room / 1048576.0); // Per heap, what VMA holds (blocks, and the allocations inside them) beside what the driver counts for the process: // usage above VMA's blocks is the driver's own memory (pipelines, command buffers, descriptor pools). VkCtx *vc = vk_ctx(); @@ -619,6 +621,42 @@ static uint64_t vram_limit(void) { return (uint64_t)limit; } +// Device memory that takes host memory. A UMA GPU's memory is the machine's RAM. On Windows the AMD driver charges +// device-local allocations to the process commit one to one (RX 9070: VRAM use and private bytes grew by the same +// 1164, 256 and 256 MiB), so on a 16 GB machine the commit limit is reached while the VRAM budget shows gigabytes free, +// and the driver then fails inside a call (#285: std::bad_alloc in amdvlk64.dll under gpl_link). Intel's Windows driver +// is taken to do the same; NVIDIA's is not measured and left out. Linux overcommits, so there only a UMA GPU's physical +// memory counts (plat_mem_room). +enum { HB_NONE, HB_COMMIT, HB_UMA }; +static int host_backed; +static uint64_t room_reserve; +static volatile uint64_t room_cached, room_ms; + +uint64_t vk_mem_host_room(void) { + if (!host_backed) return UINT64_MAX; + uint64_t now = plat_now_ms(), at = __atomic_load_n(&room_ms, __ATOMIC_ACQUIRE); + if (at && now - at < 250) return __atomic_load_n(&room_cached, __ATOMIC_RELAXED); // a query costs a system call + uint64_t commit, phys; + plat_mem_room(&commit, &phys); + uint64_t r = host_backed == HB_UMA && phys < commit ? phys : commit; + r = r == UINT64_MAX ? r : r > room_reserve ? r - room_reserve : 0; + __atomic_store_n(&room_cached, r, __ATOMIC_RELAXED); + __atomic_store_n(&room_ms, now | 1, __ATOMIC_RELEASE); + return r; +} + +// The budget is at most the use plus what the system can still give, so the paths that react to VRAM pressure (the +// mirror refusal, released textures, the headroom block) react to a system short of memory too. +static void host_cap(uint64_t used, uint64_t *budget) { + uint64_t room = vk_mem_host_room(); + if (room == UINT64_MAX || used + room >= *budget) return; + *budget = used + room ? used + room : 1; + static volatile int32_t logged; + if (!plat_xchg32(&logged, 1)) + rt_log("mem: system memory limits the device-local budget: %.0f MiB in use, %.0f MiB more beyond a reserve of " + "%.0f MiB (logged once)", used / 1048576.0, room / 1048576.0, room_reserve / 1048576.0); +} + int vk_mem_vram(uint64_t *used, uint64_t *budget, int *exact) { VkCtx *c = vk_ctx(); *used = *budget = 0, *exact = 0; @@ -634,6 +672,7 @@ int vk_mem_vram(uint64_t *used, uint64_t *budget, int *exact) { *used += b.heapUsage[h], *budget += b.heapBudget[h]; *exact = 1; if (limit && *budget > limit) *budget = limit; + if (*budget) host_cap(*used, budget); return *budget != 0; } VmaBudget vb[VK_MAX_MEMORY_HEAPS]; @@ -642,6 +681,7 @@ int vk_mem_vram(uint64_t *used, uint64_t *budget, int *exact) { if (mp->memoryHeaps[h].flags & VK_MEMORY_HEAP_DEVICE_LOCAL_BIT) *used += vb[h].statistics.blockBytes, *budget += mp->memoryHeaps[h].size; if (limit && *budget > limit) *budget = limit; + if (*budget) host_cap(*used, budget); return *budget != 0; } @@ -2243,6 +2283,9 @@ void vk_mem_class_log(const VkPhysicalDeviceProperties *p, const VkPhysicalDevic else if (host_heap < 0) cls = "uma", why = "every heap is device-local"; else cls = "discrete", why = "device-local heap separate from host memory"; int discrete = cls[0] == 'd'; + host_backed = !discrete ? HB_UMA : p->vendorID != 0x10DE ? HB_COMMIT : HB_NONE; + const char *rs = cfg_get("TOTK_MEM_RESERVE_MIB"); + room_reserve = (rs && *rs ? strtoull(rs, NULL, 10) : 1536) << 20; // Windows, other programs, our own heap char line[2048]; size_t k = (size_t)snprintf(line, sizeof line, "mem: class %s (%s; device type %d %s, %s)", cls, why, t, tn, p->deviceName); for (uint32_t h = 0; h < m->memoryHeapCount; h++) @@ -2262,6 +2305,9 @@ void vk_mem_class_log(const VkPhysicalDeviceProperties *p, const VkPhysicalDevic f & VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT ? " LAZY" : ""); } rt_log("%s", line); + rt_log("mem: device memory against system memory: %s, reserve %llu MiB (TOTK_MEM_RESERVE_MIB)", + host_backed == HB_UMA ? "commit and physical memory (uma)" : host_backed == HB_COMMIT ? "commit" : "not counted", + (unsigned long long)(room_reserve >> 20)); mirror_mode(discrete); } From d8090a85fe5dde89ee1ce9fadb880dfffe200d5f Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 09:05:09 +0300 Subject: [PATCH 04/16] Keep headroom blocks for device-local memory types only Headroom woke for every memory type that got new device memory, the staging pool's own 64 MiB blocks included, and then kept a 256 MiB spare block in that type's default pool. On the RX 9070 the default pools of host memory types 1 and 3 held 4 MiB, beside 512 MiB of spare blocks. Textures and mirrors, whose block allocations headroom moves off the render thread, live in device-local types. RX 9070, field save, 60 s: heap 0 VMA blocks 192 MiB instead of 704, driver usage 1384 MiB instead of 1896; 60 fps, 1% low 51.9. Co-Authored-By: Claude Opus 5.5 --- runtime/vk_headroom.c | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/runtime/vk_headroom.c b/runtime/vk_headroom.c index e25ceb21..88083025 100644 --- a/runtime/vk_headroom.c +++ b/runtime/vk_headroom.c @@ -75,7 +75,11 @@ static void drop_anchor(const VkCtx *c, uint32_t type) { static void top_up(const VkCtx *c, uint32_t type) { VkDeviceSize block = block_size(c, type); - if (!room(c, type, block)) { + // Device-local types only: textures and mirrors grow there. Host memory types are woken by the staging pool's own + // blocks (vk_memory.c vk_staging), while their default pool held 4 MiB: on the RX 9070 the spare blocks of types 1 + // and 3 held 512 MiB of commit for nothing. + if (!(c->mem_props.memoryTypes[type].propertyFlags & VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT) || + !room(c, type, block)) { drop_anchor(c, type); return; } From a689922180a974262c18caba8208e61b65130ece Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 09:20:09 +0300 Subject: [PATCH 05/16] Decode ASTC to BC3 by default on integrated GPUs The size rule for TOTK_ASTC_BC looked at the largest device-local heap only. On an integrated GPU that heap is system RAM reported as VRAM (10.6 GiB on the Ally X, 14.9 GiB on the 880M), so RGBA8 stayed on exactly where memory is shortest. vk_mem_uma() now turns BC3 on there as well. 7900X iGPU, field save, same exe, frame 1800: RGBA8 commit 7047 MB, GPU 49-53 ms, 16.8-18.4 fps; BC3 commit 6155 MB, GPU 42.6 ms, 21.6-21.8 fps. Co-Authored-By: Claude Opus 5.5 --- runtime/vk.h | 1 + runtime/vk_astc.c | 10 ++++++---- runtime/vk_memory.c | 2 ++ 3 files changed, 9 insertions(+), 4 deletions(-) diff --git a/runtime/vk.h b/runtime/vk.h index 955937ac..93445bb6 100644 --- a/runtime/vk.h +++ b/runtime/vk.h @@ -306,6 +306,7 @@ int vk_mem_vram(uint64_t *used, uint64_t *budget, int *exact); // Bytes the system can still give device memory beyond a reserve (TOTK_MEM_RESERVE_MIB) where device memory takes host // memory: a UMA GPU (commit and physical memory), or a discrete non-NVIDIA GPU on Windows (commit). UINT64_MAX elsewhere. uint64_t vk_mem_host_room(void); +int vk_mem_uma(void); // 1: the device class is uma (vk_mem_class_log), its memory is RAM // VRAM headroom (vk_headroom.c): the VMA callbacks that see new device memory, and the thread that allocates the next // block of each memory type in use ahead of the render thread. const VmaDeviceMemoryCallbacks *vk_headroom_callbacks(void); diff --git a/runtime/vk_astc.c b/runtime/vk_astc.c index ccfa4235..ff0b6028 100644 --- a/runtime/vk_astc.c +++ b/runtime/vk_astc.c @@ -300,17 +300,19 @@ static int create_pipeline(VkCtx *c) { // TOTK_ASTC_BC=1: the BC3 encoder, when the device samples BC3 (every desktop GPU does); 0 leaves ASTC as RGBA8. // Unset: on when the largest device-local heap is under 5 GiB. There RGBA8 ASTC, four times the size of BC3, fills // video memory (a GTX 1650 4 GiB went from 10-23 to 3-12 ms of GPU time a frame, issue #87); BC3 loses some precision -// (normal maps), so GPUs with more memory keep RGBA8. +// (normal maps), so GPUs with more memory keep RGBA8. A UMA GPU's heap is the machine's RAM however large it reads +// (10.6 GiB on an ROG Ally X, 14.9 GiB on a Radeon 880M), so there BC3 is on too: on the RX 9070, BC3 took 737 MiB off +// VMA's device-local allocations after a minute in the field, at the same GPU time. static int create_bc_pipeline(VkCtx *c) { const char *e = cfg_get("TOTK_ASTC_BC"); VkDeviceSize vram = 0; for (uint32_t h = 0; h < c->mem_props.memoryHeapCount && h < VK_MAX_MEMORY_HEAPS; h++) if (c->mem_props.memoryHeaps[h].flags & VK_MEMORY_HEAP_DEVICE_LOCAL_BIT && c->mem_props.memoryHeaps[h].size > vram) vram = c->mem_props.memoryHeaps[h].size; - int on = e && *e ? *e != '0' : vram < (5ull << 30); + int on = e && *e ? *e != '0' : vram < (5ull << 30) || vk_mem_uma(); if (!(e && *e)) - rt_log("vk: TOTK_ASTC_BC unset: BC3 %s (largest device-local heap %llu MiB)", on ? "on" : "off", - (unsigned long long)(vram >> 20)); + rt_log("vk: TOTK_ASTC_BC unset: BC3 %s (largest device-local heap %llu MiB%s)", on ? "on" : "off", + (unsigned long long)(vram >> 20), vk_mem_uma() ? ", uma: system memory" : ""); if (!on) return 0; VkFormatProperties p; vkGetPhysicalDeviceFormatProperties(c->phys, VK_FORMAT_BC3_SRGB_BLOCK, &p); diff --git a/runtime/vk_memory.c b/runtime/vk_memory.c index 653ac3ec..2fb547e7 100644 --- a/runtime/vk_memory.c +++ b/runtime/vk_memory.c @@ -645,6 +645,8 @@ uint64_t vk_mem_host_room(void) { return r; } +int vk_mem_uma(void) { return host_backed == HB_UMA; } + // The budget is at most the use plus what the system can still give, so the paths that react to VRAM pressure (the // mirror refusal, released textures, the headroom block) react to a system short of memory too. static void host_cap(uint64_t used, uint64_t *budget) { From 79c69516888dddad4d9bfae5df2da640f8e4186e Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 09:39:54 +0300 Subject: [PATCH 06/16] Measure whether device-local memory takes process commit instead of assuming it per vendor c838d96 counted system memory for every discrete GPU but NVIDIA's, an assumption. An RTX 5080 log (#398) showed 10.4 GB of process commit at frame 1200, about what the RX 9070 holds with its VRAM counted, and the RTX 3060 Ti in #670 ran out of system commit (17.8 GB) at 4K with its VRAM full. vk_mem_host_probe now allocates 128 MiB of device-local memory once after device creation and compares the process commit before and after; half the size or more turns the system memory cap on. The log line carries the measured amount, so user logs show what each driver does. RX 9070: "a 128 MiB device-local allocation took 128 MiB of process commit". Co-Authored-By: Claude Opus 5.5 --- runtime/vk.h | 4 +++- runtime/vk_device.c | 3 ++- runtime/vk_memory.c | 52 ++++++++++++++++++++++++++++++++++++++------- 3 files changed, 49 insertions(+), 10 deletions(-) diff --git a/runtime/vk.h b/runtime/vk.h index 93445bb6..9cac3e54 100644 --- a/runtime/vk.h +++ b/runtime/vk.h @@ -304,8 +304,10 @@ void vk_mem_census(uint64_t frame); // at each present: pool censu // (vk_mem_host_room) the budget is at most the use plus that room. int vk_mem_vram(uint64_t *used, uint64_t *budget, int *exact); // Bytes the system can still give device memory beyond a reserve (TOTK_MEM_RESERVE_MIB) where device memory takes host -// memory: a UMA GPU (commit and physical memory), or a discrete non-NVIDIA GPU on Windows (commit). UINT64_MAX elsewhere. +// memory: a UMA GPU (commit and physical memory), or a discrete GPU whose device-local memory took process commit in +// vk_mem_host_probe (commit). UINT64_MAX elsewhere. uint64_t vk_mem_host_room(void); +void vk_mem_host_probe(void); // vk_device.c, after the device: measures that for a discrete GPU, once int vk_mem_uma(void); // 1: the device class is uma (vk_mem_class_log), its memory is RAM // VRAM headroom (vk_headroom.c): the VMA callbacks that see new device memory, and the thread that allocates the next // block of each memory type in use ahead of the render thread. diff --git a/runtime/vk_device.c b/runtime/vk_device.c index 31fbc1a4..458cd86b 100644 --- a/runtime/vk_device.c +++ b/runtime/vk_device.c @@ -475,7 +475,8 @@ int vk_init(void) { plat_mutex_lock(&g_lock); if (!g_ready) { memset(&g_vk, 0, sizeof g_vk); - if (create_instance() && pick_device() && create_device()) g_ready = 1, vk_upload_pools_init(), vk_headroom_start(), vk_dlaa_init(); + if (create_instance() && pick_device() && create_device()) + g_ready = 1, vk_mem_host_probe(), vk_upload_pools_init(), vk_headroom_start(), vk_dlaa_init(); else destroy_all(); } int ok = g_ready; diff --git a/runtime/vk_memory.c b/runtime/vk_memory.c index 2fb547e7..b493b19d 100644 --- a/runtime/vk_memory.c +++ b/runtime/vk_memory.c @@ -589,6 +589,7 @@ void vk_mem_census(uint64_t frame) { "%.0f of %.0f MiB", h, vc->mem_props.memoryHeaps[h].flags, (unsigned long long)frame, vb[h].statistics.blockCount, vb[h].statistics.blockBytes / 1048576.0, vb[h].statistics.allocationCount, vb[h].statistics.allocationBytes / 1048576.0, vb[h].usage / 1048576.0, vb[h].budget / 1048576.0); + } } static const char *const kinds[] = {"", "import", "physical", "virtual"}; for (int j = 0; j < ng; j++) { @@ -624,10 +625,11 @@ static uint64_t vram_limit(void) { // Device memory that takes host memory. A UMA GPU's memory is the machine's RAM. On Windows the AMD driver charges // device-local allocations to the process commit one to one (RX 9070: VRAM use and private bytes grew by the same // 1164, 256 and 256 MiB), so on a 16 GB machine the commit limit is reached while the VRAM budget shows gigabytes free, -// and the driver then fails inside a call (#285: std::bad_alloc in amdvlk64.dll under gpl_link). Intel's Windows driver -// is taken to do the same; NVIDIA's is not measured and left out. Linux overcommits, so there only a UMA GPU's physical -// memory counts (plat_mem_room). -enum { HB_NONE, HB_COMMIT, HB_UMA }; +// and the driver then fails inside a call (#285: std::bad_alloc in amdvlk64.dll under gpl_link). Whether a discrete +// GPU's driver does so is measured once (vk_mem_host_probe), not assumed per vendor: an RTX 5080 log (#398) showed +// 10.4 GB of process commit at frame 1200, about what the RX 9070 holds with its VRAM counted. Linux overcommits, so +// there only a UMA GPU's physical memory counts (plat_mem_room). +enum { HB_NONE, HB_COMMIT, HB_UMA, HB_PROBE }; static int host_backed; static uint64_t room_reserve; static volatile uint64_t room_cached, room_ms; @@ -647,6 +649,40 @@ uint64_t vk_mem_host_room(void) { int vk_mem_uma(void) { return host_backed == HB_UMA; } +// A discrete GPU: one device-local allocation of HB_PROBE_SIZE, and the process commit before and after it. The driver +// charges it at allocation or not at all as far as this sees; one that charged only at first use would read as not +// counted, as before the probe. Another thread's allocation in between could only add, and half the size is the line. +#define HB_PROBE_SIZE (128ull << 20) +void vk_mem_host_probe(void) { + VkCtx *c = vk_ctx(); + if (!c || host_backed != HB_PROBE) return; + host_backed = HB_NONE; + uint64_t commit, phys; + plat_mem_room(&commit, &phys); + if (commit == UINT64_MAX) return; // no commit limit (Linux) + uint32_t type = UINT32_MAX; + for (uint32_t i = 0; i < c->mem_props.memoryTypeCount && type == UINT32_MAX; i++) + if ((c->mem_props.memoryTypes[i].propertyFlags & (VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT)) == + VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT) + type = i; + VkMemoryAllocateInfo ai = {.sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO, .allocationSize = HB_PROBE_SIZE, + .memoryTypeIndex = type}; + uint64_t r0, p0, r1, p1; + VkDeviceMemory m; + plat_process_memory(&r0, &p0); + if (type == UINT32_MAX || !p0 || vkAllocateMemory(c->device, &ai, NULL, &m) != VK_SUCCESS) { + rt_log("mem: device memory against system memory: not measured (no device-local type or allocation failed): not counted"); + return; + } + plat_process_memory(&r1, &p1); + vkFreeMemory(c->device, m, NULL); + int64_t d = (int64_t)(p1 - p0); + host_backed = d >= (int64_t)HB_PROBE_SIZE / 2 ? HB_COMMIT : HB_NONE; + rt_log("mem: device memory against system memory: %s (a %llu MiB device-local allocation took %.0f MiB of process " + "commit), reserve %llu MiB (TOTK_MEM_RESERVE_MIB)", host_backed == HB_COMMIT ? "commit" : "not counted", + (unsigned long long)(HB_PROBE_SIZE >> 20), d / 1048576.0, (unsigned long long)(room_reserve >> 20)); +} + // The budget is at most the use plus what the system can still give, so the paths that react to VRAM pressure (the // mirror refusal, released textures, the headroom block) react to a system short of memory too. static void host_cap(uint64_t used, uint64_t *budget) { @@ -2285,7 +2321,7 @@ void vk_mem_class_log(const VkPhysicalDeviceProperties *p, const VkPhysicalDevic else if (host_heap < 0) cls = "uma", why = "every heap is device-local"; else cls = "discrete", why = "device-local heap separate from host memory"; int discrete = cls[0] == 'd'; - host_backed = !discrete ? HB_UMA : p->vendorID != 0x10DE ? HB_COMMIT : HB_NONE; + host_backed = !discrete ? HB_UMA : HB_PROBE; // a discrete GPU is measured once the device exists const char *rs = cfg_get("TOTK_MEM_RESERVE_MIB"); room_reserve = (rs && *rs ? strtoull(rs, NULL, 10) : 1536) << 20; // Windows, other programs, our own heap char line[2048]; @@ -2307,9 +2343,9 @@ void vk_mem_class_log(const VkPhysicalDeviceProperties *p, const VkPhysicalDevic f & VK_MEMORY_PROPERTY_LAZILY_ALLOCATED_BIT ? " LAZY" : ""); } rt_log("%s", line); - rt_log("mem: device memory against system memory: %s, reserve %llu MiB (TOTK_MEM_RESERVE_MIB)", - host_backed == HB_UMA ? "commit and physical memory (uma)" : host_backed == HB_COMMIT ? "commit" : "not counted", - (unsigned long long)(room_reserve >> 20)); + if (host_backed == HB_UMA) + rt_log("mem: device memory against system memory: commit and physical memory (uma), reserve %llu MiB " + "(TOTK_MEM_RESERVE_MIB)", (unsigned long long)(room_reserve >> 20)); mirror_mode(discrete); } From 5e479f593bb72807f82d318e2bed36435bc56b68 Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 09:51:04 +0300 Subject: [PATCH 07/16] Remove the stray brace in vk_mem_census that stopped vk_memory.c from compiling 79c6951 left the closing brace of a debug block in the per-heap loop, so the function ended early and the build failed. Co-Authored-By: Claude Opus 5.5 --- runtime/vk_memory.c | 1 - 1 file changed, 1 deletion(-) diff --git a/runtime/vk_memory.c b/runtime/vk_memory.c index b493b19d..c887a560 100644 --- a/runtime/vk_memory.c +++ b/runtime/vk_memory.c @@ -589,7 +589,6 @@ void vk_mem_census(uint64_t frame) { "%.0f of %.0f MiB", h, vc->mem_props.memoryHeaps[h].flags, (unsigned long long)frame, vb[h].statistics.blockCount, vb[h].statistics.blockBytes / 1048576.0, vb[h].statistics.allocationCount, vb[h].statistics.allocationBytes / 1048576.0, vb[h].usage / 1048576.0, vb[h].budget / 1048576.0); - } } static const char *const kinds[] = {"", "import", "physical", "virtual"}; for (int j = 0; j < ng; j++) { From 213bc6af6afecf4d7bc148f2afc049ca623c8bb8 Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 09:53:30 +0300 Subject: [PATCH 08/16] Wait out a short out-of-memory spell instead of ending the game Crash logs ended in fatal errors when the system's commit ran out for a moment: a staging buffer (-2), a guest commit with the system at 24442 of 24447 MB, image creation (-2). Windows grows a system-managed page file and some drivers charge device memory to the process commit, so the same request often succeeds a moment later. oom.c holds the wait nvn_api_cmd.c realloc_wait already used: it requests a release, retries every 10 ms for up to 30 s, logs the first 8 with the commit numbers. rt_oom_request sets a flag that vk_texture_new_submit takes (one atomic load per submit): it drops up to 256 released textures of the two kinds sweep_pressure drops (overwritten, clean mirrored), never GPU-written content, and frees the headroom blocks. vk_oom_release does at once what needs no submit: headroom blocks, finished upload batches and deferred objects. - memory.c commit: waits and retries without frz_lock between tries; every caller waits, boot ones too. - vk_staging and the draw-data chunks (vk_exec_draw.c scratch): release, then wait; the open upload batch is not submitted, its caller still records into it. - create_tex: release and one retry; no wait under the texture lock, the texture is asked for again at its next use. - the texture write-back buffer: release, then wait. - the headroom thread keeps no spare block for 30 s after a failure. TOTK_TEST_OOM=: (commit, staging, image, chunk) fails the first n attempts; probe-kernel forces 3 refused commits, probe-vkexec 2 staging buffers, 1 image and 1 chunk, and both pass through them. Co-Authored-By: Claude Opus 5.5 --- docs/settings.md | 1 + runtime/cfg.c | 2 +- runtime/host.h | 17 +++++++ runtime/kernel_probe.c | 20 ++++++++ runtime/memory.c | 25 ++++++++-- runtime/nvn_api_cmd.c | 1 + runtime/oom.c | 106 ++++++++++++++++++++++++++++++++++++++++ runtime/vk.h | 6 +++ runtime/vk_exec_draw.c | 25 ++++++++-- runtime/vk_exec_probe.c | 11 +++++ runtime/vk_headroom.c | 23 ++++++++- runtime/vk_memory.c | 44 +++++++++++++++-- runtime/vk_texture.c | 74 ++++++++++++++++++++++------ 13 files changed, 323 insertions(+), 32 deletions(-) create mode 100644 runtime/oom.c diff --git a/docs/settings.md b/docs/settings.md index 20a51ef2..9dcf5748 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -77,6 +77,7 @@ Many rows below are developer tools that only act together with another setting | `probe_movie_bench` | `1` makes the movie probe also time the resampler that fits a movie to a game resolution of another shape, and print the time per frame. | Only used by the movie decoder probe. | Safe | | `swkbd_answer` | ``, `` or ``: answers the on-screen keyboard (for example a horse name) without opening a window. | The game gets that answer every time it asks for text. | Caution | | `swkbd_test` | `ok` or `cancel` opens the keyboard window and presses OK or Cancel on the first timer tick. | The keyboard window closes by itself. | Caution | +| `test_oom` | `:[,...]` fails the first n allocations at a site: `commit` (guest memory), `staging` (upload buffers), `image` (texture images), `chunk` (draw data buffers). | Each forced failure takes the out-of-memory path: a memory release, a wait of 10 ms per retry and log lines; a large n stalls up to 30 s and then ends the game. | Caution | | `test_pad` | `,,,` attaches a virtual gamepad whose sticks rest at these raw SDL axis values (-32768 to 32767). | The game sees a controller with that drift or deflection; a malformed value is logged and ignored. | Caution | | `test_prepare_shaders` | `1` translates every recorded shader on all usable CPUs during start. | Start takes longer and fills the shader cache folder; the CPU is fully used while it runs. | Caution | diff --git a/runtime/cfg.c b/runtime/cfg.c index 2d79b5fc..08b57739 100644 --- a/runtime/cfg.c +++ b/runtime/cfg.c @@ -59,7 +59,7 @@ static const char *const known[] = { "SHADER_MEMO", "SHADOW_RANGE", "SHADOW_RES", "SHADOW_SCALE", "SHADOW_SNAP", "SHARED_FONTS", "SHARPNESS", "SHOTS", "SHOTS_DIR", "SHOTS_FULL", "SPEED_PROBE", "SPIN", "SPIN_HANDOFF_US", "SPLIT_DRAWS", "SPLIT_US", "STICK_DEADZONE", "STICK_SENS", "SWKBD_ANSWER", - "SWKBD_TEST", "TEST_PAD", "TEST_PREPARE_SHADERS", "TEX_ALIAS", "TEX_HEAP_EXTRA_MB", "TEX_MEMO", "TEX_VRAM_PRESSURE", "TIMER_1MS", "TRACE", "TXD_TRANSPOSE", "UBO_SNAPSHOT", "UB_OVERLAY", "UB_OVERLAY_OUT", "UPSCALER", "VB_USED", "VK_DYN_A2C", "VK_DYN_VERTEX", "VK_NO_FLOAT64", + "SWKBD_TEST", "TEST_OOM", "TEST_PAD", "TEST_PREPARE_SHADERS", "TEX_ALIAS", "TEX_HEAP_EXTRA_MB", "TEX_MEMO", "TEX_VRAM_PRESSURE", "TIMER_1MS", "TRACE", "TXD_TRANSPOSE", "UBO_SNAPSHOT", "UB_OVERLAY", "UB_OVERLAY_OUT", "UPSCALER", "VB_USED", "VK_DYN_A2C", "VK_DYN_VERTEX", "VK_NO_FLOAT64", "VK_PRESENT", "VK_RECORDER", "VK_SSBO_ALIGN", "VK_SUBGROUP", "VK_SUBGROUP_PIN", "VK_VALIDATION", "VOLUME", "VRAM_HEADROOM", "VRAM_LIMIT_MIB", "VS_OUTS", "WALK_KEY", "WALK_SCALE", "WB_EXACT", "WB_FENCE_LIMIT", "WB_MERGE", "WINDOW_SIZE", "XLATE", "XLATE_ID", "XLATE_KEEP", "XLATE_PROCS", "ZSTD_CHECK", "ZSTD_NATIVE", diff --git a/runtime/host.h b/runtime/host.h index 4bb5b1d5..72e0a489 100644 --- a/runtime/host.h +++ b/runtime/host.h @@ -175,6 +175,23 @@ int mem_guest_readable(uint64_t a, uint64_t n); // [a, a+n) can be re // module or the committed heap answered from the layout, // anything else by plat_mem_readable (an OS query) +// ---- short out-of-memory spells (oom.c) +enum { RT_OOM_COMMIT, RT_OOM_STAGING, RT_OOM_IMAGE, RT_OOM_CHUNK, RT_OOM_SITES }; +extern volatile int32_t rt_oom_req; // set by rt_oom_request; vk_texture_new_submit takes it +void rt_oom_request(void); // asks the Vulkan back end to give memory back at its next + // submit (released textures, headroom blocks); any thread, + // any lock held +int rt_oom_wait(const char *what, uint64_t bytes, int (*retry)(void *arg), void *arg); + // after a failed allocation: requests a release, then calls + // retry every 10 ms for up to 30 s; 1 once retry returned 1, + // 0 after the wait (the caller ends the game). Logs the + // first 8 with the commit numbers +void *rt_realloc_wait(void *old, size_t n, const char *what); // realloc, NULL only after rt_oom_wait gave up +int rt_oom_forced(int site); // 1: fail this attempt at site (TOTK_TEST_OOM=:, + // sites commit, staging, image, chunk; or rt_oom_force) +void rt_oom_force(int site, int n); // probes: fail the next n attempts at site +int rt_oom_forced_left(int site); // forced failures still to come at site + // ---- modules (loader.c) typedef struct { const char *name; uint64_t base, size, text_end, data_off; // text_end, data_off: offsets from base diff --git a/runtime/kernel_probe.c b/runtime/kernel_probe.c index cbbc9297..83f11101 100644 --- a/runtime/kernel_probe.c +++ b/runtime/kernel_probe.c @@ -682,6 +682,25 @@ static int cmp_u64(const void *a, const void *b) { return x < y ? -1 : x > y; } +// A refused commit waits and retries (memory.c commit, oom.c rt_oom_wait): three forced refusals, then the page maps. +static void test_oom_commit(void) { + const RtGuestLayout *g = mem_layout(); + uint64_t a = g->alias.base + g->alias.size - 0x10000; + rt_oom_force(RT_OOM_COMMIT, 3); + uint64_t t0 = plat_now_ms(); + uint32_t r = mem_map_physical(a, 0x1000); + uint64_t ms = plat_now_ms() - t0; + CHECK(r == 0 && rt_oom_forced_left(RT_OOM_COMMIT) == 0 && ms >= 20, + "MapPhysicalMemory after 3 refused commits: result %#x, %d refusals left, %llu ms", r, + rt_oom_forced_left(RT_OOM_COMMIT), (unsigned long long)ms); + rt_oom_force(RT_OOM_COMMIT, 0); + if (r == 0) { + *(volatile uint64_t *)(uintptr_t)a = 1; + CHECK(mem_unmap_physical(a, 0x1000) == 0, "UnmapPhysicalMemory after the refused commits"); + } + printf("oom: commit waited %llu ms through 3 refusals\n", (unsigned long long)ms); +} + static void test_platform(void) { PlatThread *t = plat_thread_new(plat_worker, (void *)(intptr_t)1, "probe-kernel plat"); CHECK(t, "plat_thread_new"); @@ -792,6 +811,7 @@ int probe_kernel(void) { return 1; } test_platform(); + test_oom_commit(); test_crash_report(); kern_run_on_guest_main(probe_main); RtStats s = rt_stats(); diff --git a/runtime/memory.c b/runtime/memory.c index 019c0fab..bfe11290 100644 --- a/runtime/memory.c +++ b/runtime/memory.c @@ -175,12 +175,29 @@ static int thaw_fault(uint64_t a) { } // Mapping changes thaw the regions they touch and run under frz_lock, so no freeze sees them half done. -static void commit(uint64_t a, uint64_t n, const char *what) { +typedef struct { uint64_t a, n; } CommitTry; +static int commit_try(void *arg) { + const CommitTry *t = arg; + if (rt_oom_forced(RT_OOM_COMMIT)) return 0; plat_mutex_lock(&frz_lock); - thaw_range_locked(a, n, 3); - int ok = !n || plat_mem_commit(a, n); + thaw_range_locked(t->a, t->n, 3); + int ok = !t->n || plat_mem_commit(t->a, t->n); plat_mutex_unlock(&frz_lock); - if (!ok) rt_fatal("memory: commit %s %#llx+%#llx failed", what, (unsigned long long)a, (unsigned long long)n); + return ok; +} + +// A refused commit waits for memory (rt_oom_wait): the system's commit ran out for a moment (a page file growing, the +// driver's device memory charged to this process), and the Vulkan back end gives memory back at its next submit. The +// wait holds the caller's lock (lock or klock: only memory SVCs and kernel-region allocations wait behind it) but not +// frz_lock, which write faults on frozen regions need. Every caller waits, the boot's ones too: there a refusal has the +// same cause, and the wait only delays an end the game would reach anyway. +static void commit(uint64_t a, uint64_t n, const char *what) { + CommitTry t = {a, n}; + if (commit_try(&t)) return; + char w[64]; + snprintf(w, sizeof w, "memory: commit of %s at %#llx", what, (unsigned long long)a); + if (!rt_oom_wait(w, n, commit_try, &t)) + rt_fatal("memory: commit %s %#llx+%#llx failed", what, (unsigned long long)a, (unsigned long long)n); } static void decommit(uint64_t a, uint64_t n, const char *what) { diff --git a/runtime/nvn_api_cmd.c b/runtime/nvn_api_cmd.c index 874002f7..8141c61b 100644 --- a/runtime/nvn_api_cmd.c +++ b/runtime/nvn_api_cmd.c @@ -148,6 +148,7 @@ static void *realloc_wait(void *old, size_t n, const char *what) { if (p) return p; pool_drain(); big_drain(); + rt_oom_request(); // the Vulkan back end gives memory back at its next submit (oom.c) static uint32_t reports; int report = __atomic_fetch_add(&reports, 1, __ATOMIC_RELAXED) < 8; if (report) { diff --git a/runtime/oom.c b/runtime/oom.c new file mode 100644 index 00000000..77f891c0 --- /dev/null +++ b/runtime/oom.c @@ -0,0 +1,106 @@ +// Short out-of-memory spells: a failed allocation waits for memory instead of ending the game. +// +// Windows refuses commit beyond the current limit while it grows a system-managed page file, and on some drivers device +// memory counts as process commit (vk_memory.c vk_mem_host_probe), so for a moment every allocation of the process can +// fail and the same request succeeds a little later. The failure sites (memory.c commit, vk_memory.c vk_staging, +// vk_texture.c create_tex, vk_exec_draw.c transient chunks, nvn_api_cmd.c realloc_wait) ask the Vulkan back end to give +// memory back (rt_oom_request: released textures and headroom blocks, at its next submit, where its locks are free) and +// retry for up to OOM_WAIT_MS before they end the game. +// +// TOTK_TEST_OOM=:[,:...] (sites commit, staging, image, chunk) fails the first n attempts at a site, so +// the wait can be tested without running out of memory; the probes arm it with rt_oom_force. +#include +#include + +#include "cfg.h" +#include "host.h" +#include "platform/platform.h" + +#define OOM_WAIT_MS 30000u +#define OOM_STEP_MS 10u +#define OOM_REPORTS 8 +#define OOM_REQUEST_EVERY 100 // retries between two release requests: a second, since a release only frees what is old enough + +volatile int32_t rt_oom_req; + +static const char *const site_name[RT_OOM_SITES] = {"commit", "staging", "image", "chunk"}; +static volatile int32_t force_left[RT_OOM_SITES]; +static volatile int32_t forced_parsed; +static PlatOnce force_once = PLAT_ONCE_INIT; + +static void force_parse(void *arg) { + (void)arg; + const char *s = cfg_get("TOTK_TEST_OOM"); + while (s && *s) { + const char *colon = strchr(s, ':'), *end = strchr(s, ','); + if (!end) end = s + strlen(s); + if (colon && colon < end) { + for (int i = 0; i < RT_OOM_SITES; i++) + if ((size_t)(colon - s) == strlen(site_name[i]) && !strncmp(s, site_name[i], (size_t)(colon - s))) { + int n = atoi(colon + 1); + __atomic_store_n(&force_left[i], n > 0 ? n : 0, __ATOMIC_RELAXED); + rt_log("oom: TOTK_TEST_OOM fails the first %d %s attempts", n, site_name[i]); + } + } + s = *end ? end + 1 : end; + } + __atomic_store_n(&forced_parsed, 1, __ATOMIC_RELEASE); +} + +int rt_oom_forced(int site) { + if (!__atomic_load_n(&forced_parsed, __ATOMIC_ACQUIRE)) plat_once(&force_once, force_parse, NULL); + if (__atomic_load_n(&force_left[site], __ATOMIC_RELAXED) <= 0) return 0; + return plat_dec32(&force_left[site]) >= 0; +} + +void rt_oom_force(int site, int n) { + if (!__atomic_load_n(&forced_parsed, __ATOMIC_ACQUIRE)) plat_once(&force_once, force_parse, NULL); + __atomic_store_n(&force_left[site], n, __ATOMIC_RELAXED); +} + +int rt_oom_forced_left(int site) { + int n = __atomic_load_n(&force_left[site], __ATOMIC_RELAXED); + return n > 0 ? n : 0; +} + +void rt_oom_request(void) { __atomic_store_n(&rt_oom_req, 1, __ATOMIC_RELEASE); } + +int rt_oom_wait(const char *what, uint64_t bytes, int (*retry)(void *arg), void *arg) { + rt_oom_request(); + static volatile int32_t reports; + int report = plat_inc32(&reports) <= OOM_REPORTS; + double proc, used, limit; + if (report) { + plat_commit_info(&proc, &used, &limit); + rt_log("%s of %llu bytes failed (memory commit: this process %.0f MB, the system %.0f of %.0f MB); waiting up " + "to %u s for memory", what, (unsigned long long)bytes, proc, used, limit, OOM_WAIT_MS / 1000); + } + uint64_t t0 = plat_now_ms(); + for (int n = 1; plat_now_ms() - t0 < OOM_WAIT_MS; n++) { + plat_sleep_ms(OOM_STEP_MS); + if (retry(arg)) { + if (report) + rt_log("%s of %llu bytes succeeded after %llu ms", what, (unsigned long long)bytes, + (unsigned long long)(plat_now_ms() - t0)); + return 1; + } + if (n % OOM_REQUEST_EVERY == 0) rt_oom_request(); + } + plat_commit_info(&proc, &used, &limit); + rt_log("%s of %llu bytes still failed after %u s (memory commit: this process %.0f MB, the system %.0f of %.0f MB)", + what, (unsigned long long)bytes, OOM_WAIT_MS / 1000, proc, used, limit); + return 0; +} + +typedef struct { void *old, *p; size_t n; } Realloc; +static int realloc_try(void *arg) { + Realloc *r = arg; + return (r->p = realloc(r->old, r->n)) != NULL; +} + +void *rt_realloc_wait(void *old, size_t n, const char *what) { + void *p = realloc(old, n); + if (p || !n) return p; + Realloc r = {old, NULL, n}; + return rt_oom_wait(what, n, realloc_try, &r) ? r.p : NULL; +} diff --git a/runtime/vk.h b/runtime/vk.h index 9cac3e54..9ca1051d 100644 --- a/runtime/vk.h +++ b/runtime/vk.h @@ -314,6 +314,8 @@ int vk_mem_uma(void); // 1: the device class is uma (vk_ const VmaDeviceMemoryCallbacks *vk_headroom_callbacks(void); void vk_headroom_start(void); void vk_headroom_stop(void); // before vmaDestroyAllocator +void vk_headroom_release(void); // after a failed allocation: frees the spare blocks and keeps none for a while; + // any thread that holds no VMA lock (takes only the headroom lock) int vk_mem_resolve(uint64_t addr, uint64_t size, VkMemSpan *out); // 1 when all of [addr, addr+size) is backed // Changes whenever vk_mem_resolve plus VK_MEM_USE may give another span for an address: a pool added, finalized or // mapped, a mirror created, refused or forgotten, a submission started. @@ -402,6 +404,10 @@ int vk_mem_span_live(const VkMemSpan *sp); void vk_mem_note_fence(uint64_t timeline_value); void vk_mem_fault_log(void); // vk_device_fault_report: the deferred-free state, lock-free void vk_mem_collect(void); // frees what has completed +// After a failed allocation, on a thread that may hold the texture lock and the upload lock (cmd_lock) but no VMA +// lock: frees the headroom blocks and the completed upload batches and deferred objects, and requests the release +// of released textures at the next submit (rt_oom_request). +void vk_oom_release(void); typedef struct { uint64_t imported_pools, physical_pools, virtual_pools, import_failures, upload_batches; } VkMemStats; void vk_mem_stats(VkMemStats *s); void vk_mem_shutdown(void); // before vk_shutdown: waits idle, frees every memory and texture object diff --git a/runtime/vk_exec_draw.c b/runtime/vk_exec_draw.c index 51a2e829..f7ed6d10 100644 --- a/runtime/vk_exec_draw.c +++ b/runtime/vk_exec_draw.c @@ -363,6 +363,16 @@ static CbRes *cb_res(VkExec *ex) { return D->cur; } +typedef struct { const VkBufferCreateInfo *bi; const VmaAllocationCreateInfo *ai; Chunk *c; VmaAllocationInfo info; + VkResult r; } ChunkTry; +static int chunk_try(void *arg) { + ChunkTry *t = arg; + vk_mem_collect(); // the fence thread's collect waits while the caller holds cmd_lock + t->r = rt_oom_forced(RT_OOM_CHUNK) ? VK_ERROR_OUT_OF_DEVICE_MEMORY + : vmaCreateBuffer(vk_ctx()->vma, t->bi, t->ai, &t->c->buf, &t->c->alloc, &t->info); + return t->r == VK_SUCCESS; +} + static uint8_t *scratch(VkExec *ex, uint64_t size, VkBuffer *buf, VkDeviceSize *off) { CbRes *r = cb_res(ex); size = (size + 255) & ~255ull; @@ -396,10 +406,17 @@ static uint8_t *scratch(VkExec *ex, uint64_t size, VkBuffer *buf, VkDeviceSize * VmaAllocationCreateInfo ai = {.usage = VMA_MEMORY_USAGE_AUTO_PREFER_HOST, .flags = VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT | VMA_ALLOCATION_CREATE_MAPPED_BIT, .requiredFlags = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT}; - VmaAllocationInfo info; - VkResult res = vmaCreateBuffer(vk_ctx()->vma, &bi, &ai, &c->buf, &c->alloc, &info); - if (res != VK_SUCCESS) rt_fatal("vk: transient buffer of %llu bytes failed (%d)", (unsigned long long)n, (int)res); - c->map = info.pMappedData, c->size = n, c->used = 0; + // Out of memory: the recording waits for memory (rt_oom_wait) with what it holds (the texture lock at most, + // which vk_oom_release takes before cmd_lock); new chunks are made only when the spare ones ran out. + ChunkTry ct = {.bi = &bi, .ai = &ai, .c = c}; + ct.r = rt_oom_forced(RT_OOM_CHUNK) ? VK_ERROR_OUT_OF_DEVICE_MEMORY + : vmaCreateBuffer(vk_ctx()->vma, &bi, &ai, &c->buf, &c->alloc, &ct.info); + if (ct.r == VK_ERROR_OUT_OF_HOST_MEMORY || ct.r == VK_ERROR_OUT_OF_DEVICE_MEMORY) { + vk_oom_release(); + rt_oom_wait("vk: transient buffer", n, chunk_try, &ct); + } + if (ct.r != VK_SUCCESS) rt_fatal("vk: transient buffer of %llu bytes failed (%d)", (unsigned long long)n, (int)ct.r); + c->map = ct.info.pMappedData, c->size = n, c->used = 0; r->nchunks++; } *buf = c->buf; diff --git a/runtime/vk_exec_probe.c b/runtime/vk_exec_probe.c index 9d244cdf..825b47a6 100644 --- a/runtime/vk_exec_probe.c +++ b/runtime/vk_exec_probe.c @@ -968,6 +968,9 @@ int probe_vkexec(void) { const GfxBackend *b = &gfx_vulkan_backend; uint64_t heap = 0; CHECK(mem_set_heap_size(16ull << 20, &heap) == 0 && heap, "SetHeapSize 16 MiB"); + // Out-of-memory waits (oom.c): the first two staging buffers, the first texture image and the first draw-data chunk + // fail; every part below passes through the wait or the retry that follows. + rt_oom_force(RT_OOM_STAGING, 2), rt_oom_force(RT_OOM_IMAGE, 1), rt_oom_force(RT_OOM_CHUNK, 1); uint8_t *guest = (uint8_t *)(uintptr_t)heap; uint64_t first = 0, last = 0; int w = 0, h = 0, inside = 0, xfer_bytes = 0; @@ -989,6 +992,12 @@ int probe_vkexec(void) { vk_exec_xfer_shutdown(); vk_backend_shutdown(); long errors = vk_validation_errors_total(); + int oom_left[3] = {rt_oom_forced_left(RT_OOM_STAGING), rt_oom_forced_left(RT_OOM_IMAGE), rt_oom_forced_left(RT_OOM_CHUNK)}; + if (!bad && !errors && (oom_left[0] || oom_left[1] || oom_left[2])) { + printf("probe-vkexec: FAILED (forced allocation failures never reached: staging %d, image %d, chunk %d)\n", + oom_left[0], oom_left[1], oom_left[2]); + return 1; + } if (bad || errors) { printf("probe-vkexec: FAILED (%s, %ld validation errors)\n", sync_bad ? "a sync check failed" : draw_bad ? "a draw check failed" : bad ? "a clear or xfer check failed" : "checks passed", errors); @@ -1034,5 +1043,7 @@ int probe_vkexec(void) { "finished mark is the last pass, ring records exact); the report reads:\n%s\n", marks_text); printf("probe-vkexec: empty pool part passed (a zero-byte pool at the start of another: no Vulkan objects, lookups " "there find the other pool before and after its Finalize)\n"); + printf("probe-vkexec: out-of-memory part passed (2 failed staging buffers waited for, 1 failed texture image retried, " + "1 failed draw-data chunk waited for)\n"); return 0; } diff --git a/runtime/vk_headroom.c b/runtime/vk_headroom.c index 88083025..ccbacb06 100644 --- a/runtime/vk_headroom.c +++ b/runtime/vk_headroom.c @@ -12,7 +12,8 @@ // a block per memory type is held back. // Under VRAM pressure no headroom is kept: the spare block counts against the budget that decides whether a pool gets // its VRAM mirror (vk_memory.c), so while use plus two blocks passes 85% of the budget the anchor goes and nothing new -// is allocated. The same holds when the system runs short of memory (room). +// is allocated. The same holds when the system runs short of memory (room), and for HR_HOLD_MS after an allocation +// failed anywhere (vk_headroom_release). // TOTK_VRAM_HEADROOM=0 turns it off. #include "cfg.h" @@ -22,6 +23,7 @@ #define HR_PERIOD_MS 500 #define HR_SMALL_HEAP (1ull << 30) // VMA_SMALL_HEAP_MAX_SIZE: smaller heaps use blocks of a heap eighth +#define HR_HOLD_MS 30000u static struct { int on, stop; @@ -33,6 +35,7 @@ static struct { volatile int64_t made; // blocks this thread brought in volatile int64_t other; // device memory of 32 MiB or more other threads allocated (VMA blocks, large dedicated) VmaAllocation anchor[64]; // per memory type: the half block that keeps the newest spare block from being deleted + volatile uint64_t hold_until; // plat_now_ms before which no spare block is kept (vk_headroom_release) } H; static void VKAPI_PTR on_allocate(VmaAllocator a, uint32_t type, VkDeviceMemory m, VkDeviceSize size, void *user) { @@ -79,7 +82,7 @@ static void top_up(const VkCtx *c, uint32_t type) { // blocks (vk_memory.c vk_staging), while their default pool held 4 MiB: on the RX 9070 the spare blocks of types 1 // and 3 held 512 MiB of commit for nothing. if (!(c->mem_props.memoryTypes[type].propertyFlags & VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT) || - !room(c, type, block)) { + plat_now_ms() < __atomic_load_n(&H.hold_until, __ATOMIC_RELAXED) || !room(c, type, block)) { drop_anchor(c, type); return; } @@ -132,6 +135,22 @@ void vk_headroom_stop(void) { plat_event_set(&H.ev); } +// After a failed allocation: the spare blocks go at once (an empty VMA block takes the next allocation of its type or +// is given back), and none is kept for HR_HOLD_MS. H.lock is held only around VMA calls, so the caller may hold any lock +// of ours, just no VMA lock. +void vk_headroom_release(void) { + __atomic_store_n(&H.hold_until, plat_now_ms() + HR_HOLD_MS, __ATOMIC_RELAXED); + if (!H.started) return; + int n = 0; + plat_mutex_lock(&H.lock); + const VkCtx *c = H.stop ? NULL : vk_ctx(); + for (uint32_t t = 0; c && t < 64; t++) + if (H.anchor[t]) drop_anchor(c, t), n++; + plat_mutex_unlock(&H.lock); + static volatile int32_t logged; + if (n && plat_inc32(&logged) <= 8) rt_log("vk: headroom: %d spare blocks freed after a failed allocation", n); +} + void vk_headroom_start(void) { if (!H.on || H.started) return; plat_mutex_init(&H.lock); diff --git a/runtime/vk_memory.c b/runtime/vk_memory.c index c887a560..9300e9cd 100644 --- a/runtime/vk_memory.c +++ b/runtime/vk_memory.c @@ -2482,6 +2482,20 @@ void vk_upload_end(void) { plat_rmutex_unlock(&cmd_lock); } static VmaPool stg_pool; static int stg_pool_tried; +typedef struct { const VkBufferCreateInfo *bi; const VmaAllocationCreateInfo *aci; VkBuffer b; VmaAllocation a; + VmaAllocationInfo info; VkResult r; } StgTry; +static int staging_try(void *arg) { + StgTry *t = arg; + vk_mem_collect(); // upload batches and deferred objects the GPU finished meanwhile + t->r = rt_oom_forced(RT_OOM_STAGING) ? VK_ERROR_OUT_OF_DEVICE_MEMORY + : vmaCreateBuffer(vk_ctx()->vma, t->bi, t->aci, &t->b, &t->a, &t->info); + return t->r == VK_SUCCESS; +} + +// A failed staging buffer waits for memory (rt_oom_wait) before it ends the game: the headroom blocks go and the GPU's +// finished batches are freed at once, released textures at the next submit (vk_oom_release). The caller may hold the +// texture lock and cmd_lock (vk_upload_begin), both of which vk_oom_release may take after them, and no VMA lock. The open +// batch is not submitted: its caller records into it after this returns. void *vk_staging(VkDeviceSize size, VkBuffer *buf, VmaAllocation *alloc) { VkCtx *c = vk_ctx(); VkBufferCreateInfo bi = {.sType = VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO, .size = size ? size : 16, @@ -2505,11 +2519,22 @@ void *vk_staging(VkDeviceSize size, VkBuffer *buf, VmaAllocation *alloc) { plat_rmutex_unlock(&cmd_lock); } if (stg_pool && bi.size <= STG_BLOCK / 2) aci.pool = stg_pool; - VmaAllocationInfo info; - VkBuffer b; - VmaAllocation a; - VkResult r = vmaCreateBuffer(c->vma, &bi, &aci, &b, &a, &info); - if (r != VK_SUCCESS) rt_fatal("vk: staging buffer of %llu bytes failed (%d)", (unsigned long long)size, (int)r); + StgTry st = {.bi = &bi, .aci = &aci}; + st.r = rt_oom_forced(RT_OOM_STAGING) ? VK_ERROR_OUT_OF_DEVICE_MEMORY + : vmaCreateBuffer(c->vma, &bi, &aci, &st.b, &st.a, &st.info); + if (st.r != VK_SUCCESS) { + VkResult first = st.r; + if (first == VK_ERROR_OUT_OF_HOST_MEMORY || first == VK_ERROR_OUT_OF_DEVICE_MEMORY) { + vk_oom_release(); + rt_oom_wait("vk: staging buffer", bi.size, staging_try, &st); + } + if (st.r != VK_SUCCESS) + rt_fatal("vk: staging buffer of %llu bytes failed (%d, first %d)", (unsigned long long)size, (int)st.r, + (int)first); + } + VkBuffer b = st.b; + VmaAllocation a = st.a; + VmaAllocationInfo info = st.info; *buf = b; if (alloc) *alloc = a; // the caller destroys it (vmaDestroyBuffer) after vk_upload_flush(1) else { @@ -2688,6 +2713,15 @@ void vk_mem_collect(void) { plat_rmutex_unlock(&cmd_lock); } +// Lock order: the texture lock, then cmd_lock (create_tex records under the first), then the headroom lock, which is +// held only around VMA calls. A caller holding cmd_lock takes it again (recursive) and keeps the fence thread's own +// collect (vk_sync.c) out meanwhile, so this collects for it. +void vk_oom_release(void) { + rt_oom_request(); + vk_headroom_release(); + vk_mem_collect(); +} + void vk_mem_stats(VkMemStats *s) { memset(s, 0, sizeof *s); plat_mutex_lock_shared(&pool_lock); diff --git a/runtime/vk_texture.c b/runtime/vk_texture.c index a2a9ea41..9ebd7a0b 100644 --- a/runtime/vk_texture.c +++ b/runtime/vk_texture.c @@ -458,7 +458,19 @@ static Tex *create_tex(const tex_t *t, const TexKey *k, int defer_init) { } if (!img) { VmaAllocationCreateInfo ai = {.usage = VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE}; - VkResult r = vmaCreateImage(c->vma, &ci, &ai, &img, &e->alloc, NULL); + VkResult r = rt_oom_forced(RT_OOM_IMAGE) ? VK_ERROR_OUT_OF_DEVICE_MEMORY + : vmaCreateImage(c->vma, &ci, &ai, &img, &e->alloc, NULL); + // Out of memory: one more try after the headroom blocks and the finished deferred objects are freed + // (vk_oom_release, which takes cmd_lock after the texture lock held here); released textures go at the next + // submit. No wait: the texture is asked for again at its next use, while a wait would hold the texture lock. + if (r == VK_ERROR_OUT_OF_HOST_MEMORY || r == VK_ERROR_OUT_OF_DEVICE_MEMORY) { + static volatile int32_t n_retried; + vk_oom_release(); + VkResult again = vmaCreateImage(c->vma, &ci, &ai, &img, &e->alloc, NULL); + log_limited(&n_retried, "image creation failed (%d), tried again after a memory release: %s (%ux%ux%u fmt %#x)", + (int)r, again == VK_SUCCESS ? "created" : "failed again", w, h, depth, d->format); + r = again; + } if (r != VK_SUCCESS) { log_limited(&n_failed, "image creation failed (%d): nvn fmt %#x %ux%ux%u target %d levels %u layers %u", (int)r, d->format, w, h, depth, d->target, levels, layers); @@ -703,16 +715,19 @@ static int dead_candidate(const Tex *e) { // Drops overwritten entries until `need` bytes are free or the step is used up. The sort runs only under pressure, while // an old enough entry exists, and rests for a while when it finds nothing to drop. Returns the bytes freed. static uint64_t pressure_search_ns; // longest search since the last mem: released line -static uint64_t drop_overwritten(uint64_t need, int *dropped) { +// step: PRESSURE_STEP, or OOM_STEP from oom_release, which neither waits out nor starts the rest. +#define OOM_STEP 256 +static uint64_t drop_overwritten(uint64_t need, int *dropped, int step) { static int rest; - if (rest > 0) { rest--; return 0; } + int urgent = step > PRESSURE_STEP; + if (rest > 0 && !urgent) { rest--; return 0; } if (!rel_head || coarse_ms - rel_head->rel_ms < DEAD_AGE_MS) return 0; uint64_t t0 = plat_now_ns(), freed = 0; AddrIndex x; if (!addr_index(&x)) return 0; - Tex *cand[PRESSURE_STEP]; + Tex *cand[OOM_STEP]; int nc = 0; - for (Tex *e = rel_head; e && nc < PRESSURE_STEP && coarse_ms - e->rel_ms >= DEAD_AGE_MS; e = e->rel_next) { + for (Tex *e = rel_head; e && nc < step && coarse_ms - e->rel_ms >= DEAD_AGE_MS; e = e->rel_next) { if (!dead_candidate(e)) continue; int lo = 0, hi = x.n; // the first entry at e's address, then e among those while (lo < hi) { @@ -730,12 +745,25 @@ static uint64_t drop_overwritten(uint64_t need, int *dropped) { destroy_tex(cand[i]); (*dropped)++, n_pressure_drops++, n_pressure_overwritten++; } - if (!nc) rest = DEAD_RETRY_QUERIES; + if (!nc && !urgent) rest = DEAD_RETRY_QUERIES; uint64_t ns = plat_now_ns() - t0; if (ns > pressure_search_ns) pressure_search_ns = ns; return freed; } +// Clean released entries, oldest first: mirrored ones the GPU never wrote, which come back from their storage. +static uint64_t drop_clean(uint64_t need, uint64_t freed, int *dropped, int step) { + for (Tex *e = rel_head, *next; e && freed < need && *dropped < step && coarse_ms - e->rel_ms >= CLEAN_AGE_MS; e = next) { + next = e->rel_next; + if (!e->pub.mirrored || e->pub.gpu_owned || e->gpu_dirty) continue; + freed += own_bytes(e); + dropped_note(e); + destroy_tex(e); + (*dropped)++, n_pressure_drops++; + } + return freed; +} + static void sweep_pressure(void) { // tex_lock held if (vram_pressure < 0) { const char *s = cfg_get("TOTK_TEX_VRAM_PRESSURE"); @@ -750,15 +778,22 @@ static void sweep_pressure(void) { // tex_lock held uint64_t line = budget / 100 * (uint64_t)vram_pressure; if (used <= line) return; int dropped = 0; - uint64_t need = used - line, freed = drop_overwritten(need, &dropped); - for (Tex *e = rel_head, *next; e && freed < need && dropped < PRESSURE_STEP && coarse_ms - e->rel_ms >= CLEAN_AGE_MS; e = next) { - next = e->rel_next; - if (!e->pub.mirrored || e->pub.gpu_owned || e->gpu_dirty) continue; - freed += own_bytes(e); - dropped_note(e); - destroy_tex(e); - dropped++, n_pressure_drops++; - } + uint64_t need = used - line, freed = drop_overwritten(need, &dropped, PRESSURE_STEP); + drop_clean(need, freed, &dropped, PRESSURE_STEP); +} + +// rt_oom_request (an allocation failed somewhere, oom.c): the same two kinds as sweep_pressure, as many as OOM_STEP +// whatever the budget says, and the headroom blocks. Never GPU-written content that lives only in its image. The memory +// comes back once the submission being recorded is done (destroy_tex defers the images). Texture lock held. +static void oom_release(void) { + int dropped = 0; + uint64_t freed = drop_overwritten(UINT64_MAX, &dropped, OOM_STEP); + int overwritten = dropped; + freed = drop_clean(UINT64_MAX, freed, &dropped, OOM_STEP); + vk_headroom_release(); + static volatile int32_t n_logged; + log_limited(&n_logged, "out of memory: %d released textures dropped (%d overwritten, %d clean), %.0f MiB, %d kept", + dropped, overwritten, dropped - overwritten, freed / 1048576.0, nreleased); } // ---------------------------------------------------------------- uploads @@ -1714,6 +1749,8 @@ void vk_texture_new_submit(void) { if (!++submit_epoch) submit_epoch = 1; coarse_ms = plat_now_ms(); sweep_pressure(); + if (__atomic_load_n(&rt_oom_req, __ATOMIC_RELAXED) && __atomic_exchange_n(&rt_oom_req, 0, __ATOMIC_ACQUIRE)) + oom_release(); static uint64_t log_at; uint64_t f = __atomic_load_n(&gfx_counters.frames, __ATOMIC_RELAXED) / 60; if ((rt_trace & RT_TRACE_PERF) && f != log_at && tex_alias > 0) { @@ -2037,7 +2074,12 @@ static void write_back_n(Tex **v, int n) { if (np) vk_upload_flush(1); for (int i = 0; i < np; i++) { WbPart *q = &p[i]; - uint8_t *buf = malloc(q->g.img * (size_t)q->g.nz); + size_t bytes = q->g.img * (size_t)q->g.nz; + uint8_t *buf = malloc(bytes); + if (!buf) { // waits for memory with the texture lock held, after the release that needs no submit + vk_oom_release(); + buf = rt_realloc_wait(NULL, bytes, "vk: texture write-back buffer"); + } if (!buf) rt_fatal("vk: out of memory for a texture write-back"); texels_read_take(q->e, &q->g, &q->t, buf); storage_texels(&q->e->t, &q->g, &q->r, buf, 1); From 34b340a2085426ae2f6cd4b82266a4e337f96468 Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 09:57:32 +0300 Subject: [PATCH 09/16] Cap the released-texture cache by bytes Released textures stayed until 2048 of them were kept or VRAM passed 90% of the budget. On the RX 9070 a 10-minute field run kept 818 MiB of them, while almost every take-back came within a second. TOTK_TEX_RELEASED_MIB (default 256) runs the same drops as under VRAM pressure while the released entries hold more own memory than that. On the same route the run ended with 1.1 GB less process commit and 1 GB less in VMA blocks; 15 dropped textures were created again and the slow frames did not change. Also documents TOTK_MEM_RESERVE_MIB. Co-Authored-By: Claude Opus 5.5 --- docs/settings.md | 2 ++ runtime/cfg.c | 7 ++++--- runtime/vk_texture.c | 41 ++++++++++++++++++++++++++++++++--------- 3 files changed, 38 insertions(+), 12 deletions(-) diff --git a/docs/settings.md b/docs/settings.md index 20a51ef2..2be80094 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -181,6 +181,7 @@ Many rows below are developer tools that only act together with another setting | --- | --- | --- | --- | | `app_pool` | Size in bytes of the guest application memory pool; accepts decimal or `0x` hex. | The default depends on the resolution settings; `0` stops the start with a message, and too small a pool leaves the game without memory. | Risky | | `audio_off` | Any value mixes audio without opening an output device. | The game runs in silence and reports two channels; same as `audio = none`. | Caution | +| `mem_reserve_mib` (default `1536`) | MiB of system memory kept free for Windows, other programs and the game's own heap when the renderer sizes what it keeps in device memory, where device memory takes system memory (integrated GPUs, and discrete GPUs whose driver charges it to the process). | A larger value keeps fewer released textures and spare blocks when the system runs short; a smaller one lets the game use more before it holds back. | Caution | | `one_per_core` (default `0`) | `1` keeps the process on the first logical processor of each physical core; `ab` switches it with the `ab` blocks. | Busy threads stop sharing a core with a sibling thread, which can help or hurt on the CPU; it only applies when the CPU has hyperthreads. | Caution | | `reexec` | Counter of address-space retries that the runtime sets itself when it starts the process again. | The counter is cleared when the window is recreated; a value of 20 or more stops the start with a fatal error. | Risky | | `replay_chunks` (default `0`) | Most chunks a submission is cut into when `replay_workers` is set; `0` uses twice the number of recording threads. | Fewer chunks leave threads idle at the end of a submission, more add scan and submit work per chunk; no effect while `replay_workers` is `0`. | Caution | @@ -190,6 +191,7 @@ Many rows below are developer tools that only act together with another setting | `restart_wait` | Set by the runtime when it restarts itself; names the old process by id and creation time so the new process waits for it to exit. | Meant for the runtime's own use; the code does not describe a manual value. | Unknown | | `spin` (default `1`) | `0` makes a guest thread that polls memory keep its virtual core. | Polling threads can starve the thread whose item they wait for, so frames can stall. | Caution | | `spin_handoff_us` (default `50`) | Microseconds a polling wait lasts before it gives its virtual core to a waiting thread. | A shorter value hands cores over sooner; a longer one keeps them longer. | Caution | +| `tex_released_mib` (default `256`) | MiB of textures the game released that are kept for reuse; older ones beyond it are dropped. `0` keeps up to 2048 of them, whatever their size. | A larger value keeps more device memory and process commit; a smaller one makes the game create more textures again. | Caution | ## Generated-code patches diff --git a/runtime/cfg.c b/runtime/cfg.c index 2d79b5fc..73660ba0 100644 --- a/runtime/cfg.c +++ b/runtime/cfg.c @@ -59,7 +59,7 @@ static const char *const known[] = { "SHADER_MEMO", "SHADOW_RANGE", "SHADOW_RES", "SHADOW_SCALE", "SHADOW_SNAP", "SHARED_FONTS", "SHARPNESS", "SHOTS", "SHOTS_DIR", "SHOTS_FULL", "SPEED_PROBE", "SPIN", "SPIN_HANDOFF_US", "SPLIT_DRAWS", "SPLIT_US", "STICK_DEADZONE", "STICK_SENS", "SWKBD_ANSWER", - "SWKBD_TEST", "TEST_PAD", "TEST_PREPARE_SHADERS", "TEX_ALIAS", "TEX_HEAP_EXTRA_MB", "TEX_MEMO", "TEX_VRAM_PRESSURE", "TIMER_1MS", "TRACE", "TXD_TRANSPOSE", "UBO_SNAPSHOT", "UB_OVERLAY", "UB_OVERLAY_OUT", "UPSCALER", "VB_USED", "VK_DYN_A2C", "VK_DYN_VERTEX", "VK_NO_FLOAT64", + "SWKBD_TEST", "TEST_PAD", "TEST_PREPARE_SHADERS", "TEX_ALIAS", "TEX_HEAP_EXTRA_MB", "TEX_MEMO", "TEX_RELEASED_MIB", "TEX_VRAM_PRESSURE", "TIMER_1MS", "TRACE", "TXD_TRANSPOSE", "UBO_SNAPSHOT", "UB_OVERLAY", "UB_OVERLAY_OUT", "UPSCALER", "VB_USED", "VK_DYN_A2C", "VK_DYN_VERTEX", "VK_NO_FLOAT64", "VK_PRESENT", "VK_RECORDER", "VK_SSBO_ALIGN", "VK_SUBGROUP", "VK_SUBGROUP_PIN", "VK_VALIDATION", "VOLUME", "VRAM_HEADROOM", "VRAM_LIMIT_MIB", "VS_OUTS", "WALK_KEY", "WALK_SCALE", "WB_EXACT", "WB_FENCE_LIMIT", "WB_MERGE", "WINDOW_SIZE", "XLATE", "XLATE_ID", "XLATE_KEEP", "XLATE_PROCS", "ZSTD_CHECK", "ZSTD_NATIVE", @@ -99,7 +99,7 @@ static const struct { const char *key, *section; } sections[] = { {"TIMER_1MS", "performance"}, {"PIPE_WAIT", "performance"}, {"PIPE_SKIP", "performance"}, {"LIB_PREBUILD", "performance"}, {"LIB_PREBUILD_THREADS", "performance"}, {"PIPE_PREBUILD", "performance"}, {"PREWARM_XLATE", "performance"}, {"GPL", "performance"}, {"ASTC", "performance"}, {"MEMORY", "performance"}, - {"TEX_ALIAS", "performance"}, {"TEX_VRAM_PRESSURE", "performance"}, {"ASTC_BC", "performance"}, {"LOD_GUARD", "performance"}, {"FIX_C0", "performance"}, {"FIX_ZERO", "performance"}, + {"TEX_ALIAS", "performance"}, {"TEX_VRAM_PRESSURE", "performance"}, {"TEX_RELEASED_MIB", "performance"}, {"ASTC_BC", "performance"}, {"LOD_GUARD", "performance"}, {"FIX_C0", "performance"}, {"FIX_ZERO", "performance"}, {"BIND_SKIP", "performance"}, {"SHADER_MEMO", "performance"}, {"PIPE_MEMO", "performance"}, {"TEX_MEMO", "performance"}, {"VB_USED", "performance"}, {"DESC_TEMPLATE", "performance"}, {"PUSH_SKIP", "performance"}, {"SPLIT_DRAWS", "performance"}, {"SPLIT_US", "performance"}, {"VK_VALIDATION", "performance"}, {"VK_DYN_VERTEX", "performance"}, {"VK_DYN_A2C", "performance"}, {"VK_SUBGROUP_PIN", "performance"}, @@ -173,7 +173,8 @@ static const CfgMeta metas[] = { {"PIPE_PREBUILD", "1", "0|1", RESTART}, {"PREWARM_XLATE", "", "1..64", RESTART}, {"GPL", "1", "0|1", RESTART}, // textures and memory {"ASTC", "auto", "auto|gpu|native|cpu", RESTART}, {"MEMORY", "auto", "auto|import|mirror|verify", RESTART}, - {"TEX_ALIAS", "1", "0|1", RESTART}, {"TEX_VRAM_PRESSURE", "90", "0..100", RESTART}, {"ASTC_BC", "", "0|1", RESTART}, {"ZSTD_NATIVE", "1", "0|1", RESTART}, {"ZSTD_CHECK", "0", "0|1", RESTART}, + {"TEX_ALIAS", "1", "0|1", RESTART}, {"TEX_VRAM_PRESSURE", "90", "0..100", RESTART}, + {"TEX_RELEASED_MIB", "256", "0..65536", RESTART}, {"ASTC_BC", "", "0|1", RESTART}, {"ZSTD_NATIVE", "1", "0|1", RESTART}, {"ZSTD_CHECK", "0", "0|1", RESTART}, // render fixes {"LOD_GUARD", "1", "0|1", RESTART}, {"FIX_C0", "1", "0|1", RESTART}, {"FIX_ZERO", "1", "0|1", RESTART}, {"BIND_SKIP", "1", "0|1", RESTART}, {"SHADER_MEMO", "1", "0|1", RESTART}, {"PIPE_MEMO", "1", "0|1", RESTART}, {"TEX_MEMO", "1", "0|1", RESTART}, diff --git a/runtime/vk_texture.c b/runtime/vk_texture.c index a2a9ea41..1dd7662d 100644 --- a/runtime/vk_texture.c +++ b/runtime/vk_texture.c @@ -64,6 +64,7 @@ typedef struct Tex { uint32_t wt_n; // WriteTexels into the storage since the last upload struct Tex *rel_prev, *rel_next; // while released: the list of released entries, oldest first uint64_t rel_ms; // while released: when (coarse_ms) + uint64_t rel_bytes; // while released: its own memory, counted in rel_bytes_total uint64_t use_seq; // order of the last creation or take-back among all entries uint64_t rel_seq; // while released: use_seq of the newest entry placed before this release; an entry // with a later use_seq on overlapping storage replaced this one's bytes @@ -95,6 +96,7 @@ static SampSlot *sslots; static int nsslots; static nvn_hmap samplers = {.klen = sizeof(samp_par)}; static int nreleased; +static uint64_t rel_bytes_total; // own memory of the released entries static Tex *rel_head, *rel_tail; // released entries in release order (sweep_released drops from the head) static uint64_t n_uploads, n_reuploads; // Re-uploads since the last perf line (tex_lock): all, and those of textures a WriteTexels wrote since their last upload. @@ -538,7 +540,11 @@ static void own_remove(Tex *e) { plat_mutex_unlock(&owned_lock); } +static uint64_t own_bytes(const Tex *e); + static void rel_append(Tex *e) { + e->rel_bytes = own_bytes(e); + rel_bytes_total += e->rel_bytes; e->rel_next = NULL; e->rel_prev = rel_tail; if (rel_tail) rel_tail->rel_next = e; @@ -547,6 +553,8 @@ static void rel_append(Tex *e) { } static void rel_unlink(Tex *e) { + rel_bytes_total -= e->rel_bytes; + e->rel_bytes = 0; if (e->rel_prev) e->rel_prev->rel_next = e->rel_next; else rel_head = e->rel_next; if (e->rel_next) e->rel_next->rel_prev = e->rel_prev; @@ -644,12 +652,19 @@ static void sweep_released(void) { // CLEAN_AGE_MS: without the wait a fight re-created about 500 of them per 10 s. Any other render target lives only in its // image: dropping one that was merely old brought the texture back empty (black flashes in a Depths boss fight, ~170 // "left uninitialised" aliases a minute). +// +// TOTK_TEX_RELEASED_MIB (default 256; 0 = no cap): the same drops run while the released entries hold more own memory than +// that, under pressure or not. A 10-minute field run on the RX 9070 kept 818 MiB of them, 730 MiB with their storage +// taken by a later texture, while 23579 of 23660 take-backs came within a second and none after 120 s. With the +// cap the same route ended with 216 MiB of them, 1.1 GB less process commit and 1 GB less in VMA blocks; 15 dropped +// textures were created again, and the slow frames stayed the same. #define PRESSURE_STEP 32 #define CLEAN_AGE_MS 5000u #define DEAD_AGE_MS 30000u #define DEAD_QUIET_SUBMITS 600u #define DEAD_RETRY_QUERIES 8 // budget queries to skip after a search that found nothing static int vram_pressure = -1; +static uint64_t released_cap; static uint64_t n_pressure_drops, n_pressure_overwritten; static int tex_by_addr(const void *a, const void *b) { @@ -741,16 +756,23 @@ static void sweep_pressure(void) { // tex_lock held const char *s = cfg_get("TOTK_TEX_VRAM_PRESSURE"); vram_pressure = s && *s ? atoi(s) : 90; if (vram_pressure < 0 || vram_pressure > 100) vram_pressure = 90; - rt_log("vk: released textures under VRAM pressure: %s%d%%", vram_pressure ? "dropped above " : "off", vram_pressure); + const char *m = cfg_get("TOTK_TEX_RELEASED_MIB"); + released_cap = (m && *m ? strtoull(m, NULL, 10) : 256) << 20; + rt_log("vk: released textures under VRAM pressure: %s%d%%; above %llu MiB of them: %s (TOTK_TEX_RELEASED_MIB)", + vram_pressure ? "dropped above " : "off", vram_pressure, (unsigned long long)(released_cap >> 20), + released_cap ? "dropped" : "no cap"); } - if (!vram_pressure || !rel_head || submit_epoch & 7) return; // the budget query every 8 submits + if (!rel_head || submit_epoch & 7) return; // the budget query every 8 submits + uint64_t need = released_cap && rel_bytes_total > released_cap ? rel_bytes_total - released_cap : 0; uint64_t used, budget; int exact; - if (!vk_mem_vram(&used, &budget, &exact)) return; - uint64_t line = budget / 100 * (uint64_t)vram_pressure; - if (used <= line) return; + if (vram_pressure && vk_mem_vram(&used, &budget, &exact)) { + uint64_t line = budget / 100 * (uint64_t)vram_pressure; + if (used > line && used - line > need) need = used - line; + } + if (!need) return; int dropped = 0; - uint64_t need = used - line, freed = drop_overwritten(need, &dropped); + uint64_t freed = drop_overwritten(need, &dropped); for (Tex *e = rel_head, *next; e && freed < need && dropped < PRESSURE_STEP && coarse_ms - e->rel_ms >= CLEAN_AGE_MS; e = next) { next = e->rel_next; if (!e->pub.mirrored || e->pub.gpu_owned || e->gpu_dirty) continue; @@ -1740,8 +1762,9 @@ void vk_texture_new_submit(void) { (unsigned long long)f * 60, (unsigned long long)ck, (unsigned long long)n_checks, (unsigned long long)calls, (unsigned long long)untr); n_checks = 0; - rt_log("perf: frame %llu: released textures kept %d, dropped under VRAM pressure %llu (%llu overwritten)", - (unsigned long long)f * 60, nreleased, (unsigned long long)n_pressure_drops, + rt_log("perf: frame %llu: released textures kept %d (%.0f MiB), dropped under VRAM pressure or the cap %llu " + "(%llu overwritten)", (unsigned long long)f * 60, nreleased, rel_bytes_total / 1048576.0, + (unsigned long long)n_pressure_drops, (unsigned long long)n_pressure_overwritten); n_pressure_drops = n_pressure_overwritten = 0; } @@ -2533,7 +2556,7 @@ void vk_texture_shutdown(void) { by_addr = (nvn_hmap){.klen = 8}; samplers = (nvn_hmap){.klen = sizeof(samp_par)}; free(tslots), free(sslots); - tslots = NULL, sslots = NULL, ntslots = nsslots = 0, nreleased = 0; + tslots = NULL, sslots = NULL, ntslots = nsslots = 0, nreleased = 0, rel_bytes_total = 0; rel_head = rel_tail = NULL; if (sinfo) memset(sinfo, 0, sizeof *sinfo << 20), memset(sepoch, 0, sizeof *sepoch << 20); // no slot is registered: tokens 0 unlock(); From 0005c01cf5a190f01a7c2d2faf2837a73c307c82 Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 09:51:04 +0300 Subject: [PATCH 10/16] Remove the stray brace in vk_mem_census that stopped vk_memory.c from compiling 79c6951 left the closing brace of a debug block in the per-heap loop, so the function ended early and the build failed. Co-Authored-By: Claude Opus 5.5 --- runtime/vk_memory.c | 1 - 1 file changed, 1 deletion(-) diff --git a/runtime/vk_memory.c b/runtime/vk_memory.c index b493b19d..c887a560 100644 --- a/runtime/vk_memory.c +++ b/runtime/vk_memory.c @@ -589,7 +589,6 @@ void vk_mem_census(uint64_t frame) { "%.0f of %.0f MiB", h, vc->mem_props.memoryHeaps[h].flags, (unsigned long long)frame, vb[h].statistics.blockCount, vb[h].statistics.blockBytes / 1048576.0, vb[h].statistics.allocationCount, vb[h].statistics.allocationBytes / 1048576.0, vb[h].usage / 1048576.0, vb[h].budget / 1048576.0); - } } static const char *const kinds[] = {"", "import", "physical", "virtual"}; for (int j = 0; j < ng; j++) { From 8e05d2b409b35ab81ebd0af7fb250c0be5e058bd Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 10:11:44 +0300 Subject: [PATCH 11/16] Give textures a pool of their own with 64 MiB blocks Textures shared the default 256 MiB blocks with the mirrors and other buffers, and a block went back to the driver only once everything in it was gone. On the RX 9070 after a few minutes of roaming the field, 3 of 9 device-local blocks were 13-27% full, held by a hundred small textures and buffers each, and blocks held 0.8-1.4 GB more than their allocations; where device memory takes process commit, that commit backs nothing. Own-memory textures now go to a VMA pool with 64 MiB blocks (TOTK_TEX_BLOCK_MIB, 0 = the default pools). Images of a quarter block or more, images the driver wants a dedicated allocation for, and images the pool's memory type does not take get memory of their own; the requirements are read before the image is made, since VMA checks neither for a custom pool. The headroom thread keeps the pool's next block ahead like the default pools'. Same 10-minute route: 807 MiB of blocks beyond their allocations instead of 1037, most pool blocks 75-100% full, slow frames not up. Probes pass on v143. Co-Authored-By: Claude Opus 5.5 --- docs/settings.md | 1 + runtime/cfg.c | 6 ++-- runtime/vk.h | 4 +++ runtime/vk_headroom.c | 51 ++++++++++++++++++++++++---------- runtime/vk_memory.c | 64 +++++++++++++++++++++++++++++++++++++++++++ runtime/vk_texture.c | 3 +- 6 files changed, 109 insertions(+), 20 deletions(-) diff --git a/docs/settings.md b/docs/settings.md index 2be80094..daefcc60 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -191,6 +191,7 @@ Many rows below are developer tools that only act together with another setting | `restart_wait` | Set by the runtime when it restarts itself; names the old process by id and creation time so the new process waits for it to exit. | Meant for the runtime's own use; the code does not describe a manual value. | Unknown | | `spin` (default `1`) | `0` makes a guest thread that polls memory keep its virtual core. | Polling threads can starve the thread whose item they wait for, so frames can stall. | Caution | | `spin_handoff_us` (default `50`) | Microseconds a polling wait lasts before it gives its virtual core to a waiting thread. | A shorter value hands cores over sooner; a longer one keeps them longer. | Caution | +| `tex_block_mib` (default `64`) | Block size in MiB of the pool that holds the game's textures; images of a quarter block or more get memory of their own. `0` puts textures in the default pools with the buffers. | Larger blocks hold more memory that no texture uses; smaller ones mean more allocations from the driver. | Caution | | `tex_released_mib` (default `256`) | MiB of textures the game released that are kept for reuse; older ones beyond it are dropped. `0` keeps up to 2048 of them, whatever their size. | A larger value keeps more device memory and process commit; a smaller one makes the game create more textures again. | Caution | ## Generated-code patches diff --git a/runtime/cfg.c b/runtime/cfg.c index 73660ba0..f86ad083 100644 --- a/runtime/cfg.c +++ b/runtime/cfg.c @@ -59,7 +59,7 @@ static const char *const known[] = { "SHADER_MEMO", "SHADOW_RANGE", "SHADOW_RES", "SHADOW_SCALE", "SHADOW_SNAP", "SHARED_FONTS", "SHARPNESS", "SHOTS", "SHOTS_DIR", "SHOTS_FULL", "SPEED_PROBE", "SPIN", "SPIN_HANDOFF_US", "SPLIT_DRAWS", "SPLIT_US", "STICK_DEADZONE", "STICK_SENS", "SWKBD_ANSWER", - "SWKBD_TEST", "TEST_PAD", "TEST_PREPARE_SHADERS", "TEX_ALIAS", "TEX_HEAP_EXTRA_MB", "TEX_MEMO", "TEX_RELEASED_MIB", "TEX_VRAM_PRESSURE", "TIMER_1MS", "TRACE", "TXD_TRANSPOSE", "UBO_SNAPSHOT", "UB_OVERLAY", "UB_OVERLAY_OUT", "UPSCALER", "VB_USED", "VK_DYN_A2C", "VK_DYN_VERTEX", "VK_NO_FLOAT64", + "SWKBD_TEST", "TEST_PAD", "TEST_PREPARE_SHADERS", "TEX_ALIAS", "TEX_BLOCK_MIB", "TEX_HEAP_EXTRA_MB", "TEX_MEMO", "TEX_RELEASED_MIB", "TEX_VRAM_PRESSURE", "TIMER_1MS", "TRACE", "TXD_TRANSPOSE", "UBO_SNAPSHOT", "UB_OVERLAY", "UB_OVERLAY_OUT", "UPSCALER", "VB_USED", "VK_DYN_A2C", "VK_DYN_VERTEX", "VK_NO_FLOAT64", "VK_PRESENT", "VK_RECORDER", "VK_SSBO_ALIGN", "VK_SUBGROUP", "VK_SUBGROUP_PIN", "VK_VALIDATION", "VOLUME", "VRAM_HEADROOM", "VRAM_LIMIT_MIB", "VS_OUTS", "WALK_KEY", "WALK_SCALE", "WB_EXACT", "WB_FENCE_LIMIT", "WB_MERGE", "WINDOW_SIZE", "XLATE", "XLATE_ID", "XLATE_KEEP", "XLATE_PROCS", "ZSTD_CHECK", "ZSTD_NATIVE", @@ -99,7 +99,7 @@ static const struct { const char *key, *section; } sections[] = { {"TIMER_1MS", "performance"}, {"PIPE_WAIT", "performance"}, {"PIPE_SKIP", "performance"}, {"LIB_PREBUILD", "performance"}, {"LIB_PREBUILD_THREADS", "performance"}, {"PIPE_PREBUILD", "performance"}, {"PREWARM_XLATE", "performance"}, {"GPL", "performance"}, {"ASTC", "performance"}, {"MEMORY", "performance"}, - {"TEX_ALIAS", "performance"}, {"TEX_VRAM_PRESSURE", "performance"}, {"TEX_RELEASED_MIB", "performance"}, {"ASTC_BC", "performance"}, {"LOD_GUARD", "performance"}, {"FIX_C0", "performance"}, {"FIX_ZERO", "performance"}, + {"TEX_ALIAS", "performance"}, {"TEX_VRAM_PRESSURE", "performance"}, {"TEX_RELEASED_MIB", "performance"}, {"TEX_BLOCK_MIB", "performance"}, {"ASTC_BC", "performance"}, {"LOD_GUARD", "performance"}, {"FIX_C0", "performance"}, {"FIX_ZERO", "performance"}, {"BIND_SKIP", "performance"}, {"SHADER_MEMO", "performance"}, {"PIPE_MEMO", "performance"}, {"TEX_MEMO", "performance"}, {"VB_USED", "performance"}, {"DESC_TEMPLATE", "performance"}, {"PUSH_SKIP", "performance"}, {"SPLIT_DRAWS", "performance"}, {"SPLIT_US", "performance"}, {"VK_VALIDATION", "performance"}, {"VK_DYN_VERTEX", "performance"}, {"VK_DYN_A2C", "performance"}, {"VK_SUBGROUP_PIN", "performance"}, @@ -174,7 +174,7 @@ static const CfgMeta metas[] = { // textures and memory {"ASTC", "auto", "auto|gpu|native|cpu", RESTART}, {"MEMORY", "auto", "auto|import|mirror|verify", RESTART}, {"TEX_ALIAS", "1", "0|1", RESTART}, {"TEX_VRAM_PRESSURE", "90", "0..100", RESTART}, - {"TEX_RELEASED_MIB", "256", "0..65536", RESTART}, {"ASTC_BC", "", "0|1", RESTART}, {"ZSTD_NATIVE", "1", "0|1", RESTART}, {"ZSTD_CHECK", "0", "0|1", RESTART}, + {"TEX_RELEASED_MIB", "256", "0..65536", RESTART}, {"TEX_BLOCK_MIB", "64", "0..1024", RESTART}, {"ASTC_BC", "", "0|1", RESTART}, {"ZSTD_NATIVE", "1", "0|1", RESTART}, {"ZSTD_CHECK", "0", "0|1", RESTART}, // render fixes {"LOD_GUARD", "1", "0|1", RESTART}, {"FIX_C0", "1", "0|1", RESTART}, {"FIX_ZERO", "1", "0|1", RESTART}, {"BIND_SKIP", "1", "0|1", RESTART}, {"SHADER_MEMO", "1", "0|1", RESTART}, {"PIPE_MEMO", "1", "0|1", RESTART}, {"TEX_MEMO", "1", "0|1", RESTART}, diff --git a/runtime/vk.h b/runtime/vk.h index 9cac3e54..1a41e73e 100644 --- a/runtime/vk.h +++ b/runtime/vk.h @@ -314,6 +314,8 @@ int vk_mem_uma(void); // 1: the device class is uma (vk_ const VmaDeviceMemoryCallbacks *vk_headroom_callbacks(void); void vk_headroom_start(void); void vk_headroom_stop(void); // before vmaDestroyAllocator +// The texture pool (vk_memory.c vk_texture_image) gets its next block ahead too; pool NULL frees the anchor in it. +void vk_headroom_pool(VmaPool pool, uint32_t type, VkDeviceSize block); int vk_mem_resolve(uint64_t addr, uint64_t size, VkMemSpan *out); // 1 when all of [addr, addr+size) is backed // Changes whenever vk_mem_resolve plus VK_MEM_USE may give another span for an address: a pool added, finalized or // mapped, a mirror created, refused or forgotten, a submission started. @@ -349,6 +351,8 @@ void vk_defer_buffer(VkBuffer buf, VmaAllocation alloc); void vk_defer_free(void *p); // Device-local scratch for the upload batch (storage, transfer src and dst), from a pool of its own (vk_memory.c). VkResult vk_scratch_buffer(VkDeviceSize size, VkBuffer *buf, VmaAllocation *alloc); +// A game texture's image with memory of its own: the texture pool, or a dedicated allocation (vk_memory.c). +VkResult vk_texture_image(const VkImageCreateInfo *ci, VkImage *img, VmaAllocation *alloc); // Staging and scratch bytes the open upload batch holds until it completes. Large texture loads submit the batch early // (vk_texture.c UPLOAD_HELD_MAX) so the GPU starts on it and its buffers come back before the pools need new blocks. VkDeviceSize vk_upload_held(void); diff --git a/runtime/vk_headroom.c b/runtime/vk_headroom.c index 88083025..baa6ab16 100644 --- a/runtime/vk_headroom.c +++ b/runtime/vk_headroom.c @@ -13,6 +13,7 @@ // Under VRAM pressure no headroom is kept: the spare block counts against the budget that decides whether a pool gets // its VRAM mirror (vk_memory.c), so while use plus two blocks passes 85% of the budget the anchor goes and nothing new // is allocated. The same holds when the system runs short of memory (room). +// The texture pool (vk_memory.c vk_texture_image) is kept ahead the same way, with its own anchor of half its block. // TOTK_VRAM_HEADROOM=0 turns it off. #include "cfg.h" @@ -33,6 +34,10 @@ static struct { volatile int64_t made; // blocks this thread brought in volatile int64_t other; // device memory of 32 MiB or more other threads allocated (VMA blocks, large dedicated) VmaAllocation anchor[64]; // per memory type: the half block that keeps the newest spare block from being deleted + VmaPool pool; // the texture pool, its memory type and block size, and its anchor + uint32_t pool_type; + VkDeviceSize pool_block; + VmaAllocation pool_anchor; } H; static void VKAPI_PTR on_allocate(VmaAllocator a, uint32_t type, VkDeviceMemory m, VkDeviceSize size, void *user) { @@ -68,23 +73,23 @@ static int room(const VkCtx *c, uint32_t type, VkDeviceSize block) { return h->budget && h->usage + 2 * block <= h->budget / 100 * 85 && vk_mem_host_room() >= 4 * block; } -static void drop_anchor(const VkCtx *c, uint32_t type) { - if (H.anchor[type]) vmaFreeMemory(c->vma, H.anchor[type]); - H.anchor[type] = NULL; +static void drop_anchor(const VkCtx *c, VmaAllocation *anchor) { + if (*anchor) vmaFreeMemory(c->vma, *anchor); + *anchor = NULL; } -static void top_up(const VkCtx *c, uint32_t type) { - VkDeviceSize block = block_size(c, type); +// pool NULL: the default pool of the type +static void top_up(const VkCtx *c, uint32_t type, VmaPool pool, VkDeviceSize block, VmaAllocation *anchor) { // Device-local types only: textures and mirrors grow there. Host memory types are woken by the staging pool's own // blocks (vk_memory.c vk_staging), while their default pool held 4 MiB: on the RX 9070 the spare blocks of types 1 // and 3 held 512 MiB of commit for nothing. if (!(c->mem_props.memoryTypes[type].propertyFlags & VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT) || !room(c, type, block)) { - drop_anchor(c, type); + drop_anchor(c, anchor); return; } VkMemoryRequirements req = {.size = block / 2, .alignment = 256, .memoryTypeBits = 1u << type}; - VmaAllocationCreateInfo ai = {.usage = VMA_MEMORY_USAGE_UNKNOWN}; + VmaAllocationCreateInfo ai = {.usage = VMA_MEMORY_USAGE_UNKNOWN, .pool = pool}; VmaAllocation a; int64_t before = H.made; if (vmaAllocateMemory(c->vma, &req, &ai, &a, NULL) != VK_SUCCESS) return; @@ -92,12 +97,13 @@ static void top_up(const VkCtx *c, uint32_t type) { vmaFreeMemory(c->vma, a); return; } - drop_anchor(c, type); - H.anchor[type] = a; + drop_anchor(c, anchor); + *anchor = a; static volatile int32_t logged; if (plat_inc32(&logged) <= 32) - rt_log("vk: headroom: a %.0f MiB block of memory type %u allocated ahead (%lld so far; %lld allocations of 32 MiB " - "or more on other threads)", (double)block / 1048576.0, type, (long long)H.made, (long long)H.other); + rt_log("vk: headroom: a %.0f MiB block of memory type %u%s allocated ahead (%lld so far; %lld allocations of " + "32 MiB or more on other threads)", (double)block / 1048576.0, type, pool ? " (texture pool)" : "", + (long long)H.made, (long long)H.other); } static void headroom_main(void *arg) { @@ -112,10 +118,15 @@ static void headroom_main(void *arg) { plat_mutex_lock(&H.lock); const VkCtx *c = H.stop ? NULL : vk_ctx(); for (uint32_t t = 0; c && t < c->mem_props.memoryTypeCount && t < 64; t++) - if (watch >> t & 1) top_up(c, t); + if (watch >> t & 1) { + top_up(c, t, NULL, block_size(c, t), &H.anchor[t]); + if (H.pool && t == H.pool_type) top_up(c, t, H.pool, H.pool_block, &H.pool_anchor); + } int stop = H.stop; - if (stop && (c = vk_ctx())) - for (uint32_t t = 0; t < 64; t++) drop_anchor(c, t); + if (stop && (c = vk_ctx())) { + for (uint32_t t = 0; t < 64; t++) drop_anchor(c, &H.anchor[t]); + drop_anchor(c, &H.pool_anchor); + } plat_mutex_unlock(&H.lock); if (stop) return; } @@ -127,11 +138,21 @@ void vk_headroom_stop(void) { plat_mutex_lock(&H.lock); H.stop = 1; const VkCtx *c = vk_ctx(); - for (uint32_t t = 0; c && t < 64; t++) drop_anchor(c, t); + for (uint32_t t = 0; c && t < 64; t++) drop_anchor(c, &H.anchor[t]); + if (c) drop_anchor(c, &H.pool_anchor); plat_mutex_unlock(&H.lock); plat_event_set(&H.ev); } +void vk_headroom_pool(VmaPool pool, uint32_t type, VkDeviceSize block) { + if (!H.started) return; + plat_mutex_lock(&H.lock); + const VkCtx *c = vk_ctx(); + if (c) drop_anchor(c, &H.pool_anchor); + H.pool = pool, H.pool_type = type, H.pool_block = block; + plat_mutex_unlock(&H.lock); +} + void vk_headroom_start(void) { if (!H.on || H.started) return; plat_mutex_init(&H.lock); diff --git a/runtime/vk_memory.c b/runtime/vk_memory.c index c887a560..4b862c19 100644 --- a/runtime/vk_memory.c +++ b/runtime/vk_memory.c @@ -2564,6 +2564,66 @@ VkResult vk_scratch_buffer(VkDeviceSize size, VkBuffer *buf, VmaAllocation *allo VkDeviceSize vk_upload_held(void) { return open_active ? open_b.held : 0; } +// Own memory of the game's textures (vk_texture.c create_tex): a pool of its own with blocks of TOTK_TEX_BLOCK_MIB +// (default 64; 0 puts textures back in the default pools). In the default pools textures shared 256 MiB blocks with the +// mirrors and other buffers, and a block went back to the driver only once all of them were gone: on the RX 9070, +// after 4.5 minutes of roaming the field, 3 of the 9 device-local blocks were 13-27% full, held by 87-223 small +// textures and buffers each, and the full ones had hundreds of free gaps under 1 MiB, so blocks held 800 MiB more than +// their allocations. Where device memory takes process commit (vk_mem_host_probe) that commit backs nothing. A smaller +// block, holding textures only, empties sooner and wastes less when it does not. With the pool the same 10-minute route +// ended with 807 MiB of blocks beyond their allocations instead of 1037, the texture pool's 22 blocks mostly 75-100% +// full, and the slow frames did not grow. +// An image of a quarter block or more gets memory of its own (a dedicated allocation) that goes back to the driver +// with the image; so do images the driver prefers that for, and images the pool's memory type does not take. VMA +// checks neither for a custom pool (VmaAllocator_T::AllocateMemory takes the pool's type as it is), so the image's +// requirements are read here first. +static VmaPool tex_pool; +static uint32_t tex_type; +static VkDeviceSize tex_block; +static int tex_pool_tried; + +static void tex_pool_init(VkCtx *c, const VkImageCreateInfo *ci) { + plat_once(&cmd_once, cmd_init, NULL); + plat_rmutex_lock(&cmd_lock); + if (!tex_pool_tried) { + tex_block = (VkDeviceSize)cfg_int("TOTK_TEX_BLOCK_MIB") << 20; // schema default 64 + VmaAllocationCreateInfo aci = {.usage = VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE}; + VmaPoolCreateInfo pi = {.blockSize = tex_block}; + if (tex_block && vmaFindMemoryTypeIndexForImageInfo(c->vma, ci, &aci, &tex_type) == VK_SUCCESS) { + pi.memoryTypeIndex = tex_type; + if (vmaCreatePool(c->vma, &pi, &tex_pool) != VK_SUCCESS) tex_pool = NULL; + } + if (tex_pool) { + vk_headroom_pool(tex_pool, tex_type, tex_block); + rt_log("vk: texture pool: blocks of %llu MiB in memory type %u; images of %llu MiB or more get memory of " + "their own (TOTK_TEX_BLOCK_MIB)", (unsigned long long)(tex_block >> 20), tex_type, + (unsigned long long)(tex_block >> 22)); + } else { + rt_log("vk: texture pool %s: textures go to the default pools (TOTK_TEX_BLOCK_MIB)", + tex_block ? "unavailable" : "off"); + } + __atomic_store_n(&tex_pool_tried, 1, __ATOMIC_RELEASE); + } + plat_rmutex_unlock(&cmd_lock); +} + +VkResult vk_texture_image(const VkImageCreateInfo *ci, VkImage *img, VmaAllocation *alloc) { + VkCtx *c = vk_ctx(); + VmaAllocationCreateInfo ai = {.usage = VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE}; + if (!__atomic_load_n(&tex_pool_tried, __ATOMIC_ACQUIRE)) tex_pool_init(c, ci); + if (tex_pool) { + VkDeviceImageMemoryRequirements q = {.sType = VK_STRUCTURE_TYPE_DEVICE_IMAGE_MEMORY_REQUIREMENTS, .pCreateInfo = ci}; + VkMemoryDedicatedRequirements dr = {.sType = VK_STRUCTURE_TYPE_MEMORY_DEDICATED_REQUIREMENTS}; + VkMemoryRequirements2 mr = {.sType = VK_STRUCTURE_TYPE_MEMORY_REQUIREMENTS_2, .pNext = &dr}; + vkGetDeviceImageMemoryRequirements(c->device, &q, &mr); + if (dr.requiresDedicatedAllocation || dr.prefersDedicatedAllocation || mr.memoryRequirements.size >= tex_block / 4) + ai.flags = VMA_ALLOCATION_CREATE_DEDICATED_MEMORY_BIT; + else if (mr.memoryRequirements.memoryTypeBits >> tex_type & 1) + ai = (VmaAllocationCreateInfo){.usage = VMA_MEMORY_USAGE_UNKNOWN, .pool = tex_pool}; // the pool's type + } + return vmaCreateImage(c->vma, ci, &ai, img, alloc, NULL); +} + // At device creation: the staging and scratch pools with their kept blocks, made through a first small buffer each // (freed at once), so the first world frame does not allocate them (staging was first used there once the GPU took // the early texture uploads). @@ -2730,6 +2790,10 @@ void vk_mem_shutdown(void) { if (scr_pool) vmaDestroyPool(c->vma, scr_pool); // deferred scratch buffers went with collect_locked above scr_pool = NULL; scr_pool_tried = 0; + vk_headroom_pool(NULL, 0, 0); // frees the headroom's anchor in the texture pool + if (tex_pool) vmaDestroyPool(c->vma, tex_pool); // textures went with vk_texture_shutdown, deferred ones above + tex_pool = NULL; + tex_pool_tried = 0; plat_rmutex_unlock(&cmd_lock); plat_mutex_lock(&pool_lock); for (int i = 0; i < pool_index.n; i++) destroy_rec(c, pool_index.e[i].buf); diff --git a/runtime/vk_texture.c b/runtime/vk_texture.c index 1dd7662d..fb3bcc55 100644 --- a/runtime/vk_texture.c +++ b/runtime/vk_texture.c @@ -459,8 +459,7 @@ static Tex *create_tex(const tex_t *t, const TexKey *k, int defer_init) { } } if (!img) { - VmaAllocationCreateInfo ai = {.usage = VMA_MEMORY_USAGE_AUTO_PREFER_DEVICE}; - VkResult r = vmaCreateImage(c->vma, &ci, &ai, &img, &e->alloc, NULL); + VkResult r = vk_texture_image(&ci, &img, &e->alloc); // the texture pool or memory of its own if (r != VK_SUCCESS) { log_limited(&n_failed, "image creation failed (%d): nvn fmt %#x %ux%ux%u target %d levels %u layers %u", (int)r, d->format, w, h, depth, d->target, levels, layers); From 29cb79086f1ac9aeeddff78c39f83785512215cd Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 10:51:49 +0300 Subject: [PATCH 12/16] Take 64 MiB blocks from the driver for buffers and other images Since the textures moved to a pool of their own, the default device-local blocks hold mirrors and other buffers. With VMA's 256 MiB blocks one block held 53 MiB of them after 10 minutes in the field, and the headroom thread kept half a block of each device-local type ahead. TOTK_VMA_BLOCK_MIB (default 64, 0 = VMA's 256) sets the size; the headroom spare follows it. On the RX 9070, 10 minutes in the field: VMA blocks 3582 -> 3252 MiB, process commit 8614 -> 8327 MB, slow frames 13 (2.8 s) -> 9 (1.1 s). Co-Authored-By: Claude Opus 5.5 --- docs/settings.md | 1 + runtime/cfg.c | 6 +++--- runtime/vk.h | 1 + runtime/vk_device.c | 8 +++++++- runtime/vk_headroom.c | 2 +- 5 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/settings.md b/docs/settings.md index a50c5243..f45aeb51 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -194,6 +194,7 @@ Many rows below are developer tools that only act together with another setting | `spin_handoff_us` (default `50`) | Microseconds a polling wait lasts before it gives its virtual core to a waiting thread. | A shorter value hands cores over sooner; a longer one keeps them longer. | Caution | | `tex_block_mib` (default `64`) | Block size in MiB of the pool that holds the game's textures; images of a quarter block or more get memory of their own. `0` puts textures in the default pools with the buffers. | Larger blocks hold more memory that no texture uses; smaller ones mean more allocations from the driver. | Caution | | `tex_released_mib` (default `256`) | MiB of textures the game released that are kept for reuse; older ones beyond it are dropped. `0` keeps up to 2048 of them, whatever their size. | A larger value keeps more device memory and process commit; a smaller one makes the game create more textures again. | Caution | +| `vma_block_mib` (default `64`) | Block size in MiB that the Vulkan memory allocator takes from the driver for buffers and other images on heaps over 1 GiB; larger allocations than half a block get memory of their own. `0` uses the allocator's 256. | Larger blocks hold more memory that nothing uses; smaller ones mean more allocations from the driver. | Caution | ## Generated-code patches diff --git a/runtime/cfg.c b/runtime/cfg.c index 5c282d3f..7f3d5f91 100644 --- a/runtime/cfg.c +++ b/runtime/cfg.c @@ -60,7 +60,7 @@ static const char *const known[] = { "SHOTS_FULL", "SPEED_PROBE", "SPIN", "SPIN_HANDOFF_US", "SPLIT_DRAWS", "SPLIT_US", "STICK_DEADZONE", "STICK_SENS", "SWKBD_ANSWER", "SWKBD_TEST", "TEST_OOM", "TEST_PAD", "TEST_PREPARE_SHADERS", "TEX_ALIAS", "TEX_BLOCK_MIB", "TEX_HEAP_EXTRA_MB", "TEX_MEMO", "TEX_RELEASED_MIB", "TEX_VRAM_PRESSURE", "TIMER_1MS", "TRACE", "TXD_TRANSPOSE", "UBO_SNAPSHOT", "UB_OVERLAY", "UB_OVERLAY_OUT", "UPSCALER", "VB_USED", "VK_DYN_A2C", "VK_DYN_VERTEX", "VK_NO_FLOAT64", - "VK_PRESENT", "VK_RECORDER", "VK_SSBO_ALIGN", "VK_SUBGROUP", "VK_SUBGROUP_PIN", "VK_VALIDATION", "VOLUME", "VRAM_HEADROOM", "VRAM_LIMIT_MIB", "VS_OUTS", + "VK_PRESENT", "VK_RECORDER", "VK_SSBO_ALIGN", "VK_SUBGROUP", "VK_SUBGROUP_PIN", "VK_VALIDATION", "VMA_BLOCK_MIB", "VOLUME", "VRAM_HEADROOM", "VRAM_LIMIT_MIB", "VS_OUTS", "WALK_KEY", "WALK_SCALE", "WB_EXACT", "WB_FENCE_LIMIT", "WB_MERGE", "WINDOW_SIZE", "XLATE", "XLATE_ID", "XLATE_KEEP", "XLATE_PROCS", "ZSTD_CHECK", "ZSTD_NATIVE", }; @@ -99,7 +99,7 @@ static const struct { const char *key, *section; } sections[] = { {"TIMER_1MS", "performance"}, {"PIPE_WAIT", "performance"}, {"PIPE_SKIP", "performance"}, {"LIB_PREBUILD", "performance"}, {"LIB_PREBUILD_THREADS", "performance"}, {"PIPE_PREBUILD", "performance"}, {"PREWARM_XLATE", "performance"}, {"GPL", "performance"}, {"ASTC", "performance"}, {"MEMORY", "performance"}, - {"TEX_ALIAS", "performance"}, {"TEX_VRAM_PRESSURE", "performance"}, {"TEX_RELEASED_MIB", "performance"}, {"TEX_BLOCK_MIB", "performance"}, {"ASTC_BC", "performance"}, {"LOD_GUARD", "performance"}, {"FIX_C0", "performance"}, {"FIX_ZERO", "performance"}, + {"TEX_ALIAS", "performance"}, {"TEX_VRAM_PRESSURE", "performance"}, {"TEX_RELEASED_MIB", "performance"}, {"TEX_BLOCK_MIB", "performance"}, {"VMA_BLOCK_MIB", "performance"}, {"ASTC_BC", "performance"}, {"LOD_GUARD", "performance"}, {"FIX_C0", "performance"}, {"FIX_ZERO", "performance"}, {"BIND_SKIP", "performance"}, {"SHADER_MEMO", "performance"}, {"PIPE_MEMO", "performance"}, {"TEX_MEMO", "performance"}, {"VB_USED", "performance"}, {"DESC_TEMPLATE", "performance"}, {"PUSH_SKIP", "performance"}, {"SPLIT_DRAWS", "performance"}, {"SPLIT_US", "performance"}, {"VK_VALIDATION", "performance"}, {"VK_DYN_VERTEX", "performance"}, {"VK_DYN_A2C", "performance"}, {"VK_SUBGROUP_PIN", "performance"}, @@ -174,7 +174,7 @@ static const CfgMeta metas[] = { // textures and memory {"ASTC", "auto", "auto|gpu|native|cpu", RESTART}, {"MEMORY", "auto", "auto|import|mirror|verify", RESTART}, {"TEX_ALIAS", "1", "0|1", RESTART}, {"TEX_VRAM_PRESSURE", "90", "0..100", RESTART}, - {"TEX_RELEASED_MIB", "256", "0..65536", RESTART}, {"TEX_BLOCK_MIB", "64", "0..1024", RESTART}, {"ASTC_BC", "", "0|1", RESTART}, {"ZSTD_NATIVE", "1", "0|1", RESTART}, {"ZSTD_CHECK", "0", "0|1", RESTART}, + {"TEX_RELEASED_MIB", "256", "0..65536", RESTART}, {"TEX_BLOCK_MIB", "64", "0..1024", RESTART}, {"VMA_BLOCK_MIB", "64", "0..1024", RESTART}, {"ASTC_BC", "", "0|1", RESTART}, {"ZSTD_NATIVE", "1", "0|1", RESTART}, {"ZSTD_CHECK", "0", "0|1", RESTART}, // render fixes {"LOD_GUARD", "1", "0|1", RESTART}, {"FIX_C0", "1", "0|1", RESTART}, {"FIX_ZERO", "1", "0|1", RESTART}, {"BIND_SKIP", "1", "0|1", RESTART}, {"SHADER_MEMO", "1", "0|1", RESTART}, {"PIPE_MEMO", "1", "0|1", RESTART}, {"TEX_MEMO", "1", "0|1", RESTART}, diff --git a/runtime/vk.h b/runtime/vk.h index f5b69b7b..ee50f2cd 100644 --- a/runtime/vk.h +++ b/runtime/vk.h @@ -44,6 +44,7 @@ typedef struct VkCtx { // VK_FEEDBACK_RESTART (the pass ends and restarts behind the full barrier). int feedback; // VK_FEEDBACK_* uint32_t min_imported_host_alignment; // VK_EXT_external_memory_host + VkDeviceSize vma_block; // VMA's block size for heaps over 1 GiB (TOTK_VMA_BLOCK_MIB, vk_device.c) int device_index; // index in vkEnumeratePhysicalDevices } VkCtx; enum { VK_FEEDBACK_OFF, VK_FEEDBACK_RESTART, VK_FEEDBACK_LAYOUT }; diff --git a/runtime/vk_device.c b/runtime/vk_device.c index 458cd86b..760a3a46 100644 --- a/runtime/vk_device.c +++ b/runtime/vk_device.c @@ -429,8 +429,14 @@ static int create_device(void) { g_vk.min_imported_host_alignment = (uint32_t)emh.minImportedHostPointerAlignment; vk_caps_init(&g_vk); + // Blocks of 64 MiB instead of VMA's 256 (TOTK_VMA_BLOCK_MIB, 0 = VMA's). Since the textures moved to their own pool + // (vk_memory.c vk_texture_image), the default device-local blocks hold mirrors and other buffers: on the RX 9070 + // after 10 minutes in the field one 256 MiB block held 53 MiB of them, and the headroom thread kept half a block of + // each device-local type ahead (128 MiB each). Larger buffers than half a block get memory of their own. + g_vk.vma_block = (VkDeviceSize)cfg_int("TOTK_VMA_BLOCK_MIB") << 20; + if (!g_vk.vma_block) g_vk.vma_block = 256ull << 20; // VMA_DEFAULT_LARGE_HEAP_BLOCK_SIZE VmaAllocatorCreateInfo ai = {.physicalDevice = g_vk.phys, .device = g_vk.device, .instance = g_vk.instance, - .vulkanApiVersion = VK_API_VERSION_1_3, + .vulkanApiVersion = VK_API_VERSION_1_3, .preferredLargeHeapBlockSize = g_vk.vma_block, .flags = (g_vk.has_buffer_device_address ? VMA_ALLOCATOR_CREATE_BUFFER_DEVICE_ADDRESS_BIT : 0) | (g_vk.has_memory_budget ? VMA_ALLOCATOR_CREATE_EXT_MEMORY_BUDGET_BIT : 0), .pDeviceMemoryCallbacks = vk_headroom_callbacks()}; diff --git a/runtime/vk_headroom.c b/runtime/vk_headroom.c index 6bb670e8..e08c2ef2 100644 --- a/runtime/vk_headroom.c +++ b/runtime/vk_headroom.c @@ -63,7 +63,7 @@ const VmaDeviceMemoryCallbacks *vk_headroom_callbacks(void) { static VkDeviceSize block_size(const VkCtx *c, uint32_t type) { VkDeviceSize heap = c->mem_props.memoryHeaps[c->mem_props.memoryTypes[type].heapIndex].size; - return heap <= HR_SMALL_HEAP ? heap / 8 : 256ull << 20; // VMA's default preferredLargeHeapBlockSize + return heap <= HR_SMALL_HEAP ? heap / 8 : c->vma_block; // VMA's preferredLargeHeapBlockSize } // The spare block is memory the game does not use yet; where device memory takes host memory it is kept only while the From bed6962e09b0e3ec0f1ef60b097ae9993d5b110e Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 14:38:03 +0300 Subject: [PATCH 13/16] Render the handheld scene at the asked size on 1.4.3 1.4.3 scales the scene size it reads from the patch page by canvas width over the console mode's base width, which is 1280 in handheld, not 1920. A handheld 1280x720 output at render_scale 100 put 1920x1080 on the page, so the game rendered a 1920x1080 scene while the DynamicTextureAllocator heap was sized for 1280x720, and heavy scenes ran it out (crash at main+0x1c2590). scene_scale now uses the mode's base for res_init and res_dlss_mode. In handheld the game composes a 1280x720 canvas unless the output patch is on, so the output patch is switched on with the scene patch there and the canvas is the output the factor and the heap assume. Docked is unchanged. Co-Authored-By: Claude Opus 5.5 --- runtime/resolution.c | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/runtime/resolution.c b/runtime/resolution.c index 6c36e8ce..af15c514 100644 --- a/runtime/resolution.c +++ b/runtime/resolution.c @@ -14,10 +14,11 @@ // 64-bit word, +40 the renderer (1.2.1) or display configuration (1.4.3) the patched code stores there. // +56 the camera's aspect ratio as a float when the output is not 16:9 (set aspect), +60 the field-of-view factor // (set fov, res_fov_live). -// 1.4.3 scales the scene it reads by output width / 1920 (a 2560x1440 output renders its 1600x900 scene at 2128x1200; -// MacNativeGames measured the same), so its page holds the wanted size divided by that factor and the game's 5/6 needs -// no scene patch. 1.2.1 renders the size it reads (1600x900 on a 2560x1440 output): its page holds the wanted size, and -// the scene set is on whenever the output differs from 1920x1080. +// 1.4.3 scales the scene it reads by canvas width / the console mode's base width, 1920 docked and 1280 handheld (a +// 2560x1440 output renders its 1600x900 scene at 2128x1200 docked; MacNativeGames measured the same), so its page holds +// the wanted size divided by that factor (scene_scale) and the game's 5/6 needs no scene patch. 1.2.1 renders the size +// it reads (1600x900 on a 2560x1440 output): its page holds the wanted size, and the scene set is on whenever the +// output differs from 1920x1080. // // Heap: agl's DynamicTextureAllocator is one fixed heap, "DynamicTextureAllocatorMem" in // System/HeapSize/Product.Nin_NX_NVN.HeapDef.byml.zs (113664 KiB, carved from "Graphics", 201728 KiB). At 2560x1440 @@ -40,6 +41,7 @@ #include "cfg.h" #include "host.h" #include "mods.h" +#include "ov.h" #include "platform/platform.h" #define BASE_W 1920 @@ -209,6 +211,17 @@ uint64_t res_heap_extra_kib(void) { return kib + ((shadow_kib() + 1023) & ~1023ull); // whole MiB } +// 1.4.3's factor between the scene size it reads from the page and the one it renders. The game's scene setter +// (main+0x585e48 and the code before it) multiplies the page's size by the canvas width (display configuration +0x10) +// over the current console mode's base width (+0xf4 of the mode's entry, mode 1 handheld: main+0x2dac1c stores +// GetOperationMode != 1 at +0x546). The base is 1280 handheld and 1920 docked. The canvas is the output whenever the +// scene patch is on: docked the game's own canvas is 1920, handheld res_init switches the output patch on (a 1280 base +// with the game's 1280x720 handheld canvas would render R.ow / 1280 times the scene). 1.2.1 renders the size it reads. +static double scene_scale(void) { + if (!RT_V143) return 1.0; + return (double)R.ow / (ov_handheld() ? 1280 : BASE_W); +} + uint64_t res_heap_extra_bytes(void) { return ((res_heap_extra_kib() << 10) + 0x1fffff) & ~0x1fffffull; } // TOTK_TEX_HEAP_EXTRA_MB (0 to 4096): more room in "TextureHeap" and its parent "ゲームグラフィックス", the heap the @@ -485,15 +498,20 @@ void res_init(void) { return; } uint8_t *page = rt_patch_page(); - double k = RT_V143 ? (double)R.ow / BASE_W : 1.0; // 1.4.3's own scaling of the scene with the output width + double k = scene_scale(); int scene_on = R.scene_set || (!RT_V143 && (R.ow != BASE_W || R.oh != BASE_H)); + // Handheld, 1.4.3 draws a 1280x720 canvas unless the output patch is on, whatever the output setting (measured: a + // 1920x1080 output with the patch off composed the frame at 1280x720 and only the swapchain was 1920x1080). With + // the scene patch on the output patch is switched on too, so the canvas is the output size that scene_scale and + // the heap size (res_heap_extra_kib) assume. + int output_on = R.ow != BASE_W || R.oh != BASE_H || (RT_V143 && scene_on && ov_handheld()); float sc[2] = {(float)(R.sw / k), (float)(R.sh / k)}; uint64_t out = pack(R.ow, R.oh), none = 0; memcpy(page + 16, sc, sizeof sc); memcpy(page + 32, &out, 8); memcpy(page + 40, &none, 8); memcpy(page + 48, &out, 8); - rt_patch_switch(output, R.ow != BASE_W || R.oh != BASE_H); + rt_patch_switch(output, output_on); rt_patch_switch(scene, scene_on); R.on = 1; if (R.live) g_fnprof = 1; // until the game sets its render size: res_fn_hit, or res_present gives up @@ -614,7 +632,7 @@ int res_dlss_mode(const char *m) { unsigned w, h; scene_for(k ? k : R.base_k, &w, &h); if (w == R.sw && h == R.sh) return 0; - double s = RT_V143 ? (double)R.ow / BASE_W : 1.0; + double s = scene_scale(); float sc[2] = {(float)(w / s), (float)(h / s)}; memcpy((uint8_t *)rt_patch_page() + 16, sc, sizeof sc); R.sw = w, R.sh = h; From bdcfb42c07888e98307961bcabf0187576d2d0db Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 14:44:59 +0300 Subject: [PATCH 14/16] Add contributor and agent guides for pull requests, running and debugging Co-Authored-By: Claude Opus 5.5 --- .github/pull_request_template.md | 36 ++++++++++ AGENTS.md | 9 +++ CONTRIBUTING.md | 93 ++++++++++++++++++++++-- docs/agents/debugging.md | 117 +++++++++++++++++++++++++++++++ docs/agents/running.md | 90 ++++++++++++++++++++++++ docs/agents/symptoms.md | 71 +++++++++++++++++++ 6 files changed, 409 insertions(+), 7 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 docs/agents/debugging.md create mode 100644 docs/agents/running.md create mode 100644 docs/agents/symptoms.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..67f94016 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,36 @@ + + +## Problem + + + +## Change + + + +## Where it reproduces + + + +## Proof + + + +## Checks run + + + +- [ ] `python tools/check_content.py --staged` +- [ ] `totk.exe --selftest` + +## Measurements + + + +## Not run + + diff --git a/AGENTS.md b/AGENTS.md index ef92d714..2f0b5611 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,15 @@ This repository is public. Game data lives outside it and every derived file sta - Graphics bugs: [docs/maxwell.md](docs/maxwell.md) lists the Maxwell behaviour the Vulkan path must match and the TotK bugs other ports fixed. - Comments say what the code does and why, in words that stand on their own. Cite our code by file plus function (a line number may follow as a hint) and upstream code by project, file and function: `refs/` moves, so its line numbers rot. Commit hashes belong to the attribution of copied code. +## Running and debugging + +- Running the game, screenshots, frame dumps, timings: [docs/agents/running.md](docs/agents/running.md). +- Investigating a bug, glitch or crash: search [docs/agents/symptoms.md](docs/agents/symptoms.md) by the player's words first, then follow [docs/agents/debugging.md](docs/agents/debugging.md). Read the code before running the game. + +## Pull requests + +Preparing a pull request: target `dev`; the checks by changed area, the proof and the performance runs it carries are in [CONTRIBUTING.md](CONTRIBUTING.md), "Pull requests". Reviewing one: [docs/pr-review-kit/](docs/pr-review-kit/). + ## Writing Code, comments, docs and commit messages are in English. Commit messages are plain sentences without type prefixes. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1b404f3e..49784216 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,14 +29,93 @@ Use the issue form. Include the port version and game update from the title line ## Pull requests -- One topic per pull request. -- Describe the problem, then what changed. -- Say how you tested it: which version, which scene, how long. -- A change to the lifter (`recomp/`) or the CPU headers passes the differential tests in [docs/building.md](docs/building.md), "Checks". -- Commit messages are plain sentences, without `feat:` or other prefixes. -- AI-assisted code is welcome. You are responsible for having read and run it. +### Branch + +Open pull requests against `dev`. Branch from the current `dev` and rebase on it before you open the pull request. `main` receives `dev` at a release; a pull request against `main` is retargeted to `dev` before review. + +### Before you start + +- Search the open pull requests and issues on the topic. When another pull request already covers it, improve that one or say in yours how they differ. +- Fixes are reviewed before features, in order of how many players the bug hits. A feature with a design in [docs/milestones/](docs/milestones/) (mods, cheats, the menu) follows that design. For a feature without one, open an issue first. +- Find out where the bug reproduces: OS, GPU vendor and generation, driver, game update, settings. Put that in the description. + +### What the change must keep + +- **The default for everyone.** A fix for one setup (a GPU vendor, a memory size, a display) is gated on that setup. Players without the problem see no change. +- **A switch.** New behaviour on the frame path or in rendering sits behind a `totk.ini` setting or a `TOTK_*` variable, so a player can turn it off and a reviewer can compare. A new setting is described in [totk.ini.example](totk.ini.example) and [docs/settings.md](docs/settings.md). +- **The fix, not a disabled feature.** A crash that goes away with a feature off points at the bug in that feature. Turning the feature off for a vendor is not a fix. +- **The frame time on weak hardware.** Game threads and the render thread do no file I/O, no GPU allocations, no per-draw state copies and no global atomic counters. Memory kept per frame or per object is freed. The full list with measured costs: [docs/pr-review-kit/02-performance.md](docs/pr-review-kit/02-performance.md), "What the hot path must not do". +- **Other GPUs.** New Vulkan code queries each feature, extension, format and limit it uses and keeps a working path without it. Nothing is hardcoded from what one GPU reports. +- **Text in the catalogs.** Text a player sees gets an id in `runtime/ui_text.h` and an entry in `runtime/ui_text.c` for every menu language (English, Russian, Brazilian Portuguese, Simplified Chinese); installer text goes into `installer/text/*.json`. +- **The generator owns generated C.** Change `recomp/`, never `generated/`. + +### Checks by what you changed + +Run every row that matches your diff and list the results in the description. Commands and details: [docs/building.md](docs/building.md), "Checks". + +| You changed | Run | +|---|---| +| anything | `python tools/check_content.py --staged`; `build\\totk.exe --selftest` | +| `recomp/`, `runtime/cpu.h`, `runtime/simd.h` | the differential tests against Unicorn: `tests\diff\lift.py`, `simd.py`, `atomic.py`, `func.py`, `tests\flags_check.py`, `tests\excl_mt.py`; the same with a `--cpu v2` build | +| `recomp/jumptables.py` | `tests\jumptables_check.py`: 0 disagreements on 1.2.1 and 1.4.3 | +| `runtime/` | `--probe-kernel`, `--probe-vkexec`, `--probe-nvn-tex`, `--probe-shader`, plus the probe for the file you touched (list at the top of `runtime/main.c`) | +| settings | `totk.exe --probe-cfg`; `python tests\settings_doc_check.py` | +| button prompts | `.venv-py314\Scripts\python tests\romfs_prompts_test.py` | +| mods, ExeFS patches | `.venv\Scripts\python tests\exefs_patches_test.py`; `totk.exe --probe-mods` | +| `installer/` | `python tests\installer_test.py`; `python tests\installer_gui_test.py` | +| shader translator | `tools\xlate_smoke.py`; `tools\shader_census.py --version --translate` with no new failure groups | +| rendering | a run in a scene where the change acts, with `TOTK_VK_VALIDATION=1`: no new validation messages; screenshots before and after | +| frame path, timing, scheduling | the measurements below | + +Checks that need game files run on your own copy of the game. Results go into the pull request as text: pass or fail, counts, log lines. Never attach logs or dumps that contain game data. + +### Proof + +- **A bug fix** shows the bug before the change and gone after it, on the same repro: a screenshot pair, a log line, a probe or test that fails before and passes after. A scripted repro (`TOTK_INPUT_RECORD`, [docs/controls.md](docs/controls.md), "Scripted input") is the strongest. If the bug cannot be reproduced on your hardware, say so and point at the code that causes it. +- **A crash fix** names the crash: the log's crash report, `vk: pass marks` lines for a lost device. +- **Parts you could not run** (Linux-only code, HDR, vendor-only paths) are listed as unrun and gated away from everyone else. + +### Performance measurements + +A change on the frame path, in timing or in scheduling carries these numbers, or it waits until someone measures it. + +1. **Ceiling first.** Before the work, estimate the share of the frame the changed code holds on the critical path (`TOTK_CRIT` + `tools/crit_path.py`). A ceiling of a few percent is not worth a hot-path change. +2. **Build 1.4.3** with prepared shaders in that build folder (`tools/prepare_shaders.py`, [docs/building.md](docs/building.md) step 6). Caches copied from another build folder do not count. +3. **A heavy scene** where the change acts: a fight with a large enemy and a crowd, or a town, with `TOTK_FPS_LIMIT=360`. +4. **Whole runs, switch off and on, at least two each**, the same save and the same input script, timed by game seconds: + + ```powershell + .venv\Scripts\python tools\run_game.py build\v143 --script --seconds 60 --quiet --env TOTK_TRACE=perf,sched --env TOTK_FPS_LIMIT=360 --env =0 + ``` + + `--quiet` waits until no other game or build runs. Close everything heavy on the machine. Before reading the numbers, check that each run reached the world and showed the same scene. +5. **Report per run**: average fps, 1% low or worst frame, the number of `perf: slow frame` lines, VRAM; `tools/perf_summary.py` condenses the log. Add CPU, GPU, driver, RAM, resolution and the settings you changed. + +A switch toggled inside one run on a moving scene gives false results: compare whole runs. Zero new slow frames is a hard bar; an fps gain does not buy back new hitches. Background and the reasons behind each rule: [docs/pr-review-kit/02-performance.md](docs/pr-review-kit/02-performance.md). + +### Description and commits + +Fill in the pull request template: problem, change, where it reproduces, checks, measurements, what stayed unrun. One topic per pull request. + +Commit messages are plain English sentences, without `feat:`, `fix:` or other prefixes. A commit that works on an issue ends its subject with the issue numbers: `Render the handheld scene at the asked size on 1.4.3 (#998, #536)`. + +### Review and merge + +The maintainers review every pull request against [docs/pr-review-kit/](docs/pr-review-kit/): read it to see what gets a pull request rejected, which bug classes are already fixed and which invariants a change must keep. A good pull request that misses the project's conventions is fixed up while merging rather than sent back. Part of a pull request can be taken; the reason for what was left out or rejected is posted on the pull request. + +Accepted work merges into `dev` and reaches players through test builds. `main` moves only at a release. + +## Coding agents + +AI-assisted code is welcome. You are responsible for having read and run it, and the pull request says which checks ran on your machine. + +Point your agent at [AGENTS.md](AGENTS.md) (Claude Code reaches it through `CLAUDE.md`), this file and [docs/pr-review-kit/](docs/pr-review-kit/) before it writes code. [docs/agents/](docs/agents/) holds what it needs to run the game unattended, measure, and debug: the method, the bug classes of a recompiled Switch game, and a symptom catalog. The rules in them bind the agent as they bind you: + +- Key values stay out of prompts, logs, commands and files. The agent passes the keys file path to the tools. +- Results in the pull request come from runs that happened. A check the agent did not run is listed as not run. +- The agent writes the description in its own words about this diff. A review kit checklist pasted in with every box ticked tells the reviewer nothing. ## Code and docs - Code, comments, commit messages and documentation are in English. -- Generated code is never edited by hand: change the generator. +- Comments say what the code does and why. Cite our code by file and function, upstream code by project, file and function. diff --git a/docs/agents/debugging.md b/docs/agents/debugging.md new file mode 100644 index 00000000..a1327a83 --- /dev/null +++ b/docs/agents/debugging.md @@ -0,0 +1,117 @@ +# Debugging the port: method for agents + +A game run costs minutes and a full rebuild costs several more, while reading code costs seconds. Order the work so the +cheap steps decide as much as they can before the game starts. Each step ends on its stated condition. + +## Steps + +1. **Evidence.** Hold one artifact that shows the symptom: the player's screenshot, log or input recording, a + flight-recorder dump, a frame dump ([running.md](running.md), "Observing"). Done when you can point at the wrong + pixel, line or frame. +2. **Where it reproduces.** OS, GPU vendor and generation, driver, game update, settings, mods, the save. Done when you + know whether your hardware can show the bug at all. NVIDIA bugs do not reproduce on AMD; RDNA1/2 bugs do not + reproduce on RDNA3/4 (another driver branch); a Ryzen 7000 iGPU is RDNA2 and runs that branch. When your hardware + cannot show it, say so and work from the code and the reporter's logs; runs that cannot decide anything are skipped. +3. **Known already?** Search [symptoms.md](symptoms.md), [pr-review-kit/04-knowledge.md](../pr-review-kit/04-knowledge.md) + and [maxwell.md](../maxwell.md) sections 6-7 with the words the player used (black, magenta, flicker, slow motion, + missing, stale, streaks, stuck) and the object (sky, grass, shadow, fog, HUD, weapon). Then the upstream notes: + `refs/nxnative/docs`, `refs/MacNativeGames/docs` and the SavageWindRecomp issue tracker (`tools/fetch_refs.sh` + fetches `refs/`). Done when every hit is either ruled out or is your first hypothesis. A hit on a class we already + fixed: confirm that fix still holds before deriving anything new. +4. **Read the code.** The game's function in Ghidra ([building.md](../building.md), "Reverse engineering") or in + `generated//`, and our runtime path in `runtime/`. Done when the code either rules the hypothesis out or names + the exact condition a run must show. A run confirms what the code could not rule out. +5. **The cheapest falsifying check.** An existing switch (a `totk.ini` setting or a `TOTK_*` variable), a dump, a trace + line, a probe. When it refutes the hypothesis, stop: write down what was checked and why it fell, and start again + at step 3 with the next hypothesis. No build, no benchmark for a refuted idea. +6. **Repro red, then green.** The same repro shows the bug before the fix and its absence after. A fix without a + reproduced failure is a guess. +7. **Fix the cause.** A crash that goes away with a feature off points at the bug in that feature; fix the feature. + A fix that one setup needs is gated on that setup, and everyone else keeps today's behaviour. + +## Traps + +- **One-off failures.** A failure that happens once and not again: rerun before you debug it as a code bug. A crash or + a forced shutdown leaves zero-filled cache files, and memory errors on the host flip bits in files and objects. +- **Every build fails the same way at once.** Suspect the inputs and caches (game files, the OS file cache, shader and + pipeline caches), not the code. Bisecting code is pointless when the old builds fail too. +- **Compile errors in generated C** on a line the generator could not have written are a flipped bit. Regenerate and + compare hashes; `recomp/` is fine. +- **A crash that looks like a race.** Try the save first: some saves crash the same way on a real Switch. +- **Theories about locks and threads.** Read the game's own protocol in Ghidra before running anything. Ten runs on + lock theories once went where one read of the game's double-buffer code would have narrowed it. +- **Numbers from a fast machine.** A change neutral on a fast desktop can matter on a weak laptop or the Steam Deck, + in either direction. Say which hardware your numbers come from. + +## Bug classes of a recompiled Switch game + +The port runs the game's own code on another OS and another GPU. Most bugs come from places where the host differs +from the console. + +### Variable frame step and epsilon-gated timers + +The console steps the game by whole 30 Hz units, so a countdown started at a whole value reaches exactly 0. With the +real-time step (`realtime = 1`, the default) the step is a measured ratio, and the last step can leave a remainder of +about 1e-8. Many of the game's updaters step a timer only while it is above `FLT_EPSILON`; a remainder in +(0, `FLT_EPSILON`] is never stepped again. A consumer that tests the same field with `> 0` then sees it active +forever, until a load reinitialises the object. Issue #18 (weapons locked after a Fuse) was this. + +Symptom words: stuck until a reload, a teleport or a shrine; locked after an action; works sometimes; only above +30 fps. To check a report: find the field the stuck behaviour reads, then compare the updater's threshold with the +consumer's test. A change to the frame step, the pacer or the fps limit is checked for this class. + +### Thread scheduling: Horizon is not a desktop OS + +- Horizon runs a woken better-priority thread at once on its core, before the thread that woke it goes on. A host + runs both in parallel, so state can be read one step early or freed while another thread still uses it. +- Threads created with ideal core -2 start pinned to one core on Horizon. The game keys per-core data by + `GetCurrentProcessorNumber` without locks and expects that pinning. +- The game has hundreds of spin loops without a system call. On the console a spinning thread holds one core of three; + on the host it burns a host core and can keep an equal-priority waiter out. +- ARMv8 `stlr` followed by `ldar` is ordered (RCsc). C11 release/acquire lets x86 reorder that store and load. A + two-thread flag handshake that loses a wake points here; lifter changes to barriers and atomics pass + `tests\diff\atomic.py` and `tests\excl_mt.py`. +- A scheduling change is judged by how long a ready, better thread waits for a core it may use, plus the slow-frame + count. A check that made one bug rarer once added 50-75 ms hitches. + +### Maxwell behaviour versus Vulkan defaults + +The port must do what the Switch GPU does: last-vertex provoking, (0,0,0,1) for unwritten vertex outputs, colour +targets outside the shader's output map keep their texels, the G-buffer pass samples its own targets. The full list +with sources: [maxwell.md](../maxwell.md), section 7. + +### Memory shared by the CPU and the GPU + +- The game fills textures and buffers with the CPU and samples them on the GPU without the flush a desktop API needs. + Missing uploads show as magenta, brown or stale textures. +- The game reads GPU-rendered textures with the CPU (grass maps, cut and burn masks). Missing write-backs show as + effects that never happen: cut grass stays up, fire does not spread. +- Memory only the GPU writes looks idle to write-watch tracking: a store from a shader leaves no fault and no dirty bit. +- Anything kept per texture, per frame or per object without a free grows host memory until a commit failure after + hours. Watch private memory over a few idle minutes. + +### Device lost and GPU hangs + +- The `vk: pass marks` lines name the pass in flight. Validation names the misuse when there is one. +- Submits and presents share one queue under one lock. A present from its own thread on a second queue gave device + lost on NVIDIA before Turing in another port. +- Caches from another driver or GPU (pipeline caches, translated shaders) gave black windows after driver updates; + every cache is validated on load and dropped when vendor, device or `pipelineCacheUUID` change. +- A first-time shader stall over 2 s on a slow GPU trips the Windows GPU timeout (display event 4101). Large one-shot + submissions (a boot-time decode of every texture) do the same. +- Point lists from vertex shaders that write no point size are undefined without `VK_KHR_maintenance5`. + +### Windows and Wine host costs + +What the hot path must not do, with measured costs: [pr-review-kit/02-performance.md](../pr-review-kit/02-performance.md), +"What the hot path must not do". For debugging, also: + +- `SuspendThread` returns at once, but `GetThreadContext` waits until the thread leaves the kernel. A sampler or a + debugger stalls for as long as the stopped thread's file open or driver call runs. +- A thread stopped between its `sub rsp` and its stack probe has its stack pointer inside the guard page. Check + `PAGE_GUARD` with `VirtualQuery` before reading another thread's stack. +- Paths go through the W APIs with UTF-8 to UTF-16 conversion. An A API call breaks on a path with non-Latin letters, + such as a Windows user name in Cyrillic or Chinese. +- Wine emulates `GetWriteWatch` with `mprotect` and one fault per first write. Anything relying on cheap OS memory + tricks (write-watch, protection changes, fault handlers) costs more under Proton. +- `win32u.dll` frames in a host stack are kernel graphics calls: memory allocation or submission. diff --git a/docs/agents/running.md b/docs/agents/running.md new file mode 100644 index 00000000..926a09b4 --- /dev/null +++ b/docs/agents/running.md @@ -0,0 +1,90 @@ +# Running and observing the game as an agent + +How an agent runs a build into gameplay without a person at the controls, captures what the game shows, and reads the +results without flooding its context. Setting names and file formats live in [settings.md](../settings.md) and +[controls.md](../controls.md); this page says which to use when. How to judge a performance change: +[pr-review-kit/02-performance.md](../pr-review-kit/02-performance.md). + +## Before the first run + +- **A build dir per change.** Build into its own folder (`tools/build_game.py --out build/-`) so a + comparison has two exes side by side. After every build check the exe's modification time: a failed link leaves the + old `totk.exe` in place and you test old code. +- **Prepared shaders in that folder.** `tools/prepare_shaders.py build/ --version ` ([building.md](../building.md) + step 6). Without it the game compiles shaders during play, and every timing and every "a draw is missing" shot of the + first minutes says nothing about your change. Shader and pipeline caches are not copied between build folders. +- **The same `totk.ini` on both sides** of any comparison. A folder without one runs at the defaults; check the log's + `resolution:` line of each run before comparing them. +- **Saves.** `tools/run_game.py` copies the profile `build/profile`, swaps in a save from `build/save-backup//` + and deletes the copy afterwards, so the real profile is never written. To make a backup, copy the user folder from + `build/profile/save/` into `build/save-backup//`. Pick a save that starts where the change acts. + +## Running + +```powershell +.venv\Scripts\python tools\run_game.py build\ --save --seconds 30 [--script ] [--shot out.png] [--env KEY=VALUE] [--quiet] [--tag ] +``` + +- `--seconds` is game time since the world loaded (the log line `frame step: world clock starts` marks the start), at + any frame rate. Measure and script by game time; a frame count at another fps is another scene. +- `--script` replays input ([controls.md](../controls.md), "Scripted input"). A new script starts with the presses of + `tools/input/load_save.txt`, which load the first save from the title. `TOTK_INPUT_RECORD` turns a person's play into + a script; ask the user to record the repro rather than guessing the button sequence. +- `--shot` saves the last frame and builds pipelines synchronously: use it for pictures, never for timing. +- `--quiet` waits until no other `totk.exe` or `ninja.exe` runs. Every timing you report comes from a `--quiet` run. +- The log goes to `\logs\.log`; the tool prints `: rc=`. + +Run one game at a time: two instances share the GPU's memory and the CPU, and both runs' numbers are void. + +Running `totk.exe` yourself: set `TOTK_ASSUME_FOCUS=1` (an unfocused window otherwise pauses the game), +`TOTK_INPUT=none` (the user's keyboard and pad stay out) and `TOTK_BACKGROUND_WINDOW=1`. Stop only the process you +started, by PID: `taskkill /IM totk.exe` also closes the user's game. + +**Check that the run reached the world** before trusting it: the world clock line is in the log and the shot shows the +scene you expected. Title menus on a slow boot eat presses, and runs of one script drift apart after 10-15 game seconds +(enemy AI, physics, weather). Two runs are comparable only when shots at the same game second show the same scene. + +## Observing + +| You need | Use | +|---|---| +| pictures over a time span | `TOTK_SHOTS=w-:` (world seconds) and `TOTK_SHOTS_DIR`; 480x270 by default | +| the frames around a hitch or a one-frame glitch | `TOTK_FLIGHT=1`: keeps the last 600 frames with timings and thumbnails, dumps on F8, on a frame over `TOTK_FLIGHT_SPIKE_MS` or at `TOTK_FLIGHT_AT=`; `python tools/flight_view.py ` lists the worst frames and writes a contact sheet | +| every render pass of one frame | `TOTK_DUMP=` and `TOTK_DUMP_DIR`: a PNG per pass target plus `passes.txt` (draws, bound textures with swizzles, storage buffers, copies, clears) and `images.txt`; `TOTK_DUMP_BUF` adds a guest buffer | +| Vulkan misuse | `TOTK_VK_VALIDATION=1` (needs the Vulkan SDK), run into the world; compare the message kinds with a run without your change. The layer caps repeats, so counts are not totals | +| which pass the GPU was in at a device lost | the `vk: pass marks` lines; on by default on AMD, `TOTK_PASS_CRUMBS=1` elsewhere | +| a crash | the crash report at the end of the log: exception, guest and host addresses, registers | +| a run on a large card that acts like a small one | `TOTK_VRAM_LIMIT_MIB=` | + +Frame dumps: a draw's argument lines come before its pass header. Pass numbers shift between runs, so find a pass by +its draw count or its targets, not by its number. RenderDoc cannot capture this renderer ([controls.md](../controls.md), +"RenderDoc capture"). + +## Measuring + +| What | How | +|---|---| +| fps, worst frame, render-thread waits, GPU busy time, VRAM, `bound: gpu\|cpu\|pace` | `--env TOTK_TRACE=perf,sched`, then `python tools\perf_summary.py ` | +| slow frames | count the `perf: slow frame` lines; each names what the render thread was blocked on (pipeline, translation, texture, fence, pacing) | +| the frame's critical path, by thread and state | `TOTK_CRIT=w-` and `TOTK_CRIT_OUT=` with `sched` tracing, then `python tools\crit_path.py ` | +| where CPU time goes | `TOTK_PROFILE=` and `TOTK_PROFILE_FRAMES=w-`, then `python tools\prof_report.py `; `TOTK_PROFILE_RENDER=1` samples the render thread with call chains | +| a switch on a static scene | a setting set to `ab` with `TOTK_AB=` alternates the two sides in blocks of game time; `python tools\ab_summary.py --skip `. On a moving scene compare whole runs instead | + +A single run proves little: runs of one script on one build spread by a third in their 1% lows. Compare medians of at +least two whole runs per side, on a quiet machine. + +## Probes + +Each probe is a mode of `totk.exe`, run from the build folder; the list with what each covers is at the top of +`runtime/main.c`. `--selftest` needs no game files. `--probe-kernel`, `--probe-vkexec`, `--probe-nvn-tex` and +`--probe-shader` cover most runtime changes and run in seconds: run them before any game run. + +## Reading output without filling the context + +- Game logs run to megabytes. `grep` the lines you need, `tail` the end, pipe `perf_summary.py` through `grep SUMMARY`. +- Generated C runs to hundreds of thousands of lines per file. `grep -n` the function, then print its line range. +- Look at screenshots downscaled: paste several into one 1280x720 grid and read the grid once. Write down what it shows + instead of opening it again. +- Send long builds and runs to the background with their output in a file; read the last lines when they end. +- Keep a notes file in the build folder from the first finding: what is ruled out, the leading hypothesis, the next + step, temporary debug edits with file and line. A fresh session continues from it. diff --git a/docs/agents/symptoms.md b/docs/agents/symptoms.md new file mode 100644 index 00000000..55a2aca0 --- /dev/null +++ b/docs/agents/symptoms.md @@ -0,0 +1,71 @@ +# Symptoms and their usual causes + +What a player reports, the causes this port and other Switch ports (nxnative, MacNativeGames, SavageWindRecomp, +LAS Recomp) found behind it, and the first check. Search by the player's words and by the object. Which of these are +already fixed here, and where: [pr-review-kit/04-knowledge.md](../pr-review-kit/04-knowledge.md), "Fixed bug classes". +GPU semantics behind the graphics rows: [maxwell.md](../maxwell.md). The method around this table: +[debugging.md](debugging.md). + +## Graphics + +| Symptom | Usual causes | First check | +|---|---|---| +| magenta, brown or stale textures; caves or sky wrong | the CPU filled the texture and the GPU never got the upload (no flush on the console) | frame dump: the texture's upload count and mirror state in `passes.txt` | +| effects that never happen: cut grass stays up, fire does not spread | the CPU reads a GPU-rendered texture that was never written back | which texture the game reads after its fence; write-back of that target | +| black scene, black dialog background or loading map | deferred binds read at record time; a 3D target rejected; a texture compare ignoring the channel mapping | frame dump: the first pass whose target goes black | +| lime silhouettes, rectangles in the sky | a target outside the shader's output map overwritten instead of kept | dump: the target's previous contents versus after the pass | +| dark or magenta 16x16 blocks, missing characters | a pass samples its own render targets (G-buffer feedback) | feedback-loop layout and barriers on that pass | +| tile rectangles, wrong data in tiles | storage buffers bound in the wrong slot order | `passes.txt`: storage buffers with their c0 slots | +| streaks on cliffs, characters stretched into streaks | primitive restart ignored; integer vertex inputs against a float format | validation run; the draw's topology and vertex formats in the dump | +| garbage geometry on title or load screens | 8-bit indices widened on the CPU before a copy in the same submission wrote them | whether a copy to the index buffer precedes the draw in one submission | +| black tiles, masks not cleared | clears with a partial channel or stencil mask skipped or done in full | `passes.txt` clears and their masks | +| garbage in feedback effects at first use | new GPU-only images start undefined; the console starts them at zero | clear on creation and compare | +| empty clouds or fog for the whole session | a one-shot draw skipped while its pipeline built, never drawn again | `perf: slow frame` lines naming pipeline waits; the draw's first frame | +| fog that never parts, flicker in tile rows | driver constants (c0: dispatch size, point size, base instance) not filled | the c0 contents the translator expects for that stage | +| no sun shadows, wrong lighting | unwritten vertex outputs read as zero instead of (0,0,0,1) | the shader's output map | +| one flat ambient colour | a 1-layer 2D array sampled as 2D | the view type the shader expects | +| upside-down text | lower-left window origin | origin mode in the log | +| flicker or a texture swapped with a similar one | the newest texture picked at shared storage instead of the one with the matching view | texture lookup by id in the dump | + +## Timing and frame pacing + +| Symptom | Usual causes | First check | +|---|---|---| +| stuck until a reload or teleport, locked after an action | a timer remainder below `FLT_EPSILON` with the real-time step ([debugging.md](debugging.md)) | `realtime = 0` in `totk.ini`; if the bug is gone, find the timer field | +| slow motion in GPU-heavy scenes, dynamic resolution never drops | the engine's GPU time comes from report timestamps; wrong timestamps make the frame look free | what the engine reads as GPU time and what the report writes | +| frame counter wanders 50-60 | two 60 Hz clocks (vsync event and present acquire) drifting apart | whether both follow one display tick | +| a 30 Hz thread runs at 27 Hz, slow cutscenes | host sleep overshoot: Windows waitable timers wake 0.3-0.5 ms late | `TOTK_TRACE=sched` sleep asked versus took | +| 20 fps after a scheduler change | a yield back-off that starts too early | yield handling against the console's | +| climbing or movement wrong only above some fps | game code that assumes a fixed step count per frame | compare at 30, 60 and the failing rate | + +## Threads and crashes + +| Symptom | Usual causes | First check | +|---|---|---| +| state read one step early, one frame of inconsistent data | a woken better-priority thread does not run before the waker goes on | sched trace around the handoff | +| per-core data corrupted, rare crash in a container walk | threads the console pins to one core run on any host core | the thread's core mask from its creator; a run on one core | +| rare hang or lost wake | address-arbiter signal values or wake order differ from Horizon | the arbiter path against mesosphere | +| a flag handshake loses a wake | `stlr`/`ldar` ordering lost in x86 release/acquire | the guest code's barrier pattern | +| a host core at 100% while the game waits | game spin loops without system calls | profile: which guest function spins | +| crash on world load | sizes the game reads from the driver (command memory used) differ from the console's | the sizes the game asks for against the console's | +| crash with one save only | the save itself; some crash on a real Switch | the same save on another build and, if possible, on hardware | + +## Device lost, hangs, black window + +| Symptom | Usual causes | First check | +|---|---|---| +| device lost a few frames in, GPU writes to address 0 (older NVIDIA) | present from another thread or queue | every submit and present on one queue under one lock | +| device lost or garbage on one AMD generation | views the driver branch mishandles (BC block views of 3D textures) | `vk: pass marks`, validation; the formats in the pass | +| device lost on one scene, every run, one vendor | a shader or pass that driver cannot run | pass marks name the pass; skip shaders by hash to bisect | +| GPU timeout after 1-2 min, single frames over 2 s | first-time shader stalls or a huge one-shot submission on a slow GPU | prepared shaders; submission sizes at boot | +| GPU hang at boot with pipeline libraries | point lists without a point size | the shader writes point size or the device clamps it | +| black window after a driver update | caches from another driver | the log line `vk_pipeline: ... written by another device or driver`; delete the caches next to `totk.exe` | + +## Memory + +| Symptom | Usual causes | First check | +|---|---|---| +| host memory grows in play until a commit failure after hours | state kept per texture init or per frame and never freed | private memory over a few idle minutes | +| multi-GB peaks while travelling | upload staging grows inside one submission | staging bytes per submission | +| out of memory after minutes | dead textures re-entering tables | live images and allocator bytes over time | +| stutter as VRAM fills | new memory blocks allocated on the render thread (8-23 ms each) | profile the render thread over the hitch: `vkAllocateMemory` under the allocator's lock | From 2d2c6782afa66f0e025843cfa848484dd456d7f1 Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 18:50:36 +0300 Subject: [PATCH 15/16] Record the runtime headers a PGO profile was trained with and warn when they change The floating-point helpers in simd.h and simd_fp.h inline into every lifted function before llvm-profdata matches the profile, so the fpcheap change left pgo-v143 with a fifth of its weight while recomp/ stayed the same and make_release saw nothing. pgo.py merge now reads the instrumented build's Ninja deps log and stores the digests of the runtime/ headers the generated objects include (cpu.h, simd.h, simd_fp.h); make_release warns when one differs or a record has none. docs/building.md says to retrain after a change to those headers, and build_game.py names the libiconv-2.dll that MSYS2's SDL3.dll needs in deps-mingw/bin. Co-Authored-By: Claude Opus 5.5 --- docs/building.md | 15 ++++++---- tools/build_game.py | 5 ++-- tools/make_release.py | 17 ++++++++++-- tools/pgo.py | 64 +++++++++++++++++++++++++++++++++++++++---- 4 files changed, 85 insertions(+), 16 deletions(-) diff --git a/docs/building.md b/docs/building.md index fd972520..0c89a0fa 100644 --- a/docs/building.md +++ b/docs/building.md @@ -165,9 +165,12 @@ with it too: hot paths laid out straight, hot calls inlined, code that never ran bench ran 12-15% faster per frame and a fight outside the training about 6%. The installer builds with `data/pgo-.profdata` of the release when the update has one, else at -O1. -A profile only fits the generated C it was trained on: functions are matched by name and control-flow hash, so a -function whose C changes loses its counts without a warning. Retrain after a lifter or generator change, from a clean -`recomp/`. The instrumented build needs llvm-mingw, as MSYS2's clang has no profile runtime: +A profile only fits the code it was trained on: functions are matched by name and control-flow hash, so a function +whose code changes loses its counts without a warning. That code is the generated C plus the runtime headers it +includes (`cpu.h`, `simd.h`, `simd_fp.h`), whose inline helpers become part of every lifted function: a change to the +floating-point helpers once left a profile with a fifth of its weight and 2% of its gain. Retrain after a lifter or +generator change or a change to those headers, from a clean `recomp/`. The instrumented build needs llvm-mingw, as +MSYS2's clang has no profile runtime: ```powershell $llvm = "toolchain\llvm-mingw-\llvm-mingw--ucrt-x86_64" @@ -182,8 +185,10 @@ Scripted runs from saves (`tools/run_game.py`) add to the same file. Then: .venv\Scripts\python tools\pgo.py merge build\v143-pgogen --version v143 ``` -writes `build\pgo\pgo-v143.profdata` and its record (`.json`: the `recomp/` tree it fits). `make_release.py` ships every -profile of `build\pgo` in `data\` and warns when a record names another `recomp/` tree than the one released. +writes `build\pgo\pgo-v143.profdata` and its record (`.json`: the `recomp/` tree it fits and the digests of the runtime +headers the generated C included, read from the build's Ninja deps log). Merge from the checkout the instrumented build +was made in. `make_release.py` ships every profile of `build\pgo` in `data\` and warns when a record names another +`recomp/` tree than the one released or a header differs. ## Linux (in progress) diff --git a/tools/build_game.py b/tools/build_game.py index ce20c9f4..a471fb2f 100644 --- a/tools/build_game.py +++ b/tools/build_game.py @@ -46,8 +46,9 @@ of its processes (Windows job object accounting: committed private bytes). --ninja PATH names the Ninja to run; without MSYS2 the bin/ninja.exe of the release folder (tools/make_release.py) is used. --toolchain DIR builds with an llvm-mingw tree (DIR/bin/clang.exe) instead of MSYS2 UCRT64 clang. Ninja still comes from MSYS2. The libraries and headers MSYS2 supplies (Vulkan, SDL3, Opus, libvpx, VMA) then come from --deps DIR -(default toolchain/deps-mingw: include/, lib/ with the import libraries and libvpx.a, bin/ with the DLLs), and the C++ -runtime is libc++ from llvm-mingw. Such a build never reuses another build's generated objects. +(default toolchain/deps-mingw: include/, lib/ with the import libraries and libvpx.a, bin/ with the DLLs copied next to +totk.exe: SDL3.dll, libopus-0.dll and, when SDL3.dll comes from MSYS2, the libiconv-2.dll it imports, without which +the exe stops at start with 0xc000007b or a missing-DLL error), and the C++ runtime is libc++ from llvm-mingw. Such a build never reuses another build's generated objects. Split build. --make-runtime-lib compiles only runtime/ into /libtotkrt.a (what CI prebuilds). --runtime-lib PATH then compiles only the generated C and the install-time files (modules.c and INSTALL_SIDE, which bake the player's diff --git a/tools/make_release.py b/tools/make_release.py index 5f407103..e2faa33e 100644 --- a/tools/make_release.py +++ b/tools/make_release.py @@ -54,6 +54,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parent)) import build_game # noqa: E402 import build_xlate # noqa: E402 import check_content # noqa: E402 +import pgo # noqa: E402 import shader_list # noqa: E402 ROOT = Path(__file__).resolve().parent.parent @@ -385,11 +386,13 @@ def lifted_version(): def profiles(): - """{version tag: .profdata} of build/pgo (tools/pgo.py merge). A profile trained on another recomp/ than the one - shipped still works but misses the functions whose generated C changed since: warn, so the next release retrains.""" + """{version tag: .profdata} of build/pgo (tools/pgo.py merge). A profile trained on another recomp/, or with other + runtime headers inlined into the generated C, than the ones shipped still works but misses the functions whose + code changed since: warn, so the next release retrains.""" tree = subprocess.run(['git', '-C', str(ROOT), 'rev-parse', 'HEAD:recomp'], capture_output=True, text=True).stdout.strip() dirty = subprocess.run(['git', '-C', str(ROOT), 'status', '--porcelain', '--', 'recomp'], capture_output=True, text=True).stdout.strip() + retrain = 'build without a profile; retrain (docs/building.md, "Profile-guided build")' found = {} for p in sorted(PGO_DIR.glob('pgo-*.profdata')): rec = p.with_suffix('.json') @@ -397,7 +400,15 @@ def profiles(): if record.get('recomp_tree') != tree or dirty: print(f'make_release: warning: {p.name} was trained on recomp tree {record.get("recomp_tree", "unknown")[:12]}, ' f'this is {tree[:12]}{" with local changes" if dirty else ""}: functions whose generated C changed ' - 'build without a profile; retrain (docs/building.md, "Profile-guided build")', file=sys.stderr) + f'{retrain}', file=sys.stderr) + stale = pgo.stale_headers(record, ROOT) + if stale is None: + print(f'make_release: warning: {p.name} has no runtime header digests (merged before they were recorded): ' + 'a change to a header the generated C includes would go unnoticed; re-merge or retrain', + file=sys.stderr) + elif stale: + print(f'make_release: warning: {p.name} was trained with other {", ".join(stale)}: every lifted function ' + f'that inlines them may {retrain}', file=sys.stderr) found[p.stem.removeprefix('pgo-')] = p if not found: print(f'make_release: no execution profile in {PGO_DIR}: installs build the game at -O1', file=sys.stderr) diff --git a/tools/pgo.py b/tools/pgo.py index 3252552b..2b388bbd 100644 --- a/tools/pgo.py +++ b/tools/pgo.py @@ -6,18 +6,24 @@ An instrumented build (build_game.py --pgo gen) writes /pgo/default_. minute and at exit); successive runs of the same exe add to that file. llvm-profdata comes from the llvm-mingw toolchain the instrumented build used: its raw format is tied to the compiler version. -Beside the profile goes .json, the training record: the game version and the git tree of recomp/ at the merge. -The profile matches the generated C of that generator; tools/make_release.py ships it only while recomp/ is unchanged, -since llvm-profdata matches functions by name and control-flow hash and a regenerated function silently loses its -counts. Merge right after the training runs, from the commit they were built at. +Beside the profile goes .json, the training record: the game version, the git tree of recomp/ at the merge and +the digests of the runtime/ headers the generated C includes (gen_headers; their inline helpers end up inside every +lifted function). The profile matches the generated C of that generator and those headers; tools/make_release.py warns +when either changed, since llvm-profdata matches functions by name and control-flow hash and a changed function +silently loses its counts. Merge right after the training runs, from the checkout and commit they were built at. """ import argparse import datetime +import hashlib import json +import os import subprocess import sys from pathlib import Path +sys.path.insert(0, str(Path(__file__).resolve().parent)) +import build_game # noqa: E402 + ROOT = Path(__file__).resolve().parent.parent EXE = '.exe' if sys.platform == 'win32' else '' DEFAULT_DIR = ROOT / 'build' / 'pgo' # tools/make_release.py takes pgo-.profdata from here @@ -44,6 +50,51 @@ def recomp_tree(): text=True).stdout.strip() or None +def header_digest(path): + return hashlib.sha256(path.read_bytes()).hexdigest()[:16] + + +def gen_headers(build): + """{runtime-relative path: digest} of the runtime/ headers the generated objects of an instrumented build include, + from its Ninja deps log. Their inline helpers (simd_fp.h, cpu.h, ...) become part of every lifted function before + the profile is matched, so a change to one invalidates the profile as surely as a generator change.""" + env = dict(os.environ, PATH=str(build_game.UCRT) + os.pathsep + os.environ.get('PATH', '')) + r = subprocess.run([str(build_game.NINJA), '-f', str(build / 'build.ninja'), '-t', 'deps'], cwd=ROOT, env=env, + capture_output=True, text=True) + if r.returncode: + sys.exit(f'ninja -t deps failed in {build}: {(r.stdout + r.stderr).strip()[-500:]}') + runtime = (ROOT / 'runtime').resolve() + found, cur = {}, False + for line in r.stdout.splitlines(): + if not line.startswith(' '): + target = line.split(': #deps')[0].replace('\\', '/') + cur = '/obj/' in target and '/obj/runtime/' not in target + continue + if not cur: + continue + p = Path(line.strip()) + p = (p if p.is_absolute() else ROOT / p).resolve() + try: + rel = p.relative_to(runtime).as_posix() + except ValueError: + continue + if rel not in found: + found[rel] = header_digest(p) + if not found: + sys.exit(f'no runtime/ header in the deps log of {build}: was it built from this checkout?') + return dict(sorted(found.items())) + + +def stale_headers(record, root): + """The headers of a training record that differ in root/runtime now (missing ones included); None when the record + predates the header list.""" + headers = record.get('gen_headers') + if headers is None: + return None + rt = root / 'runtime' + return [h for h, d in headers.items() if not (rt / h).is_file() or header_digest(rt / h) != d] + + def merge(build, out, version, toolchain): raw = sorted((build / 'pgo').glob('*.profraw')) if not raw: @@ -51,6 +102,7 @@ def merge(build, out, version, toolchain): tree = recomp_tree() if not tree: sys.exit('recomp/ has uncommitted changes: the record could not name the generator the profile matches') + headers = gen_headers(build) out.parent.mkdir(parents=True, exist_ok=True) tmp = out.with_suffix('.profdata.tmp') cmd = [str(llvm_profdata(toolchain)), 'merge', '--failure-mode=all', '-o', str(tmp), *map(str, raw)] @@ -60,11 +112,11 @@ def merge(build, out, version, toolchain): sys.exit(f'llvm-profdata merge failed: {(p.stdout + p.stderr).strip()[-2000:]}') tmp.replace(out) record = {'version': version, 'recomp_tree': tree, 'merged': datetime.date.today().isoformat(), - 'raw_files': len(raw)} + 'raw_files': len(raw), 'gen_headers': headers} out.with_suffix('.json').write_text(json.dumps(record, indent=1) + '\n', encoding='utf-8') size = sum(f.stat().st_size for f in raw) print(f'{out}: {len(raw)} raw files ({size / 2**20:.1f} MiB) -> {out.stat().st_size / 2**20:.1f} MiB; ' - f'recomp tree {tree[:12]}') + f'recomp tree {tree[:12]}, {len(headers)} runtime headers') def main(): From 8aba3647e09532aa4acde5f0b2feff99e0faaf3e Mon Sep 17 00:00:00 2001 From: Valiantsin Dzerakh Date: Mon, 9 Nov 2026 19:57:07 +0300 Subject: [PATCH 16/16] Up version 0.3.14 --- VERSION | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSION b/VERSION index e4737652..0b69c00c 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.3.13 +0.3.14