Compare commits

...
Author SHA1 Message Date
poli0981andClaude Fable 5.2 a0690a4bc2 feat(overlay): two more members of NVIDIA's latency report - the driver's active GPU time and its GPU frame time - and every frame-generation multiplier a session saw; four reserved words, layout still 5; a read left by the session before is dropped (D142, D144; in no release yet)
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 09:53:52 +07:00
poli0981andClaude Fable 5.2 3df56f0ca1 docs: item 45 on Cyberpunk 2077 and three games the read leaves alone - read twice, 65 us at the slowest, GPU render sane there; the owner's answer: read the driver's active time (#449)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 02:31:32 +00:00
poli0981andClaude Fable 5.2 80b4437169 docs: the first real game read on 0.1.0-beta.47 - Phantom Blade Zero, three sessions: the driver found and read every second, the slowest call 45 us, no latch; its GPU render span is longer than its total there (item 45) (#448)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 02:09:38 +00:00
poli0981andClaude Fable 5.2 268ad75585 docs(handoff): 0.1.0-beta.47's release facts - the tag's run, the digests, the delta, the wiki, what SonarCloud and Qodana said on the release's commit; and a local gate that a vanished test program made red, not falsely green (#447)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 01:39:20 +00:00
poli0981andClaude Fable 5.2 3d7c273e3b release: 0.1.0-beta.47 - with Advanced metrics on, the part inside a game asks NVIDIA's driver for its latency report (D132, D136, D138-D141); the batch log says how a batch ended (D137); item 44 (d) run by the owner, twice; owner-only item 45 (#446)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 07:56:00 +07:00
poli0981andClaude Fable 5.2 29b84832ee docs(handoff): item 44 (d) was tried on 2026-11-14 and not exercised - the switch was on before the games started (two sessions refused, nothing injected), and the hooked session ran to its exit; how (d) is run (#445)
Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 00:15:09 +00:00
poli0981andClaude Fable 5.2 cd4f69af1a feat(advanced): the driver's latency report in the Agent and the App - seven series and one table under Latency; Privacy Policy 2.20 and Disclaimer 2.16; owner-only item 45 (D132, D136, D138-D141; in no release yet) (#444)
* feat(advanced): the driver's latency report in the Agent and the App - seven series and one table under Latency, what became of the read said in words; reaches GameDriver and RefusedRoute; Privacy Policy 2.20 and Disclaimer 2.16; owner-only item 45 (D132, D136, D138-D141; in no release yet)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs: the owner kept the 2 ms latch at one call after the busy-PC run (D141)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* test(app): no redundant qualifier and no redundant null suppression in the driver-read tests (Qodana)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 06:30:00 +07:00
poli0981andClaude Fable 5.2 80d1048235 feat(overlay): the driver's latency report, read while a session asks - two read-only getters, once a second, on the presenting thread; the gates that hold it (D132, D136, D138-D141; in no release yet) (#443)
* feat(overlay): the driver's latency report, read while a session asks - two getters of an nvapi64.dll the game loaded, about once a second on the presenting thread, behind a gate of four states; a module beside the executable refused, a fault or a call of 2 ms the last one; the gates that hold it (D132, D136, D138-D141; in no release yet)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(overlay): the latency log line measures its path with a bound (cpp:S5813)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(overlay): the resolve switch names every outcome (Qodana native: clang-diagnostic-switch-enum)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 00:29:23 +07:00
poli0981andClaude Fable 5.2 70a81ed765 feat(shm): the Reflex latency words of region 5 - ten reserved words named, written by nobody; the layout stays 5 (D136, D138) (#442)
* spike(reflex): the leg with a sleep - the decision table, written before the run (D139)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* spike(reflex): the getters while the game sleeps - a leg of the probe with a sleep mode, three runs, no stop condition (D139); the plan's four decisions (D138-D141) and the train's design in HANDOFF

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* feat(overlay): the PATCH_BATCH line says how a batch ended - install / restore for one apply, install singly / restore singly with the count in the high half of b (D137)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* feat(shm): the Reflex latency words of region 5 - ten reserved words named, written by nobody; the layout stays 5 (D136, D138)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 23:43:12 +07:00
poli0981andClaude Fable 5.2 c02ee63a4e feat(overlay): the PATCH_BATCH line says how a batch ended - one apply, or finished one patch at a time (D137) (#441)
* spike(reflex): the leg with a sleep - the decision table, written before the run (D139)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* spike(reflex): the getters while the game sleeps - a leg of the probe with a sleep mode, three runs, no stop condition (D139); the plan's four decisions (D138-D141) and the train's design in HANDOFF

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* feat(overlay): the PATCH_BATCH line says how a batch ended - install / restore for one apply, install singly / restore singly with the count in the high half of b (D137)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 23:16:30 +07:00
poli0981andClaude Fable 5.2 f8d4945e6d spike(reflex): the getters while the game sleeps - the probe's leg with a sleep mode (D139), and the decisions and design of the train that follows (D138-D141) (#440)
* spike(reflex): the leg with a sleep - the decision table, written before the run (D139)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* spike(reflex): the getters while the game sleeps - a leg of the probe with a sleep mode, three runs, no stop condition (D139); the plan's four decisions (D138-D141) and the train's design in HANDOFF

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 22:46:16 +07:00
poli0981andClaude Fable 5.2 fc8072019e docs(handoff): what the owner's five sessions on 0.1.0-beta.46 showed (item 44) - the batches went in whole in five games; two long ones not explained; the stop not exercised (#439)
* docs(handoff): what the owner's five sessions on 0.1.0-beta.46 showed - eighteen install batches in five games, sixteen at 81-262 ms whatever they held, two not explained (Hogwarts Legacy 1.26 s, Cyberpunk 2077 0.61 s); the stop while a game runs was not exercised; item 44's sentence about a fallback corrected

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs: the owner's answers of 2026-11-13 - Reflex route D goes to a plan for one real title, Cyberpunk 2077 (D136); the PATCH_BATCH line says how a batch ended, with the next release (D137)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 14:27:34 +00:00
poli0981andClaude Fable 5.2 2c9bc3e17c test(native): a test that is cut short is not a pass - every native test names the line it ends on and ctest requires it, a test registered without one fails the configure, and four canaries prove the rule red and green (#438)
On 2026-11-13 security software removed a freshly linked fl_guard_test.exe while a local gate ran: the process
ended early with exit code 0 and ctest printed "fl_guard ... Passed 0.66 sec" for a suite that takes three
minutes. Only the next test, which runs the same executable, made the gate red.

- src/native/CMakeLists.txt: fl_test_completes(<test> <regex>...) and fl_catch2_test_completes(<test>...) set the
  line a test must print (Catch2: "All tests passed (", or its summary row with a skipped case, never a row that
  names a failure); fl_require_every_test_completes() fails the configure when a test in tests/ or tools/ was
  registered without one.
- All 35 tests go through one of the two, each on the last line it already printed; no program changed.
- Four canaries print what a Catch2 run would - nothing, its last line, a row with a skipped case, a row with a
  failure beside "passed" - through the same helper; the two that must be red are WILL_FAIL.
- fl_nvapi_bridge, fl_process_stats, fl_nvapi_probe and fl_signer_probe passed on a line printed in the middle of
  their run; they now need it and, after it, their last line. fl_nvapi_probe also passed whatever followed its
  branch line - a pass expression makes ctest ignore the exit code.

Docs: 14_TESTING, HANDOFF, the changelog. No shipped code.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 20:36:41 +07:00
poli0981andClaude Fable 5.2 aa30080e06 docs(handoff): 0.1.0-beta.46's release facts - the tag's run, the digests, the delta, the wiki, what SonarCloud and Qodana said on the release's commit; and a local gate that counted a test cut short as passed (#437)
- Released 2026-11-13T11:10:28Z from the signed tag on 47f010a by run 43412434074; eight assets, seven digests
  equal, the build id in four natives, the delta 634,023 bytes, the wiki run. SonarCloud's gate passed on the
  release's commit with no issue open; Qodana's two reports are green on it.
- Security software on the development PC removed the freshly linked fl_guard_test.exe while a local gate ran, and
  ctest reported the run that was cut short as Passed after 0.66 s (the suite takes 181 s); only the next test,
  which runs the same executable, made the gate red. Recorded with a proposal; nothing changed.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 19:27:10 +07:00
poli0981andClaude Fable 5.2 39a747f2a3 spike: Reflex route D on the harness - the driver's two getters from an unshipped probe, against a stand-in module and the installed driver; no game touched (spike-notes §31; D132) (#436)
* spike: Reflex route D on the harness - the driver's two getters called from an unshipped probe, against a stand-in nvapi64.dll and against the installed driver; a decision table written before the runs, and what they showed (spike-notes §31; D132)

No shipped code changes and no game was touched.

- tools/fl-probe-reflex: fl_reflex_candidate.h, the call sequence that would move into the Overlay (find
  nvapi64.dll only if the process already holds it, resolve NvAPI_D3D_GetLatency and NvAPI_D3D_GetSleepStatus by
  interface id, call them SEH-guarded); --stub against tools/vendor-stubs/stub_nvapi64.cpp (ctest
  fl_reflex_probe_stub); --real against the installed driver with the probe playing the game's part - it sets
  latency markers on its own device, in its own process.
- docs/spike-notes/31-reflex-route-d-harness.md: nine pre-committed measurements and their results. No fault
  before initialisation, without markers, or beside a marker-setting thread (38 million reads); a call costs half
  a microsecond; the Direct3D 12 device the Overlay holds is the object the driver takes; the report's unit is
  microseconds. The call belongs on the presenting thread once a second, not on the watchdog. The newest frames
  of a report are not final. Ends in the owner's go or no for one real title.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs(spike): §31 in the index, §M14 and §30 point at what the harness spike showed; the probe and its stub in the build document and CLAUDE.md's tools list

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* docs(spike): HANDOFF says the route D spike is done and what a plan must keep from it; the changelog names the probe as a developer's tool

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(probe): the Reflex probe's Measure takes its callable by const reference - a forwarding reference it never forwarded (Qodana native, cppcoreguidelines-missing-std-forward)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(probe): what SonarCloud reported on the Reflex probe - the counter read through the union member it was initialised with, a guard for an empty measurement, NvU32 printed as what it is, a variable no longer named module; and the note says what a fourth run measured (1.5 us a call, 70 us at worst)

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 19:05:59 +07:00
poli0981andClaude Fable 5.2 47f010a7b7 release: 0.1.0-beta.46 - hooks go into a game together and come out together: one stop of the game's threads for a batch of patches, not one a patch (D134); the pages brought up to date with the first real sessions on 0.1.0-beta.45; owner-only item 44 (#435)
- docs/changelog/0.1.0-beta.46.md takes [Unreleased] as it stood, under an introduction that says what the
  release is and is not; CHANGELOG.md keeps an empty [Unreleased] and gains the table row.
- docs/HANDOFF.md: the beta.45 section moves verbatim to docs/handoff/history/0.1.0-beta.45.md; a new START HERE -
  what the release decided beyond D132-D135 (the refused first design and the rules that replaced it, the gate, the
  engine's verdict, the fallback), the traps of the train, NEXT, what is left open.
- Owner-only item 44, with what each outcome means written before the run.
- The release lines: ACCESSIBILITY.md, LIMITATIONS.md, README.md, legal/ACCURACY.md, legal/DISCLAIMER.md.

Documents only; nothing under src/ changes.

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 17:51:54 +07:00
poli0981andClaude Fable 5.2 28c7760d28 feat(overlay): patches go in and come out under one stop of the game's threads - MinHook's queue, behind a gate (beta.46 PR-1; D134) (#434)
* feat(overlay): patches go in and come out under one stop of the game's threads - MinHook's queue for the rows a tick finds and for the stop, behind a gate, with only patches that are still ours ever marked for a restore (beta.46 PR-1; D134)

MinHook stops every thread of the process to write a jump, and enabling or disabling one hook did that for one
jump: thirteen Streamline patches took 0.74 s to 2.8 s of a game's start in the owner's sessions of 2026-11-13,
and a stop restored its patches the same way.

- fl_patch_registry.h: fl::patch::Batch (Add: slot and create, nothing marked; Commit: enable them all, then the
  re-read of the flag Install makes) and fl::patch::RestoreAll, the stop's walk. Install and Registry untouched.
- dllmain.cpp: InstallUpscalerHooks queues every row a tick finds something for and commits once, before the
  families published "when whole"; InstallRtHooks batches its two; StopObserving calls RestoreAll. A patch's
  HOOK_INSTALLED line, family bit and latch come in that order and only once it is in. A new log line an apply,
  PATCH_BATCH install|restore (a = microseconds, b = patches). No hook body changed.
- MH_ApplyQueued applies every hook whose mark differs from its state, whoever marked it. So no mark is left
  standing, only a patch that is still ours is marked for a restore and nothing is marked "all" (a draft that did
  could put a patch back in after a stop; refused on review against hook.c), and mark, apply and commit happen
  inside a gate - a slim lock on no hook body's path, never held across a symbol lookup, re-entered by its owner.
  The verdict on an install is the engine's, not the bytes'. An apply stops at its first failure: the hooks
  after it are enabled or restored one at a time.

Measured on hook-harness's Streamline target, three runs before and after: the nine Advanced-only patches,
0.60 / 0.70 / 0.60 s one by one, are one batch of 81 / 90 / 78 ms; the stop's eighteen, 1.37 / 1.56 / 1.37 s,
are one apply of 77 / 90 / 76 ms; unhook requested to UNHOOKED, 1.27-1.48 s, is 94-109 ms.

ctest fl_unhook_inline: six new cases, against real MinHook and against a model of its table. fl_guard's
Streamline [advanced] case asserts the batch lines. No real game has been run.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

* fix(overlay, tests): what SonarCloud reported on the batching pull request - the performance counter read through the union member it was initialised with, a test's strlen, and a model index that could be -1

- dllmain.cpp: QpcNow() names QuadPart in the LARGE_INTEGER's initialiser, so the member read back is the member
  the union holds (cpp:S6232, four times on MicrosSince); MicrosSince takes the ticks.
- guard_test.cpp: the log-field helper takes a string_view instead of calling strlen (cpp:S5813).
- unhook_inline_test.cpp: the model's Set refuses an index outside its table and the test marks a foreign patch
  through a method that looks the target up (cpp:S3519: enabled[-1] if Find had failed).

No behaviour changes. The batch timings on the fixture are as before (four in 70 ms, nine in 70 ms, eighteen
out in 76 ms).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 16:41:53 +07:00
78 changed files with 6559 additions and 311 deletions

No files matched your search

+1 -1
View File
@@ -9,7 +9,7 @@ barrier. It is written for the person who has just met one; the details for deve
FrameLedger is a desktop program: its own window, its dialogs, its document windows, the icon by the clock and the
notices Windows shows for it. It draws nothing inside a game, so it cannot make a game itself any easier to use.
*Beta software: this page describes version 0.1.0-beta.45. In the app: Help ▸ Accessibility.*
*Beta software: this page describes version 0.1.0-beta.47. In the app: Help ▸ Accessibility.*
## What FrameLedger aims for
+16 -5
View File
@@ -35,12 +35,21 @@ numeric core and does not move; the heading is the full version — corrected 20
## [Unreleased]
### Changed
### Added
- **The limitations, the accuracy statement and the user guide say what the first real sessions on 0.1.0-beta.45
showed** (2026-11-13, six games): five of its six new readings were read in real games — every Streamline game
asked whether its features are supported — and no game allocated a feature's resources after FrameLedger was in
it, so that row has not been seen. No code changes.
- **For developers: the part inside a game reads two more figures of NVIDIA's latency report, and keeps every
frame-generation multiplier a session saw** (owner decisions D142, D144; nothing a user sees until the Agent and
the App read them). In a real game the driver's span between its two GPU marks was longer than the frame's whole
— it includes the card's waiting. The driver's own *active* render time and its GPU frame time are members of
the report FrameLedger already fetches; they are read from it, with **no further call into the driver**. Four
reserved words of the shared memory carry them and the multipliers seen (layout 5 as it was). `fl_reflex_summary`
and the injected `[latency]` cases hold it. Measured: +36 ns a read, once a second.
### Fixed
- **A session could start with the last read of the session before it.** In a game that kept running between two
sessions, a read of the driver's latency report that ended after the first session's last tick was taken as the
second session's first point. A new session now drops it.
## Releases
@@ -48,6 +57,8 @@ Newest first. Each file holds that release's section exactly as it stood here.
| Version | Date | Notes |
|---|---|---|
| `0.1.0-beta.47` | 2026-11-14 | [`docs/changelog/0.1.0-beta.47.md`](docs/changelog/0.1.0-beta.47.md) |
| `0.1.0-beta.46` | 2026-11-13 | [`docs/changelog/0.1.0-beta.46.md`](docs/changelog/0.1.0-beta.46.md) |
| `0.1.0-beta.45` | 2026-11-12 | [`docs/changelog/0.1.0-beta.45.md`](docs/changelog/0.1.0-beta.45.md) |
| `0.1.0-beta.44` | 2026-11-12 | [`docs/changelog/0.1.0-beta.44.md`](docs/changelog/0.1.0-beta.44.md) |
| `0.1.0-beta.43` | 2026-11-12 | [`docs/changelog/0.1.0-beta.43.md`](docs/changelog/0.1.0-beta.43.md) |
+11 -2
View File
@@ -21,7 +21,7 @@ A C++ DLL (`FrameLedger.Overlay.dll`) is injected into games the user explicitly
3. **Never implement evasion.** No manual mapping, no PE header erasure, no thread hiding, no signature obfuscation, no unlinking from the PEB module list. Injection uses documented `LoadLibraryW`. The DLL keeps its real name, real exports, and version info. A performance tool must be *visible* to anti-cheat, not hidden from it. Any PR that makes FrameLedger harder to detect is rejected on principle.
4. **Never read or write game memory outside our own hooks.** We read arguments passed to APIs we hooked and COM/handle objects we legitimately own. No pattern scanning for game internals, no reading player/entity state, no writing to game memory. Ever.
> **Amended 2026-11-13 (owner decision D132): a driver's read-only getter, with the device of the swap chain we hook.** Asked with this rule quoted, the owner ruled that calling NVIDIA's two latency getters (`NvAPI_D3D_GetLatency`, `NvAPI_D3D_GetSleepStatus`) with the device behind a swap chain the Overlay hooks is inside this rule: it reads the driver's report, not game memory, and writes nothing. **Nothing shipped does it yet**: a spike on `hook-harness` and a stub comes first (`spike-notes` §31), and a release that carries it needs the owner's go on that result. Getters only, never a setter, a marker or a sleep, and never a call that loads `nvapi64.dll` into a game.
> **Amended 2026-11-13 (owner decision D132): a driver's read-only getter, with the device of the swap chain we hook.** Asked with this rule quoted, the owner ruled that calling NVIDIA's two latency getters (`NvAPI_D3D_GetLatency`, `NvAPI_D3D_GetSleepStatus`) with the device behind a swap chain the Overlay hooks is inside this rule: it reads the driver's report, not game memory, and writes nothing. ~~Nothing shipped does it yet~~ **Shipped since 0.1.0-beta.47 (owner decisions D136, D138–D141)**, after the spike on `hook-harness`, a stub and the installed driver (`spike-notes` §31): only while a session records Advanced metrics (no switch of its own), about once a second on the presenting thread, through an `nvapi64.dll` the game had loaded — one in the game's own folder is refused, and a fault or a call of 2 ms or more ends it until the game exits (`17_HOOK_ENGINE` §Calls the Overlay makes into a driver). **It is the only call of its kind; another needs a ruling of the same kind.** Getters only, never a setter, a marker or a sleep, and never a call that loads `nvapi64.dll` into a game.
5. **The hook must never crash the game.** Every hook body: SEH-guarded, allocation-free, lock-free, no logging, no exceptions crossing the boundary. On repeated faults, self-disable (`17_HOOK_ENGINE` §Fault policy).
6. **FPS display rule (product requirement):** wherever FPS is shown and Frame Generation is active, show *Native FPS*, *Displayed FPS*, and the FG factor together (`62 → 118 FPS (×1.9 FG)`). Never a single inflated number. See `docs/03_METRICS.md`.
@@ -135,6 +135,10 @@ src/
# loaded, the game switching it, its resources allocated and freed and Streamline
# shut down, from six more calls hooked the same way (D130); slInit is not hooked
# and its entry says why (AdvancedReach.BeforeAttach, D129).
# Since 0.1.0-beta.47 (train C, D136-D141) also what NVIDIA's driver reports about
# a frame's stages - NOT an argument of a hooked call: the Overlay calls two
# read-only getters of the driver itself (reach GameDriver); seven adv.* series
# and one table, and AdvancedDriverRead says what became of the read.
FrameLedger.Infrastructure/ # SQLite, shm reader, vendor APIs, injector interop, parsers,
# and Capture/ (PR-C): ShmRingAttacher/ShmCaptureSink over the
# reader, HeldProcessLivenessSource, TargetResolver (path only,
@@ -191,7 +195,9 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
# agent-cost (D110, 2026-11-11: a developer tool, not a gate - what the shipped
# Agent costs per second of session, Advanced metrics off and on),
# nvapi-readonly-check (D108, 2026-11-11: every NVAPI call of the bridge is on
# nvapi-allowed-calls.txt, and none there writes or identifies),
# nvapi-allowed-calls.txt, and none there writes or identifies; since beta.47 also
# the Overlay - no NvAPI call by name, and the only interface ids it may name are
# the two on overlay-nvapi-allowed.txt),
# overlay-fields-check (D116, 2026-11-12: every member of a vendor's struct the
# Overlay reads for Advanced metrics is in fl_adv_fields.h and on
# overlay-allowed-fields.txt; a camera's position, axes and matrices nowhere)
@@ -205,6 +211,9 @@ tools/ # accuracy-check, changelog-check, chokepoint-che
# (--vulkan since #140, --opengl since #141)
# fl-probe-* -> guard, hook profile, interposer, NVAPI, process
# stats, signer, Vulkan layer; fl-baseline-probe;
# and fl-probe-reflex (2026-11-13, D132: the spike of Reflex route D,
# spike-notes §31 - unshipped, with a stand-in nvapi64.dll among the stubs;
# built from the Overlay's own fl_reflex.h since beta.47);
# vendor-stubs/ -> fixture DLLs with the vendors' export names
rules/detection-rules.json # engine/platform/capability + anticheat blocklist
guide/ # the user guide (beta.12, D44): ~~eight~~ short English pages for players, embedded in the
+8 -3
View File
@@ -5,7 +5,7 @@ hooking on for — and reading the graphics calls the game makes. That is why it
resolution, the upscaler, frame generation and ray tracing apart. It is also where its limits come from. This
page lists them in plain words; each item links to the document that has the details.
*Beta software: this page describes version 0.1.0-beta.45.*
*Beta software: this page describes version 0.1.0-beta.47.*
## Games it will not measure
@@ -124,8 +124,13 @@ shown is recorded too, from outside the game. ([Capture](docs/04_CAPTURE.md))
- **Ray tracing** is *Yes*, *No* or *N/A* — measured from the game's ray-tracing calls on Direct3D 12, and
N/A where FrameLedger could not look. **Path tracing is never stated as a fact**: there is no API signal
for it. You can correct any of these by hand, and your correction is labelled as yours.
- HDR output, NVIDIA Reflex latency, the video-memory budget Windows gives a game, and shader-compilation
stutter are **not measured yet** — they read N/A. ([Accuracy](legal/ACCURACY.md))
- HDR output, end-to-end latency (click to screen), the video-memory budget Windows gives a game, and
shader-compilation stutter are **not measured yet** — they read N/A. ([Accuracy](legal/ACCURACY.md))
- **NVIDIA's own latency report** is read only with *Advanced metrics* on, only on an NVIDIA card, only in a
Direct3D 12 game that uses NVIDIA Reflex: how long the driver says each stage of a frame took, about once a
second. They are the driver's numbers, not FrameLedger's measurement. FrameLedger asks the driver for them from
inside the game; a read that is slow or faults is switched off until the game is closed, and the session says so.
([Advanced metrics](guide/12-advanced-metrics.md))
## The game's memory
+10 -3
View File
@@ -13,7 +13,7 @@ app too (Help ▸ User guide, Help ▸ Limitations, Help ▸ Accessibility), and
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-11-11.** The software is a beta; its latest
> **beta is `0.1.0-beta.45`** (2026-11-12), an unsigned installer built from that tag with its
> **beta is `0.1.0-beta.47`** (2026-11-14), an unsigned installer built from that tag with its
> checksums published beside it (alphas — experimental builds that try a newer .NET — are published apart). The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -87,8 +87,15 @@ app too (Help ▸ User guide, Help ▸ Limitations, Help ▸ Accessibility), and
> mean, median and peak. The game's other processes (launchers, helpers) are not counted.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** the video-memory budget Windows gives a game, which frame
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
> spikes were shader compilation, end-to-end PC latency, and HDR. Stutter count and stutter time are
> measured from frame times.
> - **NVIDIA's latency report (only with Advanced metrics on; Direct3D 12; a game that uses NVIDIA Reflex):** how
> long the driver says each stage of a frame took — simulation, render submit, present, driver, the operating
> system's queue, the graphics card — read from the graphics driver about once a second and shown as the driver
> reported it: **the driver's numbers, not a measurement by FrameLedger**, an average of the frames of one read,
> never checked against another tool, and not the delay from a click to the screen. Read with a test program
> against one driver and one card; **no real game had been read when this was written**. A game that does not use
> Reflex has none. The session summary's latency fields stay N/A.
> - **Pacing, VSync and the graphics card (since beta.14):** the share of the time below 30 FPS, below 60 FPS and below
> the monitor's refresh rate, measured from frame times with small margins so that a game held at its limit is not
> counted as below it (a rate less than 2 % under the line reads partly as at it), and how much one frame's time
@@ -205,7 +212,7 @@ Elevation is **optional — for everything.** Hooked capture is the normal path
## Install
> **The latest beta is `v0.1.0-beta.45` (2026-11-12); before it `v0.1.0-beta.44` (2026-11-12), `v0.1.0-beta.43` (2026-11-12), `v0.1.0-beta.42` (2026-11-12), `v0.1.0-beta.41` (2026-11-12), `v0.1.0-beta.40` (2026-11-12), `v0.1.0-beta.39` (2026-11-11), `v0.1.0-beta.38` (2026-11-11), `v0.1.0-beta.37` (2026-11-11), `v0.1.0-beta.36` (2026-11-10), `v0.1.0-beta.35` (2026-11-09), `v0.1.0-beta.34` (2026-11-06), `v0.1.0-beta.33` (2026-11-03), `v0.1.0-beta.32` (2026-10-31), `v0.1.0-beta.31` (2026-10-26), `v0.1.0-beta.30` (2026-10-26), `v0.1.0-beta.29` (2026-10-25), `v0.1.0-beta.28` (2026-10-20), `v0.1.0-beta.27` (2026-10-20), `v0.1.0-beta.26` (2026-10-19), `v0.1.0-beta.25` (2026-10-19), `v0.1.0-beta.24` (2026-10-19), `v0.1.0-beta.23` (2026-10-14), `v0.1.0-beta.22` (2026-10-13), `v0.1.0-beta.21` (2026-10-13), `v0.1.0-beta.20` (2026-10-12), `v0.1.0-beta.19` (2026-10-12), `v0.1.0-beta.18` (2026-10-07), `v0.1.0-beta.17` (2026-10-07), `v0.1.0-beta.16` (2026-10-06), `v0.1.0-beta.15` (2026-10-06), `v0.1.0-beta.14` (2026-10-06), `v0.1.0-beta.13` (2026-10-04), `v0.1.0-beta.12` (2026-10-04), `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read the notes of the one you install — `CHANGELOG.md` links each release's own file under `docs/changelog/` — for what it measures, what it does not yet, and how to update, before installing. A source build is `docs/12_BUILD.md`.
> **The latest beta is `v0.1.0-beta.47` (2026-11-14); before it `v0.1.0-beta.46` (2026-11-13), `v0.1.0-beta.45` (2026-11-12), `v0.1.0-beta.44` (2026-11-12), `v0.1.0-beta.43` (2026-11-12), `v0.1.0-beta.42` (2026-11-12), `v0.1.0-beta.41` (2026-11-12), `v0.1.0-beta.40` (2026-11-12), `v0.1.0-beta.39` (2026-11-11), `v0.1.0-beta.38` (2026-11-11), `v0.1.0-beta.37` (2026-11-11), `v0.1.0-beta.36` (2026-11-10), `v0.1.0-beta.35` (2026-11-09), `v0.1.0-beta.34` (2026-11-06), `v0.1.0-beta.33` (2026-11-03), `v0.1.0-beta.32` (2026-10-31), `v0.1.0-beta.31` (2026-10-26), `v0.1.0-beta.30` (2026-10-26), `v0.1.0-beta.29` (2026-10-25), `v0.1.0-beta.28` (2026-10-20), `v0.1.0-beta.27` (2026-10-20), `v0.1.0-beta.26` (2026-10-19), `v0.1.0-beta.25` (2026-10-19), `v0.1.0-beta.24` (2026-10-19), `v0.1.0-beta.23` (2026-10-14), `v0.1.0-beta.22` (2026-10-13), `v0.1.0-beta.21` (2026-10-13), `v0.1.0-beta.20` (2026-10-12), `v0.1.0-beta.19` (2026-10-12), `v0.1.0-beta.18` (2026-10-07), `v0.1.0-beta.17` (2026-10-07), `v0.1.0-beta.16` (2026-10-06), `v0.1.0-beta.15` (2026-10-06), `v0.1.0-beta.14` (2026-10-06), `v0.1.0-beta.13` (2026-10-04), `v0.1.0-beta.12` (2026-10-04), `v0.1.0-beta.11` (2026-10-03), `v0.1.0-beta.10` (2026-09-28), `v0.1.0-beta.9` (2026-09-26), `v0.1.0-beta.8` (2026-09-25), `v0.1.0-beta.7` (2026-09-23), `v0.1.0-beta.6` (2026-09-23), `v0.1.0-beta.5` (2026-09-22), `v0.1.0-beta.4` (2026-09-21), `v0.1.0-beta.3` (2026-09-21), `v0.1.0-beta.2` (2026-09-17) and `v0.1.0-beta.1` (2026-09-16).** They are pre-releases: read the notes of the one you install — `CHANGELOG.md` links each release's own file under `docs/changelog/` — for what it measures, what it does not yet, and how to update, before installing. A source build is `docs/12_BUILD.md`.
1. Download the latest `FrameLedger.App-win-Setup.exe` from [Releases](https://github.com/poli0981/frameledger/releases). It installs into `%LOCALAPPDATA%\FrameLedger.App`; your data stays in `%LOCALAPPDATA%\FrameLedger`, and uninstalling asks before touching it.
2. SmartScreen may warn — releases are not code-signed (free, open-source project). Verify the SHA-256 checksum published with each release, then **More info → Run anyway**.
+1 -1
View File
@@ -36,7 +36,7 @@ Let `D` = session duration (first → last present), `F_app` = frames the *game*
| **Frametime σ** | population stddev of `ft_app` (ms) | 1 |
| **Stutter count** | `ft_app[i] > 2 × rollingMedian(ft_app, 19)` (centered, window in **frames**) | 1 |
| **Stutter time %** | `Σ ft_app[stutter] / Σ ft_app × 100` | 1 |
| **PC latency** | mean/p95 of `reflexLatencyUs` when Reflex reports it | **1 only** |
| **PC latency** | mean/p95 of `reflexLatencyUs` when Reflex reports it *(nothing fills `reflexLatencyUs`: a report arrives after its frame's record is written. Since train C, 2026-11-13, the driver's stage report is read as seven Advanced series beside the frames — `18_GPU_VENDOR_APIS` §The inventory — and these session fields stay N/A)* | **1 only** |
| **PSO stutter %** | share of stutter frames with `psoCreatedThisFrame > 0` | **1 only** |
| **Time below 30 / 60 FPS** (beta.14) | share of `Σ ft_app` in frames that count as below X — `ft > 1.10 × 1000/X`, or the nine-frame rolling median `> 1.02 × 1000/X` (§Pacing) | 1 |
| **Time below refresh** (beta.14) | the same over **presents**, X = `display_monitor_hz` — the display's rate, so over what the display received | 1 |
+25
View File
@@ -165,6 +165,31 @@ What the region is, as a contract between the two sides:
counts `slShutdown` calls, with `FL_ADV_VALID_SL_SHUTDOWN` (bit 6 of the mask) set once one was seen. All three
are a session's and a new request clears them. `FL_HOOK_SL_ALLOCATE_RESOURCES` (bit 20),
`FL_HOOK_SL_FREE_RESOURCES` (21) and `FL_HOOK_SL_SHUTDOWN` (22) are published with their patches.
- **Reflex latency words (train C; written by the Overlay since 0.1.0-beta.47; owner decisions D136, D138).** The
ten reserved words that ended the first line (@24..63) are `latState`, `latReads`, `latFrames` and seven sums:
simulation, render submit, present, driver, OS render queue, GPU render, and the total from simulation start to
GPU render end. **The layout is still 5**: no offset and no size moved, and the handshake's build id refuses a
mismatched pair before either side reads the other. Unlike every other group here they are **not what the game
passed to a call the Overlay hooks**: the Overlay makes a call of its own, about once a second, on the presenting
thread, to the driver's two read-only getters, through an `nvapi64.dll` the game had already loaded
(`17_HOOK_ENGINE` §Memory / latency). `latState`'s low byte is a `FlLatencyState` — no device, no module, refused
(a module in the executable's own folder, D140), no getter, reading, error, slow (D141), faulted, stalled — and
above it the driver's sleep status as switches *seen on* and *seen off* and the last frame-generation multiplier.
`latFrames` and the sums are **of the newest read not yet published** — zero when no read was made since the
publication before — so a reader divides one publication's sum by its frames and never adds publications up. A
sum of all ones is a span some summed frame did not report. `FL_ADV_VALID_LATENCY` (bit 7 of the mask) is set once
a read returned OK for the request; it is not one of "the game's calls were read", and `latState` is published
whether or not it is set.
- **Four more latency words (0.1.0-beta.48; owner decisions D142, D144).** The first line was full, so they are
four of the seven reserved words that ended the `sl::DLSSOptions` line (@100..115; three remain, @116..127) —
nothing of DLSS's, and **the layout is still 5** for the same reasons. `latGpuActiveSumUs` and `latGpuFrameSumUs`
are the two times the driver works out itself — the graphics card's render time *excluding the idles in
between* (`gpuActiveRenderTimeUs`) and one frame's GPU end to the next's (`gpuFrameTimeUs`) — summed over the
frames of the newest read that gave one; `latGpuCounts` holds how many did, the first in its low half and the
second in its high half, because a frame can give one and not the other. A frame that gives zero (an older
driver leaves both zero) or more than a second is in neither the sum nor the count, and is still summed for the
seven spans. `latMultipliersSeen` is the session's: bit n is set once the sleep status gave frame-generation
multiplier n since the request, bit 31 standing for 31 and more; `latState` still carries the last one.
- The Vulkan layer never writes it. `ShmLayoutMirrorTests.TheAdvancedStateMirrorMatches` checks every member's
offset against `fl-layout-dump`; `ShmRingReaderTests` the three reads and that the request is stored either way.
+1
View File
@@ -35,6 +35,7 @@ Targets:
- `hook-harness` → the dummy **D3D11 + D3D12** app, WARP + composition swapchain so it runs headless on CI (`17_HOOK_ENGINE` §Test harness). D3D12 is device → command queue → swapchain, which is the acquisition asymmetry a D3D11-only fixture cannot exercise. ~~Vulkan and OpenGL modes to follow as those hooks land.~~ **`--vulkan --hold-presenting N` since 2026-09-06 (P1 item 3):** a real swapchain on a hidden window through the real loader, reached by `LoadLibraryW("vulkan-1.dll")` so only the vendored headers are needed and CI (no loader) still builds it; exit 77 = cannot run here, which the ctest reads as SKIP. **`--opengl --hold-presenting N` since the same day (P1 item 4):** a real context on a hidden window, `SwapBuffers`'d through gdi32 as a title does, on Microsoft's generic renderer — so it runs on CI.
- `fl-probe-hookprofile` → build-profile probes for `/guard:cf` and `-D_HAS_EXCEPTIONS=0` (`20_OPEN_QUESTIONS` §H1/§H3)
- `fl-probe-guard` → measures the Windows APIs the guard is built on, unelevated (`spike-notes.md` §1). Not the guard, and takes no injection rights.
- `fl-probe-reflex` → the instrument of `spike-notes` §31 (2026-11-13, owner decision D132) — **since the owner said go (D136) it is built from the Overlay's own header, `FrameLedger.Overlay/include/fl_reflex.h`**, so its ctest runs the shipped call sequence with Control Flow Guard enforced; its `--real` also prints which image the two getter addresses lie in (`nvapi64_impl.dll`, not the `nvapi64.dll` that is asked). What it was written as: the call sequence Reflex route D would put into the Overlay — find `nvapi64.dll` only if the process already holds it, resolve the driver's two getters by interface id, call them — in an unshipped probe built with the Overlay's flags. `--stub` runs it against `fl_stub_nvapi64` → `nvapi64.dll` (a stand-in with knobs for a missing getter, an empty report, an error and a call that does not return; its outputs in a directory of their own, so that its `nvapi64.lib` is never beside the vendored one's name) and is ctest `fl_reflex_probe_stub`; `--real` runs it against the installed driver on an NVIDIA adapter, with the probe setting the latency markers a game would, in its own process — a measurement, never a test. It takes the vendored NVAPI headers' include directory and **does not link `nvapi64.lib`**. Nothing shipped includes its header.
- `fl_stub_sl_interposer` → `sl.interposer.dll`, and `fl_stub_sl_common` → `sl.common.dll` (`src/native/tools/vendor-stubs/`). **Fixtures, never shipped**, built under `FL_BUILD_TOOLS`; nothing `12_BUILD` publishes references them. They export the **measured** vendor names from `docs/vendor-exports.json` so the Overlay's symbol resolution is observable, and the second is a **decoy** exporting the same name from a different module — without it, "we resolve module-scoped" is a property no test can falsify. Their **output filenames are the vendor's and their version blocks are ours**: `fl_add_version_resource` takes the real filename so a file called `sl.interposer.dll` in our build tree still says plainly that it is FrameLedger's, which `19_SAFETY` requires of everything we build.
- `fl_stub_ffx_dx12` → `amd_fidelityfx_dx12.dll`, `fl_stub_ffx_upscaler` → `amd_fidelityfx_upscaler_dx12.dll`, `fl_stub_ffx_fg` → `amd_fidelityfx_framegeneration_dx12.dll` — the three AMD **leaves** — and `fl_stub_ffx_loader` → `amd_fidelityfx_loader_dx12.dll`, a **forwarding stand-in** bound to the two 2.x leaves through their FrameLedger-named *direct* entry — the way the real loader was measured to bypass the leaves' exports — so `--hold-presenting-ffx` can push every dispatch through a loader that is hooked along with the leaves and prove the count reads 1× (2026-09-04). Same rules as the Streamline stubs: fixtures, never shipped, vendor filenames with our version blocks. `fl_stub_ffx_fsr3_host` → `ffx_fsr3_x64.dll` (2026-09-05): the FSR 3.0 **host** facade, exporting the four names `SpeaksFsr3Host` probes for through the vendored `fsr3-v3.0.4` header's own `FFX_API`; `--ffx-topology fsr3host|fsr3host+mono` drives it, and `hookinventory-check` Pass C reads it as the export parser's second positive control.
- **`fl_fidelityfx_headers`** → an INTERFACE target over the five vendored FidelityFX ffx-api headers (`src/native/third_party/fidelityfx/`, tag v2.3.0, MIT by exception). Three include directories because upstream's headers include each other by relative path; include directories only and nothing to link — no `.lib` is vendored — and `hookinventory-check` Pass C reads the Overlay's export table because `ffx_api.h` declares its entry points `__declspec(dllexport)` unconditionally.
+27
View File
@@ -31,6 +31,7 @@ The anti-cheat guard is the one component where a bug can cost someone an accoun
- **Record and header layout:** `static_assert(sizeof(...) == 64)` and `offsetof` assertions for `FlFrameRecord` **and all ~~three~~ ~~four~~ five header structs** *(five since layout 5, 2026-11-11: `FlAdvancedState`, 1472 bytes; what reads and writes it is tested at four levels since 0.1.0-beta.40 — `fl_adv_fields` the Overlay's header alone, `fl_guard` `[advanced]` the injected Overlay with the word off and on, `InGameAdvancedSamplerTests` / `CaptureSessionTests` / `SessionRecorderTests` what the Agent makes of a publication, and `AgentEndToEndTests.WhatTheGameTellsFsrIsStoredOnlyByASessionThatRecordsAdvancedMetrics` the shipped Agent, the real Overlay and the harness: two sessions of one target, the first storing nothing of it)* (`FlShmHandshake`, `FlWriterState`, `FlControlBlock`, and `FlDisplayState` since layout 4, beta.10) — plus D33's `FlTolerance`, mirrored the same way *(corrected 2026-10-04)* — the Agent reads across the process boundary in every one of them. Both halves exist as of 2026-08-05: the native side is `layout_test.cpp` plus the `static_assert`s (ctest `fl_shm_layout`), and the runtime offset dump from `tools/fl-layout-dump` is consumed by `ShmLayoutMirrorTests`, which walks the field list in **both directions** and additionally asserts blittability — `Marshal.SizeOf` and every offset stay correct for a mirror that uses `[MarshalAs(ByValTStr)] string`, while `Unsafe.SizeOf` drops from 64 to 40 and the struct can no longer be read from a mapped view.
- **Fault policy:** injected SEH faults in a fake hook body → counter increments, original still called, self-disable at 3.
- **Hook index verification, by behaviour.** A vtable slot carries no identity, so "check that slot 8 *is* `Present`" is not a question the runtime can answer — the earlier wording here required something unimplementable. What is answerable: patch the slot, call the method, see whether the detour ran (`17_HOOK_ENGINE` §Getting vtable addresses; proved for slots 8, 13 and 22 in `spike-notes.md` §H4). Runs headless on CI via WARP and `CreateSwapChainForComposition`. A deliberate mismatch aborts installation instead of patching.
- **A run that was cut short is not a pass** (2026-11-13). ctest calls a test passed when its process exits with 0, and on that day the development PC's security software removed a freshly linked `fl_guard_test.exe` while the gate ran: ctest printed `fl_guard ... Passed 0.66 sec` for a suite that takes three minutes, and the gate went red only because the next test runs the same executable and could not find it. So **every native test now names the line it ends on** — `fl_test_completes(<test> <regex>…)`, or `fl_catch2_test_completes(<test>…)` for a Catch2 executable (its `All tests passed (` line, or its summary row when a case was skipped, and never a row that names a failure) — and ctest requires that line (`PASS_REGULAR_EXPRESSION`; the helpers and the reasons are in `src/native/CMakeLists.txt`, above `enable_testing()`). Three things hold it: **the configure fails** when a test in `tests/` or `tools/` was registered without one (tried: a test added bare stops CMake with its name); **four canary tests** print what a Catch2 run would — nothing, its last line, a row with a skipped case, a row with a failure beside "passed" — through the same helper, and the two that must be red are `WILL_FAIL`; and the tests that were passing on a line printed in the *middle* of their run (`fl_nvapi_bridge`, `fl_process_stats`, `fl_nvapi_probe`, `fl_signer_probe`) now need that line and, after it, their last one. For `fl_nvapi_probe` this also closes what `fl_nvapi_bridge` was fixed for on 2026-09-25: a pass expression makes ctest ignore the exit code, so a run that printed its branch and then `FAILED` passed. `fl_signer_probe` accepts either ending — its criterion was always that the answers are printed. A `SKIP_RETURN_CODE` still wins over a missing line. **Not covered**: the managed tests (`dotnet test` reports a host that died) and a process that is stopped *after* printing its last line.
- **Every probe must be shown to fail.** A probe that ends in an unconditional assertion is green by construction and its ctest is decorative — `fl_proxy_swapchain` shipped in exactly that state. Before a probe counts as a regression net, break the thing it watches and watch it go red.
## Managed unit tests
@@ -158,6 +159,32 @@ own work item on the STA thread and puts back — and with the keys a parameter,
> Until the run happens, the honest state of this line is *unmeasured*, not *passing*.
3. Results recorded in the release notes ("measured overhead this release: …").
**What a patch costs when it goes in and comes out (since 0.1.0-beta.46) is not the per-present number above**, and
is measured where it happens: `fl_guard`'s Streamline `[advanced]` case prints the microseconds of each install
batch and of the stop's one restore (the Overlay's `PATCH_BATCH` lines), and the time from the unhook request to
`UNHOOKED`; it asserts that every lazily installed patch is under a batch line, that the stop is one, and that the
restore stays under a second — the bound the one-patch-at-a-time stop did not meet on the development PC. In a real
game the same lines are in `logs\overlay-<pid>-….log` — read there on 2026-11-13 for five games: eighteen install
batches, 81–262 ms for sixteen of them and 0.61 s and 1.26 s for two (`17_HOOK_ENGINE` §Unhooking, *Batches*); and
on 2026-11-14 two restores of twenty-nine patches each, 83 ms and 86 ms, when the owner stopped the part inside a
running game.
**The call into the driver (train C, 0.1.0-beta.47) is tested in three places, each for what the
others cannot say.** `fl_reflex_summary` (Catch2) drives `fl_adv_fields.h`'s reader on reports written by hand: the
two newest frames held back, a frame summed once, a span the driver did not report, a span no frame can have, frame
ids that start again, and the ten words of a publication — and since 0.1.0-beta.48 the driver's two own times
(summed over the frames that gave one, each with its own count; zero and more than a second are not counted and
refuse nothing) and the bit a multiplier has. `fl_guard`'s seven `[latency]` cases inject the Overlay
into a Direct3D 12 target that has loaded a stand-in `nvapi64.dll`, and read that module's call counts from outside
through its named section (`fl_stub_nvapi_shared.h`) — so "the driver was not called" is a count: not asked → not
even asked for the addresses; asked → about one read a second, sums equal to the stand-in's, every counted read a
received call; an error; a span not reported; the request off; a second session; the stop; a call of 50 ms (the
last one); a fault (counted once, the hooks stay); a module without the getters; no module (none is loaded); a
module beside the executable (refused, never asked); Direct3D 11 (not read). `fl_reflex_probe_stub` runs the same
header, `fl_reflex.h`, in a process that **enforces Control Flow Guard** — the injected cases do not: `hook-harness`
is not a CFG image. **None of them is a driver.** `fl-probe-reflex --real` is the measurement against the installed
one, run by hand (`spike-notes` §31), and a real game is owner-only item 45.
## Tier cross-validation (accuracy regression net) — **GONE, 2026-08-28, and this is the entry to read before planning P5**
~~Run the same game session with Tier 1 and Tier 2 simultaneously where possible (ETW does not conflict with hooking) and compare frametime distributions: Avg/1% Low must agree within **1%**. Divergence beyond that means one of the two paths is wrong and blocks the release. This is also the check that would have caught the original detection-accuracy problem.~~
+128 -7
View File
@@ -172,6 +172,54 @@ Every hook must be listed here with a purpose. Anything not on this list is not
| ✅ `opengl32.dll!wglSwapBuffers` (2026-09-06, P1 item 4) | The OpenGL present hook (§Presentation). A system module, not a vendor one, so — like the row below — it is deliberately **not** in `FL_HOOK_INVENTORY` and `hookinventory-check` does not cover it; listed here so the table above and these two rows together are the whole inventory |
| ✅ `kernelbase.dll!LoadLibraryExW` (2026-09-06, P1 item 1) | The wake for lazily loaded runtimes and the in-process anti-cheat stop — §DLL entry step 3 above carries the mechanism. **Rule 4:** it reads one argument the API was given (`flags`) and one property of a handle the loader just returned to *its own caller* (the module file name); nothing of the game's. **~~It is the only hook on a system module, and~~ Like `wglSwapBuffers` above it, it is deliberately not in `FL_HOOK_INVENTORY` (corrected 2026-10-04):** that table is *vendor* symbols resolved by name and gated by `hookinventory-check` against `vendor-exports.json`, and `LoadLibraryExW` is neither vendor nor uncertain. It is listed here instead so the table above and this row together are the whole inventory. It **never** installs, uninstalls or patches anything itself (§H2) |
### Calls the Overlay makes into a driver — not hooks, and the only ones
Everything else on this page learns what it learns from the arguments of a call the game made. This is the one
place the Overlay **makes a call of its own** into code that is neither the game's nor FrameLedger's, and it is
listed here so that nobody takes it for a hook or adds a second one without the same ruling
(`CLAUDE.md` rule 4's note of 2026-11-13, owner decisions D132, D136, D138–D141).
| Call | When, where | Rule 4 | What bounds it |
|---|---|---|---|
| **NVIDIA's `NvAPI_D3D_GetLatency` and `NvAPI_D3D_GetSleepStatus`** — the driver's two read-only latency getters (Advanced metrics train C; `fl_reflex.h`; **since 0.1.0-beta.47**) | **Only while a session asks for Advanced metrics** (D138: no switch of its own), only for a Direct3D 12 swap chain whose device is the one the Overlay holds, **about once a second, on the presenting thread, after that present's record is published**. The watchdog finds the addresses once for the process and arms one read at a time; a present pays one relaxed load. The addresses come from an `nvapi64.dll` **the game had already loaded** — asked for by name, never loaded — through its `nvapi_QueryInterface` and the two interface ids of the vendored `nvapi_interface.h`. The Overlay links no NVAPI | The owner's ruling (D132): a driver's read-only getter called with the device behind the swap chain the Overlay hooks reads the driver's report, not game memory, and writes nothing. Getters only — never a setter, a marker or a sleep (`tools/nvapi-readonly-check.ps1` holds which ids code loaded into a game may name: these two). What is read of the two structs is on `tools/overlay-allowed-fields.txt` like every other vendor member | **An `nvapi64.dll` in the executable's own folder is refused** (D140): the driver's is in Windows' directories. **A fault** in a getter is caught by a guard of its own, counted once in `faultCount`, and ends the reads for the process. **One call of 2 ms or more** ends them too (D141). **A call that has not returned after two seconds** is logged, flushed and published as stalled — nothing can stop it, and the presenting thread it holds is the game's. Each is until the game exits |
**Where the addresses are, measured** (`fl-probe-reflex --real`, driver 32.0.16.2114): System32's `nvapi64.dll` is a
shim and answers the two ids with addresses inside **`nvapi64_impl.dll`**, in the driver's own store. So an address
is accepted when it is executable code of an image the process has loaded, and **the Overlay keeps a reference on
that image as well as on `nvapi64.dll`** — two modules the game loaded, never released, for the reason
`ResolveScoped` gives: a presenting thread may be about to call. `nvapi64_impl.dll` is a Control Flow Guard image;
the probe, which enforces CFG, has made the calls from the header that ships, so on this driver the getters are
valid targets. **Not excluded**: a game that enforces CFG on a driver the probe has not been run against — a target
that were not valid is a fast-fail no guard catches.
**In a real game** (the owner, 2026-11-14, Phantom Blade Zero on 0.1.0-beta.47, three sessions, frame generation
×3 and off): the module was found four to five seconds after the attach — `nvapi64.dll` in System32, the getters in
`nvapi64_impl.dll`, as on the probe — a read was made about every second for 344 s, 52 s and 1 119 s, **the slowest
call took 24, 20 and 45 µs**, and no latch fired: no error, no slow call, no fault, no stall. **Cyberpunk 2077 the
same morning**, two sessions (frame generation ×2 and off, 260 s and 581 s): found 4.8 s and 2.6 s after the attach,
the slowest call 34 and 65 µs, no latch. Two Direct3D 11 games and one Direct3D 12 game with no `nvapi64.dll` were
left alone, each with its one line. Two games read, one driver.
**Two more members of the same report, and the multipliers seen (0.1.0-beta.48; owner decisions D142, D144).** In
Phantom Blade Zero the span between the driver's two GPU marks was longer than the frame's whole: it includes the
card's waiting. NVIDIA's header has the figure that does not — `gpuActiveRenderTimeUs`, "excluding the idles in
between" — and beside it `gpuFrameTimeUs`, one frame's GPU end to the next's. Both are read from the report the
getter already filled: **no call is added, and no interface id** (`tools/nvapi-readonly-check.ps1` is unchanged;
the two names are on `tools/overlay-allowed-fields.txt`). The buffer is the Overlay's own, so there is no question
of a member lying past what a game allocated; an older driver leaves both zero, and zero is read as *not given* —
each time has its own count, and neither decides which frames the seven spans are made of. The sleep status'
frame-generation multiplier is now also kept as the set of values a session saw (a session that generated ×2 and
ended in a menu read 1). **One defect fixed with it**: a read that ended after a session's last tick was taken by
the next session as its first point; a new request now drops it. **Measured** (the header's own function, the
Overlay's flags, a report of 62 summed frames, 2 million reports × 3, twice): 393–396 ns before, 429–434 ns after
— **+36 ns a read**, once a second, and after the call's time has been taken, so it cannot reach the 2 ms latch.
The present path is unchanged: one relaxed load.
**The gate.** One word, four states — idle, armed, reading, off (`dllmain.cpp`, above `ReadLatencyOnce`). Only the
watchdog arms; a presenting thread takes *armed* to *reading* by compare-exchange and owns the 15.4 KB report
buffer (static storage, never a game thread's stack) and the read's result until it stores *idle* or *off*; the
watchdog takes the result only when nobody is reading. No lock, and no second read while one is under way.
### Watchdog observations — not hooks, and listed here so nobody mistakes them for one
| Observation | Mechanism | Rule 4 | Why |
@@ -196,8 +244,8 @@ Every hook must be listed here with a purpose. Anything not on this list is not
| NGX parameter accessors (`NVSDK_NGX_Parameter_SetI/GetI/SetUI`) — **exported by `sl.common.dll` only; see below** | `Width`/`Height` (render) vs `OutWidth`/`OutHeight` (output), `PerfQualityValue` (quality preset), sharpness |
| ✅ Streamline: `slEvaluateFeature` · ~~⏳ `slInit`~~ *(not hooked, and not to be: owner decision D129, 2026-11-12 — its row below says why)*, ~~`slSetFeatureLoaded`~~ *(its own row below since beta.45)*, ~~`slSetConstants`~~ *(its own row below since beta.43)*, ~~`slGetFeatureRequirements`~~ *(its own row below since beta.44, with `slGetFeatureVersion`)* | Feature set actually active when the game goes through SL rather than NGX directly (`kFeatureDLSS`, `DLSS_G`, `DLSS_RR`, `Reflex`, `NIS`; since beta.34 `kFeatureDLSS_NR` — DLSS 5's neural rendering, its own fact bit and family `FL_HOOK_SL_NEURAL_RENDERING`, D84; rule 4: the `feature` argument of the API hooked, nothing else). **Built 2026-08-09**, identity only: one MinHook detour on `sl.interposer.dll!slEvaluateFeature`, resolved **module-scoped** and installed lazily by the watchdog. Sets `FL_MEASURED_UPSCALER` + `FL_HOOK_UPSCALER_IDENTITY`; decodes `kFeatureDLSS`/`kFeatureNIS` and reports `FL_UPSCALER_UNKNOWN` for anything else. **Never `FL_UPSCALER_NONE`** — a Streamline-only writer cannot see FFX, XeSS or NGX-direct, and `NONE` is the only one of the three states that may be aggregated as a negative. **Since 0.1.0-beta.40 (Advanced metrics train B, D111), and only while the Agent asks** (`FlControlBlock.advancedRequested`): the `sl::DLSSOptions` a title chains into `inputs` — the struct the quality mode is read from — is read further: `outputWidth`/`outputHeight`, `preExposure`, `exposureScale`, `colorBuffersHDR`, the five presets of version 1, and where the struct's own `structVersion` proves them present `ultraQualityPreset` and `useAutoExposure` (≥ 2) and `alphaUpscalingEnabled` (≥ 3) — §Which struct version carries which field. Rule 4: more members of the same argument of the same call; `fl_adv_fields.h` is the one place, `tools/overlay-fields-check.ps1` holds it. No new patch site. **Measured** (the header's own functions, `/O2 /guard:cf /Qspectre /MT`, 20 M calls × 3): +9.5–11.7 ns per evaluation that chains the options while asked; with the word at 0, one relaxed load and a branch not taken — below what the bench resolves. Most titles set these through `slDLSSSetOptions`, which is not an export, and read N/A (train D) |
| ✅ Streamline: `slSetConstants` (0.1.0-beta.43, Advanced metrics train B; owner decisions D111–D116, D122) | **What the game tells Streamline about a frame**, once per frame and viewport, read from the `sl::Constants` it passes — rule 4: an argument of the call hooked, and of it only the members named here. **Read:** `jitterOffset`, `mvecScale`, `cameraNear`, `cameraFar`, `cameraFOV`, `cameraAspectRatio` and the seven `Boolean`s (`depthInverted`, `cameraMotionIncluded`, `motionVectors3D`, `reset`, `orthographicProjection`, `motionVectorsDilated`, `motionVectorsJittered`). **Never read:** the five matrices (bytes 32..351 of the struct), `cameraPinholeOffset`, and the camera's position and three axes (bytes 368..423) — `tools/overlay-fields-check.ps1` refuses their names anywhere in code loaded into a game, and ctest `fl_adv_fields` publishes two structs that differ in every one of those bytes and gets the same bytes out. **The one row that is not installed unless asked for** (D111): `InstallByFamily` returns before it resolves the symbol in a process the Agent has never asked for Advanced metrics — resolving takes a reference on the module — so with the option off the export's first bytes are the file's (`fl_guard` `[advanced]` reads them from the target). Once asked, the patch goes in on that watchdog tick and stays for the life of the process; the detour forwards without looking while the request is off, and after a stop (`MayObserve`). **Every call** checks the struct's GUID and a `structVersion` of at least 1 before any member is read, and the viewport handle's the same way; every member read is one version 1 carries, so a version-1 struct laid against unreadable memory is read whole without a fault (the same ctest). **Summaries are the first viewport's**: a title with two viewports sets constants for each every frame, and "the last value" across them would flip twice a frame; the call count is of every viewport. `FLT_MAX` is Streamline's "not set" here and is kept nowhere (D119's plane at infinity is FidelityFX's). Family `FL_HOOK_SL_CONSTANTS` (bit 13), published with the patch: it entitles no field of a frame record, and tells "hooked, never called" from "not hooked". **Measured overhead** (the detour's body on the headers, the Overlay's flags, 20 million calls a run, three runs): not asked **+0.57 / +0.60 / +0.58 ns**; asked, the summarised viewport **+19.61 / +19.54 / +19.79 ns**; asked, another viewport +5.83 / +6.01 / +5.62 ns. |
| ✅ Streamline: `slGetFeatureVersion` and `slGetFeatureRequirements` (0.1.0-beta.44, Advanced metrics train B's third step; owner decisions D111–D116, D122) | **What Streamline answers when the game asks about a feature** — which version it is, and what it requires. Two rows, two patches, two detours of one shape: **the original runs first, exactly once, on every path, with both arguments forwarded untouched**, and the struct the game passed is read only when the original said `eOk` — a refusal leaves the struct as the game made it, which is not an answer. Rule 4: an argument of the call hooked, read after the call, and of it only the members named here. **Read from `sl::FeatureVersion`:** `versionSL`, `versionNGX`. **Read from `sl::FeatureRequirements`:** `flags`, `maxNumCPUThreads`, `maxNumViewports`, `numRequiredTags`, `osVersionDetected`, `osVersionRequired`, `driverVersionDetected`, `driverVersionRequired`. **Never read:** `requiredTags` — the pointer the count belongs to — and everything after `driverVersionRequired`: the Vulkan queue counts and the pointers to the names of extensions and features. **No pointer of the game's is followed** (`tools/overlay-fields-check.ps1`, parameters `fv` and `fr`; ctest `fl_adv_fields`: two answers that differ only in those bytes publish the same region, and an answer cut off where the Vulkan members begin, laid against unreadable memory, is read without a fault; the injected `fl_guard` case's stub hands back wild pointers and no fault is counted). **Installed only where asked for** (D111), as `slSetConstants` is: `InstallByFamily` returns before it resolves either symbol in a process the Agent has never asked for Advanced metrics; once in, a patch stays for the life of the process and its detour forwards without looking while the request is off. **They are the first two rows of the table**: a game asks these while it starts, the watchdog patches rows in the table's order, and each patch stops the game's threads for a moment (0.1–0.25 s apart in the owner's logs of 2026-11-12, where `slSetConstants` was the fifth Streamline patch in, 1.9–7.8 s after the attach). In a process never asked they are passed over and the order changes nothing. ~~**Most sessions will still have missed the calls** — an attach after the game's start-up is the usual case — and the session then says the call was hooked and the game did not ask again.~~ *(Measured 2026-11-12, the owner's eight sessions on beta.44: both calls were read in six of six Streamline sessions on five games — Unreal's Streamline plugin asks again after the attach, Cyberpunk 2077 asks again for requirements and not for versions. A game that asks only while starting still reads "hooked, not asked again".)* Three conditions before a read, as for `slSetConstants`: the Agent is asking, observing has not stopped, and the struct carries its own GUID and a version of at least 1 on this call (a struct with another GUID is not kept: the injected case sends one). Every member read is version 1's (§Which struct version carries which field). **Twelve slots** in region 5 (`FlAdvancedState.features`, layout 5 as it was), one per feature in the order first asked about; the last answer about a feature is the one kept; a thirteenth feature is not kept. **A new request does not empty them**: what version a feature is and what it requires are facts about the process, and a second session of a game that kept running would otherwise have nothing where the first had the answer — the one group `Reset` leaves, with its bit of the mask. Streamline 1.x is refused before anything is resolved (`SpeaksStreamline2`). Families `FL_HOOK_SL_FEATURE_VERSION` (bit 15) and `FL_HOOK_SL_FEATURE_REQUIREMENTS` (bit 16), each published with its patch; neither entitles a field of a frame record. **Measured overhead** (the detours' bodies on the headers, the Overlay's flags, 20 million calls a run, three runs, eight features asked about in turn): the version — not asked **+0.58 / +0.61 / +0.58 ns**, asked **+14.82 / +14.54 / +14.47 ns**; the requirements — not asked **+0.58 / +0.63 / +0.61 ns**, asked **+20.88 / +21.01 / +20.96 ns**. A game makes these calls a handful of times. |
| ✅ Streamline: `slIsFeatureSupported`, `slIsFeatureLoaded`, `slSetFeatureLoaded` (0.1.0-beta.45; owner decisions D129–D131) | **Whether a feature is supported, whether it is loaded, and the game switching it on and off.** Three rows, three patches. Rule 4: bare arguments and results of the calls hooked, and no vendor struct at all — the feature's id; the `sl::Result` `slIsFeatureSupported` returned, **every result**, since a refusal is the answer to that question (the original runs first, both arguments forwarded untouched); the `bool` `slIsFeatureLoaded` wrote, read only when it returned `eOk`; the `bool` the game passed to `slSetFeatureLoaded`, noted before the call. **The adapter `slIsFeatureSupported` is asked about is never read** (D131): `sl::AdapterInfo` holds the adapter's LUID or a Vulkan physical device; the detour forwards the reference and `tools/overlay-fields-check.ps1` refuses the names of its members (`deviceLUID`, `deviceLUIDSizeInBytes`, `vkPhysicalDevice`) anywhere in the Overlay and the Vulkan layer — the fixture's adapter carries a wild pointer. **Installed only where asked for** (D111), as the four rows before them. `slIsFeatureSupported` and `slIsFeatureLoaded` follow the two rows of beta.44 at the head of the table; `slSetFeatureLoaded` follows `slSetConstants`. **Kept in word 1 of the feature's slot** (region 5, layout 5 as it was): bit 2 and the result in bits 8..15, bits 3 and 4, bits 5 and 6 — the last two a session's, cleared by a new request; the rest the process's, kept (`fl_adv_fields.h` `kFeatureSessionBits`). A refused feature therefore has a slot now, with nothing in it but that word. The declarations of the three functions are the same from Streamline v2.0.0 to v2.14.16, and `sl::Result` is the same forty codes in the same order at all sixteen tags (`include/sl_result.h`, `05a3c7e3889c` … `8a844b68ff55`), so a code means the same whatever interposer answered. Families `FL_HOOK_SL_FEATURE_SUPPORTED` (bit 17), `FL_HOOK_SL_FEATURE_LOADED` (18), `FL_HOOK_SL_SET_FEATURE_LOADED` (19), each published with its patch. **Measured overhead** (the detours' bodies on the headers, the Overlay's flags, 20 million calls a run, three runs, eight features in turn): `slIsFeatureSupported` — not asked **+1.50 / +1.48 / +1.50 ns**, asked **+11.97 / +11.98 / +12.08 ns**; `slIsFeatureLoaded` — **+1.79 / +1.77 / +1.89 ns**, **+12.35 / +12.31 / +12.33 ns**; `slSetFeatureLoaded` — **+1.44 / +1.47 / +1.80 ns**, **+11.28 / +11.54 / +11.45 ns**. **`slInit` is not a row and will not be** (D129): a game calls it once, before the Overlay is in the process or before a patch can land — launch mode waits for the presentation runtime before it injects, nothing is ever patched on a game's thread (§H2), and a row that exists only for Advanced metrics waits for the Agent's request. **A stop takes about 160 ms for every patch it restores** (measured on the fixture, 0.1.0-beta.45: each `MH_DisableHook` snapshots the system's threads): twelve patches took 1.9 s, fifteen 2.4 s, and the watchdog's wait for the stop's log lines, 2 s until then, is now a quarter of a second for every patch the registry can hold. |
| ✅ Streamline: `slGetFeatureVersion` and `slGetFeatureRequirements` (0.1.0-beta.44, Advanced metrics train B's third step; owner decisions D111–D116, D122) | **What Streamline answers when the game asks about a feature** — which version it is, and what it requires. Two rows, two patches, two detours of one shape: **the original runs first, exactly once, on every path, with both arguments forwarded untouched**, and the struct the game passed is read only when the original said `eOk` — a refusal leaves the struct as the game made it, which is not an answer. Rule 4: an argument of the call hooked, read after the call, and of it only the members named here. **Read from `sl::FeatureVersion`:** `versionSL`, `versionNGX`. **Read from `sl::FeatureRequirements`:** `flags`, `maxNumCPUThreads`, `maxNumViewports`, `numRequiredTags`, `osVersionDetected`, `osVersionRequired`, `driverVersionDetected`, `driverVersionRequired`. **Never read:** `requiredTags` — the pointer the count belongs to — and everything after `driverVersionRequired`: the Vulkan queue counts and the pointers to the names of extensions and features. **No pointer of the game's is followed** (`tools/overlay-fields-check.ps1`, parameters `fv` and `fr`; ctest `fl_adv_fields`: two answers that differ only in those bytes publish the same region, and an answer cut off where the Vulkan members begin, laid against unreadable memory, is read without a fault; the injected `fl_guard` case's stub hands back wild pointers and no fault is counted). **Installed only where asked for** (D111), as `slSetConstants` is: `InstallByFamily` returns before it resolves either symbol in a process the Agent has never asked for Advanced metrics; once in, a patch stays for the life of the process and its detour forwards without looking while the request is off. **They are the first two rows of the table**: a game asks these while it starts, the watchdog patches rows in the table's order, and each patch stops the game's threads for a moment (0.1–0.25 s apart in the owner's logs of 2026-11-12, where `slSetConstants` was the fifth Streamline patch in, 1.9–7.8 s after the attach). *(Since 0.1.0-beta.46 the rows a tick finds go in together, under one stop of the threads — §Unhooking, Batches — so the order no longer decides which row waits behind which; it is still the order of their log lines.)* In a process never asked they are passed over and the order changes nothing. ~~**Most sessions will still have missed the calls** — an attach after the game's start-up is the usual case — and the session then says the call was hooked and the game did not ask again.~~ *(Measured 2026-11-12, the owner's eight sessions on beta.44: both calls were read in six of six Streamline sessions on five games — Unreal's Streamline plugin asks again after the attach, Cyberpunk 2077 asks again for requirements and not for versions. A game that asks only while starting still reads "hooked, not asked again".)* Three conditions before a read, as for `slSetConstants`: the Agent is asking, observing has not stopped, and the struct carries its own GUID and a version of at least 1 on this call (a struct with another GUID is not kept: the injected case sends one). Every member read is version 1's (§Which struct version carries which field). **Twelve slots** in region 5 (`FlAdvancedState.features`, layout 5 as it was), one per feature in the order first asked about; the last answer about a feature is the one kept; a thirteenth feature is not kept. **A new request does not empty them**: what version a feature is and what it requires are facts about the process, and a second session of a game that kept running would otherwise have nothing where the first had the answer — the one group `Reset` leaves, with its bit of the mask. Streamline 1.x is refused before anything is resolved (`SpeaksStreamline2`). Families `FL_HOOK_SL_FEATURE_VERSION` (bit 15) and `FL_HOOK_SL_FEATURE_REQUIREMENTS` (bit 16), each published with its patch; neither entitles a field of a frame record. **Measured overhead** (the detours' bodies on the headers, the Overlay's flags, 20 million calls a run, three runs, eight features asked about in turn): the version — not asked **+0.58 / +0.61 / +0.58 ns**, asked **+14.82 / +14.54 / +14.47 ns**; the requirements — not asked **+0.58 / +0.63 / +0.61 ns**, asked **+20.88 / +21.01 / +20.96 ns**. A game makes these calls a handful of times. |
| ✅ Streamline: `slIsFeatureSupported`, `slIsFeatureLoaded`, `slSetFeatureLoaded` (0.1.0-beta.45; owner decisions D129–D131) | **Whether a feature is supported, whether it is loaded, and the game switching it on and off.** Three rows, three patches. Rule 4: bare arguments and results of the calls hooked, and no vendor struct at all — the feature's id; the `sl::Result` `slIsFeatureSupported` returned, **every result**, since a refusal is the answer to that question (the original runs first, both arguments forwarded untouched); the `bool` `slIsFeatureLoaded` wrote, read only when it returned `eOk`; the `bool` the game passed to `slSetFeatureLoaded`, noted before the call. **The adapter `slIsFeatureSupported` is asked about is never read** (D131): `sl::AdapterInfo` holds the adapter's LUID or a Vulkan physical device; the detour forwards the reference and `tools/overlay-fields-check.ps1` refuses the names of its members (`deviceLUID`, `deviceLUIDSizeInBytes`, `vkPhysicalDevice`) anywhere in the Overlay and the Vulkan layer — the fixture's adapter carries a wild pointer. **Installed only where asked for** (D111), as the four rows before them. `slIsFeatureSupported` and `slIsFeatureLoaded` follow the two rows of beta.44 at the head of the table; `slSetFeatureLoaded` follows `slSetConstants`. **Kept in word 1 of the feature's slot** (region 5, layout 5 as it was): bit 2 and the result in bits 8..15, bits 3 and 4, bits 5 and 6 — the last two a session's, cleared by a new request; the rest the process's, kept (`fl_adv_fields.h` `kFeatureSessionBits`). A refused feature therefore has a slot now, with nothing in it but that word. The declarations of the three functions are the same from Streamline v2.0.0 to v2.14.16, and `sl::Result` is the same forty codes in the same order at all sixteen tags (`include/sl_result.h`, `05a3c7e3889c` … `8a844b68ff55`), so a code means the same whatever interposer answered. Families `FL_HOOK_SL_FEATURE_SUPPORTED` (bit 17), `FL_HOOK_SL_FEATURE_LOADED` (18), `FL_HOOK_SL_SET_FEATURE_LOADED` (19), each published with its patch. **Measured overhead** (the detours' bodies on the headers, the Overlay's flags, 20 million calls a run, three runs, eight features in turn): `slIsFeatureSupported` — not asked **+1.50 / +1.48 / +1.50 ns**, asked **+11.97 / +11.98 / +12.08 ns**; `slIsFeatureLoaded` — **+1.79 / +1.77 / +1.89 ns**, **+12.35 / +12.31 / +12.33 ns**; `slSetFeatureLoaded` — **+1.44 / +1.47 / +1.80 ns**, **+11.28 / +11.54 / +11.45 ns**. **`slInit` is not a row and will not be** (D129): a game calls it once, before the Overlay is in the process or before a patch can land — launch mode waits for the presentation runtime before it injects, nothing is ever patched on a game's thread (§H2), and a row that exists only for Advanced metrics waits for the Agent's request. **A stop takes about 160 ms for every patch it restores** (measured on the fixture, 0.1.0-beta.45: each `MH_DisableHook` snapshots the system's threads): twelve patches took 1.9 s, fifteen 2.4 s, and the watchdog's wait for the stop's log lines, 2 s until then, is now a quarter of a second for every patch the registry can hold. **Since 0.1.0-beta.46 (D134) a stop restores its patches under one stop of the threads**: eighteen in 76–90 ms on the fixture, where one by one they took 1.37–1.56 s (§Unhooking, Batches). |
| ✅ Streamline: `slAllocateResources`, `slFreeResources`, `slShutdown` (0.1.0-beta.45; owner decision D130) | **The game allocating and freeing a feature's resources, and shutting Streamline down — counted, and nothing else.** Three rows, three patches. Rule 4: the feature's id is the only argument looked at; the command buffer and the viewport of the two resource calls are forwarded and never read (the fixture's command buffer is a wild pointer), and `slShutdown` has no argument. **`slFreeResources` and `slShutdown` are on a game's way out**: each detour notes the call first and then calls the original, exactly once, and runs nothing of ours after it returns; the fixture goes on calling the stub after `slShutdown`, through every detour. **Installed only where asked for** (D111); the last three Streamline rows of the table. **Kept** in word 1 of the feature's slot as two four-bit counts — allocations in bits 16..19, frees in 20..23, each stopping at 15 and never carrying into its neighbour — and, for `slShutdown`, in `FlAdvancedState.slShutdowns` (@308, the first of three reserved words; layout 5 as it was) with `FL_ADV_VALID_SL_SHUTDOWN` (bit 6 of the mask). All three are a session's: a new request clears them. Families `FL_HOOK_SL_ALLOCATE_RESOURCES` (bit 20), `FL_HOOK_SL_FREE_RESOURCES` (21), `FL_HOOK_SL_SHUTDOWN` (22). The three declarations are the same from Streamline v2.0.0 to v2.14.16. **Measured overhead** (the detours' bodies on the headers, the Overlay's flags, 20 million calls a run, three runs): `slAllocateResources` — not asked **+0.70 / +0.72 / +0.80 ns**, asked **+10.43 / +10.53 / +10.74 ns**; `slFreeResources` — **+0.61 / +0.84 / +0.58 ns**, **+10.33 / +10.57 / +10.44 ns**; `slShutdown` — not asked within the bench's noise (+0.06 / −0.12 / +0.04 ns), asked **+3.39 / +3.37 / +3.52 ns**. Inventory 23 → 26 rows; a Streamline title with Advanced metrics asked for now carries thirteen patches on the interposer, and a stop restores each in about 160 ms (the row above). **In real games (2026-11-13: six sessions, five games)** `slAllocateResources` was not called once after the attach, `slFreeResources` once in one game (Phantom Blade Zero, frame generation's) and `slShutdown` once in one (Dying Light: The Beast); no session counted a fault, and the two games that fault while closing did so at the offsets they had before these hooks. Installing the thirteen interposer patches took 0.7 s to 2.8 s of a game's start, 57 to 215 ms a patch. The owner's word on both (2026-11-13): `slAllocateResources` keeps its patch and is looked at again with more sessions (D135); installs and restores are to be batched, one stop of the threads for a batch (D134, 0.1.0-beta.46). |
| ✅ Streamline: `slSetTag` — **and, since 2026-09-05, every tag's TYPE** (`slTagCensus`; a HUD-less / UI tag marks the present `FL_FG_DLSS_G`, rule 4: the same argument) | The **global** resource tags, where a title states the size of the buffer it is upscaling *from*: `kBufferTypeScalingInputColor`'s extent → `renderW/H` — **or, since 2026-09-05, the size the tagged `sl::Resource` declares when the extent is zero** (`TagSize` in `fl_sl_inputs.h`, shared by all three tag routes; GUID-checked; a Resource declaring no size is still the honest unknown). **Built 2026-08-15** (`FL_HOOK_UPSCALER_PARAMS`), and it is an ALTERNATIVE to the local tags in `slEvaluateFeature`'s `inputs`, not a layer over them — `sl_core_api.h:258` says global and local tags "do NOT interact", so a title using one yields nothing from the other and both are read. Published only on a frame where an evaluation was also seen, because a tag is viewport state that outlives any one frame. This row was MISSING from this table while the hook shipped, which is the gap the banner above now names |
| ✅ Streamline: `slSetTagForFrame` — **and every tag's TYPE, as above** | The same global tags through **Streamline 2.8's frame-based entry point**, which deprecates `slSetTag`: `(const FrameToken&, const ViewportHandle&, const ResourceTag*, uint32_t, CommandBuffer*)` — the token first, then exactly `slSetTag`'s list, handed to the same tag walk. **Built 2026-09-04** (`FL_HOOK_UPSCALER_PARAMS`, its own trampoline; the family is now **published when whole** — once every tag export the loaded interposer has is patched — because publishing on the first row entitled records the second was not yet producing, 38 of 41 on the fixture: the ffx leaves' #110 defect again, fixed the same way). Measured need: Dying Light: The Beast (SL 2.8.0) published `Dlss` identity on every batch and the params bit on none across three captures, because a 2.8 title that tags per frame never calls the deprecated export. The token is not read; the frame count stays with `slGetNewFrameToken`. The installer picks this detour by SYMBOL (`kSymbolSlSetTagForFrame`, bound to the row by `static_assert`), not by family, since the two rows share a family bit and differ in signature |
@@ -405,7 +453,7 @@ or version, so the question is whether the declaration ever changed:
| Hook / call | Yields |
|---|---|
| ~~`IDXGIAdapter3::QueryVideoMemoryInfo` (we **call** it, not hook it, once per second from our own thread)~~ | ~~**Per-process VRAM** `CurrentUsage` + `Budget` — previously impossible; now exact~~ **Never built; superseded 2026-10-03 (D43):** the game's memory is read from OUTSIDE the game by the Agent (`18_GPU_VENDOR_APIS` §The game process's memory), so nothing in the Overlay calls it. Only the budget would need it, and that stays open (`20_OPEN_QUESTIONS` §M11) |
| NVAPI Reflex: ~~hook `NvAPI_D3D_SetSleepMode`, `NvAPI_D3D_SetLatencyMarker`~~; call `NvAPI_D3D_GetLatency` *(**never built.** The two hooks cannot be: neither function is an export — `20_OPEN_QUESTIONS` §M14. What a call-only route would take is read through in `spike-notes` §30, 2026-11-12, and waits for the owner's go or no)* | Reflex on/off + PC latency breakdown. Declarations come from the vendored MIT NVAPI headers (`18_GPU_VENDOR_APIS` §L3); the Overlay links them like any other header. NVIDIA-only — the whole block compiles out to a no-op capability flag elsewhere |
| NVAPI Reflex: ~~hook `NvAPI_D3D_SetSleepMode`, `NvAPI_D3D_SetLatencyMarker`~~; call `NvAPI_D3D_GetLatency` and `NvAPI_D3D_GetSleepStatus` *(the two hooks cannot be: neither function is an export — `20_OPEN_QUESTIONS` §M14. **The calls are made since 0.1.0-beta.47** — §Calls the Overlay makes into a driver, above; owner decisions D132, D136)* | Reflex on/off + PC latency breakdown. Declarations come from the vendored MIT NVAPI headers (`18_GPU_VENDOR_APIS` §L3); the Overlay links them like any other header. NVIDIA-only — the whole block compiles out to a no-op capability flag elsewhere |
### Explicitly not hooked
Input APIs, file I/O, network, memory allocators, window messages beyond what the overlay needs, anything game-specific. Rule 4 in CLAUDE.md.
@@ -650,7 +698,7 @@ Field notes — each of these was a defect in an earlier revision:
header — they are written by the other process, and mixing them into an
Overlay-written line reintroduces exactly the false sharing the split exists to
prevent. Layout is normative in `07_IPC` §A + B.
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present. *(Added 2026-10-04: the summary leaves out the per-present `IDXGISwapChain::GetLastPresentCount` call (§H5, the `dxgiUnseen` count) and the display sample every 500 ms at most (region 4).)*
- **The hot path performs: one QPC read, a few field reads from cached state, one 60-byte store, two relaxed atomic stores and two compiler fences.** No syscall, no allocation, no lock, no logging. Target ≤ 1 µs per present. *(Added 2026-10-04: the summary leaves out the per-present `IDXGISwapChain::GetLastPresentCount` call (§H5, the `dxgiUnseen` count) and the display sample every 500 ms at most (region 4).)* *(Added 2026-11-13, train C, 0.1.0-beta.47: after the store, one relaxed load of the latency gate; and, while a session asks for Advanced metrics and the watchdog armed one, a call into the driver about once a second — §Calls the Overlay makes into a driver. That call is the one thing on this path that is not bounded by FrameLedger's own code: 0.5–2.6 µs measured against the installed driver, and a call of 2 ms or more is the last.)*
- Per-frame mutable state (current upscaler, render res, dispatch counts) lives in a small struct updated by the feature hooks and *read* by the present hook; counters reset at present.
## The watchdog thread — the only thread we add to the game
@@ -714,8 +762,9 @@ Every hook body is wrapped:
```
- Any SEH exception inside our code ⇒ increment `faultCount`, record which hook, **return control to the original function** so the game continues.
- 3 faults total ⇒ set `status = self_disabled`, ~~uninstall all hooks (`MH_DisableHook(MH_ALL_HOOKS)`)~~ restore each patch's prologue only while its bytes are still our jump (compare-and-restore per patch through `StopObserving`, §Unhooking, §H7 — `MH_ALL_HOOKS` would have removed an overlay chained after us; corrected 2026-09-27), stop writing, stay dormant. The Agent sees the flag and finalizes the session as `degraded`.
- 3 faults total ⇒ set `status = self_disabled`, ~~uninstall all hooks (`MH_DisableHook(MH_ALL_HOOKS)`)~~ restore each patch's prologue only while its bytes are still our jump (compare-and-restore per patch through `StopObserving`, §Unhooking, §H7 — `MH_ALL_HOOKS` would have removed an overlay chained after us; corrected 2026-09-27; since 0.1.0-beta.46 the patches that are still ours come out together, under one stop of the threads — §Unhooking, Batches), stop writing, stay dormant. The Agent sees the flag and finalizes the session as `degraded`.
- Never `__try` around the call to the original function — only around *our* code, so we never mask a game bug as ours or vice versa.
- **One exception, since train C (2026-11-13): the two driver getters the Overlay calls itself** (§Calls the Overlay makes into a driver) are under a guard of their own, `fl_reflex.h`'s, with the same filter. They are not "the original function" — the game did not make these calls, we did, so a fault in them is ours to answer for. It is counted once through `NoteFault`, and the read is switched off for the process in the same breath, so that one fault cannot become the three that self-disable. **A caught fault does not give back a lock the driver held**: the guard is containment, not safety, which is why nothing is called again after it.
- The trampoline call to the original is always executed exactly once, on every path, including error paths.
## Unhooking
@@ -761,6 +810,67 @@ Every hook body is wrapped:
> the shipped sequence against real MinHook patches: a full registry leaves the target's bytes untouched and
> MinHook unasked; a stop arranged between the enable and the re-read ends with the function unpatched; a failed
> patch gives its slot back; a slot is invisible to the walk until committed.
>
> **Batches, 0.1.0-beta.46 (owner decision D134): one stop of the game's threads for a group of patches.** MinHook
> writes a jump with every other thread of the process stopped — a snapshot of the system's threads, then a
> suspend, a context read and a resume for each of the process's — and `MH_EnableHook` / `MH_DisableHook` for one
> target do all of that for one jump. The owner's logs of 2026-11-13 put a number on it: the thirteen Streamline
> patches took 0.74 s to 2.8 s of a game's start, 57 to 215 ms each, and a stop restored its patches the same way.
> MinHook 1.3.4 can queue — `MH_QueueEnableHook` / `MH_QueueDisableHook` mark a hook, `MH_ApplyQueued` executes
> every mark under one stop — and `fl_patch_registry.h` now has the two sequences that use it:
> `fl::patch::Batch` (`Add`: slot and create, nothing marked; `Commit`: enable them all) and
> `fl::patch::RestoreAll`, which is the stop's walk. `InstallUpscalerHooks` queues every row a tick finds
> something for and commits once, before the families that are published "when whole"; `InstallRtHooks` batches
> its two; `StopObserving` calls `RestoreAll`. A patch's `HOOK_INSTALLED` line, family bit and latch still come in
> that order and only once it is in. The loader detour, OpenGL and the three DXGI patches of init are as they were.
>
> **What the queue makes dangerous, and what the code therefore never does** (the plan was reviewed against
> `hook.c` before a line was written, and its first form was refused). `MH_ApplyQueued` applies **every** hook
> whose mark differs from its state — the process has one table, not one per caller. So (1) **no mark is ever left
> standing**: a hook that failed to enable has its mark removed, or the next apply — the stop's own — would enable
> it; (2) **only a patch that is still ours is ever marked for a restore** (`StillOurs`, as before; §H7), and
> nothing is marked "all" — the refused draft marked everything and then un-marked what it must not restore, and
> un-marking a hook that is already out marks it for *enabling*: the stop would have put a patch back in after the
> stop; (3) **mark, apply and commit happen inside a gate** (`MinHookEngine::BeginQueue`, a slim lock taken
> exclusively) so the watchdog's apply cannot execute the stop's marks nor the stop's the watchdog's. The gate is
> held for one apply and never across a symbol lookup, which takes the loader's lock. It is the one lock in the
> Overlay, and it is on no hook body's path: the only way from a hook to it is the stop itself, which already
> waited for MinHook's own lock and a stop of the threads for every patch. Its owner re-enters it without
> waiting. **The verdict on an install is the engine's, not the bytes'**: a foreign overlay patching over us a
> moment after the apply would read as "not in", and treating that as a failure would mark a restore nobody had
> compared. `MH_ApplyQueued` stops at the first hook that fails and says only that one did; the ones after it
> are then enabled — or, in the stop, restored — one at a time, so one bad patch still costs one patch.
> The write-then-read pair is unchanged: the stop clears the flag and then walks; `Commit` commits its slots and
> then re-reads the flag, and takes out — compared first — what it put in when the flag is clear. A stop that
> lands before the commit enables nothing.
>
> **Measured** on `hook-harness`'s Streamline target, the development PC, three runs before and after (`fl_guard`
> `[advanced]` prints them): the nine Advanced-only patches went in one by one over 0.60 s / 0.70 s / 0.60 s
> from the first log line to the ninth, 76–88 ms each; as one batch they take **81 / 90 / 78 ms**. The stop restored
> eighteen patches in 1.37 s / 1.56 s / 1.37 s; under one apply, **77 / 90 / 76 ms** — and from the Agent's request
> to `UNHOOKED`, 1.27–1.48 s became 94–110 ms. One stop of the threads costs what it cost for one patch, whether it
> covers four, nine or eighteen. A new log line says so in the field: `PATCH_BATCH install` / `restore`, `a` the
> microseconds, `b` the patches. ~~**Not measured:** a real game — how long one stop of the threads is with a few
> hundred of them, and whether any title minds patches arriving together (owner-only item 44).~~ **In real games**
> (the owner's five sessions of 2026-11-13 on 0.1.0-beta.46 — Hogwarts Legacy, Phantom Blade Zero, Black Myth:
> Wukong, Cyberpunk 2077, Clair Obscur: Expedition 33; eighteen install batches of two to sixteen patches): every
> batch went in whole, with the hooks beta.45 installed and no `PATCH_FAILED`; **sixteen batches cost 81–262 ms
> whatever they held**, which is what one patch cost in the same game before. Streamline's thirteen, first line to
> last on beta.45 against the one batch now: Phantom Blade Zero 0.74–0.85 s → 88 ms, Cyberpunk 2077 1.18 s → 93 ms
> (with three more patches in the batch), Black Myth: Wukong 1.65 s → 188 ms (twelve), Hogwarts Legacy 2.80 s →
> **1.26 s**. That last one and a batch of three in Cyberpunk 2077 (**0.61 s**) are not explained: the cost does
> not follow the count — sixteen patches in 93 ms, three in 609 ms — and **the log cannot tell one long stop from an
> apply that failed part-way and was finished one patch at a time**, because a batch writes a line only for a patch
> that fails for good. **Since 0.1.0-beta.47 the line says which** (owner decision D137): `install` or `restore` is a batch that went under its one apply; `install singly` or `restore singly` is one whose apply said it had failed, and the high half of `b` then counts the patches handed to MinHook one at a time (`b=0x0003000d`: thirteen in, three of them singly) — attempts, not stops: MinHook makes no stop for a patch the failed apply had already done. So a long `a=` on a plain `install` line is one long stop of the threads. ~~**Still not measured: the restore in a real game**~~ **The restore in a real game** (the owner, 2026-11-14,
> Phantom Blade Zero, twice): twenty-nine patches out under one apply of **83 ms and 86 ms**, every one restored,
> none declined, and the game went on for minutes and closed cleanly (owner-only item 44 (d)). One more thing the
> queue changes for the better: MinHook's single-target disable does not move a thread that is suspended inside
> the patched bytes (`hook.c` passes the enable action to its thread fix-up in both directions); the queued apply
> does. ctest `fl_unhook_inline` drives `Batch` and `RestoreAll` against real MinHook (three in under one apply,
> a duplicate target refused without holding the others up, a foreign patch left byte for byte) and against a
> model of MinHook's table for what real MinHook cannot be made to do on demand: an apply that fails halfway or
> not at all, a stop inside the apply, a committed patch that is already out — the refused draft's failure — and
> that no mark is ever standing or made outside the gate.
~~`FlRequestUnhook()` (or the control flag) ⇒ `MH_DisableHook(MH_ALL_HOOKS)`, restore vtable entries **only where they are still ours**, flush the ring, set status.~~ *(Corrected 2026-10-04: both reach `StopObserving` — compare-and-restore per patch as the note above says, then the status; there is no `MH_ALL_HOOKS`, no vtable entry and no ring flush. The watchdog flushes the native log on its way out.)* **The DLL is not `FreeLibrary`'d from the live process** — a thread could still be inside a trampoline. It goes dormant and unloads with the process. This is deliberate and documented.
@@ -789,6 +899,12 @@ before it. And when the slot has changed, going dormant costs nothing: we stay
loaded anyway, and our detour remains in someone else's chain doing nothing
harmful.
> **Said plainly, 2026-11-13: for the inline patches that re-check has never been made.** MinHook owns the write
> window — it stops the threads, changes the protection and writes — and `StillOurs` is asked before it is called,
> not inside. Between the two a foreign overlay could patch over us, on a thread MinHook has not stopped yet. The
> batches of 0.1.0-beta.46 neither close that window nor widen it: the comparison and the write are apart by one
> stop of the threads, as they were for each patch, once instead of once a patch.
Verified by `hook-harness --probe-unhook` (ctest `fl_unhook_preserves_foreign`),
which simulates the foreign hooker rather than depending on RTSS being
installed, so it is deterministic and runs on CI. Both halves are asserted: we
@@ -810,7 +926,12 @@ No logging in hook bodies. A small fixed-size in-memory ring of structured event
> writing), and since beta.42 `PATCH_FAILED` (a patch that did not go in, once per target and reason — §Unhooking)
> and `FFX_DISPATCH`, `FFX_QUERY`, `UPSCALE_ROUTE`, `RUNTIME_CENSUS` (the note at the end of this section), and
> since beta.43 `FFX_CONFIGURE` — each configure type a hooked ffx module was handed, in a process where
> `ffxConfigure` is hooked at all (one asked for Advanced metrics).
> `ffxConfigure` is hooked at all (one asked for Advanced metrics) — and since beta.46 `PATCH_BATCH`: one line an
> apply, `install` or `restore`, `a` the microseconds it took and `b` the patches it covered (§Unhooking, Batches).
> **`LATENCY` (train C, 0.1.0-beta.47)**: one line each time the state of the driver read changes — `a` the
> `FlLatencyState`, the text what it means — and, when the module is found, two more with the end of the path
> `nvapi64.dll` was loaded from and of the image its getters are in. Written by the watchdog; a fault in a getter
> is a `FAULT` line from the presenting thread, as any fault is.
> **Three flush points — four since beta.42, the same note —, none on a present path:** the end of `InitThread` (so the
> file exists from the start of the session and a crash mid-session still leaves it), the watchdog when
> `FlControlBlock.logFlushRequested` changes (a counter the Agent bumps at session end; nothing clears it),
@@ -822,7 +943,7 @@ No logging in hook bodies. A small fixed-size in-memory ring of structured event
> it reads 0. When the stop ran on a presenting thread — `MayObserve`'s one-frame safety stop — the watchdog's one
> final flush could run while that thread was still writing, and the lines after it (the kernelbase loader detour is
> the last patch) reached the ring after the last flush ever made. The stop now says when its last line is in, and
> wakes the watchdog; the final flush waits for that, bounded at 2 s, then writes `STOP_FLUSHED`. And each slot has a
> wakes the watchdog; the final flush waits for that, bounded at 2 s *(a quarter of a second for every patch the registry can hold since beta.45; the stop is one apply since beta.46 and the bound is for its fallback)*, then writes `STOP_FLUSHED`. And each slot has a
> commit word written after its fields: `LogNote` claims a slot with one `fetch_add` and fills it afterwards, so a
> flush on another thread could print a slot still being filled. A flush now prints only slots whose writer has
> finished — an ordinary flush stops at the first that is not, for the next one; the final flush names it in a `#`
+24 -4
View File
@@ -872,6 +872,12 @@ planning, the design reviewed against the code before it was approved.
- **Privacy Policy 2.18** at beta.44 (approved with that release's plan): 2.17 named two further calls and what
they give; Streamline's answers about a feature are in neither list, so they are named, with what of the answer
is never read — the lists it points to.
- **Privacy Policy 2.20 and Disclaimer 2.16** at beta.47, train C (wording approved with the plan of
2026-11-13): the first thing read inside a game that is **not an argument of a call the game made**. The Privacy
Policy names what is stored — how long each stage of a frame took, as the driver reports it, and the driver's
low-latency state; never a time of day, never an input's moment. The Disclaimer drops "API arguments and nothing
else" for what is true, and §2 gains the paragraph on the one call the component makes itself: where, how often,
on which thread, what it never calls, what ends it, and that a call which never returned could not be stopped.
- **Privacy Policy 2.17** at beta.43 (approved with that release's plan): 2.16 listed DLSS's and FSR's upscaling
parameters by name, and Streamline's per-frame constants and the frame-generation configuration are in neither
list, so they are named — and §4 says the two calls are intercepted only once a session with the option on has
@@ -1075,13 +1081,27 @@ before FrameLedger is inside it, so no hook could read it — D129), `Spike` (Tr
| `sl.init.preferences` | The preferences the game started Streamline with | SessionFact | Streamline | BeforeAttach | Text |
| `sl.constants.camera` | Camera position, axes and matrices | SessionFact | Streamline | PlayerState | Text |
**Inside the game: what the graphics driver reports, asked for by the part inside the game itself** *(train C,
owner decisions D132, D136, D138 — `17_HOOK_ENGINE` §Calls the Overlay makes into a driver; since 0.1.0-beta.47)*
Not an argument of a hooked call: the Overlay calls the driver's two read-only latency getters about once a second,
only while a session records Advanced metrics, only for a Direct3D 12 game that had already loaded the driver's
`nvapi64.dll`. The report becomes seven series — `adv.nvapi.reflex.frame_report.` and `simulation`,
`render_submit`, `present`, `driver`, `os_queue`, `gpu_render`, `total` — each point the mean, in microseconds, of
the frames one read summed; the sleep status becomes one table of the driver's five switches as seen over the
session. What the *game* asked of Reflex (`nvapi.reflex.mode`) is an argument of a function no module exports:
reading it takes a patch at an address learned at run time, which is refused.
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `nvapi.reflex.mode` | Reflex: low-latency mode, boost, the frame-rate limit | SessionFact | Nvapi | RefusedRoute | Text |
| `nvapi.reflex.sleep_status` | What the driver's low-latency state is | SessionFact | Nvapi | GameDriver | Table |
| `nvapi.reflex.frame_report` | Latency per frame: simulation, render submit, present, driver, OS queue, GPU render | Series, one per device | Nvapi | GameDriver | Microseconds |
**Inside the game: routes a spike decides**
| Id | What it is | Scope | Source | Reach | Unit |
|---|---|---|---|---|---|
| `nvapi.reflex.mode` | Reflex: low-latency mode, boost, the frame-rate limit | SessionFact | Nvapi | Spike | Text |
| `nvapi.reflex.sleep_status` | What the driver's low-latency state is | SessionFact | Nvapi | Spike | Text |
| `nvapi.reflex.frame_report` | Latency per frame: simulation, render submit, present, driver, OS queue, GPU render | Series, one per device | Nvapi | Spike | Microseconds |
| `sl.dlss.optimal_settings` | The render size and sharpness DLSS recommends | SessionFact | Streamline | Spike | Text |
| `sl.dlss.vram_estimate` | DLSS's own estimate of its video memory | Series | Streamline | Spike | Mebibytes |
| `sl.dlssg.options` | DLSS frame generation: mode, frames to generate | SessionFact | Streamline | Spike | Text |
@@ -1091,7 +1111,7 @@ before FrameLedger is inside it, so no hook could read it — D129), `Spike` (Tr
| `sl.dlssd.options` | Ray reconstruction's options | SessionFact | Streamline | Spike | Text |
| `sl.nis.options` | NVIDIA Image Scaling's options | SessionFact | Streamline | Spike | Text |
| `sl.deepdvc.options` | RTX Dynamic Vibrance's options | SessionFact | Streamline | Spike | Text |
| `sl.reflex.state` | Reflex through Streamline: availability and its frame reports | SessionFact | Streamline | Spike | Table |
| `sl.reflex.state` | Reflex through Streamline: availability and its frame reports | SessionFact | Streamline | RefusedRoute | Table |
| `sl.pcl.markers` | PC-latency markers the game sets | Series | Streamline | Spike | Count |
**Closed by a licence**
+11 -1
View File
@@ -1549,6 +1549,16 @@ probe never showed a deadlock.
> real-game leg — a title that pulls Streamline or D3D12 in lazily, hooked through the wake — which the
> `loader detour:` report line will show as a non-zero wake count with the family present from the first
> bucket.
>
> **0.1.0-beta.46 (owner decision D134): one suspension for a batch, and the rule is as it was.** The rows a
> watchdog tick finds are enabled under one `MH_ApplyQueued` — one stop of the threads where there was one a row
> (`17_HOOK_ENGINE` §Unhooking, Batches). Still only on the watchdog, never from the detour and never on a game's
> thread; the gate around the queue is not held across a symbol lookup, so it is never held with the loader's lock
> wanted. What a stop of the threads costs in a real game was read from the owner's logs of 2026-11-13: 57 to
> 215 ms, thirteen times over for a Streamline title until this release. **On beta.46, the same evening** (five
> games, eighteen batches): 81–262 ms a batch for sixteen of them, and two that took 0.61 s and 1.26 s while their
> game was loading — one stop where there were three and thirteen, and still a second of every thread of Hogwarts
> Legacy standing still. Not explained (`17_HOOK_ENGINE` §Unhooking, Batches).
### H11 ◐ · XeFG and FSR3-FG identity — **AMD built 2026-09-04 through the ffx-api leaves, complete 2026-09-06; Intel closed by licence; FSR 3.0 host route built 2026-09-05**
@@ -1863,7 +1873,7 @@ Moved verbatim, in this order.
| M12 ❓ | **Advanced metrics — which NVAPI rows answer on real hardware (D101, 2026-11-11).** `18_GPU_VENDOR_APIS` §The inventory lists sixty `nvapi.` rows whose reach is `Agent`. They are declared in the vendored headers; **none has been called on a GPU**, and CI has no driver, so it never takes that branch. Unknown per row: whether the RTX 5080 on the current driver answers or returns `NVAPI_NOT_SUPPORTED` (the memory-temperature target already does not exist on that card). | **The measurement is the bridge's probe on the owner's PC**, then the page itself (the release's owner-only item). Pre-committed: a call that does not answer → that row is N/A with NVAPI's own status as the reason, and nothing is put in its place; a call that hangs or faults twice → the row is off for the session (§Runtime policy); a value that contradicts the vendor's own tool → the row is withheld until it is explained. **Half answered the same day, by the bridge's own test on the dev box** (ctest `fl_nvapi_bridge`, AVAILABLE branch; RTX 5080): every fact answers (`present = 0xFFFFF`), eight of ten live groups answer (`0x33F` — no board and no power-supply temperature sensor on this card: N/A, by the first pre-committed outcome), the display answers its four groups, the global profile lists 24 settings; figures in `18_GPU_VENDOR_APIS` §L3. **Still open**: the same values on the page beside the vendor's own tool, and the session rows (`nvapi.session.*`), which need a game. **And one thing seen once and not explained**: in one test run of about a dozen that day, `FlNvReadLive` came back with no field at all although `FlNvReadFacts`, a moment earlier in the same process, had answered everything; nine further runs did not show it. A handle the driver invalidated is the usual cause of that shape, and nothing here re-enumerates after `FlNvInit`. Pre-committed for the reader that owns the thread: two readings in a row with no field → release and initialise the bridge again, once, and say so in the log; if that does not bring the fields back the layer is off for the session, as any layer that fails twice is. |
| M13 ❓ | **Advanced metrics — LibreHardwareMonitor's CPU, memory, motherboard and storage groups, elevated, with PawnIO (D103, 2026-11-11).** Never opened by any build: §M10's elevated run has not been taken either, and this is a larger surface — a sensor chip on the LPC bus, the embedded controller, SPD over SMBus, SMART. Unknown: whether each group opens on the owner's board, what a refresh costs, whether opening the storage group touches removable drives (this PC once had a failing USB drive), and whether any group enables a privilege (`PrivilegeFootprintTests`). | **One elevated run with the probe verb, before the option exists.** Pre-committed: the storage group cannot be opened without touching removable drives → `lhm.storage.*` stays N/A in beta.39 and its reach reads `Deferred`; a node that throws twice → skipped for the session; the Agent above 1% of one core or 150 MB with the option on (NFR-2) → the slow groups are read less often or dropped before the release; a privilege enabled by a group → that group is not opened, and the owner is asked. **Two of the four answered 2026-11-11, before the option exists.** (1) **Storage: not opened, by the first outcome.** LibreHardwareMonitor 0.9.6's `StorageGroup` lists every drive through DiskInfoToolkit's `ReloadStorages` with no filter by bus and follows drives plugged in later — it cannot be opened without touching removable drives. `lhm.storage.*` reads `Deferred`, and `LhmGroups` has no member for it. (2) **Cost, unelevated, measured with `probe-advanced`** on the dev box: one refresh of the graphics-card group alone is 14 ms of processor time (62 ms elapsed) — 1.4% of one core at one a second, above NFR-2 — and one NVAPI read 0.4 ms. By the third outcome the sensor library is read every fifth tick (0.28%). **Still open, and the owner's**: the same probe as administrator with PawnIO — whether the processor, memory and motherboard groups open on this board, what they cost, and `PrivilegeFootprintTests`' new case on a token that holds the privileges (CI's does; the dev box's unelevated run passes by construction). **The first run was taken on 2026-11-12, by the owner, in ordinary use** (0.1.0-beta.40, the Agent as administrator with PawnIO, an i7-14700KF on a board with an IT8689E chip, an RTX 5080), and read here from a copy of the ledger and the Agent's log, not from a probe. **The groups open and read**: nine of ten sessions stored 119 processor series (a clock and a load per thread, temperatures, powers, voltages), 14 memory series and 21 motherboard series (six fans, six temperatures, nine voltages) beside the card's 41 — 195 from the sensor library in all. **No value was compared with another tool**; that is still the owner's. **Two faults, one cause** (`Infrastructure.Telemetry.LhmLibrary`): the Agent held up to three `Computer`s at once, and the library keeps the driver it reads the processor through and its bus mutexes per process — closing one `Computer` let go of them under the others. After seven sessions the Advanced reader's processor device threw `NullReferenceException` twice and was left alone (the page lost the processor until the reader reopened); once a session's start met another instance's close, the reader's `Open` threw `ObjectDisposedException`, and that session stored 17 series instead of 212. **Fixed 2026-11-12**: opens and closes are serialised and a `Computer` is parked, not closed, while another is in use. The cause is read from the log's timing and was not reproduced — it needs this elevation — so **whether the faults are gone is the owner's next sessions to show**: no `advanced: a device is left alone` and no `did not open` in the Agent's log. **First evidence, 2026-11-12, 0.1.0-beta.41, the same PC:** seven sessions between 06:38 and 07:01 with no `advanced:` line at all, each with the option on storing 212 or 213 series; on beta.40 that morning the processor device faulted out after each of six sessions (04:34–05:07) — thirteen of sixteen over the night. The reader failing to open was seen once in sixteen, so this is not yet enough to call that one gone. Still open: any value beside another tool. |
| M16 ✅ | **The L2 telemetry layer's cost — the first number, and it is above NFR-2 (found 2026-11-11, measuring something else).** `LhmTelemetrySource` refreshes LibreHardwareMonitor's graphics-card group once a second in every recorded session. `probe-advanced` measured that refresh, through the same library and the same group, at **14 ms of processor time** on the dev box (RTX 5080, 41 mapped sensors, about twenty of them the Direct3D engine nodes the library enumerates per card) — 1.4% of one core, where NFR-2 allows the whole Agent 1% during capture and `14_TESTING` §Hook overhead's Agent figure has never been measured. This is a measurement of the call, not yet of a session: L2's own poller was not instrumented. | **Measure L2 in a session** (the Agent's processor time over a ten-minute capture, telemetry at 1000 ms and at 2000 ms). Pre-committed: at or under 1% → this row closes with the number; above → the owner chooses between a slower default for `telemetry.interval_ms`, reading the sensors the layer keeps from NVAPI on NVIDIA cards (L3 already has most, at 0.4 ms), or amending NFR-2 to what is measured. Not decided here, and nothing about L2 changes in the Advanced-metrics train. **Measured in a real Agent, 2026-11-11 (owner decision D110), and answered (D117).** `tools/agent-cost.ps1` runs the shipped `FrameLedger.Agent.exe --console capture` against a copy of hook-harness in a scratch data folder — a session that is not hooked, so the telemetry poller runs as in every session and nothing drains frames — and reads the Agent process's own processor time at exit; the cost per second is the slope between a 45 s and a 165 s session, two runs of each. Dev box (RTX 5080, not elevated, layers `l1+lhm+nvapi`): **19.3 ms of processor time per second of session = 1.93 % of one core with Advanced metrics off** (2,312 and 2,312 ms over 45 s; 4,594 and 4,656 ms over 165 s), **20.4 ms = 2.04 % with it on** (2,984 and 3,000; 5,547 and 5,344); peak working set 113 MiB and 119 MiB. A first pass with 30 s and 90 s sessions gave 1.56 % and 2.21 % — its two short runs differed by 670 ms, which is why the lengths were raised. So the probe's number holds in a session: the Agent's steady cost is about twice NFR-2's 1 %, nearly all of it the layer every session has always used, and the new option adds about a tenth of a percent. **The owner's answer: NFR-2 is amended to ≤ 2.5 % of one core** — the limit had never been measured, the sensors keep their one reading a second, and nothing in the code changes. Not measured: a hooked session (the drain's cost on top), a session with the Agent elevated and PawnIO's groups open, another PC. |
| M14 ❓ | **Reflex latency per frame — is there a route within rules 4 and 5? (Train C, 2026-11-11.)** `17_HOOK_ENGINE` §Memory / latency names hooks on `NvAPI_D3D_SetSleepMode` / `SetLatencyMarker` and a call to `NvAPI_D3D_GetLatency`. NVAPI resolves all three through `nvapi_QueryInterface` by id — they are not exports, so a hook on them is a patch at an address learned at run time, the class refused on 2026-08-09. The route to try first needs no hook: the Overlay's own background thread **calls** `GetLatency` with the device of the swap chain it already hooks, once a second (the call returns the last 64 frames' reports). Unknown: whether calling into the driver from that thread is safe on every device kind, what it costs, what it returns when the game never enabled Reflex, and what it means for the Disclaimer's sentence about that thread. | **A spike on `hook-harness` and a stub first, then one real title.** Pre-committed: no route without a patch at a run-time address or a loader-lock call on the game's thread → Reflex stays N/A and the page says why; overhead above NFR-1 → the same. The owner says go or no on the spike's result. **2026-11-12 — the reading that comes before that spike is `spike-notes` §30** (owner decision D130: a document first, beside 0.1.0-beta.45; nothing was run). It finds: a hook on NVAPI's latency functions is the refused class, and a hook on Streamline's Reflex and PCL functions is train D's wrapper (§M15) — and would miss a game that fetched them before the attach, as `slInit` is missed (D129); the Overlay calling `slReflexGetState` itself breaks the thread contract the vendor's header states; **what remains is the route named in this row**, the Overlay calling two driver getters with the game's device, and a no-injection ETW route that gives the game-side markers only and makes the game post messages to its own window. Corrected there: `nvapi64.dll` exports **two** functions on the dev box (`nvapi_Direct_GetMethod` beside `nvapi_QueryInterface`), not one. The go or no is the owner's, and a go needs the owner's ruling that calling a driver getter with the game's device is inside rule 4. **2026-11-13 — the owner answered (D132, D133).** Route D goes to the spike this row names, on `hook-harness` and a stub `nvapi64.dll`, with the ruling: a driver's read-only getter called with the device of the swap chain the Overlay hooks is inside rule 4 (`CLAUDE.md`, the rule's note of that day). No real game before the owner has seen the result, and nothing shipped changes for the spike (`spike-notes` §31, written after 0.1.0-beta.46). Route C is **refused**; the ETW route **stays closed**, and §G is not reopened. |
| M14 ❓ | **Reflex latency per frame — is there a route within rules 4 and 5? (Train C, 2026-11-11.)** `17_HOOK_ENGINE` §Memory / latency names hooks on `NvAPI_D3D_SetSleepMode` / `SetLatencyMarker` and a call to `NvAPI_D3D_GetLatency`. NVAPI resolves all three through `nvapi_QueryInterface` by id — they are not exports, so a hook on them is a patch at an address learned at run time, the class refused on 2026-08-09. The route to try first needs no hook: the Overlay's own background thread **calls** `GetLatency` with the device of the swap chain it already hooks, once a second (the call returns the last 64 frames' reports). Unknown: whether calling into the driver from that thread is safe on every device kind, what it costs, what it returns when the game never enabled Reflex, and what it means for the Disclaimer's sentence about that thread. | **A spike on `hook-harness` and a stub first, then one real title.** Pre-committed: no route without a patch at a run-time address or a loader-lock call on the game's thread → Reflex stays N/A and the page says why; overhead above NFR-1 → the same. The owner says go or no on the spike's result. **2026-11-12 — the reading that comes before that spike is `spike-notes` §30** (owner decision D130: a document first, beside 0.1.0-beta.45; nothing was run). It finds: a hook on NVAPI's latency functions is the refused class, and a hook on Streamline's Reflex and PCL functions is train D's wrapper (§M15) — and would miss a game that fetched them before the attach, as `slInit` is missed (D129); the Overlay calling `slReflexGetState` itself breaks the thread contract the vendor's header states; **what remains is the route named in this row**, the Overlay calling two driver getters with the game's device, and a no-injection ETW route that gives the game-side markers only and makes the game post messages to its own window. Corrected there: `nvapi64.dll` exports **two** functions on the dev box (`nvapi_Direct_GetMethod` beside `nvapi_QueryInterface`), not one. The go or no is the owner's, and a go needs the owner's ruling that calling a driver getter with the game's device is inside rule 4. **2026-11-13 — the owner answered (D132, D133).** Route D goes to the spike this row names, on `hook-harness` and a stub `nvapi64.dll`, with the ruling: a driver's read-only getter called with the device of the swap chain the Overlay hooks is inside rule 4 (`CLAUDE.md`, the rule's note of that day). No real game before the owner has seen the result, and nothing shipped changes for the spike (`spike-notes` §31, written after 0.1.0-beta.46). Route C is **refused**; the ETW route **stays closed**, and §G is not reopened. **2026-11-13 — the harness spike is done (`spike-notes` §31), and none of its stop conditions fired.** With a stand-in module: nothing is called or loaded when `nvapi64.dll` is absent, a missing getter is refused whole, an error and a report of nothing read as what they are, and a call the driver holds for seconds stops only the thread that made it — so not the watchdog. With the installed driver (32.0.16.2114, RTX 5080), in the probe's own process and with the probe setting the markers a game would: no fault before `NvAPI_Initialize`, without markers, or across 38 million reads beside a marker-setting thread; a call costs half a microsecond to a microsecond and a half; the report is readable from markers alone, in microseconds; and the Direct3D 12 **device** — the object the Overlay already holds — is what the driver takes. What only a game can say is unanswered: a game's own device, a real report, another driver. **The owner's next word is go or no for one real title**; a go is a plan of its own first. **2026-11-13, the same evening — go (D136)**: a plan for one title, Cyberpunk 2077; no code before the plan is approved, and no release carrying it before a stop while a game runs has been exercised on 0.1.0-beta.46 (owner-only item 44 (d)). **2026-11-13, the plan and four more answers (D138–D141).** The read has **no switch of its own**: it is part of Advanced metrics, so after the release it reaches every Direct3D 12 game that loaded the driver's `nvapi64.dll`, for everyone who switched Advanced metrics on — "one title" is the order of the owner's first runs, not a limit in code (D138). The probe ran a leg with a sleep mode first (D139; `spike-notes` §31, *The leg with a sleep*): **the getters do not wait behind `NvAPI_D3D_Sleep`** — thirty-one million reads beside a thread that slept 97 % of the time, none of a millisecond; a read after a sleeping frame costs about 2.6 µs. An `nvapi64.dll` loaded from the game's own folder is refused with the reason (D140). One call of 2 ms or more switches the read off until the game exits (D141). The plan's design, as reviewed against the source, is in [`handoff/history/0.1.0-beta.46.md`](handoff/history/0.1.0-beta.46.md) §The train after 0.1.0-beta.46. **2026-11-13, night — written; released as 0.1.0Line truncated
| M15 ❓ | **The Streamline state behind `slGetFeatureFunction` — re-examined, not reopened (Train D, 2026-11-11).** The owner asked for the refusal in `handoff/history/p0-queue-1-6.md` to be looked at again. `18_GPU_VENDOR_APIS` §The trains states the route to try (hook the export, hand back a wrapper for a fixed list of names) and what it raises: the wrapper is a write to what the game receives, which rule 4 forbids as written; a wrapper must outlive the Overlay's unhook; a game that fetched its functions before the hook existed is never seen. | **A written design against each of the five grounds, then a spike.** Pre-committed: any ground unanswered → the route stays refused, and `sl.dlssg.*`, `sl.reflex.*` and the rest of that block read N/A with "refused" as the reason. Proceeding needs the owner's amendment of rule 4, asked with the rule quoted. |
| M10 ✅ | ~~PDH `\GPU Engine(*)\Utilization Percentage` summed across engines does not reproduce the Task Manager figure the doc invokes. Decide what we actually report and label it accordingly~~ **Decided 2026-09-09 (PR-E1): L1 does not read the engine counters at all.** `LoadPct` is L2's vendor-reported `GPU Core` load (measured ✓ on NVIDIA, §M5 row R1) and is labelled *GPU load (vendor)* wherever it is shown; on a machine without L2 the field is N/A, never a sum that is not the number the user expects. What L1 does read from PDH is one counter, `\GPU Adapter Memory(luid_…_phys_0)\Dedicated Usage`, bound by LUID — the figure Task Manager labels "Dedicated GPU memory", measured 1301 MB at an idle desktop on the RTX 5080. Reopening this needs a measurement of `max(engine)` against Task Manager's own number, not a decision |
+269 -149
View File
@@ -84,6 +84,8 @@ owner-only items stay below; the history of every train, the passed owner-only i
| `§beta.42`, what the owner's seven sessions on beta.42 showed (D121 answered, the guard's lost launches), beta.43's design as planned | [`handoff/history/0.1.0-beta.42.md`](handoff/history/0.1.0-beta.42.md) |
| `§beta.43`, what the owner's nine sessions on beta.43 showed, session by session (item 41), the traps of that train | [`handoff/history/0.1.0-beta.43.md`](handoff/history/0.1.0-beta.43.md) |
| `§beta.44`, what the owner's eight sessions on beta.44 showed, session by session (item 42), this release's facts, the traps of that train | [`handoff/history/0.1.0-beta.44.md`](handoff/history/0.1.0-beta.44.md) |
| `§beta.45`, what the owner's seven sessions on beta.45 showed, session by session (item 43), that release's facts and SonarCloud's gate on its commit, the traps of that train | [`handoff/history/0.1.0-beta.45.md`](handoff/history/0.1.0-beta.45.md) |
| `§beta.46`, what the owner's five sessions on beta.46 showed (item 44), the design of the train that followed as the plan's review left it (`§The train after 0.1.0-beta.46`), that release's facts, the traps of that train | [`handoff/history/0.1.0-beta.46.md`](handoff/history/0.1.0-beta.46.md) |
| `§Owner-only`, an open item | [§Owner-only](#owner-only--no-pr-can-close-these) below |
| `§Owner-only`, a passed item (3, 12, 14–19, 38, 39) | [`handoff/owner-only-passed.md`](handoff/owner-only-passed.md) |
| `§Traps`, `§Two corrections carried forward` | [`handoff/traps.md`](handoff/traps.md) |
@@ -91,163 +93,126 @@ owner-only items stay below; the history of every train, the passed owner-only i
---
## **START HERE** — 2026-11-12, 0.1.0-beta.45: six more of Streamline's calls, hooked only where asked; `slInit` stays out; the Reflex spike as a document
## **START HERE** — 2026-11-14, 0.1.0-beta.47: the part inside a game asks NVIDIA's driver for its latency report; the batch log says how a batch ended
*Status is `docs/changelog/0.1.0-beta.45.md`; this is what no other file carries.* The owner ran eight sessions on
beta.44 the evening it was released and said: add the three new ones, update, go on. They were read from a copy of
the ledger and the logs (#426); asked to reopen D112, the owner was shown why `slInit` cannot be seen and chose to
leave it out (D129), chose six other calls for one release (D130), and approved the plan with Privacy Policy 2.19's
wording. Four pull requests and this one: #427 (`slIsFeatureSupported`, `slIsFeatureLoaded`, `slSetFeatureLoaded`
in the Overlay; D129–D131), #428 (`slAllocateResources`, `slFreeResources`, `slShutdown`), #429 (the Agent, the
App, Privacy Policy 2.19), #430 (train C's spike, a document: `spike-notes` §30). **What the eight sessions on
beta.44 showed, session by session, is [`handoff/history/0.1.0-beta.44.md`](handoff/history/0.1.0-beta.44.md)**;
what each pull request built is [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Hook inventory (the two rows of the six
calls, with their measured cost) and [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Train B (the fourth step).
*Status is `docs/changelog/0.1.0-beta.47.md`; this is what no other file carries.* The owner ran five sessions on
beta.46 the evening it was released and said: check and go on. They were read (#439), the owner took six decisions
(D136–D141) and approved the plan of the train the same evening, and the five pull requests of it were merged
overnight: #440 (the decisions; the probe's leg with a sleep mode), #441 (D137), #442 (the latency words of region
5), #443 (the Overlay makes the read; the gates; the fixtures), #444 (the Agent, the App, the legal texts,
owner-only item 45). The release was held for item 44 (d), which the owner ran on 2026-11-14 (#445, and below).
**What the five sessions showed, the design of the train as the plan's review left it, and the traps of beta.46
are [`handoff/history/0.1.0-beta.46.md`](handoff/history/0.1.0-beta.46.md)**; what the read is and what bounds it
is [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Calls the Overlay makes into a driver; what was measured is
[`spike-notes/31-reflex-route-d-harness.md`](spike-notes/31-reflex-route-d-harness.md).
### What this release decided, beyond D129–D131
### What this release decided, beyond D136–D141
- **Everything the six calls give is word 1 of a feature's slot, and one reserved word.** Bits 2–4 the two answers
(supported, with the `sl::Result` in bits 8..15; loaded and its value), bits 5–6 the game switching the feature
off and on, bits 16..19 and 20..23 two counts that stop at fifteen and never carry; `slShutdowns` took the first
of three reserved words (@308). Layout 5 and schema 23 as they were. **The answers are the process's and a new
request keeps them; the switching, the counts and the shutdowns are a session's and a new request clears them.**
- **A refusal is the answer.** `slIsFeatureSupported`'s detour calls the original first and keeps whatever it
returned; the page names it by NVIDIA's enumerator (forty codes, the same order at sixteen upstream tags from
v2.0.0 to v2.14.16), `result <n>` past the list, 255 for a code a byte could not carry.
- **The two calls on a game's way out note the call, then call the original, and run nothing after it** —
`slFreeResources` and `slShutdown`. The fixture shuts Streamline down and goes on using the stub through every
detour.
- **The adapter is never read** (D131), and the build refuses the names of `sl::AdapterInfo`'s members in the code
loaded into a game (`overlay-fields-check`); the fixture hands a wild LUID pointer.
- **A stop restores its patches one after another, about 160 ms each.** MinHook stops every thread of the process
for each `MH_DisableHook`. With six more patches the stop's last log lines were cut at the two seconds the
Overlay waited for them; the wait is now sized to the patch table (`250 ms × kMaxPatches`). The patches were
always restored; `UNHOOKED` is written after the last. **Not changed, and proposed**: queueing the restores (and
the installs) so the threads are stopped once — a change to the hook engine's order of operations, which wants
its own pull request, its own measurement and the owner's word. Until then a stop in a Streamline game with
Advanced metrics on takes two to three seconds on the thread that stops.
- **Six calls are one sentence on the page**, each by its function's name under which of three things became of
it; a row stored before this release has none of the six and no such sentence.
- **`AdvancedReach.BeforeAttach` is a reason of its own** for `sl.init.preferences`: not "a later release". No
catalog entry carries `NewHook` any more; the value stays, for rows a later train may add.
- **Where the rows sit in the table** (rows are patched in its order): the two questions after beta.44's two, at
the head; `slSetFeatureLoaded` after `slSetConstants`; the three counted calls last of the Streamline block.
- **Train C's spike is a reading** (`spike-notes` §30): hooking NVAPI's or Streamline's latency functions is
refused or is train D's wrapper; the Overlay calling `slReflexGetState` breaks the vendor's thread contract;
what remains is the Overlay calling two driver getters with the game's device, and a no-injection ETW route
that gives half the number. It ends in three questions that are the owner's.
- **It is the first thing the Overlay does in a game that is not reading a hooked call's arguments**, and it is
listed as that — its own table in `17_HOOK_ENGINE`, its own reach in the catalog (`GameDriver`, not a stretched
`Game`), its own paragraph in the Disclaimer. A second call of this kind needs a ruling of the same kind (D132).
- **Resolve on the watchdog, once for the process; call on the presenting thread, after the record is published,
behind one gate of four states** — idle, armed, reading, off. The plan's first draft had a busy flag beside
accumulators: two presenting threads could have read back to back, and the watchdog could have published half a
read. The whole design as reviewed is in the history file, §The train after 0.1.0-beta.46.
- **`nvapi64.dll` is a shim.** The check that the two addresses lie inside the module it asked refused the real
driver: the getters are in `nvapi64_impl.dll`, in the driver's store. An address is accepted when it is executable
code of a loaded image, and a reference is kept on that image too. Only the run against the installed driver
could find it — the stand-in answers with addresses of its own.
- **The code that is called is a Control Flow Guard image**; the plan's review had reasoned from the shim, which is
not. The probe enforces CFG and makes the calls from the header that ships, so this driver's getters are valid
targets. A CFG-enforcing game on another driver is not covered, and a refusal there is a fast-fail.
- **The layout stayed 5**: ten reserved words of region 5 took the read. `FL_HOOK_REFLEX`, `FL_MEASURED_LATENCY`
and `reflexLatencyUs` stay unset — there is no hook, and the numbers are series beside the frames.
- **D141 was asked twice.** A run on a busy PC showed the 2 ms latch can fire on a pause that was Windows'; the
owner kept one call. Do not re-ask without a real game's numbers.
- **What the game asked of Reflex, and Reflex through Streamline, are `RefusedRoute`** — a patch at a run-time
address, and a call the vendor forbids from another thread (D133). `sl.pcl.markers` waits for train D's spike.
### What item 44's last part showed (2026-11-14)
- **A first try did not exercise it** (sessions 203–205, #445): *Disable all hooking* was on before the games were
started, so two sessions were `RefusedKillSwitch` with nothing injected, and the hooked one ran to its exit.
- **The second try did, twice, in Phantom Blade Zero** (sessions 206 and 207): the game started with the switch
off, was recorded for a minute and a half, and the switch was turned on while it ran. Each log has `STOP` at the
next safety scan, **an `UNHOOK_RESTORED` line for every one of the twenty-nine patches, all at one time**, one
`PATCH_BATCH restore` — **83 309 µs and 85 578 µs for twenty-nine** — and `STOP_FLUSHED … a=1`. Nothing was
declined. Both sessions ended `KillSwitchEngaged`, tier 1, no fault, no record dropped, writer status
*unhooked*; the game ran on for three and four minutes and closed with nothing in Windows' application log.
Restoring twenty-nine one by one would have cost about 2.4 s at this game's 84 ms a stop.
- **Not said by the logs**: whether the owner felt a hitch at the stop. Not exercised: (e) a game with no
Streamline and (g) off means off — both are parts of item 45 now.
### Traps this train left
- **The catalog table of `18_GPU_VENDOR_APIS` is compared with the catalog row for row by a test**: a catalog
entry and its row go in the same commit, or the Application tests are red.
- **Qodana's native report again found an index into the feature slots computed as a 32-bit product** (#427, the
harness's probe): write `size_t{2} * FL_ADV_FEATURE_WORDS`. It is advisory and auto-merge does not wait for it;
both reports were read before each merge.
- **A second `region` inside the probe's block is C4456**, and warnings are errors: name the inner one otherwise.
- **A test method over sixty lines is MA0051** in the test projects too; split the assertions by what they cover.
- **The injected test waits for the stop**: with eighteen patches a stop takes about three seconds, so its wait is
200 iterations.
- **The shell tool refuses `sleep N; command`**: wait in a background `until` loop.
- **After a lower pull request is squashed**, `git diff <old tip> origin/main` empty proves the squash is the
branch; then `git rebase --onto origin/main <old tip> <next branch>` and a forced push with lease.
### What the owner's seven sessions on beta.45 showed (2026-11-13)
The owner ran seven sessions on six games the day after the release and said: check the logs and go on. Read from
a copy of the ledger (sessions 190–196), the seven overlay logs, the Agent's log and Windows' application log —
no FrameLedger binary was run against the owner's data. **Every session is hooked, `normal`, with no fault
counted, no dropped record and no `PATCH_FAILED`; the count of early ends is 0 on all six games.** The update
showed the terms once: Privacy Policy 2.19 was accepted at 07:23:36.
| Game (session, length) | Interposer | `slIsFeatureSupported` | `slIsFeatureLoaded` | `slSetFeatureLoaded` | allocate | free | shutdown |
|---|---|---|---|---|---|---|---|
| Phantom Blade Zero (190, 2 h 48 min; 191, 1 h 32 min) | 2.14.1 | **read** — Reflex, DLSS frame generation, PCL `eOk`; ImGUI and DeepDVC `eErrorFeatureMissing` | **read** — Reflex, frame generation *on* | not called | not called | **read** — frame generation, 1 | not called |
| Cyberpunk 2077 (193, 7 min) | 2.14.1 | **read** — frame generation, DLSS, ray reconstruction, Reflex `eOk`; NIS `eErrorFeatureMissing` | **read** — the four *on* | **read** — the four, *on and off* | not called | not called | not called |
| Dying Light: The Beast (194, 4 min) | 2.8.0 | **read** — DLSS, frame generation, PCL, Reflex, NIS `eOk` | not called | **read** — all five, *on and off* | not called | not called | **read** — 1 |
| Hogwarts Legacy (195, 4 min) | 2.14.16 | **read** — frame generation, Reflex, DeepDVC, DLSS 5's `kFeatureDLSS_NR`, PCL `eOk`; ImGUI `eErrorFeatureMissing` | **read** — the first four *on* | not called | not called | not called | not called |
| Black Myth: Wukong (196, 3 min) | 2.7.4 | **read** — frame generation, Reflex, PCL `eOk` | not called | not called | not called | not called | not called |
| Kingdom Come: Deliverance II (192, 4 min) | none | not hooked | not hooked | not hooked | not hooked | not hooked | not hooked |
- **`slIsFeatureSupported` was read in every Streamline session, and `slAllocateResources` in none.** Item 43
wrote the meaning of that before the run: a call no game makes after the attach gives nothing in attach mode, and
whether it keeps its patch is the owner's to say. `slFreeResources` and `slShutdown` were each read once, in one
game each; `slIsFeatureLoaded` in three games, `slSetFeatureLoaded` in two.
- **A refusal reads as one.** Phantom Blade Zero and Hogwarts Legacy ask about `kFeatureImGUI`, Streamline's
debug overlay, and are told it is missing; Cyberpunk 2077 is told the same of NIS, which Dying Light is told is
supported. Phantom Blade Zero is told DeepDVC is missing although Streamline answered its requirements.
- **The count says how often, not when.** Dying Light's one shutdown and Phantom Blade Zero's one freeing of frame
generation's resources may each be the game closing; nothing in a session says. Dying Light switched all five
features off and on.
- **The way out is as it was.** Hogwarts Legacy faulted at its exit in `_nvngx.dll`, `0xc0000005` at offset
`0x6aa85` — the offset of its six before, since 2026-11-06, hooked or not — and Black Myth: Wukong in
Steam's `crashhandler64.dll`, `0xc0000409` at `0x39b49`, the offset of its three before (Steam's file is now
11.23.65.88). Windows' log has no fault for the other four games; the two hooks on a game's way out were in all
five Streamline games.
- **Rates are where they were**, for what a comparison without the same scene is worth: Phantom Blade Zero ×4 at
64 → 255 (beta.44: 63 → 251), Wukong 85 → 341 (90 → 361), Cyberpunk 2077 164 → 327 (137 → 275), Dying Light ×4
at 48 → 194 (beta.42: 54 → 216), Kingdom Come 58.8 presented (59.3).
- **An install stops the game's threads once a patch, as a restore does.** The thirteen interposer patches took
0.74 s on Phantom Blade Zero, 1.2 s on Cyberpunk 2077, 1.7 s on Dying Light and Wukong (twelve there) and
**2.8 s on Hogwarts Legacy** — 57 to 215 ms a patch, while the game starts. That is the cost the proposal to
queue patches (§What this release decided) would cut, measured on real games.
- **No stop was exercised.** Every session ended with the game closing, so no log has an `UNHOOK_RESTORED` line.
Item 43 (g) said a log "ends with an `UNHOOK_RESTORED` line for each patch": that is true only of a session
stopped while its game runs, and the item was worded wrongly.
- **Not exercised: off means off** — Advanced metrics was on in every session. **Not visible in the data**: (c), whether *loaded* agrees with the game's own menu, and (h), the
catalog's wording on the page — both are what the owner sees.
- **For train C's spike**: Streamline says Reflex is supported in all five games and loaded in the three that
ask; Cyberpunk 2077 and Dying Light switch it off and on (`spike-notes` §30 has the note).
- **A bash here-document ate backslashes again** and wrote a NUL byte into a `.cpp`. Edit scripts are files.
- **A file made by the Write tool is LF**; `dotnet format --verify-no-changes` fails a new `.cs` for it. Convert.
- **`NvAPI_Status(__cdecl*)(…)` is a call by name to `nvapi-readonly-check`**: the status type has an alias in
`fl_reflex.h`. And a member of the Overlay's own named like a vendor's (`fgMultiplier`) fails
`overlay-fields-check` outside the header.
- **A copy of the harness in `%TEMP%` leaves an overlay log the run's sweep does not own** (it matches this
build's harness by path): the test that makes the copy sweeps it.
- **Stacked pull requests, with a dirty tree**: once the lower one is squash-merged GitHub retargets the next to
`main`; `gh pr update-branch` works while the upper branch only adds, and conflicts once it edited lines the
lower one added — then `git rebase -S --onto origin/main <lower tip> <branch>` and a forced push with lease.
- **Advisory checks found real things after the local gate was green**: SonarCloud a `wcslen`, Qodana's native
report a `switch` that did not name two enumerators, its managed report two redundant qualifiers and a
redundant `!`. Hold a merge until both have reported.
- **The probe's numbers depend on what else the PC does**: a run beside a build read 3.4 µs where three alone read
2.6, and saw reads of 2 ms. Say which kind a number is.
### NEXT
1. ~~**The owner runs item 43**~~ **Run and read 2026-11-13** (§What the owner's seven sessions on beta.45
showed): five of the six calls read in real games, nothing different on the way out, no fault. *Off means off*
was not exercised, and `slAllocateResources` was called by no game.
2. ~~**The owner reads `spike-notes` §30 and answers its three questions.**~~ **Answered 2026-11-13 (D132,
D133)**: route D goes to a spike on `hook-harness` and a stub — the owner ruled that a driver's read-only getter
called with the device of the hooked swap chain is inside rule 4 — and no real game is touched before the owner
has seen its result (`spike-notes` §31, to be written after 0.1.0-beta.46 is tagged); route C is refused; the
ETW route stays closed. No shipped code changes for the spike.
3. ~~**The stop's cost** (above): whether to batch the restores is the owner's to say.~~ **Decided 2026-11-13
(D134): batch them, installs too** — a pull request of its own, measured on the harness, released alone as
**0.1.0-beta.46**. The plan was reviewed against MinHook's source before it was approved: `MH_ApplyQueued`
applies every entry whose queued state differs, not only the caller's, so the queue-to-apply sequence is
serialised, only targets that are still ours are ever queued for a restore, and nothing is queued "for all".
4. **`slAllocateResources` keeps its patch** (D135); looked at again with more sessions.
5. **Train D** after train C, the same way: a spike first.
1. ~~**The owner runs item 45**~~ **Run on 2026-11-14 in Phantom Blade Zero, three sessions: the read works in a
real game** (item 45's last paragraphs) — the driver was found, read every second, and no call took more than
45 µs. **Cyberpunk 2077 followed the same morning, twice, and three games the read must leave alone** (sessions
211–215): read, 65 µs at the slowest, and *not read* where it should be. **Still to run of it**: Reflex off in
a game's menu, off means off; and the owner's word on whether the games felt different.
2. **The owner answered on the *GPU render* line (2026-11-14): read the driver's active time.** Two more members
of the report FrameLedger already fetches — no further call into the driver. ~~**Plan first**~~ **Planned and
approved the same day as the train of 0.1.0-beta.48 (D142–D147)**: the native half first, then the Agent, the
App and the texts, then the sampling period, then the release and owner-only item 46 — one batch of tests for
the owner, with what is left of item 45 in it. What the plan gathered: the multiplier row that keeps only the last value, the pages that still say no real game
was read, the Agent's 1.32 s between samples beside `hz` 1.0. The owner tests what is left once, on that
release. Still the owner's to say: more titles; the session summary's latency fields; D141 (the slowest call
seen in a game is 65 µs, thirty times under it).
3. **`slAllocateResources`** keeps its patch (D135); looked at again when there are more sessions.
4. **Train D** after train C, the same way: a spike first — `sl.pcl.markers` waits for it, and §30 found its hook
would miss a game that fetched its functions before the attach.
### Left open by this session
- ~~**This release's own facts** — the tag's run, the digests, the delta — are not in any file yet: the release is cut
after this text. Record them in the next pull request, with what SonarCloud and Qodana said.~~ **Recorded
2026-11-12: 0.1.0-beta.45 was released 2026-11-12T16:40:42Z** (23:40 in the owner's time zone) from the signed
tag on `550d830` (#431), by run 43257803723 — green at the first attempt, one run for the one tag push. Eight
2026-11-14: 0.1.0-beta.47 was released 2026-11-14T01:11:19Z** (08:11 in the owner's time zone) from the signed
tag on `3d7c273` (#446), by run 43537436561 — green at the first attempt, one run for the one tag push. Eight
assets; the seven digests of `SHA256SUMS.txt` equal the ones GitHub computed; the four shipped natives carry
`FL_BUILD_ID v0.1.0-beta.45`. The delta from beta.44 is 1,762,465 bytes beside a full package of 110,767,499 —
"Delta processed 0452 files. 0024 patched, 0428 unchanged". The wiki was published by run 43261335359. The
rehearsal on the release branch (run 43253780609, at `f4e3fe2`, the released tree) had made a delta of 1,779,418
bytes with the same file counts. **Qodana's two reports are green on `550d830`.** On the way Qodana's native
report found two index products in the harness's probe (#427), fixed before that pull request merged; every
later report was clean, and each was read before its merge. No required check failed on this train.
**SonarCloud's quality gate failed on `550d830`, on one condition: duplicated lines on new code, 3.7 % where the
gate allows 3 %.** No issue is open and coverage on new code is 98.6 %. The 39 lines are the six new members of
`FlHookFamily` (`ShmLayout.cs`) and of its Domain mirror `HookFamilies` — two enums that are the same on purpose
(Domain references nothing, and `MetricEnumMirrorTests` fails when they differ), which six members at once took
over a threshold that two at a time had stayed under. The job is advisory and the release was already cut. The
pull request that records this leaves the Domain's mirror out of duplication detection, with the reason in
`SonarQube.Analysis.xml` and in `13_CI_CD` §SonarCloud; **whether the gate is green again is for the analysis of
that commit on `main` to say**, and it is not in this text. *(It said so the same night: green on `d3e8dd3`,
duplicated lines on new code 0.0 %, no issue open.)* One more thing the train showed: main's branch
protection wants a pull request up to date, so of two that were green at once the second (#430) had to be
rebased after the first merged, and ran its checks again.
- ~~**No real game was run on this build.** Six new patch sites, tested with the harness and the stub; their cost
measured on the headers.~~ **Seven sessions on six games, 2026-11-13** (§What the owner's seven sessions on
beta.45 showed). The published release notes say the six calls "have not been run in a real game"; a released
file is not edited.
- **`slAllocateResources` has a patch no game has used**: not called after the attach in any of six sessions on
five games. ~~Whether it stays is the owner's.~~ It stays for now (D135, 2026-11-13).
- **Off means off (item 42 (f)) has never been exercised on a real game**; it is item 43 (f) now, for all ten.
`FL_BUILD_ID v0.1.0-beta.47`. The delta from beta.46 is 1 820 144 bytes beside a full package of 110 795 507 —
"Delta processed 0452 files. 0024 patched, 0428 unchanged". The wiki was published by run 43539059710. The
rehearsal on the release branch (run 43534606602, at `43426fe`, the released tree) had made a delta of 1 838 295
bytes with the same file counts. **SonarCloud answered on `3d7c273`: the quality gate passed and no issue is open
on `main`. Qodana's two reports, CodeQL and `check` are green on that commit.** On the way the advisory checks
found three things after local gates were green (§Traps), and no required check failed.
- **The release branch's local gate was red once, for a reason outside the code** (2026-11-14 07:20): the freshly
linked `fl_guard_test.exe` was gone from the build tree seconds after the gate began — Windows Defender's log has
three configuration changes at 07:20:53–56 and no detection; which security program removed the file is not
known, and nothing of its settings was looked at further or touched. `fl_guard` ended after 0.72 s **and was
counted as failed, not passed**: the rule of #438 (a native test names the line it ends on) did what it was
written for. Run again, the gate was green.
- ~~**No real game has run the read.**~~ Two have (Phantom Blade Zero and Cyberpunk 2077, 2026-11-14). **The accuracy
statement, `LIMITATIONS.md` and the guide still say no real game had been read**: true when written, to be
brought up to date with the next release, as beta.46's pages were.
- **In Phantom Blade Zero the driver's *GPU render* span is longer than its total** (item 45): shown as reported,
not explained. In Cyberpunk 2077 it is not. The owner's answer: read the driver's active time (NEXT 2).
- **The Agent's samples are 1.32 s apart while `sensor_blobs.hz` says 1.0** (seen 2026-11-14 in the `t_ms` series,
in sessions back to beta.42). Not looked into: whether anything reads `hz` as the spacing.
- **No test runs the whole path through the real Agent**: the injected tests stop at the shared memory and the
sampler's start from it; no end-to-end case loads the stand-in module under an Agent session.
- **Two install batches of beta.46 took 0.61 s and 1.26 s and nothing explains them** (Hogwarts Legacy, Cyberpunk
2077). Since this release the log says whether a batch went singly; the next long one can be read.
- **The Japanese strings are new and unreviewed**, as every `ja` string is.
- **Off means off has never been exercised on a real game** (item 43 (f), item 44 (g), now item 45 (g)); nor (c)
and (h) of item 43, which only the owner sees.
- **Valor Mortis's crash at 51 s** (twice, beta.40 and beta.44) **and Black Myth: Wukong's fault in Steam's crash
handler at every exit** are not explained. One session of each with hooking off is the comparison that is missing.
- **What item 41 left unexercised**: a configure through the FidelityFX 2.3 loader (Cyberpunk 2077 with FSR frame
@@ -255,13 +220,12 @@ showed the terms once: Privacy Policy 2.19 was accepted at 07:23:36.
- **A fault while a game is closing is not seen by a hooked session** (D127: written down, not changed).
- **`docs/LIST_GAME_TESTED.md` is as of 2026-11-06**: refreshing it is a new copy of the ledger and the owner's review.
- **Item 40 (d)** was not exercised and the owner has not said item 40 passed. **Items 36 (d) and 37 are still open.**
- **What an empty process snapshot does to the watcher's tick in a real session** was not looked into (seen once in
a test on 2026-11-12).
- **`LIMITATIONS.md` and the accuracy statement still say the processor's, the memory's and the motherboard's
sensors "have never been read on real hardware"** — the owner's to reword. The alpha line still rests (D98).
**Owner-only:** item 43; the three questions of `spike-notes` §30; one session each of Valor Mortis and Black
Myth: Wukong with hooking off; what item 41 left unexercised; item 40 (d).
**Owner-only:** what is left of item 45 (Reflex off in a game's menu; off means off; how it felt); one session
each of Valor Mortis and Black Myth: Wukong with hooking off; what item 41 left unexercised;
item 40 (d).
## Owner-only — no PR can close these
@@ -705,8 +669,8 @@ Myth: Wukong with hooking off; what item 41 left unexercised; item 40 (d).
starting the game afresh runs it without any of the ten hooks, and if that cures it the hook is one of the
six new ones or the four before — the overlay log's last `HOOK_INSTALLED` lines and Windows' fault entry say
which is nearer. A game that will not start at all: *Disable all hooking* (Settings ▸ Capture).
**Seven sessions were run on 2026-11-13 and read the same day** (START HERE §What the owner's seven sessions on
beta.45 showed): (a) happened — Privacy Policy 2.19 accepted once; (b) five Streamline games, six sessions —
**Seven sessions were run on 2026-11-13 and read the same day** ([`handoff/history/0.1.0-beta.45.md`](handoff/history/0.1.0-beta.45.md) §What the owner's
seven sessions on beta.45 showed): (a) happened — Privacy Policy 2.19 accepted once; (b) five Streamline games, six sessions —
`slIsFeatureSupported` read in all, `slIsFeatureLoaded` in three games, `slSetFeatureLoaded` in two,
`slFreeResources` and `slShutdown` once in one game each, **`slAllocateResources` in none**; (d) held on Kingdom
Come: Deliverance II; (e) **nothing different**: Hogwarts Legacy and Black Myth: Wukong fault while closing in
@@ -715,6 +679,150 @@ Myth: Wukong with hooking off; what item 41 left unexercised; item 40 (d).
`UNHOOK_RESTORED` lines was not exercised and was worded wrongly. **(f) was not exercised; (c) and (h) are the
owner's to say.** Taken as passed on the owner's "check the logs and go on", 2026-11-13; (f) stays open.
`slAllocateResources` keeps its patch (D135, the same day).
44. **beta.46 — hooks in and out under one stop of the threads, in real games** (D134). **Not first on a game under
the user-mode exception's trial** (D38): a crash there ends the exception for good. (a) **The update from
beta.45**: Help ▸ Check for updates, *Restart to update* with no game running; **the terms window does not
show** (nothing new is read). (b) **Any Streamline game with Advanced metrics on** (Hogwarts Legacy first — its
thirteen patches took 2.8 s on beta.45 — then Phantom Blade Zero, Cyberpunk 2077, Dying Light: The Beast, Black
Myth: Wukong): play as usual and close the game. Its `logs\overlay-<pid>-….log` has `PATCH_BATCH install`
lines, and the `sl.interposer.dll` `HOOK_INSTALLED` lines above each carry **the same time** to the thousandth
of a second, not times 0.06–0.2 s apart. Say the `a=` of each `PATCH_BATCH` line: it is the microseconds the
game's threads were stopped for that batch. (c) **How the game's start feels**: no worse than on beta.45 — the
hitching while a game with Streamline starts should, if anything, be shorter. (d) **A stop while the game
runs**, which no session has exercised since beta.43: with a game running and being recorded, switch *Disable
all hooking* on in Settings ▸ Capture; the part inside the game stops at its next safety scan, within 30
seconds. The game must go on running without a freeze of seconds; the log then has `STOP`, an `UNHOOK_RESTORED`
line for every patch, one `PATCH_BATCH restore` line and `STOP_FLUSHED … a=1`. Switch it back off afterwards. (e) **A game with no
Streamline** (Kingdom Come: Deliverance II, Lies of P): its FSR rows are under `PATCH_BATCH` lines as well, and
the session reads as before. (f) **Nothing else moved**: no crash, no `PATCH_FAILED`, no `UNHOOK_DECLINED`
unless another overlay is running, the same hooks in `HOOK_INSTALLED` as on beta.45 for the same game, frame
rates and the frame-generation factor as before, the Advanced rows as before. (g) **Off means off** (item 43
(f), never run): with Advanced metrics off, start a game afresh; no `HOOK_INSTALLED` line names any of the ten
Advanced-only calls.
**What each outcome means, written before the run.** A `PATCH_BATCH install` whose `a=` is about what one
patch cost on beta.45 (60 000–220 000) is the expected answer: one stop of the threads. An `a=` of a second or
more: one stop is long in that game — say which game and the number; it is still one where there were thirteen,
but it is what would decide whether batches need a ceiling. `HOOK_INSTALLED` lines of one batch with different
times: the batch fell back to one patch at a time — the log then also has a `PATCH_FAILED` — say so with the
log. A game that hitches at its start as it did not on beta.45, or freezes at (d): say so at once, with the
game; 0.1.0-beta.45 is the build without this change. A hook that was in on beta.45 and is not on beta.46
(compare the `HOOK_INSTALLED` lines), or a session that reads *not hooked* where it read *read*: the batch lost
a patch — the log's `PATCH_FAILED` line names it and why. A crash in play or at exit that is new: say so at
once; *Disable all hooking* runs the game with nothing patched after the start.
**Five sessions were run on 2026-11-13 and read the same day** ([`handoff/history/0.1.0-beta.46.md`](handoff/history/0.1.0-beta.46.md)
§What the owner's five sessions on beta.46 showed): (a) held — the terms window did not show; (b) five Streamline games — every batch's lines carry one
time; `a=` is 81 417–261 920 for sixteen of the eighteen batches, **1 260 835 for Hogwarts Legacy's thirteen
and 608 700 for three of Cyberpunk 2077's**, neither explained — and the sentence above about a fallback is
wrong: a batch finished one patch at a time leaves no line unless a patch fails for good, so the log cannot say
which of the two a long `a=` was; (f) held — no crash in play, no `PATCH_FAILED`, no `UNHOOK_DECLINED`, the
same hooks as on beta.45, rates and factor as before, the two known faults on the way out at their old offsets.
**(d), (e) and (g) were not exercised; (c) is the owner's to say.** Not passed: (d) is the half of this release
that no real game has run.
**2026-11-14, three more sessions (203–205), read the same morning — (d) is still not exercised.** *Disable all
hooking* was switched on **before** the games were started, not while one was being recorded: Cyberpunk 2077
(06:34) and Phantom Blade Zero (06:38) were each recorded as `RefusedKillSwitch` — tier 2, nothing injected, no
overlay log for either process, which is FR-2.4 doing what it says and not what (d) asks. With the switch off
again, Phantom Blade Zero (06:46, 518 s) was hooked from its start to its exit: twenty-two patches under one
batch of 84 ms and ray tracing's two under one of 81 ms, ×3.0 at 89 → 268, no fault, a clean exit — and **no
`STOP`, no `UNHOOK_RESTORED`, no `PATCH_BATCH restore` line**, because nothing stopped it while it ran. Windows'
application log has no fault since 06:30. **How (d) is run**: start the game with the switch **off** and wait
until FrameLedger shows it recording; **then**, with the game still running, switch *Disable all hooking* on;
play on for half a minute; switch it off; close the game.
**2026-11-14, the second try (sessions 206 and 207, Phantom Blade Zero): (d) held, twice.** The game started with
the switch off and was being recorded; the switch was turned on while it ran. Each log has `STOP` at the next
safety scan, an `UNHOOK_RESTORED` line for every one of the twenty-nine patches at one time, one `PATCH_BATCH
restore` — `a=83309` and `a=85578`, `b=0x1d` — and `STOP_FLUSHED … a=1`; no `UNHOOK_DECLINED`. Both sessions
ended `KillSwitchEngaged`, tier 1, no fault, nothing dropped; the game ran on for three and four minutes and
closed with nothing in Windows' application log. Whether a hitch was felt at the stop is the owner's to say.
**Taken as passed for what 0.1.0-beta.47 was held on** — (a), (b), (d), (f). **(e) and (g) were never run**: they
are (f) and (g) of item 45.
45. **beta.47 — NVIDIA's latency report, read inside a game** (D132, D136, D138–D141). **Cyberpunk 2077 first**
(D136), **and not first on a game under the user-mode exception's trial** (D38): a crash there ends the exception for good.
This is the first release in which the part inside a game *makes a call of its own* — into the graphics driver,
about once a second, on the game's presenting thread — so read (a) before (b). (a) **The update**: Help ▸ Check
for updates, *Restart to update* with no game running; **the terms window shows once, with Privacy Policy 2.20
and Disclaimer 2.16** — the Disclaimer's §2 has a new paragraph, *One call it makes itself, into the graphics
driver*. Settings ▸ *Advanced metrics* says the same in its description. (b) **Cyberpunk 2077, Advanced metrics
on, frame generation OFF, Reflex on in the game's menu**, five minutes of play, then close the game as usual.
Its `logs\overlay-<pid>-….log` has `LATENCY` lines: *reading the driver's latency report*, and two more with
the end of two paths — `…\System32\nvapi64.dll` and `…\nvapi64_impl.dll`. On the Advanced page, the session
has a group **Latency**: the table *What the driver's low-latency state is* (five rows by NVIDIA's names, and
`fgMultiplier`) and, in the chart's list, *Latency per frame* with seven lines. The line under the session ends
with *NVIDIA's latency report, which FrameLedger asks the graphics driver for inside the game: read.* Say the
*total* line's usual value, and **whether the game felt any different with the option on** — a hitch once a
second is the thing to look for. (c) **The same with frame generation ON** (DLSS ×2 or more): the driver's
pacer is another thread, and this is the arrangement the probe could not make. (d) **Reflex switched off in the
game's menu**, if the game lets you: say what the line reads — *read* or *asked, and the driver reported no
frame*; both are possible and neither is wrong. (e) **Only after (b) and (c) are clean, a second game** that
uses Reflex through Streamline (Phantom Blade Zero, Clair Obscur, Black Myth: Wukong, Hogwarts Legacy). (f) **A
game that is not Direct3D 12 or has no NVIDIA library** (Kingdom Come: Deliverance II, Lies of P): the line
reads *not read*, with which of the two. (g) **Off means off**: with Advanced metrics off, start a game afresh;
its log has no `LATENCY` line. (h) **Nothing else moved**: no fault counted, frame rates and the
frame-generation factor as before, the game closes as it did.
**What each outcome means, written before the run.** *Read*, with a total of a few to a few tens of
milliseconds that moves with the frame rate: route D works in a real game; what comes next — more titles, the
session summary — is the owner's to say. *Asked, and the driver reported no frame* in a game whose Reflex is
on: the driver has a report for another object than the device FrameLedger holds; nothing is harmed, and the
title is not readable this way. *Not read — the game has not loaded nvapi64.dll* in Cyberpunk 2077: what its
files said did not happen at run time; another title is tried. *Stopped — a call took N µs*: **one call of a few
thousand microseconds, once, is most likely a pause of the game's thread on a busy PC** (`spike-notes` §31, *A
run on a busy PC*) — start the game again and see whether it repeats; if it repeats, or N is ten thousand or
more, the driver holds the call in that game and **route D stops for it** — say so with the number. *Stopped — a
call into the driver faulted*, or a fault counted in the session: **route D stops** (the commitment of §30) —
say so at once, with the log. **A game that freezes** with a `LATENCY` line saying a call has not returned, or
that freezes at all with the option on and not with it off: close it, say so at once; Advanced metrics off is
the way to play it, and route D ends. **A hitch once a second** with the option on that is not there with it
off: say so at once — the two-millisecond latch did not catch what a player can feel. **The game closing by
itself a second or two after it starts, only with the option on** (Windows' Application log: exception
`0xc0000409`): a Control Flow Guard refusal of the call — say so at once with the entry; that game enforces
what the probe could only check for this driver. Spans that make no sense — a part larger than the total, a
line that is always zero: say which; they are the driver's numbers and are shown as it reported them.
**Three sessions were run on 2026-11-14 and read the same morning — in Phantom Blade Zero, not Cyberpunk 2077**
(sessions 208–210, Direct3D 12, Streamline 2.14.1). **The read works in a real game.** (a) held: the terms were
accepted once, Disclaimer 2.16 and Privacy Policy 2.20. In all three the overlay log has `LATENCY … reading the
driver's latency report` four to five seconds after the attach, with `C:\WINDOWS\SYSTEM32\nvapi64.dll` and
`…\nvapi64_impl.dll` on the two lines after it, and **no later `LATENCY` line**: no error, no slow call, no
fault, no stall. Each session's line reads *read*, and the slowest call into the driver was **24, 20 and 45 µs**.
Frame generation on: session 208, ×3.0 at 85 → 256 — and the driver's own `fgMultiplier` read 3. Off: sessions
209 and 210, multiplier 1. Seven series in each, 227 / 24 / 823 points: 90 %, 62 % and 98 % of the Agent's own
once-a-second samples (the short session spent its first seconds before the module was found). With frame
generation ×3: total 23.4 ms, simulation 4.4, render submit 10.3, present 0.7, driver 10.9, OS queue 13.0, GPU
render 11.5 (means). The driver's switches: `bLowLatencyMode`, `bUseGameSleep` and `bFullscreenIFlip` *on at
times, off at others*; `bFsVrr` and `bCplVsyncOn` *off* — so in a game the low-latency switch does read on,
which it never did for the probe. No fault counted, nothing dropped, a normal exit each time, nothing about the
game in Windows' application log; rates as on beta.46 for the same game.
**One outcome the list above names: a part larger than the total.** *GPU render* reads 16.4 ms where the *total*
reads 5.4 ms (session 209), and about equals it in session 210 (16.0 against 15.9 ms). The span is the driver's
`gpuRenderStartTime` to `gpuRenderEndTime`, and in this game that start lies **before** the frame's own
simulation start: it reads like the time between two frames' GPU ends, idle time included — a reading, not a
fact; the driver has a field of its own for the active time (`gpuActiveRenderTimeUs`), which FrameLedger does
not read. It is shown as the driver reported it. The spans also overlap — render submit, driver and OS queue
together are longer than the total — so they are not parts that add up, and the page does not say they are.
**Not run**: Cyberpunk 2077, which (b) and (c) name; (d) Reflex off in the game's menu; (f) a game that is not
Direct3D 12 or has no NVIDIA library; (g) off means off. **Not said**: whether the game felt any different with
the option on. Not passed as written; what the three sessions were run for is answered.
**Five more sessions the same morning (211–215), read at 09:15: Cyberpunk 2077 twice, and three games the
read must leave alone.** (b), (c) **Cyberpunk 2077** (Streamline 2.14.1, DLSS): session 211 with frame
generation ×2.0 for 42 % of it (166 → 330) and menus for the rest, session 212 without, at 238 FPS. The module
was found 4.8 s and 2.6 s after the attach, in the same two files; each session's line reads *read*; **the
slowest call took 34 and 65 µs**; no later `LATENCY` line. 190 of 195 and 429 of 438 samples carry a report.
The total: 13.5 ms while frames were generated, 4.1 ms in the menus, 11.7 ms at 238 FPS without generation.
**GPU render is 2.7 ms there and never longer than the total** (0 of 429 samples; 1 of 190) — so what the
three sessions above showed is Phantom Blade Zero's, not the route's. `bLowLatencyMode` *on* throughout. The
table's `fgMultiplier` reads **1 in the session that held ×2 for 105 seconds**: the row keeps the last value
read, and that session ended in a menu — a row that lists what was seen would not mislead. D137's first
Cyberpunk batches: eight of them, 85–221 ms, every one `install` in one apply; beta.46's 0.61 s did not recur.
(f) **Not Direct3D 12**: Crown & Coin (213) and Psycho-Sleuth (214), both Direct3D 11 — one `LATENCY no
Direct3D 12 device` line each, nothing after it, the session's line reads *not read — not Direct3D 12*.
**Direct3D 12 with no NVIDIA library**: Dread Fields (215) — `the game has not loaded nvapi64.dll`, said once,
*not read*. The three ran at the same time and were recorded apart. (h) held in all five: no fault counted,
nothing dropped, normal exits, nothing in Windows' application log.
**A correction to the paragraph above**: the Agent's samples are **1.32 s apart, not one second** (the `t_ms`
series; so in every session looked at back to beta.42, while `sensor_blobs.hz` says 1.0 — not looked into),
so the shares are 227 of 258, 24 of 39 and 823 of 846 samples, and the gaps are the first seconds of a session.
**The owner's answer on the *GPU render* line (2026-11-14): read the driver's active time** — planned as one
train with what else is open. **Left of this item**: (d) Reflex off in the game's menu, (g) off means off, and
the owner's word on how the games felt; the owner runs what is left once, with that train's release.
**Answered 2026-08-05, do not re-ask:** remove `gameguard` and keep `guard` (approved
over a red `Rules` gate, with the reasoning recorded in the merge commit); vendor NVAPI
@@ -862,8 +970,20 @@ Where each owner decision is recorded — the file and its section, and a label
| D131 | [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Hook inventory | the adapter a game asks `slIsFeatureSupported` about (`sl::AdapterInfo`: a LUID, or a Vulkan physical device) is never read — the feature's id and the result only; a build check refuses the struct's member names in code loaded into a game |
| D132 | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) §M14, `CLAUDE.md` rule 4's note of 2026-11-13 | Reflex route D goes to a spike on `hook-harness` and a stub first — and the ruling a go needed: calling a driver's read-only getter with the device of the swap chain the Overlay hooks is inside rule 4. No real game before the owner has seen the result |
| D133 | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) §M14, [`spike-notes/30-reflex-latency.md`](spike-notes/30-reflex-latency.md) | Reflex route C (the Overlay calling `slReflexGetState`) is refused; the no-injection ETW route stays closed, and §G with it |
| D134 | `HANDOFF` START HERE §NEXT | installs and restores are batched through MinHook's queue — one stop of the game's threads for a batch, not one a patch — in a pull request of its own, measured, released alone (0.1.0-beta.46) |
| D134 | [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Unhooking, *Batches* | installs and restores are batched through MinHook's queue — one stop of the game's threads for a batch, not one a patch — in a pull request of its own, measured, released alone (0.1.0-beta.46) |
| D135 | [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Hook inventory | `slAllocateResources` keeps its patch although no game called it in the first six sessions; looked at again when there are more |
| D136 | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) §M14, [`spike-notes/31-reflex-route-d-harness.md`](spike-notes/31-reflex-route-d-harness.md) §The question for the owner | Reflex route D goes on to one real title, Cyberpunk 2077 — a plan of its own first, no code before it is approved, and no release carrying it before item 44 (d) has been run |
| D137 | [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Unhooking, *Batches* | the `PATCH_BATCH` line says how a batch ended — one apply, or finished one patch at a time — after two batches in real games took 0.61 s and 1.26 s and the log could not say which; with the next release, not one of its own |
| D138 | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) §M14, [`handoff/history/0.1.0-beta.46.md`](handoff/history/0.1.0-beta.46.md) §The train after 0.1.0-beta.46 | the Reflex read has no switch of its own: it is part of Advanced metrics — so it reaches every Direct3D 12 game that loaded the driver's `nvapi64.dll`, for everyone who switched Advanced metrics on; "one title" is the order of the owner's first runs (item 45), not a limit in code |
| D139 | [`spike-notes/31-reflex-route-d-harness.md`](spike-notes/31-reflex-route-d-harness.md) §The leg with a sleep | before any Overlay code the probe runs a leg with `NvAPI_D3D_SetSleepMode` and `NvAPI_D3D_Sleep` — writes, in the probe's own process, on its own device, in no shipped binary |
| D140 | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) §M14 | an `nvapi64.dll` loaded from the game's own folder — a replacement, not the driver's — is refused, and the session says why |
| D141 | [`20_OPEN_QUESTIONS.md`](20_OPEN_QUESTIONS.md) §M14 | one call into the driver of 2 ms or more switches the Reflex read off until the game exits |
| D142 | [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Calls the Overlay makes into a driver | asked on 2026-11-14 with Phantom Blade Zero's *GPU render* longer than its total: read the driver's `gpuActiveRenderTimeUs`, and with it `gpuFrameTimeUs` — two more members of the report already fetched, no further call |
| D143 | [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §The inventory | the start-to-end *GPU render* line stays, stored and shown, under a label that says it includes the card's idle time |
| D144 | [`07_IPC.md`](07_IPC.md) §Region 5 | the driver's frame-generation multiplier is kept as every value a session saw, not the last one |
| D145 | [`../legal/ACCURACY.md`](../legal/ACCURACY.md) | the accuracy statement, the README and the guide say two real games were read on one driver (they said none); Privacy Policy 2.21 and Disclaimer 2.17 with it |
| D146 | [`06_DATA_MODEL.md`](06_DATA_MODEL.md) §sensor_blobs | the Agent's samples were 1.32 s apart under a 1 s setting (it waited the whole interval after its work): sample on a fixed period, and store the rate the samples had |
| D147 | [`03_METRICS.md`](03_METRICS.md) | the session summary's latency fields stay N/A: the driver's total is simulation start to GPU end, not input to display |
| D109 | [`../legal/DISCLAIMER.md`](../legal/DISCLAIMER.md) §5, §5A | asked on 2026-11-11 with both sentences quoted: the Disclaimer goes to 2.15 with the Privacy Policy — PawnIO and the admin mode are no longer "for the CPU temperature" alone; with Advanced metrics on they also read the processor's, the memory's and the motherboard's sensors. The admin mode's disclosure follows (`agent-admin-dialog/2`) |
---
+42
View File
@@ -0,0 +1,42 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.46 was cut, 2026-11-13 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.46] - 2026-11-13
**The forty-sixth pre-release: hooks go into a game together, and come out together.** Putting a hook in or taking
it out stops every thread of the game for a moment. Until now that happened once for every hook: in the first real
sessions on 0.1.0-beta.45 the thirteen NVIDIA Streamline hooks took between 0.7 and 2.8 seconds of a game's start,
and stopping a session took about a sixth of a second for each hook. The hooks FrameLedger finds something for at
one moment are now put in under **one** stop of the game's threads, and a stop takes all of them out under one.
This release is that change and nothing else in the part that runs inside a game; the pages are also brought up to
date with what those first sessions showed. The same unsigned installer: verify its hash against `SHA256SUMS.txt`,
then *More info → Run anyway*.
**What it is not, yet.** It has **not been run in a real game**. On FrameLedger's own test program nine hooks go
in within 78–90 thousandths of a second where they took 0.6–0.7 seconds, and eighteen come out within 76–90 where
they took 1.4–1.6 seconds; how long one stop of the threads is in a game with a few hundred of them, and whether
any game minds its hooks arriving together, are for the first real sessions to say. Nothing new is read and
nothing a hook reads has changed, so the terms are the ones you accepted. Of 0.1.0-beta.45's six new readings five
have now been read in real games; no game run so far set up a feature's resources after FrameLedger was in it, so
that row has not been seen. Everything 0.1.0-beta.45's notes say is not yet done still stands.
**Updating from `0.1.0-beta.45`:** Help ▸ Check for updates, then *Restart to update* with no game running. **The
terms are not shown again** (Privacy Policy 2.19 as before). No change to the ledger (schema 23), the detection
rules stay at `2026.11.2`. **The code loaded into a game changed in this release**, so a game that was running
during the update keeps the old part until it is started again.
### Changed
- **Hooks go into a game together, and come out together** (owner decision D134). Putting a hook in or taking it
out stops every thread of the game for a moment, and until now that happened once for every hook: the thirteen
Streamline hooks took 0.7 to 2.8 seconds of a game's start in real sessions (2026-11-13), and stopping a session
took about a sixth of a second for each hook — two to three seconds, sometimes on the thread that draws. The
hooks a moment finds are now put in under **one** stop of the threads, and a stop takes all of them out under
one. On FrameLedger's own test program: nine hooks in 78–90 ms where they took 0.6–0.7 s; eighteen out in
76–90 ms where they took 1.4–1.6 s. What a hook reads and when it is installed are unchanged, and no hook's own
code changed. The log of the part inside the game has a new line for each such moment (`PATCH_BATCH`, with the
time it took and the number of hooks). **Not run in a real game yet.**
- **The limitations, the accuracy statement and the user guide say what the first real sessions on 0.1.0-beta.45
showed** (2026-11-13, six games): five of its six new readings were read in real games — every Streamline game
asked whether its features are supported — and no game allocated a feature's resources after FrameLedger was in
it, so that row has not been seen. No code changes.
+92
View File
@@ -0,0 +1,92 @@
<!-- Moved from CHANGELOG.md's [Unreleased] when 0.1.0-beta.47 was cut, 2026-11-14 (D66). CHANGELOG.md lists every release. -->
## [0.1.0-beta.47] - 2026-11-14
**The forty-seventh pre-release: with Advanced metrics on, FrameLedger reads NVIDIA's own report of where a frame's
time goes.** On an NVIDIA card, in a Direct3D 12 game that uses NVIDIA Reflex, a session recorded with *Advanced
metrics* on now also stores how long the graphics driver says each stage of a frame took — simulation, render
submit, present, driver, the operating system's queue, the graphics card — as seven lines under *Latency* on the
Advanced page, with a table of the driver's low-latency state. **They are the driver's numbers, not a measurement
by FrameLedger**, and they are not the delay from a click to the screen. The same unsigned installer: verify its
hash against `SHA256SUMS.txt`, then *More info → Run anyway*.
**This is the first release in which the part inside a game makes a call of its own.** Until now it only read what
a game itself passed to the graphics calls FrameLedger intercepts. To read this report it asks the graphics driver,
about once a second, on the game's own thread that presents its frames — two functions of the driver that only
read. It reaches them through NVIDIA's library only where the game had already loaded it, and never loads that
library itself; a copy sitting in the game's own folder is not the driver's and is not used. It is built to step
back rather than disturb a game: a request that takes two thousandths of a second or more, or that goes wrong, is
the last one until the game is closed, and the session says so. **With Advanced metrics off — the default — none
of this happens.** The Disclaimer and the Privacy Policy say all of it; the terms window shows once.
**What it is not, yet.** **No real game has been read.** The reading was written and tested against FrameLedger's
own test program with a stand-in for NVIDIA's library, and measured with a test tool against one driver on one
card (GeForce RTX 5080, driver 32.0.16.2114): there a request takes about three millionths of a second, and none
took a thousandth while the tool, like a game using Reflex, slept between frames. What a game's own threads, frame
generation, another driver or another card do with it is for the first real sessions to say; a game that enforces
Windows' Control Flow Guard on a driver that tool was not run against is not covered. On a busy PC the
two-thousandths limit will now and then switch the reading off for a pause that was Windows' and not the driver's;
the session then says *stopped* with the time, and the next start of the game reads again. The session summary's
latency fields still read N/A, and nothing here is read on Direct3D 11, Vulkan or OpenGL. No test runs the whole
path from the game to the ledger through the real capture agent; the Japanese texts are new and unreviewed.
**Also in this release.** The log of the part inside a game now says how a group of hooks went in or came out —
in one go, or one hook at a time — after two groups in the first real sessions on 0.1.0-beta.46 took far longer than
the rest and the log could not say why. And 0.1.0-beta.46's other half has now been seen in a real game: stopping
the part inside a running game took all twenty-nine hooks out under one stop of 83–86 thousandths of a second,
twice, and the game went on.
**Measured overhead this release.** A presented frame: one more read of one word; too small to measure on the
test program. The request to the driver, once a second while Advanced metrics is on: 2.5–2.6 millionths of a second
at the median after a frame that slept, 8–67 at worst, in three runs alone; 3.4 and 130 on a busy PC. Not measured
in a game.
**Updating from `0.1.0-beta.46`:** Help ▸ Check for updates, then *Restart to update* with no game running. **The
terms are shown once** — Privacy Policy 2.20 and Disclaimer 2.16. No change to the ledger (schema 23) or to the
shared memory's layout (5); the detection rules stay at `2026.11.2`. **The code loaded into a game changed in this
release**, so a game that was running during the update keeps the old part until it is started again.
### Changed
- **The log of the part inside a game says how a group of hooks went in or came out** (owner decision D137). Since
0.1.0-beta.46 hooks are put into a game in groups, the game's threads stopped once for a group. In the owner's
first sessions two groups took much longer than the others (0.6 s and 1.3 s against 0.1-0.3 s), and the log
could not tell one long stop from a group that had to be finished one hook at a time. The `PATCH_BATCH` line now
reads `install` or `restore` for a group that went in one go, and `install singly` or `restore singly`, with a
count, for one that did not. Nothing else about hooking changed, and what a game is measured by is the same.
### Fixed
- **For developers: a native test that is cut short no longer counts as passed.** The quality gate's native tests
were judged by their exit code alone, and a test program that was stopped early with a clean exit code read as
*Passed* - seen once, when security software removed the test program while the gate ran. Every native test now
has to print the line it ends on, a test added without one stops the build's configure step, and four tests
exist only to prove the rule goes red when it should. Nothing a user installs changed.
### Added
- **The part inside a game can read NVIDIA's own latency report, with Advanced metrics on** (owner decisions D132, D136,
D138-D141). While a session records Advanced metrics, and only then, it asks the graphics driver about once a
second for its report of a frame's stages - simulation, render submit, present, driver, the operating system's
queue, the graphics card - and for its low-latency state. It is a call FrameLedger makes itself, on the thread
that presents the game's frames, through NVIDIA's `nvapi64.dll` only where the game had already loaded it;
Direct3D 12 only. A copy of that library sitting in the game's own folder is refused. A call that faults or takes
two milliseconds is the last one until the game is closed. **The Advanced page shows it** under *Latency*: seven
lines, one a stage, and a table of the driver's low-latency state; the line under a session says what became of
the read - read, the driver reported no frame, not read and why, or stopped and why. They are the driver's
numbers, not a measurement by FrameLedger, and no real game had been read when this was written. **Privacy
Policy 2.20 and Disclaimer 2.16** say what is stored and what the part inside a game now does; the terms window
will show once.
- **For developers: room in the shared memory for NVIDIA Reflex latency** (owner decisions D136, D138). Ten reserved
words of the block that carries Advanced metrics from a game are now named for the driver's latency report -
where the read stands, and a sum for each stage of a frame. Nothing writes them yet and nothing reads them; the
shared memory's layout version did not change.
- **For developers, nothing a user installs: a probe for NVIDIA Reflex latency** (owner decision D132). An
unshipped tool, `fl-probe-reflex`, and a stand-in `nvapi64.dll` among the test fixtures measure what it would take
to read the driver's latency report from inside a game - on FrameLedger's own test program and against the
installed driver, never in a game. What it found is `docs/spike-notes/31-reflex-route-d-harness.md`. A further
leg (owner decision D139) measured the same reads while the probe itself used Reflex's sleep, as a game does:
the reads do not wait behind it. The owner has said to go on to a real game (D136); that work is not in any
release yet. Nothing in the App, the Agent or the part that runs inside a game changed.
+175
View File
@@ -0,0 +1,175 @@
# HANDOFF history — 0.1.0-beta.45
*Moved verbatim from `docs/HANDOFF.md` when 0.1.0-beta.46 was cut, 2026-11-13 (owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" mean HANDOFF.md as it stood then, and a path it writes is relative to `docs/`. **Its §NEXT says 0.1.0-beta.46 is to come**: it was released the next day, and what it built and decided is HANDOFF.md's section for it.*
## **START HERE** — 2026-11-12, 0.1.0-beta.45: six more of Streamline's calls, hooked only where asked; `slInit` stays out; the Reflex spike as a document
*Status is `docs/changelog/0.1.0-beta.45.md`; this is what no other file carries.* The owner ran eight sessions on
beta.44 the evening it was released and said: add the three new ones, update, go on. They were read from a copy of
the ledger and the logs (#426); asked to reopen D112, the owner was shown why `slInit` cannot be seen and chose to
leave it out (D129), chose six other calls for one release (D130), and approved the plan with Privacy Policy 2.19's
wording. Four pull requests and this one: #427 (`slIsFeatureSupported`, `slIsFeatureLoaded`, `slSetFeatureLoaded`
in the Overlay; D129–D131), #428 (`slAllocateResources`, `slFreeResources`, `slShutdown`), #429 (the Agent, the
App, Privacy Policy 2.19), #430 (train C's spike, a document: `spike-notes` §30). **What the eight sessions on
beta.44 showed, session by session, is [`handoff/history/0.1.0-beta.44.md`](handoff/history/0.1.0-beta.44.md)**;
what each pull request built is [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Hook inventory (the two rows of the six
calls, with their measured cost) and [`18_GPU_VENDOR_APIS.md`](18_GPU_VENDOR_APIS.md) §Train B (the fourth step).
### What this release decided, beyond D129–D131
- **Everything the six calls give is word 1 of a feature's slot, and one reserved word.** Bits 2–4 the two answers
(supported, with the `sl::Result` in bits 8..15; loaded and its value), bits 5–6 the game switching the feature
off and on, bits 16..19 and 20..23 two counts that stop at fifteen and never carry; `slShutdowns` took the first
of three reserved words (@308). Layout 5 and schema 23 as they were. **The answers are the process's and a new
request keeps them; the switching, the counts and the shutdowns are a session's and a new request clears them.**
- **A refusal is the answer.** `slIsFeatureSupported`'s detour calls the original first and keeps whatever it
returned; the page names it by NVIDIA's enumerator (forty codes, the same order at sixteen upstream tags from
v2.0.0 to v2.14.16), `result <n>` past the list, 255 for a code a byte could not carry.
- **The two calls on a game's way out note the call, then call the original, and run nothing after it** —
`slFreeResources` and `slShutdown`. The fixture shuts Streamline down and goes on using the stub through every
detour.
- **The adapter is never read** (D131), and the build refuses the names of `sl::AdapterInfo`'s members in the code
loaded into a game (`overlay-fields-check`); the fixture hands a wild LUID pointer.
- **A stop restores its patches one after another, about 160 ms each.** MinHook stops every thread of the process
for each `MH_DisableHook`. With six more patches the stop's last log lines were cut at the two seconds the
Overlay waited for them; the wait is now sized to the patch table (`250 ms × kMaxPatches`). The patches were
always restored; `UNHOOKED` is written after the last. **Not changed, and proposed**: queueing the restores (and
the installs) so the threads are stopped once — a change to the hook engine's order of operations, which wants
its own pull request, its own measurement and the owner's word. Until then a stop in a Streamline game with
Advanced metrics on takes two to three seconds on the thread that stops.
- **Six calls are one sentence on the page**, each by its function's name under which of three things became of
it; a row stored before this release has none of the six and no such sentence.
- **`AdvancedReach.BeforeAttach` is a reason of its own** for `sl.init.preferences`: not "a later release". No
catalog entry carries `NewHook` any more; the value stays, for rows a later train may add.
- **Where the rows sit in the table** (rows are patched in its order): the two questions after beta.44's two, at
the head; `slSetFeatureLoaded` after `slSetConstants`; the three counted calls last of the Streamline block.
- **Train C's spike is a reading** (`spike-notes` §30): hooking NVAPI's or Streamline's latency functions is
refused or is train D's wrapper; the Overlay calling `slReflexGetState` breaks the vendor's thread contract;
what remains is the Overlay calling two driver getters with the game's device, and a no-injection ETW route
that gives half the number. It ends in three questions that are the owner's.
### Traps this train left
- **The catalog table of `18_GPU_VENDOR_APIS` is compared with the catalog row for row by a test**: a catalog
entry and its row go in the same commit, or the Application tests are red.
- **Qodana's native report again found an index into the feature slots computed as a 32-bit product** (#427, the
harness's probe): write `size_t{2} * FL_ADV_FEATURE_WORDS`. It is advisory and auto-merge does not wait for it;
both reports were read before each merge.
- **A second `region` inside the probe's block is C4456**, and warnings are errors: name the inner one otherwise.
- **A test method over sixty lines is MA0051** in the test projects too; split the assertions by what they cover.
- **The injected test waits for the stop**: with eighteen patches a stop takes about three seconds, so its wait is
200 iterations.
- **The shell tool refuses `sleep N; command`**: wait in a background `until` loop.
- **After a lower pull request is squashed**, `git diff <old tip> origin/main` empty proves the squash is the
branch; then `git rebase --onto origin/main <old tip> <next branch>` and a forced push with lease.
### What the owner's seven sessions on beta.45 showed (2026-11-13)
The owner ran seven sessions on six games the day after the release and said: check the logs and go on. Read from
a copy of the ledger (sessions 190–196), the seven overlay logs, the Agent's log and Windows' application log —
no FrameLedger binary was run against the owner's data. **Every session is hooked, `normal`, with no fault
counted, no dropped record and no `PATCH_FAILED`; the count of early ends is 0 on all six games.** The update
showed the terms once: Privacy Policy 2.19 was accepted at 07:23:36.
| Game (session, length) | Interposer | `slIsFeatureSupported` | `slIsFeatureLoaded` | `slSetFeatureLoaded` | allocate | free | shutdown |
|---|---|---|---|---|---|---|---|
| Phantom Blade Zero (190, 2 h 48 min; 191, 1 h 32 min) | 2.14.1 | **read** — Reflex, DLSS frame generation, PCL `eOk`; ImGUI and DeepDVC `eErrorFeatureMissing` | **read** — Reflex, frame generation *on* | not called | not called | **read** — frame generation, 1 | not called |
| Cyberpunk 2077 (193, 7 min) | 2.14.1 | **read** — frame generation, DLSS, ray reconstruction, Reflex `eOk`; NIS `eErrorFeatureMissing` | **read** — the four *on* | **read** — the four, *on and off* | not called | not called | not called |
| Dying Light: The Beast (194, 4 min) | 2.8.0 | **read** — DLSS, frame generation, PCL, Reflex, NIS `eOk` | not called | **read** — all five, *on and off* | not called | not called | **read** — 1 |
| Hogwarts Legacy (195, 4 min) | 2.14.16 | **read** — frame generation, Reflex, DeepDVC, DLSS 5's `kFeatureDLSS_NR`, PCL `eOk`; ImGUI `eErrorFeatureMissing` | **read** — the first four *on* | not called | not called | not called | not called |
| Black Myth: Wukong (196, 3 min) | 2.7.4 | **read** — frame generation, Reflex, PCL `eOk` | not called | not called | not called | not called | not called |
| Kingdom Come: Deliverance II (192, 4 min) | none | not hooked | not hooked | not hooked | not hooked | not hooked | not hooked |
- **`slIsFeatureSupported` was read in every Streamline session, and `slAllocateResources` in none.** Item 43
wrote the meaning of that before the run: a call no game makes after the attach gives nothing in attach mode, and
whether it keeps its patch is the owner's to say. `slFreeResources` and `slShutdown` were each read once, in one
game each; `slIsFeatureLoaded` in three games, `slSetFeatureLoaded` in two.
- **A refusal reads as one.** Phantom Blade Zero and Hogwarts Legacy ask about `kFeatureImGUI`, Streamline's
debug overlay, and are told it is missing; Cyberpunk 2077 is told the same of NIS, which Dying Light is told is
supported. Phantom Blade Zero is told DeepDVC is missing although Streamline answered its requirements.
- **The count says how often, not when.** Dying Light's one shutdown and Phantom Blade Zero's one freeing of frame
generation's resources may each be the game closing; nothing in a session says. Dying Light switched all five
features off and on.
- **The way out is as it was.** Hogwarts Legacy faulted at its exit in `_nvngx.dll`, `0xc0000005` at offset
`0x6aa85` — the offset of its six before, since 2026-11-06, hooked or not — and Black Myth: Wukong in
Steam's `crashhandler64.dll`, `0xc0000409` at `0x39b49`, the offset of its three before (Steam's file is now
11.23.65.88). Windows' log has no fault for the other four games; the two hooks on a game's way out were in all
five Streamline games.
- **Rates are where they were**, for what a comparison without the same scene is worth: Phantom Blade Zero ×4 at
64 → 255 (beta.44: 63 → 251), Wukong 85 → 341 (90 → 361), Cyberpunk 2077 164 → 327 (137 → 275), Dying Light ×4
at 48 → 194 (beta.42: 54 → 216), Kingdom Come 58.8 presented (59.3).
- **An install stops the game's threads once a patch, as a restore does.** The thirteen interposer patches took
0.74 s on Phantom Blade Zero, 1.2 s on Cyberpunk 2077, 1.7 s on Dying Light and Wukong (twelve there) and
**2.8 s on Hogwarts Legacy** — 57 to 215 ms a patch, while the game starts. That is the cost the proposal to
queue patches (§What this release decided) would cut, measured on real games.
- **No stop was exercised.** Every session ended with the game closing, so no log has an `UNHOOK_RESTORED` line.
Item 43 (g) said a log "ends with an `UNHOOK_RESTORED` line for each patch": that is true only of a session
stopped while its game runs, and the item was worded wrongly.
- **Not exercised: off means off** — Advanced metrics was on in every session. **Not visible in the data**: (c), whether *loaded* agrees with the game's own menu, and (h), the
catalog's wording on the page — both are what the owner sees.
- **For train C's spike**: Streamline says Reflex is supported in all five games and loaded in the three that
ask; Cyberpunk 2077 and Dying Light switch it off and on (`spike-notes` §30 has the note).
### NEXT
1. ~~**The owner runs item 43**~~ **Run and read 2026-11-13** (§What the owner's seven sessions on beta.45
showed): five of the six calls read in real games, nothing different on the way out, no fault. *Off means off*
was not exercised, and `slAllocateResources` was called by no game.
2. ~~**The owner reads `spike-notes` §30 and answers its three questions.**~~ **Answered 2026-11-13 (D132,
D133)**: route D goes to a spike on `hook-harness` and a stub — the owner ruled that a driver's read-only getter
called with the device of the hooked swap chain is inside rule 4 — and no real game is touched before the owner
has seen its result (`spike-notes` §31, to be written after 0.1.0-beta.46 is tagged); route C is refused; the
ETW route stays closed. No shipped code changes for the spike.
3. ~~**The stop's cost** (above): whether to batch the restores is the owner's to say.~~ **Decided 2026-11-13
(D134): batch them, installs too** — a pull request of its own, measured on the harness, released alone as
**0.1.0-beta.46**. The plan was reviewed against MinHook's source before it was approved: `MH_ApplyQueued`
applies every entry whose queued state differs, not only the caller's, so the queue-to-apply sequence is
serialised, only targets that are still ours are ever queued for a restore, and nothing is queued "for all".
4. **`slAllocateResources` keeps its patch** (D135); looked at again with more sessions.
5. **Train D** after train C, the same way: a spike first.
### Left open by this session
- ~~**This release's own facts** — the tag's run, the digests, the delta — are not in any file yet: the release is cut
after this text. Record them in the next pull request, with what SonarCloud and Qodana said.~~ **Recorded
2026-11-12: 0.1.0-beta.45 was released 2026-11-12T16:40:42Z** (23:40 in the owner's time zone) from the signed
tag on `550d830` (#431), by run 43257803723 — green at the first attempt, one run for the one tag push. Eight
assets; the seven digests of `SHA256SUMS.txt` equal the ones GitHub computed; the four shipped natives carry
`FL_BUILD_ID v0.1.0-beta.45`. The delta from beta.44 is 1,762,465 bytes beside a full package of 110,767,499 —
"Delta processed 0452 files. 0024 patched, 0428 unchanged". The wiki was published by run 43261335359. The
rehearsal on the release branch (run 43253780609, at `f4e3fe2`, the released tree) had made a delta of 1,779,418
bytes with the same file counts. **Qodana's two reports are green on `550d830`.** On the way Qodana's native
report found two index products in the harness's probe (#427), fixed before that pull request merged; every
later report was clean, and each was read before its merge. No required check failed on this train.
**SonarCloud's quality gate failed on `550d830`, on one condition: duplicated lines on new code, 3.7 % where the
gate allows 3 %.** No issue is open and coverage on new code is 98.6 %. The 39 lines are the six new members of
`FlHookFamily` (`ShmLayout.cs`) and of its Domain mirror `HookFamilies` — two enums that are the same on purpose
(Domain references nothing, and `MetricEnumMirrorTests` fails when they differ), which six members at once took
over a threshold that two at a time had stayed under. The job is advisory and the release was already cut. The
pull request that records this leaves the Domain's mirror out of duplication detection, with the reason in
`SonarQube.Analysis.xml` and in `13_CI_CD` §SonarCloud; **whether the gate is green again is for the analysis of
that commit on `main` to say**, and it is not in this text. *(It said so the same night: green on `d3e8dd3`,
duplicated lines on new code 0.0 %, no issue open.)* One more thing the train showed: main's branch
protection wants a pull request up to date, so of two that were green at once the second (#430) had to be
rebased after the first merged, and ran its checks again.
- ~~**No real game was run on this build.** Six new patch sites, tested with the harness and the stub; their cost
measured on the headers.~~ **Seven sessions on six games, 2026-11-13** (§What the owner's seven sessions on
beta.45 showed). The published release notes say the six calls "have not been run in a real game"; a released
file is not edited.
- **`slAllocateResources` has a patch no game has used**: not called after the attach in any of six sessions on
five games. ~~Whether it stays is the owner's.~~ It stays for now (D135, 2026-11-13).
- **Off means off (item 42 (f)) has never been exercised on a real game**; it is item 43 (f) now, for all ten.
- **Valor Mortis's crash at 51 s** (twice, beta.40 and beta.44) **and Black Myth: Wukong's fault in Steam's crash
handler at every exit** are not explained. One session of each with hooking off is the comparison that is missing.
- **What item 41 left unexercised**: a configure through the FidelityFX 2.3 loader (Cyberpunk 2077 with FSR frame
generation), a game with neither library.
- **A fault while a game is closing is not seen by a hooked session** (D127: written down, not changed).
- **`docs/LIST_GAME_TESTED.md` is as of 2026-11-06**: refreshing it is a new copy of the ledger and the owner's review.
- **Item 40 (d)** was not exercised and the owner has not said item 40 passed. **Items 36 (d) and 37 are still open.**
- **What an empty process snapshot does to the watcher's tick in a real session** was not looked into (seen once in
a test on 2026-11-12).
- **`LIMITATIONS.md` and the accuracy statement still say the processor's, the memory's and the motherboard's
sensors "have never been read on real hardware"** — the owner's to reword. The alpha line still rests (D98).
**Owner-only:** item 43; the three questions of `spike-notes` §30; one session each of Valor Mortis and Black
Myth: Wukong with hooking off; what item 41 left unexercised; item 40 (d).
+247
View File
@@ -0,0 +1,247 @@
# HANDOFF history — 0.1.0-beta.46
*Moved verbatim from `docs/HANDOFF.md` when 0.1.0-beta.47 was cut, 2026-11-14 (owner decision D66); `docs/HANDOFF.md` §How this file is split lists every part. Nothing below was edited, so its "below" and "above" mean HANDOFF.md as it stood then, and a path it writes is relative to `docs/`. **Its §The train after 0.1.0-beta.46 says the release is held**: item 44 (d) was run on 2026-11-14 and 0.1.0-beta.47 was released that day; what it built and decided is HANDOFF.md's section for it.*
## **START HERE** — 2026-11-13, 0.1.0-beta.46: patches go in and come out under one stop of the game's threads; Reflex route D goes to a harness spike
*Status is `docs/changelog/0.1.0-beta.46.md`; this is what no other file carries.* The owner ran seven sessions on
beta.45 the day after it was released and said: check the logs and go on. They were read from a copy of the ledger
and the logs (#433), and the same day the owner took four decisions on what they showed (D132–D135) and approved
the plan. Two pull requests and this one: #433 (what the sessions showed; the decisions; rule 4's note in
`CLAUDE.md`), #434 (the batches, D134). **What the seven sessions on beta.45 showed, session by session, is
[`handoff/history/0.1.0-beta.45.md`](handoff/history/0.1.0-beta.45.md)**; what the batches are, what the queue
makes dangerous and what was measured is [`17_HOOK_ENGINE.md`](17_HOOK_ENGINE.md) §Unhooking, *Batches*.
### What this release decided, beyond D132–D135
- **The first design was wrong, and reading MinHook's source before writing a line is what found it.** It marked
every hook for disabling and then un-marked the ones it must not restore. `MH_ApplyQueued` applies every hook
whose mark differs from its state; un-marking a hook that is already out marks it for *enabling*, and the stop's
own apply would have put a patch back in after the stop — logged as "declined", with the status `UNHOOKED`. The
rules that replaced it are in `fl_patch_registry.h`: no mark left standing, only a patch that is still ours
marked for a restore, nothing marked "all", and mark–apply–commit inside a gate.
- **The gate is the Overlay's one lock, and it is on no hook body's path.** A slim lock, exclusive, held for one
apply, never across a symbol lookup (the loader's lock). The one way from a hook to it is the stop, which always
waited for MinHook's own lock and a stop of the threads. Its owner re-enters it without waiting: a slim lock taken
twice by one thread never returns.
- **The verdict on an install is the engine's, not the bytes'.** Reading the target back after the apply would take
a foreign overlay that patched over us in that instant for a failure, and mark a restore nobody had compared.
- **An apply stops at its first failure and says only that one failed.** The hooks after it are enabled — in the
stop, restored — one at a time, so one bad patch still costs one patch, and a stop still takes everything out.
- **One stop of the threads costs what it cost for one patch**: 77–91 ms on the fixture for four, nine or eighteen.
What it costs in a game with a few hundred threads is not known; the `PATCH_BATCH` line's `a=` is there to say.
- **Init's three DXGI patches, the loader detour and OpenGL are as they were** — three already went in together,
the other two are one each. Ray tracing's two are a batch of their own, apart from the upscaler rows', so that a
batch's size in a test does not depend on which tick a D3D12 device appeared in.
- **`fl_guard`'s timing assertion is on the restore only** (under a second for eighteen patches): the time from an
Advanced request to its families includes the wait for the watchdog's tick, and batching changes the tick's
phase, so that number went *up* in the test while the install itself went from 0.6 s to 0.08 s. The install is
asserted by count — every lazily installed patch under a `PATCH_BATCH` line — not by time.
- ~~**The spike of route D is still to be written**~~ **The spike of route D was run the same day** (`spike-notes`
§31; `tools/fl-probe-reflex`, ctest `fl_reflex_probe_stub`): a decision table written before the runs, a stand-in
`nvapi64.dll`, then the installed driver in the probe's own process. None of §30's stop conditions fired. Two
things it decided that a plan must keep: **the call belongs on the presenting thread, once a second** — a call
the driver holds stops the thread that made it, so not the watchdog, and at a microsecond or so it needs no thread
of its own — and **the newest frames of a report are not final** (one run read a span of half an hour in the
newest frame). Rule 4's note (D132) is in `CLAUDE.md`; nothing shipped calls a driver.
### Traps this train left
- **GPG's agent had restarted and the pinentry timed out three times in a row**; nothing could be committed until
the owner unlocked the key (`echo test | gpg --clearsign` in the owner's own terminal). Say so and go on with
what needs no commit — planning did not.
- **A here-document still eats backslashes** (a `\n` inside a C++ string in an edit script): write the script to a
file. It cost one failed edit again.
- **A Catch2 `WARN` longer than the console's width wraps**, and a filter on its first words loses the number at
its end: keep a measured line short.
- **To measure the old build beside the new one**: `git stash push -- <the changed sources>`, build, run the one
test case by name (its `INFO` log prints when a new assertion fails, which it does on the old build), `git stash
pop`, build again.
- **SonarCloud's gate was red on #434 before it merged, on three things it was right about**: a `LARGE_INTEGER`
initialised with `{}` and read through `QuadPart` (cpp:S6232 - write `{.QuadPart = 0}`, as the rest of the file
does since #336), a `strlen` in a test, and a test model indexed with what a lookup returned unchecked. Its job is
advisory and auto-merge does not wait for it: the pull request was held until the fix was analysed.
- **`docs/14_TESTING` and the changelog are where a non-per-present cost goes**; "measured overhead" in a pull
request body means what the change can move — here the install and the stop, not a present.
### What the owner's five sessions on beta.46 showed (item 44, read 2026-11-13)
The owner updated at 20:29 (+07) the day of the release, ran five Streamline games with Advanced metrics on — one
session each, four to nine minutes, sessions 198–202 — and said: check and go on. Read from a copy of the ledger
and the logs, and from Windows' application log. None of the five is under the user-mode exception.
| Session | Game | Install batches in the log's order: `a=` in microseconds · patches | The interposer's patches on beta.45, first line to last |
|---|---|---|---|
| 198 | Hogwarts Legacy | **1 260 835 · 13** (Streamline) — 261 920 · 3 — 227 061 · 2 | 2.80 s, 0.19–0.31 s a patch |
| 199 | Phantom Blade Zero | 81 417 · 3 — 92 512 · 6 — 88 455 · 13 (Streamline) — 99 253 · 2 | 0.74 s and 0.85 s |
| 200 | Black Myth: Wukong | 187 931 · 12 (Streamline) — 157 010 · 3 — 109 025 · 2 | 1.65 s |
| 201 | Cyberpunk 2077 | 93 168 · 16 (Streamline's thirteen and the FSR loader's three) — **608 700 · 3** — 177 970 · 3 — 120 878 · 2 | 1.18 s |
| 202 | Clair Obscur: Expedition 33 | 168 527 · 3 — 165 405 · 16 (Streamline's thirteen and FSR frame generation's three) — 218 172 · 2 | no session on beta.45 |
- **The batches went in whole.** In every log the `HOOK_INSTALLED` lines above a `PATCH_BATCH install` carry one
time to the thousandth of a second; there is no `PATCH_FAILED` and no `UNHOOK_DECLINED`; and the hooks are the
ones beta.45 installed for the same game, compared name for name (four games; Clair Obscur had no log on beta.45).
- **Sixteen of the eighteen batches cost 81–262 ms, whatever they held** — two patches or sixteen. That is what one
patch cost in the same game on beta.45, as expected.
- **Two did not, and neither is explained.** Hogwarts Legacy's thirteen took **1.26 s** — under half the 2.8 s they
took one by one, and about five times what one stop cost in that game the same afternoon. Three of Cyberpunk
2077's took **0.61 s**, which is what three patches cost there one by one. **The log cannot tell one long stop
from an apply that failed part-way and was finished one patch at a time**: a batch writes a line only for a patch
that fails for good (item 44's text said a fallback leaves a `PATCH_FAILED`; that was wrong). What speaks for one
long stop: the queued apply fails only where a page's protection cannot be changed, and thirteen single stops in
Hogwarts Legacy would have cost 2.5 s or more. *A reading, not a measurement*: a stop waits until every thread of
the game has taken its suspension, and how long that takes follows what the game is doing at that instant — both
happened while the game was loading — and not how many patches the stop covers.
- **What that means for a ceiling on a batch** (item 44's own words for a second or more, written before the run):
the eighteen batches say the cost does not follow the count — sixteen patches in 93 ms, three in 609 ms — so
splitting a batch would add stops, not shorten one. What is missing is the line that says how a batch ended.
- **Nothing else moved.** All five hooked, `normal`, no fault counted, no record dropped. Rates and factor beside
each game's earlier sessions: Cyberpunk 2077 149 → 298 (×2.0) beside 164 → 327 and 137 → 275; Hogwarts Legacy
61 → 245 (×4.0) beside 59 → 236; Black Myth: Wukong 78 → 315 (×4.0) beside 85 → 341; Phantom Blade Zero 87 → 261
(×3.0) beside 81 → 244 at ×3.0 on beta.43; Clair Obscur 112 → 339 (×3.0) beside 106 → 323 on beta.44.
- **The way out is as it was.** Hogwarts Legacy faults in `_nvngx.dll` at `0x6aa85` and Black Myth: Wukong in
Steam's `crashhandler64.dll` at `0x39b49` — the module and the offset of every build read so far. The other
three games leave nothing in Windows' application log.
- **The Advanced rows are as on beta.45**, and Clair Obscur gave its first reading of the six calls (interposer
2.7.30): `slIsFeatureSupported` and `slIsFeatureLoaded` read, among them a feature no session had named before,
`kFeatureLatewarp` (Streamline's answer: `eErrorFeatureMissing`). `slAllocateResources` and `slShutdown` were
called in none of the five (D135 stands). That game's `hook_crash_count` of 3 is old: it dates from 2026-10-20
and is the same in the copy read for item 43.
- **Not exercised: the stop.** Every session ended with its game exiting; no log has a `STOP` or a `PATCH_BATCH
restore` line. **`RestoreAll` has still run in no real game** — item 44 (d). Nor (e), a game with no Streamline,
nor (g), off means off: `telemetry.advanced` was on throughout. (c), how a game's start feels, is the owner's to
say. (a) held: the terms window did not show.
### The train after 0.1.0-beta.46: Reflex route D in a game, and D137 (plan approved 2026-11-13)
*Nothing of this is in a release. The release pull request is not opened before the owner has run item 44 (d).*
**Where it stands (2026-11-14):** all five are merged — #440 (PR-0), #441 (D137), #442 (the words), #443 (the
Overlay), #444 (the Agent, the App, the legal texts, owner-only item 45); `main` is `cd4f69a`. What is left is the
release, which waits for the owner: **item 44 (d) was tried on 2026-11-14 and not exercised** (the switch was on
before the games started — item 44's last paragraph). **Not verified by any test: the whole path through the real Agent** —
the injected tests stop at the shared memory, the sampler's tests start from it; no end-to-end case loads the
stand-in module under an Agent session. The Japanese strings are new and unreviewed, as every `ja` string is.
The owner approved the plan the evening item 44 was read. Its order: **PR-0** the decisions and the probe's leg
with a sleep (done: `spike-notes` §31 — no stop condition) → **PR-1** D137 → **PR-2** the words in region 5, written
by nobody → **PR-3** the Overlay, the gates, the fixtures → **PR-4** the Agent, the App, strings, documents, legal
texts and owner-only item 45 → **the release, held**. What the plan's review against the source decided — a draft
of mine was wrong in six places — and that no other file carries yet:
- **Resolve on the watchdog, once for the process; call on the presenting thread.** The watchdog asks Windows for
an `nvapi64.dll` that is *already loaded* (never loads it), only while a session asks for Advanced metrics and a
Direct3D 12 device is held; it keeps one reference and never releases it; it refuses a module in the executable's
own folder (D140); it fetches `nvapi_QueryInterface` and the two ids under a guard and checks with `VirtualQuery`
that both addresses lie inside ~~that module~~ an image the process has loaded. "No getter" and "refused" are
final for the process; "no module" is asked again each second. **Found when the header was run against the
installed driver: `nvapi64.dll` is a shim and the two getters are in `nvapi64_impl.dll`** (`spike-notes` §31,
*What moving the sequence into the Overlay found*) — so the check accepts another loaded image, a reference is
kept on that image as well, and the code that is called *is* a Control Flow Guard image (the plan's review had
reasoned from the shim, which is not).
- **One atomic gate with four states** — idle, armed, reading, off — not a busy flag beside accumulators (two
presenting threads could read back to back, and the watchdog could drain half a read). The watchdog drains only
when it sees *idle* and arms at most once a second by its own clock (the loader detour wakes it more often); a
present does one relaxed load, takes *armed* to *reading*, reads into a static buffer (the report is 15.4 KB: never
on a game thread's stack), and stores *idle* or *off*. A request that goes off takes *armed* back.
- **After the record is published, and only for a swap chain whose device is the one held** (`g_d3d12Device` is the
first device seen, not "this chain's": a flag in the chain's slot, set in `ResolveApi`).
- **The latches, each until the game exits**: a fault in a getter (its own guard with `FlFilter`; counted once
through `NoteFault`, so the session shows it and it cannot reach the three that self-disable); one call of 2 ms or
more (D141); the watchdog finding *reading* on two ticks running — logged and flushed at once, published as
stalled, and **nothing can stop a call that does not return**. An error status or an empty report is recorded and
reading goes on.
- **What D141 costs, measured once on a busy PC** (`spike-notes` §31, *A run on a busy PC*): the 2 ms latch will
sometimes fire on a pause that was Windows' and not the driver's — a few sessions in a hundred at worst, by a
reading of one run. The owner chose one call over two knowing it errs towards the game; item 45's outcomes must
say how the two are told apart (the microseconds published with *slow*). **Asked again with this run in hand,
the owner kept it: one call (2026-11-13). Do not re-ask.**
- **The summary**: only frames newer than the last one summed; the two newest of a report skipped (§31: not final);
a zero end point is "span not reported" (published as all ones), not a refused frame; a frame is refused for a
span that runs backwards, one over a second, or no total; frame ids that go backwards restart the sequence.
- **Layout 5 stays**: the ten reserved words of region 5's first line take it (`slShutdowns` is the precedent; the
handshake compares the build id anyway, and a trial must be removable without a layout 7). The sleep interval is
not stored. No new request word (D138). `FL_HOOK_REFLEX`, `FL_MEASURED_LATENCY` and `reflexLatencyUs` stay unset:
there is no hook, and the numbers are a series beside the frames; `sessions.reflex_active` stays NULL.
- **Managed side**: a new reach, `GameDriver`, not a relaxed test of `Game` (whose meaning is "the arguments of a
call the Overlay hooks"); `nvapi.reflex.frame_report` as seven series, `nvapi.reflex.sleep_status` as a table of
switches *seen on / seen off*; `nvapi.reflex.mode`, `sl.reflex.state` and `sl.pcl.markers` become *refused* with
the reason; `InGameAdvancedSampler.Take` must read the latency state when the mask is zero and keep the new bit
out of `SawAnything`.
- **The gates**: `overlay-fields-check` learns the two NVAPI structs (`frameID` joins the shared members; `version`
is written outside the header); `nvapi-readonly-check` gets a pass over the Overlay — no `NvAPI_*(` token, every
id that equals one of `nvapi_interface.h`'s on a list of exactly two, `Sleep` a writer verb; `hookinventory-check`
refuses an `nvapi` import. The injected tests prove nothing about Control Flow Guard (the harness does not enforce
it): the probe includes the header that ships, so `fl_reflex_probe_stub` tests the shipped sequence under it.
- **The legal texts change in PR-4** (Disclaimer 2.16, Privacy Policy 2.20, the accuracy statement): the part
inside the game now *makes a call of its own*, once a second, on the game's presenting thread.
### NEXT
1. ~~**The owner runs item 44**~~ **Read 2026-11-13** (§What the owner's five sessions on beta.46 showed): the
install half held in five games. **Still to run, the owner's: (d) a stop while a game runs** — *Disable all
hooking* with a game being recorded — which is the half of beta.46 no real game has exercised; (e) a game with
no Streamline; (g) off means off. Not first on a game under the user-mode exception's trial (D38).
~~**Proposed, not done: `PATCH_BATCH` says how the batch ended**~~ **Decided the same evening (D137):
`PATCH_BATCH` says how the batch ended** — under one apply, or finished one patch at a time, and how many — so
that a long `a=` can be read. It goes with the next release, not in one of its own. **Written 2026-11-13**:
`install` / `restore` for one apply, `install singly` / `restore singly` with the count in the high half of `b`
(`17_HOOK_ENGINE` §Unhooking, *Batches*). It explains nothing about the two long batches already seen; it makes
the next one readable.
2. ~~**The spike of Reflex route D on `hook-harness`**~~ **Done 2026-11-13** (`spike-notes` §31): on the harness
and against the installed driver the two getters are harmless, cost about a microsecond and return a readable
report, and the Direct3D 12 device the Overlay holds is what the driver takes. **The owner's next word is go or no
for one real title** — a go is a plan of its own before any code (where the numbers go, the Disclaimer's and the
Privacy Policy's wording, `nvapi-readonly-check` over the Overlay). Routes C and E are closed (D133).
**The owner said go on 2026-11-13 (D136): a plan first, for Cyberpunk 2077.** No code before the plan is
approved, and no release that carries it before item 44 (d) — the stop while a game runs — has been run.
**The plan was approved the same evening, with D138–D141** (§The train after 0.1.0-beta.46).
3. **`slAllocateResources`** keeps its patch (D135); looked at again when there are more sessions.
4. **Train D** after train C, the same way: a spike first — and §30 found its hook would miss a game that fetched
its functions before the attach.
### Left open by this session
- ~~**This release's own facts** — the tag's run, the digests, the delta — are not in any file yet: the release is cut
after this text. Record them in the next pull request, with what SonarCloud and Qodana said.~~ **Recorded
2026-11-13: 0.1.0-beta.46 was released 2026-11-13T11:10:28Z** (18:10 in the owner's time zone) from the signed
tag on `47f010a` (#435), by run 43412434074 — green at the first attempt, one run for the one tag push. Eight
assets; the seven digests of `SHA256SUMS.txt` equal the ones GitHub computed; the four shipped natives carry
`FL_BUILD_ID v0.1.0-beta.46`. The delta from beta.45 is 634,023 bytes beside a full package of 110,767,120 —
"Delta processed 0452 files. 0021 patched, 0431 unchanged". The wiki was published by run 43414965433. The
rehearsal on the release branch (run 43409330961, at `7b4ecd7`, the released tree) had made a delta of 668,012
bytes with the same file counts. **SonarCloud answered on `47f010a`: the quality gate passed and no issue is open
on `main`. Qodana's two reports are green on that commit.** On the way SonarCloud was red on #434 (six issues
in the new code, fixed before it merged — §Traps), and no required check failed.
- **A local gate once counted `fl_guard` as passed after 0.66 s** (2026-11-13 17:30, the spike's branch). The
security software on the development PC was switched on for three minutes while the gate ran; the freshly linked
`fl_guard_test.exe` was removed from the build tree, **ctest reported the run that was cut short as `Passed`**
(the suite takes 181 s), and the gate went red only because the next test, `fl_prescan`, runs the same executable
and could not find it. Run again with that software off, the gate was green. Nothing was changed for it: a test
whose process ends early with a zero exit code is a pass to ctest, and the suite has no line it must print to
count. ~~Worth a guard of its own (a `PASS_REGULAR_EXPRESSION` on Catch2's last line, or a minimum number of test
cases); proposed, not done.~~ **Done the same evening, on the owner's word**: every native test names the line it
ends on and ctest requires it; a test registered without one fails the configure; four canaries prove the rule
red and green (`14_TESTING` §Native unit tests; `src/native/CMakeLists.txt`). Two things it turned up: four tests
passed on a line they print in the middle of their run, and `fl_nvapi_probe` passed whatever it printed after its
branch line — a pass expression makes ctest ignore the exit code.
- ~~**No real game was run on this build.**~~ Five were, on 2026-11-13 (above): the order in which patches reach a
game changed for every game, and the five took it. **The restore under one apply has run in no real game.**
- **Two batches took 1.26 s and 0.61 s and nothing explains them** (Hogwarts Legacy, Cyberpunk 2077); the log has
no line that tells a long stop from a batch finished one patch at a time.
- **Off means off has never been exercised on a real game** (item 43 (f), now item 44 (g)); nor (c) and (h) of
item 43, which only the owner sees.
- **Valor Mortis's crash at 51 s** (twice, beta.40 and beta.44) **and Black Myth: Wukong's fault in Steam's crash
handler at every exit** are not explained. One session of each with hooking off is the comparison that is missing.
- **What item 41 left unexercised**: a configure through the FidelityFX 2.3 loader (Cyberpunk 2077 with FSR frame
generation), a game with neither library.
- **A fault while a game is closing is not seen by a hooked session** (D127: written down, not changed).
- **For the inline patches the comparison has never been re-made under the write window** (`17_HOOK_ENGINE`
§Compare-and-restore says so now): MinHook owns that window.
- **`docs/LIST_GAME_TESTED.md` is as of 2026-11-06**: refreshing it is a new copy of the ledger and the owner's review.
- **Item 40 (d)** was not exercised and the owner has not said item 40 passed. **Items 36 (d) and 37 are still open.**
- **What an empty process snapshot does to the watcher's tick in a real session** was not looked into (seen once in
a test on 2026-11-12).
- **`LIMITATIONS.md` and the accuracy statement still say the processor's, the memory's and the motherboard's
sensors "have never been read on real hardware"** — the owner's to reword. The alpha line still rests (D98).
**Owner-only:** item 44 (d), (e), (g) and what (c) felt like — **(d) is what the next release waits for**; item 45 once that release exists; the go or no on `spike-notes` §31 (one real title); one session each of Valor Mortis and
Black Myth: Wukong with hooking off; what item 41 left unexercised; item 40 (d).
+17
View File
@@ -63,6 +63,23 @@ are kept because they record what each version changed and why (owner decision D
>
> Version 2.5 (2026-09-27, 0.1.0-beta.10) adds how a tracked game's window is shown — read from Windows — and the engine build name read from an Unreal Engine game's executable. It is also the first version to say two things the software already did: it reads the **content** of a library game's executable (markers in its first 8 MB and its import table, since the detection of engines and features; and, when a session starts, the graphics-library markers in the whole file), and it reads the processor load and the memory in use (since 0.1.0-beta.3). Nothing here leaves your device, as before.
### What version 2.20 of the Privacy Policy and 2.16 of the Disclaimer changed (0.1.0-beta.47, train C)
**The part inside a game makes a call of its own** (owner decisions D132, D136, D138–D141; the wording's main
points approved with the plan of 2026-11-13). Every earlier version could say that the component reads only what a
game passes to the graphics calls it intercepts. With Advanced metrics on, in a Direct3D 12 game that had loaded
NVIDIA's driver library, it now also asks the driver, about once a second, for the driver's report of the last
frames' stages and its low-latency state. So: the **Privacy Policy** (2.20) names what a session stores of it —
durations and five switches, never a time of day, never the moment of an input — in §1's item on Advanced metrics
and in §4's list of what the component observes. The **Disclaimer** (2.16) changes three places: "What it observes
inside the game" names the report; the sentence "API arguments and nothing else" is replaced by what is true; and
§2, after the paragraph on the background thread, gains the paragraph on this call — that it is made on the game's
presenting thread, through a library the game loaded and FrameLedger never loads, that two files are kept loaded
for it, that it calls nothing that sets or delays, what ends it, and **that a call which never returned could not be
stopped**. The accuracy statement loses "PC latency (Reflex)" from "not measured at all" — end-to-end latency
still is not measured — and gains the item saying these are the driver's numbers, read from no real game when it
was written.
### What version 2.19 of the Privacy Policy changed (0.1.0-beta.45)
**Six more calls read inside the game, only while Advanced metrics is on** (train B's fourth step, owner decisions
+1
View File
@@ -54,3 +54,4 @@ Each section below lives in its own file under `docs/spike-notes/`, moved verbat
| §28 | The main line on .NET 11's release — the whole gate, and what the analyses read (2026-11-11, beta.37, D94–D96) | [`spike-notes/28-dotnet11-main.md`](spike-notes/28-dotnet11-main.md) |
| §29 | C# 15 against the checks — the canary, and where its constructs would go (2026-11-11, beta.37, D96) | [`spike-notes/29-csharp15-canary.md`](spike-notes/29-csharp15-canary.md) |
| §30 | Reflex latency per frame — the routes there are, and what each would cost; a reading, nothing run (2026-11-12, beside beta.45, D130; §M14) | [`spike-notes/30-reflex-latency.md`](spike-notes/30-reflex-latency.md) |
| §31 | Reflex route D on the harness — the driver's two getters called from an unshipped probe, against a stand-in module and the installed driver; no game touched (2026-11-13, after beta.46, D132; §M14) | [`spike-notes/31-reflex-route-d-harness.md`](spike-notes/31-reflex-route-d-harness.md) |
+2 -1
View File
@@ -173,4 +173,5 @@ route.
2. **Route C: refused.**
3. **Route E: left closed**; §G is not reopened.
The spike is `spike-notes` §31, written after 0.1.0-beta.46 is tagged.
The spike is [`spike-notes` §31](31-reflex-route-d-harness.md), run on 2026-11-13: none of the stop conditions
above fired on the harness, and it ends in the question of one real title.
@@ -0,0 +1,221 @@
## 31 · Reflex route D on the harness — the driver's two getters, called from a probe *(2026-11-13, after 0.1.0-beta.46, owner decisions D132, D133; `20_OPEN_QUESTIONS` §M14)*
**Why this was measured.** §30 read the routes to Reflex latency per frame and left one that needs no patch: the
Overlay calling the driver's two getters, `NvAPI_D3D_GetLatency` and `NvAPI_D3D_GetSleepStatus`, with the device of
the swap chain it hooks. The owner said go on 2026-11-13 (D132) — **to a spike on the harness first** — and ruled
that such a call is inside rule 4 (`CLAUDE.md`, the rule's note). This is that spike. **No shipped code changed and
no game was touched**: the call sequence lives in an unshipped probe, and nothing loaded into a game includes it.
**The instrument.** `src/native/tools/fl-probe-reflex` (built with the Overlay's flags; ctest
`fl_reflex_probe_stub` for the half a build machine can run):
- `fl_reflex_candidate.h` — what would move into the Overlay: find `nvapi64.dll` **if the process already holds
it** (never load it), ask its export `nvapi_QueryInterface` for the two getters by the ids of the vendored
`nvapi_interface.h`, call them SEH-guarded, summarise the sixty-four frames. It does not link `nvapi64.lib`:
the static library loads the DLL itself, from a trusted location and with a signature check.
- `--stub`: against `tools/vendor-stubs/stub_nvapi64.cpp`, a stand-in module with knobs for what a driver cannot be
made to do on demand.
- `--real`: against the installed driver on this PC's NVIDIA adapter, **with the probe playing the game's part** —
it loads `nvapi64.dll`, calls `NvAPI_Initialize`, and **sets latency markers on its own device** for a few
hundred frames. That is a write, and it is said here plainly: a getter has nothing to return without it, the
process is the probe's own, and no shipped binary contains the call (D108's read-only rule is about the Agent's
bridge; rule 4's note is about a game). The owner was told and approved it with the plan.
### The decision table, written before any run
| # | Measured | Outcome → consequence |
|---|---|---|
| M1 | Stub: the module absent; a getter absent; an error; a report of nothing; sixty-four reports; both device kinds | Anything called or loaded when the module is absent, or a wrong classification → the candidate is wrong and is fixed before any driver run. Otherwise: these cases are harmless as written. |
| M2 | Stub: a call that does not return for 1.5 s, made on a thread of its own and made by a thread that has other work | Made by the busy thread, that thread stands still → **the call may not be made on the Overlay's watchdog** (it supervises, installs and flushes): a thread of its own, or the presenting thread if M6 allows. A thread of its own is a second background thread, and the Disclaimer's sentence about "one" changes. |
| M3 | Real: the getters **before** `NvAPI_Initialize` | A fault → a game that holds the module but has not initialised it would fault under us, and the Overlay cannot initialise NVAPI itself (not a getter): **route D stops** unless initialisation can be known without a call. An error status → harmless: read as "not available". |
| M4 | Real: initialised, 120 frames, **no marker** | Zero frames or an error → as the header says: a game that does not use Reflex reads N/A. Frames with content → record what the driver fills in by itself. |
| M5 | Real: 300 frames **with markers** | Frames with sensible spans → the report is readable by a third party in the process. Zero frames → markers alone are not enough (a sleep mode is needed too): route D reads only games that set one, and the note says so. |
| M6 | Real: the cost of one call (2000 calls, on the presenting thread) | NFR-1 allows 1 µs a present. Once a second on the presenting thread costs `call / presents-a-second` a present: at 60 a second a call may cost 60 µs. Median within that → the presenting thread, once a second, is allowed. Above it, or a worst case over 1 ms → **never on the presenting thread**; a thread of its own (M2). |
| M7 | Real: the getters on another thread four times a second for 60 s, beside a thread that presents and sets markers | **Any fault → route D stops** (pre-committed, §30). Error statuses or empty reports → recorded; they decide whether a read is trusted. Frames a second beside the poller more than 0.5 % below alone → the rate is too high or the route too costly: lower it and measure again, or stop. |
| M8 | Real, Direct3D 12: read with the device, read with the queue, markers on each | The device works → the Overlay already holds it (`g_d3d12Device`). **Only the queue works → Direct3D 12 is out of reach**: the Overlay does not hold the queue (`ResolveApi`: `GetDevice` does not return it) and may not go looking for it. Route D would then be Direct3D 11 only. |
| M9 | Real: the unit of the report's times | The gap between two frames' `simStartTime` against the probe's own frame time. Whatever it is, is recorded; a unit that cannot be told → the spans are not shown as times. |
Not in this spike, whatever it shows: anything in a game; where the numbers would go (shared memory, the Agent, the
page); the wording of the Disclaimer and the Privacy Policy. Those are a plan of their own, after the owner's go.
### Results
**Where.** The dev box of §Environment: Windows 11 Pro build 29648, RTX 5080, NVIDIA driver 32.0.16.2114
(`nvapi64.dll` of the same version), 2026-11-13. `--stub` on software devices; `--real` three times (and a fourth,
shorter, after a fix to the probe — row M6), on the NVIDIA
adapter, each with a 256×256 composition swap chain presented without a wait — some 14,000 to 17,000 frames a
second, which is what makes the cost of anything beside it visible and is nothing like a game.
| # | What was seen | Against the table |
|---|---|---|
| M1 | Stub, all 20 checks pass: with the module absent `Resolve` says so, calls nothing and loads nothing; a module without the getters is refused whole; an error comes back as the error; a report of nothing is zero frames; sixty-four reports are read as the header lays them out; the driver is handed the device and only the device, Direct3D 11 and Direct3D 12 alike; no device, no call. | Harmless as written. |
| M2 | A call held for 1.5 s on a thread of its own: another thread ticked 16 times in its first second. The same call made by that ticking thread: **0 ticks** in the second. | **Not on the watchdog.** A thread of its own, or the presenting thread (M6). |
| M3 | The getters **before** `NvAPI_Initialize`, with the module loaded: both resolve, `GetLatency` returns `NVAPI_OK` and sixty-four empty frames. No fault, three runs. | Harmless: an uninitialised NVAPI reads as "nothing reported". |
| M4 | Initialised, 120 frames, no marker: `NVAPI_OK`, zero frames with anything; the sleep status is `NVAPI_OK` with every field zero. | As the header says. A game that does not use Reflex reads N/A, and the read costs it nothing else. |
| M5 | 300 frames with markers, **no sleep mode set**: sixty-four frames, the newest one or two ids behind the last frame drawn. Per frame the driver fills simulation end, render submit start/end, present start/end, driver end, OS queue start/end and GPU start/end; `inputSampleTime` and `driverStartTime` stay zero (the probe sets no input marker). | **Readable by a third party in the process, from markers alone.** |
| M6 | 2000 calls back to back on the presenting thread: `GetLatency` median **0.50 µs** in the three runs (mean 0.53–0.54, worst 1.2 / 1.5 / 3.0 µs) and **1.50 µs in a fourth**, made that evening after a fix to the probe, with the PC doing other things (mean 1.54, worst 70 µs); `GetSleepStatus` median 0.10 µs in all four, worst 0.7 / 0.8 / 62 / 12 µs. | **Far within NFR-1 once a second**: at 60 presents a second a call may cost 60 µs, and the medians are 0.5–1.5. **Not within it at every present**: the fourth run's median alone is over the microsecond NFR-1 allows a present, and single calls of 62 and 70 µs were seen. Once a second is what is proposed. |
| M7 | 60 s, four reads a second from another thread beside the presenting, marker-setting thread, three runs: **228 reads each, none not OK, none faulted, none empty**; worst read 103 / 112 / 248 µs on the polling thread; no marker error. Frames a second beside the poller against alone: −1.3 % (one 60 s leg against one 5 s leg), then in six alternating 10 s legs −1.4 % and −0.6 % — **with single legs between +5.9 % and −9.9 %**. | **No fault: the route does not stop.** The half-percent line cannot be read off this: the loop's own drift from leg to leg is ten times it, in both directions. So a dose was measured instead — next row. |
| M7b | The same poller **never pausing**: 38.3 million reads in 30 s (**1.28 million a second**), none not OK, none faulted, worst read 2.7 ms; frames a second −3.3 % (legs −1.1 %, −5.3 %, −3.7 %). | Three hundred thousand times the proposed rate costs about three percent of an uncapped loop. Four reads a second is that divided by 320,000: not measurable, and not half a percent. **The driver also took 38 million reads beside some three million marker calls without an error** — the concurrency §30 could only infer. |
| M8 | Direct3D 12: markers set with the **device** — no error; read with the device and read with the queue both return the same sixty-four frames; the sleep status is `NVAPI_OK` with either; markers set with the queue work as well and are read back with the device. | **The device works**, and it is the object the Overlay already holds. |
| M9 | `simStartTime` of two neighbouring frames 91 and 43 apart in two runs where the probe measured 81 and 64 µs a frame, and the absolute values are the time of day (1 794 560 148 756 529 on 2026-11-13). | **Microseconds, on the clock of the Unix epoch.** Spans are differences of two of them. |
**One thing seen that is not understood.** In the first of the three runs the newest frame of the Direct3D 11
report had a `presentEndTime` 1 844 674 519 µs — half an hour — after its own `simStartTime`; the other two runs
show 36–72 µs there, and the Direct3D 12 reads 46–51 µs every time. The frame was the newest in the report, read
within microseconds of being presented. Whatever it was, **the newest frames of a report are not final**: a reader
must not take the last few as complete, and must refuse a span that no frame can have.
### What this settles, and what it does not
- **Settled, on this driver and this adapter**: the two getters can be found without loading anything and called
with a Direct3D 11 device or the Direct3D 12 device the Overlay holds; they do not fault before initialisation,
without markers, or beside a thread that sets markers at 16,000 frames a second; a call costs half a microsecond
to a microsecond and a half;
the report is readable from markers alone and its unit is known. None of §30's stop conditions fired: no fault or
hang attributable to the call, no overhead near NFR-1, and the Direct3D 12 device is the one already held.
- **Decided by M2 and M6 together**: the call belongs on the **presenting thread, once a second** — a microsecond
or so a second, with a worst case seen of 70 µs — not on the watchdog and not on a new thread. So the Disclaimer's "one background thread"
would not change; what would change is its list of what the part inside the game does at a present.
- **Not settled, because only a game can say**: a game's own device — many threads, deferred contexts, a device a
game is about to release; what a real title's report holds (input sample, the GPU times of a real frame, frame
generation's `aiFrameTimeUs`); whether a title that uses Reflex through Streamline alone leaves `nvapi64.dll`
findable by name (not looked at); a driver other than 32.0.16.2114, and any card but this
one; a call that blocks — the stub shows what a block does to its thread, and nothing here made the driver block.
- **Not looked into**: Direct3D 11 in the Overlay, which keeps no D3D11 device today (`ResolveApi` releases it):
reading there means holding one, a reference the Overlay does not take now; and the incomplete newest frame above.
### The question for the owner
**Go to one real title, or stop here?** A go means a plan of its own before any code: the two calls in the present
detour once a second, **only while a session asks for Advanced metrics** (D111), only where the game already
loaded `nvapi64.dll`, Direct3D 12 first (the device is already held); a place for the numbers — a series beside the
frames, since a report arrives after its frame's record is written (§30); `nvapi-readonly-check` extended to the
Overlay and taught that `Sleep` is a writer; the Disclaimer's and the Privacy Policy's wording; the first run on a
title of the owner's choosing that is not inside the anti-cheat exception's trial (D38), with what each outcome
means written before it. A no leaves `nvapi.reflex.*` and `sl.reflex.*` at N/A with the reason, and this note as
the record of why it was within reach.
**Answered 2026-11-13 (owner decision D136): go, to a plan.** The title is Cyberpunk 2077. No code before the plan
is approved, and no release that carries the calls before a stop while a game runs has been exercised on
0.1.0-beta.46 (owner-only item 44 (d)).
### The leg with a sleep (owner decision D139) — the table, written before the run
The plan's review found the largest thing the runs above never touched: **no run set a sleep mode or called
`NvAPI_D3D_Sleep`**, and a game that uses Reflex does both, every frame. If the driver makes a getter wait behind
the game's sleep, a read on the presenting thread holds a present for as long as the sleep lasts. The owner said:
measure it in the probe first (D139). The probe plays the game's part once more — `NvAPI_D3D_SetSleepMode` (low
latency on, a minimum interval of 4 166 µs, markers used) and `NvAPI_D3D_Sleep` at the start of every frame, on its
own Direct3D 12 device, in its own process. **Both are writes**, as the markers were; no shipped binary contains
either, and the sleep mode is switched back off before the device is released.
| # | What is measured | What it decides |
|---|---|---|
| S1 | The sleep mode takes: `SetSleepMode` returns OK, the sleep status then reads low-latency on, and a frame takes about the interval | Not OK, or the status does not change → the leg did not exercise a sleep; said so, nothing concluded from S2–S4. |
| S2 | The two getters on the thread that sleeps and presents: one `GetLatency` after each of 2000 frames, and 2000 calls back to back | **Median above 60 µs → stop** (NFR-1 at 60 presents a second). **Any call of 2 ms or more → stop**: on a presenting thread that is the latch of D141, in every game that uses Reflex. |
| S3 | The getters on **another** thread four times a second for 20 s, and without a pause for 10 s, while the first thread sleeps and presents — against the same two runs on the same device **before** the sleep mode was set | **A fault → stop** (§30). Reads of 2 ms or more that the control does not have → the getter waits behind the sleep: **stop**, and the note says the route reads only games that do not sleep. Reads of 1 ms or more at the same rate as the control → the scheduler, not the sleep. |
| S4 | What the report holds once the game sleeps: frames with anything, and the sleep status's fields | Recorded: it is what a real title's report would look like more closely than M5's. An empty report → a sleep mode changes what markers alone gave; recorded, the reader's "nothing reported" covers it. |
A stop here means no Overlay code is written and the owner is asked again.
### The leg with a sleep — results
Three runs of `fl-probe-reflex --real 10` on 2026-11-13 (RTX 5080, driver 32.0.16.2114), the leg after R5.
**No stop condition fired.**
| # | What was seen | Reading |
|---|---|---|
| S1 | `SetSleepMode` returned OK in all three runs. A frame then took 4 159 µs (the interval asked for is 4 166), 4 037–4 041 of them inside `NvAPI_D3D_Sleep`; no sleep error. The sleep status afterwards: interval 4 166 µs, `bUseGameSleep` 1 — and **`bLowLatencyMode` 0**, although the mode was set with it on. | The sleep was exercised: the thread stood inside it 97 % of the time. **The status's low-latency field is not the flag the game set**, on this driver; why is not known. It is shown as the driver's word, never as "the game switched Reflex on". |
| S2 | One `GetLatency` after each of 2000 sleeping frames, on the thread that sleeps and presents: median **2.5 / 2.6 / 2.6 µs**, mean 2.7–2.8, worst 66.9 / 16.8 / 8.0 µs, none of 2 ms. Back to back: median 0.7 µs (worst 10.2 / 81.6 / 4.1); `GetSleepStatus` median 0.2 µs. | Far inside both limits. A read after a frame that slept costs four or five times a read made back to back — a cold cache, by the look of it — and that is the Overlay's case: **about 2.6 µs, once a second**. |
| S3 | From another thread while the first slept and presented at 240 frames a second. Four reads a second for 20 s: 80 reads a run, none not OK, none faulted, worst 64 / 82 / 12 µs (the control before the sleep mode: 92 / 209 / 119 µs). Without a pause for 10 s: **10.26 / 10.26 / 10.43 million reads**, none not OK, none faulted, worst 442 / 635 / 286 µs, **none of a millisecond** (the control: 9.97 / 9.94 / 9.89 million, worst 1 605 / 1 390 / 203 µs, one read of a millisecond in two of the three runs). | **The getter does not wait behind the sleep.** Thirty-one million reads were made while another thread was inside the sleep nearly all the time, and none took a millisecond; the slow reads there are belong to the control. |
| S4 | The report: sixty-four frames with content. `driverStartTime` is filled in all sixty-four — it was zero in M5, without a sleep mode; `inputSampleTime` in none (the probe sets no input marker). Simulation start to present end 102–151 µs, to GPU end 150–191 µs; `gpuActiveRenderTimeUs` 0. | With a sleep mode the driver span is reported. A reader that treats a zero end point as "span not reported" covers both shapes. |
**What it does not say**: a game's own sleep, on a game's own threads, with a real frame's work between the sleep
and the present; frame generation's pacer; another driver. Those are what the first real title is for (D136).
### What moving the sequence into the Overlay found (2026-11-13, the same evening)
The call sequence became `FrameLedger.Overlay/include/fl_reflex.h`, with one check the candidate did not have: that
the two addresses the module answers with are code of the module. **Run against the installed driver, that check
refused the driver.** `C:\Windows\System32\nvapi64.dll` is a shim: it answers both ids with addresses inside
`nvapi64_impl.dll`, in the driver's own store (`…\DriverStore\FileRepository\nv_dispi.inf_amd64_…`), an image of
its own. Three consequences, all in the header now:
- An address is accepted when it is **executable code of an image the process has loaded** — which still refuses
the heap, a stack and nowhere — not only when it is inside `nvapi64.dll`.
- **A reference is kept on that image too.** The addresses are code only while `nvapi64_impl.dll` stays loaded, and
what the shim does with it when a game unloads NVAPI was not looked at.
- **The note above was wrong about Control Flow Guard.** It reasoned from `nvapi64.dll`, which is not a CFG image;
the code that is called is in `nvapi64_impl.dll`, which is one (`dumpbin`: instrumented, a function table of
5 332 entries). The probe enforces CFG and has made the calls from the shipped header, so on this driver the two
getters are valid targets. A game that enforces CFG, on a driver the probe was not run against, is not covered:
a target that were not valid is a fast-fail no guard catches.
The stand-in module answers with addresses of its own, which is why the stub leg could not find this; only the
real run could. The probe's `--real` now prints the image each address lies in.
### A run on a busy PC, and what it says about the 2 ms latch (D141)
The run that confirmed the corrected header (`Resolve` OK, the reads as before) was made while a native build and an
injected test ran on the same PC — the probe's own loop made 9 000 frames a second where it had made 16 000. It is
the only run so far that was not alone, and it is the nearer one to a game:
| | Alone (three runs) | Busy (one run) |
|---|---|---|
| `GetLatency` after a sleeping frame, on the thread that sleeps and presents (2000 reads) | median 2.5–2.6 µs, worst 8–67 µs | median 3.4 µs, worst 130 µs, none of 2 ms |
| From another thread without a pause, while the first sleeps: reads of 1 ms or more / of 2 ms or more | 0 / 0 in 10.3 million | **536 / 25 in 2.9 million**, worst 3.5 ms |
| The same before the sleep mode was set | 1 / 0 in 9.9 million | 6 / 2 in 3.2 million, worst 2.2 ms |
| Four reads a second for 20 s | worst 12–82 µs | worst 110 µs, none of 1 ms |
**A reading, not a measurement of a game**: a thread that does nothing but call is taken off its processor now and
then on a busy PC, and a read that was under way then is as long as the pause. Twenty-five such pauses of 2 ms or
more in ten seconds of calling is 2.5 a second; a read of 3 µs made once a second is inside one of them about once
in a hundred thousand reads. **So the latch of D141 will, on a busy PC, sometimes switch the read off for a pause
that was Windows' and not the driver's** — of the order of a few sessions in a hundred, for sessions of two hours,
if a game's presenting thread is paused as often as this probe's poller was; a presenting thread usually is not.
The session then says *stopped: slow* with the microseconds, and the next start of the game reads again. That is the
trade the owner chose with D141 (one call, not two): it errs towards the game. The number published with the state
is what tells the two apart afterwards — a driver that holds a call does it again and for longer; a pause is a few
milliseconds, once.
**The owner was asked again with this table in hand and kept D141 as it is: one call** (2026-11-13).
### The first real game (2026-11-14, 0.1.0-beta.47, the owner's sessions 208–210)
Phantom Blade Zero, Direct3D 12, three sessions — frame generation ×3, then off twice. What only a game could say,
and now has for one title on this driver:
- **The game's own device is the one the driver takes**, and `nvapi64.dll` is findable by name in a game that uses
Reflex through Streamline: resolved four to five seconds after the attach, the shim in System32 and the getters
in `nvapi64_impl.dll`.
- **No latch fired in 1 515 seconds of reading**: the slowest call was 24, 20 and 45 µs, under a game's real load
and with frame generation's pacer running. The busy-PC reading above put a false latch at a few sessions in a
hundred at worst; three sessions cannot confirm or deny that.
- **The report is real**: with frame generation ×3 the total is 23 ms; without it, 5.4 ms at 149 presents a second
and 15.9 ms at 67. `inputSampleTime` is not read; `driverStartTime` is reported (the driver series has points).
- **The sleep status' low-latency switch reads on in a game** (on at times, off at others) — it never did for the
probe. And the driver's `fgMultiplier` read 3 in the session FrameLedger measured at ×3.0.
- **`gpuRenderStartTime` lies before `simStartTime` in this game**: start to end is 16.4 ms where simulation start
to GPU end is 5.4 ms. The span includes whatever the GPU did before this frame's simulation began — it reads
like the interval between two frames' GPU ends. The header's `gpuActiveRenderTimeUs` is the active time and is
not read by FrameLedger. The probe could not show this: its frames have no GPU work to speak of.
Not said by these sessions: ~~Cyberpunk 2077 (REDengine's own NVAPI use)~~, a game that enforces Control Flow
Guard, another driver, and whether the player feels the read.
**Cyberpunk 2077, the same morning (sessions 211 and 212).** Frame generation ×2 for 105 s of the first, off in
the second at 238 FPS. Read in both; the slowest call 34 and 65 µs; a report in 97 % and 98 % of the samples.
- **The spans are sane there**: total 11.7 ms at 238 FPS, GPU render 2.7 ms, never longer than the total (0 of
429 samples). With frames generated the total is 13.5 ms; in the menus 4.1 ms. So `gpuRenderStartTime` before
`simStartTime` is Phantom Blade Zero's, where *GPU render* sits at 16.4 ms whether the game presents 149 or 67
times a second.
- **`fgMultiplier` read 1 in the session that generated ×2**: the word carries the last value, and the session
ended in a menu. The table needs the values seen, not the last one.
- **Samples are 1.32 s apart** (the Agent's `t_ms`), reads one second apart: a read is not always the one sampled.
- **Left alone as designed**: two Direct3D 11 games (state 1, one line) and a Direct3D 12 game that never loaded
`nvapi64.dll` (state 2, said once, asked again each second without a line).
**The owner's ruling on the span (2026-11-14): read the driver's active time** — `gpuActiveRenderTimeUs`, which
the header defines as the same interval "excluding the idles in between", and with it `gpuFrameTimeUs`. Both are
members of the report already fetched.
+1 -1
View File
@@ -22,7 +22,7 @@ The link under them, *Read what the hook does and does not do*, opens the safety
| **Minimum session length (s)** | A shorter session is not kept. 5 to 600 seconds. *Agent.* | 30 |
| **Sensor interval (ms)** | How often the PC's sensors are read during a session. 500 to 2000 ms. *Agent.* | 1000 |
| **Raw series kept per game** | How many of each game's newest sessions keep their per-frame data; older ones keep their statistics. 0 keeps everything. *Agent.* | 20 |
| **Advanced metrics** | Reads more from the graphics driver and the hardware sensors during a session — the graphics card's memory and load in detail, each fan and voltage, what your display can do, the driver's settings for the game — and stores it with the session. Off: nothing more is read or stored. It applies from the next session; a session recorded while it was off is not filled in later. While it is on, the **Advanced** page is in the list on the left ([Advanced metrics](12-advanced-metrics.md)). *Agent.* | Off |
| **Advanced metrics** | Reads more from the graphics driver and the hardware sensors during a session — the graphics card's memory and load in detail, each fan and voltage, what your display can do, the driver's settings for the game — and stores it with the session. In a game FrameLedger measures from inside it also reads what the game tells DLSS, Streamline and FSR, and — on an NVIDIA card, in a Direct3D 12 game that uses NVIDIA's library — asks the graphics driver about once a second how long each stage of a frame took ([Advanced metrics](12-advanced-metrics.md)). Off: nothing more is read or stored. It applies from the next session; a session recorded while it was off is not filled in later. While it is on, the **Advanced** page is in the list on the left ([Advanced metrics](12-advanced-metrics.md)). *Agent.* | Off |
## Data
+30
View File
@@ -83,6 +83,33 @@ the session says, for each call, whether it was *read*, *hooked — the game did
the game did not load the library that has the call*; the six calls of 0.1.0-beta.45 are named in one sentence,
under which of the three happened to each.
### What NVIDIA's driver says about each frame's stages
On an NVIDIA card, in a **Direct3D 12** game that uses **NVIDIA Reflex**, a session with Advanced metrics on also
stores the driver's own latency report: how long the driver says each stage of a frame took — *simulation*,
*render submit*, *present*, *driver*, *operating system's render queue*, *GPU render*, and the *total* from the start
of simulation to the end of the graphics card's work. They are seven lines under **Latency**, one point about every
second, each the average of the frames the driver reported since the point before, in microseconds. A table beside
them shows the driver's low-latency state as five switches, by NVIDIA's own names, each *On*, *Off* or *On at times,
off at others*.
Three things to know about them:
- **They are the driver's numbers, not FrameLedger's.** FrameLedger does not measure these stages; it stores what
the driver reports and has not checked it against another tool. They are not the delay from a click to the screen.
- **FrameLedger asks for them from inside the game**, about once a second — the one thing it does in a game that is
not reading what the game itself passes along. It asks only through NVIDIA's library where the game had already
loaded it, and never loads that library itself. A copy of the library sitting in the game's own folder (some
mods put one there) is not the driver's, and FrameLedger does not use it.
- **It switches itself off rather than disturb the game.** If one request takes two thousandths of a second or
more, or goes wrong, FrameLedger makes no further request until the game is closed. The line under the session
then says *stopped*, and why; the next time the game starts it reads again. On a busy PC this can happen for a
pause that was Windows' and not the driver's.
The line under the session says what happened: *read*; *asked, and the driver reported no frame* (the game does not
use Reflex); *not read* with the reason — the game does not present through Direct3D 12, it has not loaded NVIDIA's
library, or that library is in the game's own folder; or *stopped*.
**Many games will show nothing here**, and the line under the session says why: *the game made none of the calls
these are read from* — most games set their DLSS options through a call FrameLedger cannot see, and only games that
use FSR 3.1 or later through AMD's own library show the FSR rows — or *the session was not measured inside the game*.
@@ -111,6 +138,9 @@ comes from, and whether it is read. Where it is not, the reason is written out:
- **not present on this PC** — the driver's own figures exist on NVIDIA cards only;
- **read inside a game FrameLedger measures, when the game makes the call** — what the game tells DLSS and FSR
(above). Some further readings inside the game **come with a later release**;
- **read inside a game FrameLedger measures, from the graphics driver** — NVIDIA's latency report (above);
- **not read: it would take a patch at an address found while the game runs, or a call the vendor forbids from
outside the game's own threads** — what the game asked of Reflex, and Reflex's state through Streamline;
- **the game makes this call once, before FrameLedger is inside it** — what the game started Streamline with. It is
not read, and no later release will read it;
- **never read** — a serial number, a display's identification data, which other programs are encoding, the camera's
+9 -2
View File
@@ -12,7 +12,7 @@
HTML comments are not part of the block.
-->
> ⚠ **What FrameLedger actually measures today — 2026-11-11.** The software is a beta; its latest
> **beta is `0.1.0-beta.45`** (2026-11-12), an unsigned installer built from that tag with its
> **beta is `0.1.0-beta.47`** (2026-11-14), an unsigned installer built from that tag with its
> checksums published beside it (alphas — experimental builds that try a newer .NET — are published apart). The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -86,8 +86,15 @@
> mean, median and peak. The game's other processes (launchers, helpers) are not counted.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** the video-memory budget Windows gives a game, which frame
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
> spikes were shader compilation, end-to-end PC latency, and HDR. Stutter count and stutter time are
> measured from frame times.
> - **NVIDIA's latency report (only with Advanced metrics on; Direct3D 12; a game that uses NVIDIA Reflex):** how
> long the driver says each stage of a frame took — simulation, render submit, present, driver, the operating
> system's queue, the graphics card — read from the graphics driver about once a second and shown as the driver
> reported it: **the driver's numbers, not a measurement by FrameLedger**, an average of the frames of one read,
> never checked against another tool, and not the delay from a click to the screen. Read with a test program
> against one driver and one card; **no real game had been read when this was written**. A game that does not use
> Reflex has none. The session summary's latency fields stay N/A.
> - **Pacing, VSync and the graphics card (since beta.14):** the share of the time below 30 FPS, below 60 FPS and below
> the monitor's refresh rate, measured from frame times with small margins so that a game held at its limit is not
> counted as below it (a rate less than 2 % under the line reads partly as at it), and how much one frame's time
+17 -6
View File
@@ -1,6 +1,6 @@
# FrameLedger — Disclaimer
**Version:** 2.15 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.16 · **Effective:** {{RELEASE_DATE}}
## 0. This is pre-release software
@@ -43,11 +43,11 @@ Be precise about what that does and does not promise, because the shorter versio
Install it somewhere only you can write to, and verify the published SHA-256 checksums.
**What it observes inside the game:** arguments the game passes to graphics APIs we intercept (presentation, upscaling, ray tracing, pipeline creation).
**What it observes inside the game:** arguments the game passes to graphics APIs we intercept (presentation, upscaling, ray tracing, pipeline creation) — and, only while Advanced metrics is on, one thing that is not an argument: the graphics driver's own report of how long the stages of the game's last frames took, which the component asks NVIDIA's driver for itself (§2 says exactly how).
**What it reads about the game from outside it, in every session:** the game process's own memory use — its dedicated and shared video memory and its working sets, the figures Windows' Task Manager shows — from Windows' performance counters and process-memory information. For a game it does not inject into, FrameLedger opens the game's process for this with the least access Windows offers, once a second, and closes it again; it reads nothing inside the process.
> **What of that list is observed today is stated once, in §4 below** (the block `legal/ACCURACY.md` carries, dated). The list here describes what the software is designed to observe, and the boundary — API arguments and nothing else — holds for all of it.
> **What of that list is observed today is stated once, in §4 below** (the block `legal/ACCURACY.md` carries, dated). The list here describes what the software is designed to observe, and the boundary — API arguments, and the one report asked of the graphics driver that the line above names; nothing of the game's own memory — holds for all of it.
**What it never does:** read or write the game's memory outside those API arguments; read save files, input, chat, or network traffic; modify game behavior; hide itself from any security software; or install a kernel driver of its own.
@@ -72,7 +72,11 @@ FrameLedger is designed to reduce that risk substantially:
the game exits.
- FrameLedger contains **no evasion techniques of any kind** — it does not hide, rename, obfuscate, or disguise itself. It is intended to be plainly identifiable to any security software that looks.
For completeness about what it *does* run inside the game: besides the intercepted calls themselves, the component starts **one background thread**. It wakes once a second, or when the game loads a library, and then: checks FrameLedger's own shared memory for a request to stop and for the heartbeat of the safety scan described above; asks Windows, by name, whether the graphics, upscaling and frame-generation libraries it knows about are loaded, and puts its interception into the ones that are (for ray tracing it creates one command list on the game's own Direct3D 12 device, to find the functions to intercept); writes its counters to FrameLedger's shared memory; and writes FrameLedger's own log file. It does not scan the game's memory, list the modules or processes on the system, or query Windows services — deliberately, because software that does those things from inside a game process looks like the thing this tool is trying not to be mistaken for.
For completeness about what it *does* run inside the game: besides the intercepted calls themselves, the component starts **one background thread**. It wakes once a second, or when the game loads a library, and then: checks FrameLedger's own shared memory for a request to stop and for the heartbeat of the safety scan described above; asks Windows, by name, whether the graphics, upscaling and frame-generation libraries it knows about are loaded, and puts its interception into the ones that are (for ray tracing it creates one command list on the game's own Direct3D 12 device, to find the functions to intercept); writes its counters to FrameLedger's shared memory; and writes FrameLedger's own log file.
**One call it makes itself, into the graphics driver — only while Advanced metrics is on.** In a Direct3D 12 game that had already loaded NVIDIA's driver library (`nvapi64.dll`), the component asks that library — by name, among what the game loaded; it never loads it — for two of the driver's read-only functions, and keeps the library and the driver file those functions are in from being unloaded for as long as the game runs. Then, about once a second, **on the game's own thread that presents its frames**, right after a frame has been handed over, it calls them: one returns the driver's report of how long the stages of the last frames took, the other the driver's low-latency state. It calls no function that sets, marks or delays anything. A library of that name sitting in the game's own folder is not the driver's and is not called. What this costs the game is the length of that call, once a second — a few millionths of a second where it was measured. A call that faults is caught, counted once, and not repeated; a call that takes two thousandths of a second or more is the last one until the game is closed. **A call that never returns would hold the game's presenting thread, and FrameLedger cannot stop it** — it has not happened in any test, and it is said here because it is the one thing in this component whose length FrameLedger's own code does not bound. With Advanced metrics off — the default — none of this happens.
It does not scan the game's memory, list the modules or processes on the system, or query Windows services — deliberately, because software that does those things from inside a game process looks like the thing this tool is trying not to be mistaken for.
- FrameLedger injects into a game only after you enable that game individually. For every other game — and for any game where the safety checks refuse — it records the session's start, end and duration together with whatever hardware sensor readings your machine provides and the game's own memory use as Windows reports it (§1), and reports every other measurement as not available. **There is no measurement mode that works without injecting**; an earlier version of this document described one, and it was never built. FrameLedger never estimates a value it could not measure, and it always shows which of the two modes produced a session. Neither mode requires administrator rights.
**However, these protections cannot be complete:**
@@ -121,7 +125,7 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
<!-- accuracy-block:begin -->
> ⚠ **What FrameLedger actually measures today — 2026-11-11.** The software is a beta; its latest
> **beta is `0.1.0-beta.45`** (2026-11-12), an unsigned installer built from that tag with its
> **beta is `0.1.0-beta.47`** (2026-11-14), an unsigned installer built from that tag with its
> checksums published beside it (alphas — experimental builds that try a newer .NET — are published apart). The source holds the desktop app
> (library, store import, charts, settings) and the background Agent, which records a session when a
> game in the library runs (unless you switched its recording off), injects only into games you enabled
@@ -195,8 +199,15 @@ Frame timing is derived from high-resolution timestamps taken at the moment the
> mean, median and peak. The game's other processes (launchers, helpers) are not counted.
> - **Video memory:** in use on the whole graphics card, recorded from Windows and GPU-driver telemetry
> and charted. **Not measured at all:** the video-memory budget Windows gives a game, which frame
> spikes were shader compilation, PC latency (Reflex), and HDR. Stutter count and stutter time are
> spikes were shader compilation, end-to-end PC latency, and HDR. Stutter count and stutter time are
> measured from frame times.
> - **NVIDIA's latency report (only with Advanced metrics on; Direct3D 12; a game that uses NVIDIA Reflex):** how
> long the driver says each stage of a frame took — simulation, render submit, present, driver, the operating
> system's queue, the graphics card — read from the graphics driver about once a second and shown as the driver
> reported it: **the driver's numbers, not a measurement by FrameLedger**, an average of the frames of one read,
> never checked against another tool, and not the delay from a click to the screen. Read with a test program
> against one driver and one card; **no real game had been read when this was written**. A game that does not use
> Reflex has none. The session summary's latency fields stay N/A.
> - **Pacing, VSync and the graphics card (since beta.14):** the share of the time below 30 FPS, below 60 FPS and below
> the monitor's refresh rate, measured from frame times with small margins so that a game held at its limit is not
> counted as below it (a rate less than 2 % under the line reads partly as at it), and how much one frame's time
+3 -3
View File
@@ -1,6 +1,6 @@
# FrameLedger — Privacy Policy
**Version:** 2.19 · **Effective:** {{RELEASE_DATE}}
**Version:** 2.20 · **Effective:** {{RELEASE_DATE}}
**Short version: everything stays on your PC. FrameLedger has no accounts, no telemetry, no analytics, and never uploads your data anywhere.**
@@ -11,7 +11,7 @@ Stored in `%LOCALAPPDATA%\FrameLedger` on your device:
- Your game library entries (names, executable paths, metadata you or the app filled in, and whether each one is recorded).
- Images you choose for a game (Edit…), copied into the `covers` folder; choosing the store's image again, or removing the game together with its sessions, deletes the copy. Artwork a store's app keeps on your PC, or a game ships in its own folder, is shown from where it is and not copied.
- Performance sessions: frame timing series, computed statistics, hardware sensor series (temperatures, load, power, memory usage, and the graphics card's clock speeds, fan speed, memory temperature and whether its power limit or heat held it back), the game's own memory use (its dedicated and shared video memory, private working set, working set and commit, once a second), session duration, crash flags, the graphics driver's settings the game ran under (NVIDIA only), how the game's window was shown (full-screen, borderless or windowed, for how long, its size and the monitor's), tags and notes you write.
- **Only while Settings ▸ Advanced metrics is on** (it is off unless you switch it on), with each session: more hardware sensor series — the graphics card's memory use in detail, its load by part, its clocks, voltages, currents, power, each fan and its video encoder's use; and, when the capture agent runs as administrator with PawnIO installed, the processor's temperatures, load, clocks, power and voltages by core, the memory in use and its modules' temperatures, and the motherboard's temperatures, fans and voltages — and a description of the hardware: the graphics card's firmware version, architecture, bus and memory sizes, the graphics driver's package and the chipset it names, the motherboard's and the memory modules' model names, what each connected display can do (the HDR formats it accepts, its brightness range, variable refresh), whether variable refresh was in use on the display the game ran on and the colour space the game presented in, and the graphics driver's settings — its global ones and the ones it holds for the game (NVIDIA only). For a game FrameLedger injects into, a session then also stores what the game itself passed to its upscaler in the calls FrameLedger intercepts: the output size, the model presets and the exposure values it gave DLSS, whether it said its colour buffers are HDR, auto-exposure and alpha upscaling; and the sharpening, the size of the jitter, the exposure, the depth range, the lowest and highest field of view and the flags it gave FSR, the frame time it reported to FSR, and FSR's own video memory when the game asked for it; what the game told NVIDIA Streamline about each frame — the size of the jitter, the motion-vector scale, the depth range and whether depth is inverted, the lowest and highest field of view, the aspect ratio, whether the projection is orthographic, how its motion vectors are stored and how often it reset the upscaler's history; and how it configured FSR frame generation — on or off, whether it may run asynchronously, its flags, whether only generated frames are presented, and the rectangle it generates in; and what NVIDIA Streamline answered when the game asked it about a feature — which features the game asked about, the version of each and of its NGX model, and what each requires: the graphics APIs it supports, whether V-Sync must be off and hardware-accelerated GPU scheduling on, how many processor threads, viewports and buffers, and the versions of Windows and of the graphics driver that Streamline found beside the ones the feature needs ; and, for each Streamline feature the game asks about or controls: whether Streamline answers that it is supported, whether it is loaded, whether the game switched it on or off while it ran, and how many times its resources were allocated and freed; and whether the game shut Streamline down, and how many times — never the lists Streamline's answer points to (the buffers' names, the names of Vulkan extensions and features), never what identifies the graphics card that the game hands over with its question, never the content of a graphics resource, and never where the game's camera is, which way it looks, or its matrices. No serial number, no display identification data (EDID) and no list of other programs is read or stored. Switching the option off stops the reading, inside a game as well; what earlier sessions stored stays with them until you delete those sessions.
- **Only while Settings ▸ Advanced metrics is on** (it is off unless you switch it on), with each session: more hardware sensor series — the graphics card's memory use in detail, its load by part, its clocks, voltages, currents, power, each fan and its video encoder's use; and, when the capture agent runs as administrator with PawnIO installed, the processor's temperatures, load, clocks, power and voltages by core, the memory in use and its modules' temperatures, and the motherboard's temperatures, fans and voltages — and a description of the hardware: the graphics card's firmware version, architecture, bus and memory sizes, the graphics driver's package and the chipset it names, the motherboard's and the memory modules' model names, what each connected display can do (the HDR formats it accepts, its brightness range, variable refresh), whether variable refresh was in use on the display the game ran on and the colour space the game presented in, and the graphics driver's settings — its global ones and the ones it holds for the game (NVIDIA only). For a game FrameLedger injects into, a session then also stores what the game itself passed to its upscaler in the calls FrameLedger intercepts: the output size, the model presets and the exposure values it gave DLSS, whether it said its colour buffers are HDR, auto-exposure and alpha upscaling; and the sharpening, the size of the jitter, the exposure, the depth range, the lowest and highest field of view and the flags it gave FSR, the frame time it reported to FSR, and FSR's own video memory when the game asked for it; what the game told NVIDIA Streamline about each frame — the size of the jitter, the motion-vector scale, the depth range and whether depth is inverted, the lowest and highest field of view, the aspect ratio, whether the projection is orthographic, how its motion vectors are stored and how often it reset the upscaler's history; and how it configured FSR frame generation — on or off, whether it may run asynchronously, its flags, whether only generated frames are presented, and the rectangle it generates in; and what NVIDIA Streamline answered when the game asked it about a feature — which features the game asked about, the version of each and of its NGX model, and what each requires: the graphics APIs it supports, whether V-Sync must be off and hardware-accelerated GPU scheduling on, how many processor threads, viewports and buffers, and the versions of Windows and of the graphics driver that Streamline found beside the ones the feature needs ; and, for each Streamline feature the game asks about or controls: whether Streamline answers that it is supported, whether it is loaded, whether the game switched it on or off while it ran, and how many times its resources were allocated and freed; and whether the game shut Streamline down, and how many times — never the lists Streamline's answer points to (the buffers' names, the names of Vulkan extensions and features), never what identifies the graphics card that the game hands over with its question, never the content of a graphics resource, and never where the game's camera is, which way it looks, or its matrices. For a Direct3D 12 game that had itself loaded NVIDIA's driver library, a session also stores what the graphics driver reports about the game's frames when FrameLedger asks it, about once a second, from inside the game: how long each stage of a frame took — simulation, render submit, present, the driver, the operating system's queue and the graphics card, and the whole from the start of simulation to the end of the graphics card's work — as averages in microseconds, and the driver's low-latency state (five switches it reports, and its frame-generation multiplier) — never a time of day, and never the moment the player pressed anything. No serial number, no display identification data (EDID) and no list of other programs is read or stored. Switching the option off stops the reading, inside a game as well; what earlier sessions stored stays with them until you delete those sessions.
- A hardware snapshot per session (CPU/GPU model, driver version, RAM size, OS build, display mode) used for the "what changed between sessions" feature.
- App settings, logs (rotated daily — the app keeps 7 days, the capture agent 14 — including the logs written by the component loaded into games), and, after a crash of the app itself, crash dump files.
- Which games you enabled code injection for, and when you consented.
@@ -43,7 +43,7 @@ An exported session (CSV or JSON) and a bug report can contain your games' names
## 4. What the app can technically observe
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; whether a game you enabled hooking for runs in an app container, and which of Windows' code-protection settings it runs under (for example, accepting only Microsoft-signed code), read from Windows before any injection; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation) — and, only while Advanced metrics is on, more of the parameters of the upscaling calls, and the parameters of ten further calls it begins to intercept in a game only once a session with that option on has started there (the constants the game gives NVIDIA Streamline for each frame, the game's configuration of FSR frame generation, Streamline's answers to the game's four questions about a feature — which version it is, what it requires, whether it is supported and whether it is loaded — and the game switching a feature on or off, allocating and freeing its resources, and shutting Streamline down), which are then stored with the session (sizes, presets, exposure, sharpening, the jitter's size, the motion-vector scale, the depth range, the range of the field of view, flags, the reported frame time, the upscaler's own memory, how frame generation is configured, the versions and requirements of Streamline's features, whether each is supported and loaded, and how often the game switched it, allocated and freed its resources and shut Streamline down), never the camera's position, direction or matrices, and never what identifies the graphics card; the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured, the version information of its upscaling, frame-generation and neural-rendering libraries, and whether each was loaded from the game's folder or from the graphics driver's own copy (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling and neural-rendering libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), the version marks an engine keeps in its own files (Unity's player library and the header of its data file, the header of a Godot data pack, an RPG Maker game's title, core script and Game.ini, the library Game.ini names, and the version file of a Ren'Py game's engine), and the store files that name it (Steam's and GOG's, on your disk) and, for a game the Xbox app or the Microsoft Store installed, the package files in its install folder that describe it (`MicrosoftGame.config` and `appxmanifest.xml`) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the lists of installed games that the Steam, GOG GALAXY, Epic Games and itch apps keep on your disk, and where GOG GALAXY is installed, the folders the Xbox app installs games into on each drive (named by the `.GamingRoot` file at the drive's root) with each game's package files, and Windows' answer to whether that game's package is installed for you — read when you import your library and when you press Play, to find the store that installed a game and hand the game to that store's app — Steam's and GOG GALAXY's also when you open a game's page, to find the artwork their apps keep for it; the cover and banner images that the Steam and GOG GALAXY apps keep on your disk for a game in your library and the logo and splash-screen images a game from the Xbox app ships in its own folder — read to show them on its page, never copied or sent anywhere; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; and — only while Advanced metrics is on — that driver's description of the graphics card and of each connected display, what it reports about the display a tracked game's window is on, its settings for a tracked game and its global ones (read only), and, when the capture agent runs as administrator with PawnIO installed, the sensors and model names of the processor, the memory and the motherboard (never a drive's), all of which areLine truncated
To do its job, FrameLedger observes: which of *your tracked* executables — the entries in your library whose recording is on — are running, and their process trees; whether a game you enabled hooking for runs in an app container, and which of Windows' code-protection settings it runs under (for example, accepting only Microsoft-signed code), read from Windows before any injection; the parameters your games pass to the graphics APIs it intercepts (presentation, upscaling, ray tracing, pipeline creation) — and, only while Advanced metrics is on, more of the parameters of the upscaling calls, and the parameters of ten further calls it begins to intercept in a game only once a session with that option on has started there (the constants the game gives NVIDIA Streamline for each frame, the game's configuration of FSR frame generation, Streamline's answers to the game's four questions about a feature — which version it is, what it requires, whether it is supported and whether it is loaded — and the game switching a feature on or off, allocating and freeing its resources, and shutting Streamline down), which are then stored with the session (sizes, presets, exposure, sharpening, the jitter's size, the motion-vector scale, the depth range, the range of the field of view, flags, the reported frame time, the upscaler's own memory, how frame generation is configured, the versions and requirements of Streamline's features, whether each is supported and loaded, and how often the game switched it, allocated and freed its resources and shut Streamline down), never the camera's position, direction or matrices, and never what identifies the graphics card; and — only while Advanced metrics is on, only in a Direct3D 12 game that had itself loaded NVIDIA's driver library — the graphics driver's own report of the game's last frames and its low-latency state, which the component asks that driver for itself about once a second (it makes that call; the game does not), keeping only how long each stage took; the memory use of a tracked game's process — its dedicated and shared video memory, from Windows' GPU performance counters, and its working sets and commit, from Windows' process-memory information, for which a game it does not inject into is opened with the least access Windows offers and closed again (never its memory's content); loaded module names of a game being captured, the version information of its upscaling, frame-generation and neural-rendering libraries, and whether each was loaded from the game's folder or from the graphics driver's own copy (for detection and for the anti-cheat safety check); the names of the files in each library game's install folder, the version information of its executable and of the upscaling and neural-rendering libraries it ships, the content of its executable file (the markers of the engine and of the graphics libraries it carries, the libraries it imports, and the engine build name an Unreal Engine game carries), the version marks an engine keeps in its own files (Unity's player library and the header of its data file, the header of a Godot data pack, an RPG Maker game's title, core script and Game.ini, the library Game.ini names, and the version file of a Ren'Py game's engine), and the store files that name it (Steam's and GOG's, on your disk) and, for a game the Xbox app or the Microsoft Store installed, the package files in its install folder that describe it (`MicrosoftGame.config` and `appxmanifest.xml`) — to detect its engine, its engine version and its features and to check it for anti-cheat before any injection is possible; the lists of installed games that the Steam, GOG GALAXY, Epic Games and itch apps keep on your disk, and where GOG GALAXY is installed, the folders the Xbox app installs games into on each drive (named by the `.GamingRoot` file at the drive's root) with each game's package files, and Windows' answer to whether that game's package is installed for you — read when you import your library and when you press Play, to find the store that installed a game and hand the game to that store's app — Steam's and GOG GALAXY's also when you open a game's page, to find the artwork their apps keep for it; the cover and banner images that the Steam and GOG GALAXY apps keep on your disk for a game in your library and the logo and splash-screen images a game from the Xbox app ships in its own folder — read to show them on its page, never copied or sent anywhere; the size, position and state of a tracked game's window and the monitor it is on, read from Windows and not from the game, and — for a game FrameLedger injects into — whether the game asked for exclusive full-screen; the NVIDIA driver's settings for your tracked executables (read only: the DLSS and frame-generation overrides the NVIDIA App set); hardware sensor values from your graphics driver's own libraries; and — only while Advanced metrics is on — that driver's description of the graphLine truncated
It does **not** read game memory outside those API parameters, and does not read game saves, chat, input content, network traffic, or anything unrelated to performance measurement. It records only for programs you added to your library and did not switch recording off for — a program whose recording is off is not watched at all — and injects only into games you individually enabled.
+63
View File
@@ -263,6 +263,7 @@ public static class Strings
nameof(Advanced_Facts_Header),
nameof(Advanced_Header),
nameof(Advanced_InGameCallsLine),
nameof(Advanced_InGameDriverLine),
nameof(Advanced_InGameFeatureCallsLine),
nameof(Advanced_InGameLine),
nameof(Advanced_InGameMoreCallsLine),
@@ -286,12 +287,24 @@ public static class Strings
nameof(Advanced_State_Viewer),
nameof(Advanced_State_Waiting),
nameof(Advanced_Status_InGame),
nameof(Advanced_Status_InGameDriver),
nameof(Advanced_Status_Read),
nameof(Advanced_Status_Readable),
nameof(Advanced_Status_SourceSilent),
nameof(Advanced_Tab_Machine),
nameof(Advanced_Tab_Session),
nameof(Advanced_Tab_Sources),
nameof(AdvDriverRead_Error),
nameof(AdvDriverRead_Faulted),
nameof(AdvDriverRead_NoDirect3D12),
nameof(AdvDriverRead_NoGetter),
nameof(AdvDriverRead_NoModule),
nameof(AdvDriverRead_NothingReported),
nameof(AdvDriverRead_Read),
nameof(AdvDriverRead_Refused),
nameof(AdvDriverRead_Slow),
nameof(AdvDriverRead_Stalled),
nameof(AdvDriverRead_Unknown),
nameof(AdvGroup_Board),
nameof(AdvGroup_Cpu),
nameof(AdvGroup_Display),
@@ -322,6 +335,7 @@ public static class Strings
nameof(AdvReach_NotInHeaders),
nameof(AdvReach_PlayerState),
nameof(AdvReach_Refused),
nameof(AdvReach_RefusedRoute),
nameof(AdvReach_Spike),
nameof(AdvScope_MachineFact),
nameof(AdvScope_Series),
@@ -340,10 +354,12 @@ public static class Strings
nameof(AdvToken_discrete),
nameof(AdvToken_dolby_vision),
nameof(AdvToken_draw_debug_view),
nameof(AdvToken_driver),
nameof(AdvToken_driver_default),
nameof(AdvToken_edr),
nameof(AdvToken_fpci),
nameof(AdvToken_game_ready),
nameof(AdvToken_gpu_render),
nameof(AdvToken_gsync_module),
nameof(AdvToken_hdr10),
nameof(AdvToken_hdr10_plus),
@@ -360,13 +376,18 @@ public static class Strings
nameof(AdvToken_off),
nameof(AdvToken_on),
nameof(AdvToken_on_and_off),
nameof(AdvToken_os_queue),
nameof(AdvToken_pci),
nameof(AdvToken_pci_express),
nameof(AdvToken_present),
nameof(AdvToken_render_submit),
nameof(AdvToken_rtx_new_feature),
nameof(AdvToken_rtx_production),
nameof(AdvToken_scrgb_linear),
nameof(AdvToken_simulation),
nameof(AdvToken_srgb),
nameof(AdvToken_studio),
nameof(AdvToken_total),
nameof(AdvToken_ulmb),
nameof(AdvToken_usable_now),
nameof(AdvToken_user_set),
@@ -2006,6 +2027,8 @@ public static class Strings
public static string Advanced_InGameCallsLine => ResourceManager.GetString(nameof(Advanced_InGameCallsLine), Culture) ?? nameof(Advanced_InGameCallsLine);
public static string Advanced_InGameDriverLine => ResourceManager.GetString(nameof(Advanced_InGameDriverLine), Culture) ?? nameof(Advanced_InGameDriverLine);
public static string Advanced_InGameFeatureCallsLine => ResourceManager.GetString(nameof(Advanced_InGameFeatureCallsLine), Culture) ?? nameof(Advanced_InGameFeatureCallsLine);
public static string Advanced_InGameLine => ResourceManager.GetString(nameof(Advanced_InGameLine), Culture) ?? nameof(Advanced_InGameLine);
@@ -2052,6 +2075,8 @@ public static class Strings
public static string Advanced_Status_InGame => ResourceManager.GetString(nameof(Advanced_Status_InGame), Culture) ?? nameof(Advanced_Status_InGame);
public static string Advanced_Status_InGameDriver => ResourceManager.GetString(nameof(Advanced_Status_InGameDriver), Culture) ?? nameof(Advanced_Status_InGameDriver);
public static string Advanced_Status_Read => ResourceManager.GetString(nameof(Advanced_Status_Read), Culture) ?? nameof(Advanced_Status_Read);
public static string Advanced_Status_Readable => ResourceManager.GetString(nameof(Advanced_Status_Readable), Culture) ?? nameof(Advanced_Status_Readable);
@@ -2064,6 +2089,28 @@ public static class Strings
public static string Advanced_Tab_Sources => ResourceManager.GetString(nameof(Advanced_Tab_Sources), Culture) ?? nameof(Advanced_Tab_Sources);
public static string AdvDriverRead_Error => ResourceManager.GetString(nameof(AdvDriverRead_Error), Culture) ?? nameof(AdvDriverRead_Error);
public static string AdvDriverRead_Faulted => ResourceManager.GetString(nameof(AdvDriverRead_Faulted), Culture) ?? nameof(AdvDriverRead_Faulted);
public static string AdvDriverRead_NoDirect3D12 => ResourceManager.GetString(nameof(AdvDriverRead_NoDirect3D12), Culture) ?? nameof(AdvDriverRead_NoDirect3D12);
public static string AdvDriverRead_NoGetter => ResourceManager.GetString(nameof(AdvDriverRead_NoGetter), Culture) ?? nameof(AdvDriverRead_NoGetter);
public static string AdvDriverRead_NoModule => ResourceManager.GetString(nameof(AdvDriverRead_NoModule), Culture) ?? nameof(AdvDriverRead_NoModule);
public static string AdvDriverRead_NothingReported => ResourceManager.GetString(nameof(AdvDriverRead_NothingReported), Culture) ?? nameof(AdvDriverRead_NothingReported);
public static string AdvDriverRead_Read => ResourceManager.GetString(nameof(AdvDriverRead_Read), Culture) ?? nameof(AdvDriverRead_Read);
public static string AdvDriverRead_Refused => ResourceManager.GetString(nameof(AdvDriverRead_Refused), Culture) ?? nameof(AdvDriverRead_Refused);
public static string AdvDriverRead_Slow => ResourceManager.GetString(nameof(AdvDriverRead_Slow), Culture) ?? nameof(AdvDriverRead_Slow);
public static string AdvDriverRead_Stalled => ResourceManager.GetString(nameof(AdvDriverRead_Stalled), Culture) ?? nameof(AdvDriverRead_Stalled);
public static string AdvDriverRead_Unknown => ResourceManager.GetString(nameof(AdvDriverRead_Unknown), Culture) ?? nameof(AdvDriverRead_Unknown);
public static string AdvGroup_Board => ResourceManager.GetString(nameof(AdvGroup_Board), Culture) ?? nameof(AdvGroup_Board);
public static string AdvGroup_Cpu => ResourceManager.GetString(nameof(AdvGroup_Cpu), Culture) ?? nameof(AdvGroup_Cpu);
@@ -2124,6 +2171,8 @@ public static class Strings
public static string AdvReach_Refused => ResourceManager.GetString(nameof(AdvReach_Refused), Culture) ?? nameof(AdvReach_Refused);
public static string AdvReach_RefusedRoute => ResourceManager.GetString(nameof(AdvReach_RefusedRoute), Culture) ?? nameof(AdvReach_RefusedRoute);
public static string AdvReach_Spike => ResourceManager.GetString(nameof(AdvReach_Spike), Culture) ?? nameof(AdvReach_Spike);
public static string AdvScope_MachineFact => ResourceManager.GetString(nameof(AdvScope_MachineFact), Culture) ?? nameof(AdvScope_MachineFact);
@@ -2160,6 +2209,8 @@ public static class Strings
public static string AdvToken_draw_debug_view => ResourceManager.GetString(nameof(AdvToken_draw_debug_view), Culture) ?? nameof(AdvToken_draw_debug_view);
public static string AdvToken_driver => ResourceManager.GetString(nameof(AdvToken_driver), Culture) ?? nameof(AdvToken_driver);
public static string AdvToken_driver_default => ResourceManager.GetString(nameof(AdvToken_driver_default), Culture) ?? nameof(AdvToken_driver_default);
public static string AdvToken_edr => ResourceManager.GetString(nameof(AdvToken_edr), Culture) ?? nameof(AdvToken_edr);
@@ -2168,6 +2219,8 @@ public static class Strings
public static string AdvToken_game_ready => ResourceManager.GetString(nameof(AdvToken_game_ready), Culture) ?? nameof(AdvToken_game_ready);
public static string AdvToken_gpu_render => ResourceManager.GetString(nameof(AdvToken_gpu_render), Culture) ?? nameof(AdvToken_gpu_render);
public static string AdvToken_gsync_module => ResourceManager.GetString(nameof(AdvToken_gsync_module), Culture) ?? nameof(AdvToken_gsync_module);
public static string AdvToken_hdr10 => ResourceManager.GetString(nameof(AdvToken_hdr10), Culture) ?? nameof(AdvToken_hdr10);
@@ -2200,20 +2253,30 @@ public static class Strings
public static string AdvToken_on_and_off => ResourceManager.GetString(nameof(AdvToken_on_and_off), Culture) ?? nameof(AdvToken_on_and_off);
public static string AdvToken_os_queue => ResourceManager.GetString(nameof(AdvToken_os_queue), Culture) ?? nameof(AdvToken_os_queue);
public static string AdvToken_pci => ResourceManager.GetString(nameof(AdvToken_pci), Culture) ?? nameof(AdvToken_pci);
public static string AdvToken_pci_express => ResourceManager.GetString(nameof(AdvToken_pci_express), Culture) ?? nameof(AdvToken_pci_express);
public static string AdvToken_present => ResourceManager.GetString(nameof(AdvToken_present), Culture) ?? nameof(AdvToken_present);
public static string AdvToken_render_submit => ResourceManager.GetString(nameof(AdvToken_render_submit), Culture) ?? nameof(AdvToken_render_submit);
public static string AdvToken_rtx_new_feature => ResourceManager.GetString(nameof(AdvToken_rtx_new_feature), Culture) ?? nameof(AdvToken_rtx_new_feature);
public static string AdvToken_rtx_production => ResourceManager.GetString(nameof(AdvToken_rtx_production), Culture) ?? nameof(AdvToken_rtx_production);
public static string AdvToken_scrgb_linear => ResourceManager.GetString(nameof(AdvToken_scrgb_linear), Culture) ?? nameof(AdvToken_scrgb_linear);
public static string AdvToken_simulation => ResourceManager.GetString(nameof(AdvToken_simulation), Culture) ?? nameof(AdvToken_simulation);
public static string AdvToken_srgb => ResourceManager.GetString(nameof(AdvToken_srgb), Culture) ?? nameof(AdvToken_srgb);
public static string AdvToken_studio => ResourceManager.GetString(nameof(AdvToken_studio), Culture) ?? nameof(AdvToken_studio);
public static string AdvToken_total => ResourceManager.GetString(nameof(AdvToken_total), Culture) ?? nameof(AdvToken_total);
public static string AdvToken_ulmb => ResourceManager.GetString(nameof(AdvToken_ulmb), Culture) ?? nameof(AdvToken_ulmb);
public static string AdvToken_usable_now => ResourceManager.GetString(nameof(AdvToken_usable_now), Culture) ?? nameof(AdvToken_usable_now);
+85 -1
View File
@@ -665,6 +665,10 @@
<value>ゲームが毎フレーム Streamline に伝える内容: {0}。FSR フレーム生成の設定方法: {1}。</value>
<comment>review</comment>
</data>
<data name="Advanced_InGameDriverLine" xml:space="preserve">
<value>NVIDIA の遅延レポート (FrameLedger がゲーム内でグラフィックス ドライバーに問い合わせます): {0}。</value>
<comment>review</comment>
</data>
<data name="Advanced_InGameFeatureCallsLine" xml:space="preserve">
<value>各 Streamline 機能のバージョン: {0}。各機能の要件: {1}。</value>
<comment>review</comment>
@@ -757,6 +761,10 @@
<value>FrameLedger が計測するゲーム内で、ゲームがその呼び出しを行ったときに読み取り</value>
<comment>review</comment>
</data>
<data name="Advanced_Status_InGameDriver" xml:space="preserve">
<value>FrameLedger が計測するゲーム内で、グラフィックス ドライバーから読み取り: FrameLedger が約 1 秒に 1 回問い合わせます</value>
<comment>review</comment>
</data>
<data name="Advanced_Status_Read" xml:space="preserve">
<value>読み取り中</value>
<comment>review</comment>
@@ -781,6 +789,50 @@
<value>ソース</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_Error" xml:space="preserve">
<value>ドライバーがエラーを返しました</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_Faulted" xml:space="preserve">
<value>ゲーム終了まで停止 - ドライバーへの呼び出しでフォールトが発生しました</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_NoDirect3D12" xml:space="preserve">
<value>読み取っていません - このゲームは Direct3D 12 で表示していません</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_NoGetter" xml:space="preserve">
<value>読み取っていません - ライブラリが 2 つの関数を返しませんでした</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_NoModule" xml:space="preserve">
<value>読み取っていません - ゲームが NVIDIA の nvapi64.dll を読み込んでおらず、FrameLedger がそれを読み込むことはありません</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_NothingReported" xml:space="preserve">
<value>問い合わせましたが、ドライバーはフレームを報告しませんでした - このゲームは NVIDIA Reflex を使用していません</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_Read" xml:space="preserve">
<value>読み取りました</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_Refused" xml:space="preserve">
<value>読み取っていません - ゲーム内の nvapi64.dll はゲーム自身のフォルダーにあり、ドライバーのものではありません</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_Slow" xml:space="preserve">
<value>ゲーム終了まで停止 - ドライバーへの呼び出しに {0:N0} µs かかりました。2,000 µs 以上かかった呼び出しが最後になります</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_Stalled" xml:space="preserve">
<value>停止 - ドライバーへの呼び出しが戻りませんでした</value>
<comment>review</comment>
</data>
<data name="AdvDriverRead_Unknown" xml:space="preserve">
<value>記録なし</value>
<comment>review</comment>
</data>
<data name="AdvGroup_Board" xml:space="preserve">
<value>マザーボード</value>
<comment>review</comment>
@@ -901,6 +953,10 @@
<value>読み取らない: センサー ライブラリがすべての USB デバイスを探索することになるため</value>
<comment>review</comment>
</data>
<data name="AdvReach_RefusedRoute" xml:space="preserve">
<value>読み取りません: ゲーム実行中にしか分からないアドレスへのパッチ、またはゲーム自身のスレッド以外からの呼び出しをベンダーが禁じている関数が必要になるためです - どちらも行いません</value>
<comment>review</comment>
</data>
<data name="AdvReach_Spike" xml:space="preserve">
<value>調査中 (未決定)</value>
<comment>review</comment>
@@ -969,6 +1025,10 @@
<value>Dolby Vision</value>
<comment>review</comment>
</data>
<data name="AdvToken_driver" xml:space="preserve">
<value>ドライバー</value>
<comment>review</comment>
</data>
<data name="AdvToken_driver_default" xml:space="preserve">
<value>ドライバーの既定値</value>
<comment>review</comment>
@@ -989,6 +1049,10 @@
<value>Game Ready</value>
<comment>review</comment>
</data>
<data name="AdvToken_gpu_render" xml:space="preserve">
<value>GPU 描画</value>
<comment>review</comment>
</data>
<data name="AdvToken_gsync_module" xml:space="preserve">
<value>G-SYNC モジュール</value>
<comment>review</comment>
@@ -1053,6 +1117,10 @@
<value>オンのときとオフのときがあります</value>
<comment>review</comment>
</data>
<data name="AdvToken_os_queue" xml:space="preserve">
<value>OS の描画キュー</value>
<comment>review</comment>
</data>
<data name="AdvToken_pci" xml:space="preserve">
<value>PCI</value>
<comment>review</comment>
@@ -1061,6 +1129,14 @@
<value>PCI Express</value>
<comment>review</comment>
</data>
<data name="AdvToken_present" xml:space="preserve">
<value>プレゼント</value>
<comment>review</comment>
</data>
<data name="AdvToken_render_submit" xml:space="preserve">
<value>描画コマンドの送信</value>
<comment>review</comment>
</data>
<data name="AdvToken_rtx_new_feature" xml:space="preserve">
<value>RTX 新機能ブランチ</value>
<comment>review</comment>
@@ -1073,6 +1149,10 @@
<value>scRGB (リニア)</value>
<comment>review</comment>
</data>
<data name="AdvToken_simulation" xml:space="preserve">
<value>シミュレーション</value>
<comment>review</comment>
</data>
<data name="AdvToken_srgb" xml:space="preserve">
<value>sRGB</value>
<comment>review</comment>
@@ -1081,6 +1161,10 @@
<value>Studio</value>
<comment>review</comment>
</data>
<data name="AdvToken_total" xml:space="preserve">
<value>合計 (シミュレーション開始から GPU 描画終了まで)</value>
<comment>review</comment>
</data>
<data name="AdvToken_ulmb" xml:space="preserve">
<value>ULMB</value>
<comment>review</comment>
@@ -1486,7 +1570,7 @@
<comment>review</comment>
</data>
<data name="Settings_Advanced_Body" xml:space="preserve">
<value>セッション中にグラフィックス ドライバーとハードウェア センサーからさらに多くを読み取り、セッションと一緒に保存します - グラフィックス カードのメモリと負荷の詳細、各ファンと電圧、ディスプレイの対応機能、ゲームに対するドライバーの設定など。FrameLedger が内部から計測するゲームでは、ゲームが DLSS、Streamline、FSR に渡す内容 (サイズ、プリセット、シャープニング、露出、深度範囲、フレーム生成の設定) も読み取ります - カメラの位置は決して読み取りません。オフ: ゲーム内も含め、追加の読み取りも保存も行いません。次のセッションから適用され、オフの間に記録したセッションが後から補われることはありません。</value>
<value>セッション中にグラフィックス ドライバーとハードウェア センサーからさらに多くを読み取り、セッションと一緒に保存します - グラフィックス カードのメモリと負荷の詳細、各ファンと電圧、ディスプレイの対応機能、ゲームに対するドライバーの設定など。FrameLedger が内部から計測するゲームでは、ゲームが DLSS、Streamline、FSR に渡す内容 (サイズ、プリセット、シャープニング、露出、深度範囲、フレーム生成の設定) も読み取ります - カメラの位置は決して読み取りません。NVIDIA のカードで、NVIDIA のライブラリを使用する Direct3D 12 のゲームでは、フレームの各段階にかかった時間を、FrameLedger がゲーム内から約 1 秒に 1 回グラフィックス ドライバーに問い合わせます - これは、ゲームのフレームを表示するスレッド上で FrameLedger 自身が行う呼び出しです。オフ: ゲーム内も含め、追加の読み取りも保存も行いません。次のセッションから適用され、オフの間に記録したセッションが後から補われることはありません。</value>
<comment>review</comment>
</data>
<data name="Settings_Advanced_Label" xml:space="preserve">
+64 -1
View File
@@ -504,6 +504,9 @@
<data name="Advanced_InGameCallsLine" xml:space="preserve">
<value>What the game tells Streamline each frame: {0}. How it configures FSR frame generation: {1}.</value>
</data>
<data name="Advanced_InGameDriverLine" xml:space="preserve">
<value>NVIDIA's latency report, which FrameLedger asks the graphics driver for inside the game: {0}.</value>
</data>
<data name="Advanced_InGameFeatureCallsLine" xml:space="preserve">
<value>Which version each Streamline feature is: {0}. What each requires: {1}.</value>
</data>
@@ -573,6 +576,9 @@
<data name="Advanced_Status_InGame" xml:space="preserve">
<value>Read inside a game FrameLedger measures, when the game makes the call</value>
</data>
<data name="Advanced_Status_InGameDriver" xml:space="preserve">
<value>Read inside a game FrameLedger measures, from the graphics driver: FrameLedger asks for it about once a second</value>
</data>
<data name="Advanced_Status_Read" xml:space="preserve">
<value>Read</value>
</data>
@@ -591,6 +597,39 @@
<data name="Advanced_Tab_Sources" xml:space="preserve">
<value>Sources</value>
</data>
<data name="AdvDriverRead_Error" xml:space="preserve">
<value>the driver answered with an error</value>
</data>
<data name="AdvDriverRead_Faulted" xml:space="preserve">
<value>stopped until the game closed - a call into the driver faulted</value>
</data>
<data name="AdvDriverRead_NoDirect3D12" xml:space="preserve">
<value>not read - the game does not present through Direct3D 12</value>
</data>
<data name="AdvDriverRead_NoGetter" xml:space="preserve">
<value>not read - the library did not answer for the two functions</value>
</data>
<data name="AdvDriverRead_NoModule" xml:space="preserve">
<value>not read - the game has not loaded NVIDIA's nvapi64.dll, and FrameLedger never loads it</value>
</data>
<data name="AdvDriverRead_NothingReported" xml:space="preserve">
<value>asked, and the driver reported no frame - the game does not use NVIDIA Reflex</value>
</data>
<data name="AdvDriverRead_Read" xml:space="preserve">
<value>read</value>
</data>
<data name="AdvDriverRead_Refused" xml:space="preserve">
<value>not read - the nvapi64.dll in the game is in the game's own folder, not the driver's</value>
</data>
<data name="AdvDriverRead_Slow" xml:space="preserve">
<value>stopped until the game closed - a call into the driver took {0:N0} µs, and one of 2,000 µs or more is the last</value>
</data>
<data name="AdvDriverRead_Stalled" xml:space="preserve">
<value>stopped - a call into the driver did not return</value>
</data>
<data name="AdvDriverRead_Unknown" xml:space="preserve">
<value>not stated</value>
</data>
<data name="AdvGroup_Board" xml:space="preserve">
<value>Motherboard</value>
</data>
@@ -681,6 +720,9 @@
<data name="AdvReach_Refused" xml:space="preserve">
<value>Not read: it would make the sensor library search every USB device</value>
</data>
<data name="AdvReach_RefusedRoute" xml:space="preserve">
<value>Not read: it would take a patch at an address found while the game runs, or a call the vendor forbids from outside the game's own threads - both refused</value>
</data>
<data name="AdvReach_Spike" xml:space="preserve">
<value>Being studied; not decided</value>
</data>
@@ -732,6 +774,9 @@
<data name="AdvToken_dolby_vision" xml:space="preserve">
<value>Dolby Vision</value>
</data>
<data name="AdvToken_driver" xml:space="preserve">
<value>driver</value>
</data>
<data name="AdvToken_driver_default" xml:space="preserve">
<value>Driver default</value>
</data>
@@ -747,6 +792,9 @@
<data name="AdvToken_game_ready" xml:space="preserve">
<value>Game Ready</value>
</data>
<data name="AdvToken_gpu_render" xml:space="preserve">
<value>GPU render</value>
</data>
<data name="AdvToken_gsync_module" xml:space="preserve">
<value>G-SYNC module</value>
</data>
@@ -795,12 +843,21 @@
<data name="AdvToken_on_and_off" xml:space="preserve">
<value>On at times, off at others</value>
</data>
<data name="AdvToken_os_queue" xml:space="preserve">
<value>operating system's render queue</value>
</data>
<data name="AdvToken_pci" xml:space="preserve">
<value>PCI</value>
</data>
<data name="AdvToken_pci_express" xml:space="preserve">
<value>PCI Express</value>
</data>
<data name="AdvToken_present" xml:space="preserve">
<value>present</value>
</data>
<data name="AdvToken_render_submit" xml:space="preserve">
<value>render submit</value>
</data>
<data name="AdvToken_rtx_new_feature" xml:space="preserve">
<value>RTX new-feature branch</value>
</data>
@@ -810,12 +867,18 @@
<data name="AdvToken_scrgb_linear" xml:space="preserve">
<value>scRGB (linear)</value>
</data>
<data name="AdvToken_simulation" xml:space="preserve">
<value>simulation</value>
</data>
<data name="AdvToken_srgb" xml:space="preserve">
<value>sRGB</value>
</data>
<data name="AdvToken_studio" xml:space="preserve">
<value>Studio</value>
</data>
<data name="AdvToken_total" xml:space="preserve">
<value>total, simulation start to GPU render end</value>
</data>
<data name="AdvToken_ulmb" xml:space="preserve">
<value>ULMB</value>
</data>
@@ -1120,7 +1183,7 @@
<value>The agent did not answer the rules update.</value>
</data>
<data name="Settings_Advanced_Body" xml:space="preserve">
<value>Read more from the graphics driver and the hardware sensors during a session - the graphics card's memory and load in detail, each fan and voltage, what your display can do, the driver's settings for the game - and, in a game FrameLedger measures from inside, what the game tells DLSS, Streamline and FSR (sizes, presets, sharpening, exposure, the depth range, how frame generation is configured - never where the camera is). All of it is stored with the session. Off: nothing more is read or stored, inside a game either. It applies from the next session, and a session recorded while it was off is not filled in later.</value>
<value>Read more from the graphics driver and the hardware sensors during a session - the graphics card's memory and load in detail, each fan and voltage, what your display can do, the driver's settings for the game - and, in a game FrameLedger measures from inside, what the game tells DLSS, Streamline and FSR (sizes, presets, sharpening, exposure, the depth range, how frame generation is configured - never where the camera is). On an NVIDIA card, in a Direct3D 12 game that uses NVIDIA's own library, FrameLedger also asks the graphics driver about once a second, from inside the game, how long each stage of a frame took - a call it makes itself on the thread that shows the game's frames. All of it is stored with the session. Off: nothing more is read or stored, inside a game either. It applies from the next session, and a session recorded while it was off is not filled in later.</value>
</data>
<data name="Settings_Advanced_Label" xml:space="preserve">
<value>Advanced metrics</value>
+64 -1
View File
@@ -499,6 +499,9 @@
<data name="Advanced_InGameCallsLine" xml:space="preserve">
<value>Những gì game báo cho Streamline mỗi khung hình: {0}. Cách game cấu hình frame generation của FSR: {1}.</value>
</data>
<data name="Advanced_InGameDriverLine" xml:space="preserve">
<value>Báo cáo độ trễ của NVIDIA, do FrameLedger hỏi driver đồ họa ngay bên trong game: {0}.</value>
</data>
<data name="Advanced_InGameFeatureCallsLine" xml:space="preserve">
<value>Mỗi tính năng Streamline là phiên bản nào: {0}. Mỗi tính năng cần gì: {1}.</value>
</data>
@@ -568,6 +571,9 @@
<data name="Advanced_Status_InGame" xml:space="preserve">
<value>Được đọc bên trong game mà FrameLedger đo, khi game thực hiện lời gọi đó</value>
</data>
<data name="Advanced_Status_InGameDriver" xml:space="preserve">
<value>Được đọc bên trong game mà FrameLedger đo, từ driver đồ họa: FrameLedger hỏi khoảng mỗi giây một lần</value>
</data>
<data name="Advanced_Status_Read" xml:space="preserve">
<value>Đang đọc</value>
</data>
@@ -586,6 +592,39 @@
<data name="Advanced_Tab_Sources" xml:space="preserve">
<value>Nguồn</value>
</data>
<data name="AdvDriverRead_Error" xml:space="preserve">
<value>driver trả về lỗi</value>
</data>
<data name="AdvDriverRead_Faulted" xml:space="preserve">
<value>đã dừng cho tới khi đóng game - một lời gọi vào driver gặp lỗi (fault)</value>
</data>
<data name="AdvDriverRead_NoDirect3D12" xml:space="preserve">
<value>không đọc - game không hiển thị qua Direct3D 12</value>
</data>
<data name="AdvDriverRead_NoGetter" xml:space="preserve">
<value>không đọc - thư viện không trả về hai hàm cần gọi</value>
</data>
<data name="AdvDriverRead_NoModule" xml:space="preserve">
<value>không đọc - game chưa nạp nvapi64.dll của NVIDIA, và FrameLedger không bao giờ nạp nó</value>
</data>
<data name="AdvDriverRead_NothingReported" xml:space="preserve">
<value>đã hỏi, driver không báo khung hình nào - game không dùng NVIDIA Reflex</value>
</data>
<data name="AdvDriverRead_Read" xml:space="preserve">
<value>đã đọc</value>
</data>
<data name="AdvDriverRead_Refused" xml:space="preserve">
<value>không đọc - nvapi64.dll trong game nằm ở chính thư mục của game, không phải của driver</value>
</data>
<data name="AdvDriverRead_Slow" xml:space="preserve">
<value>đã dừng cho tới khi đóng game - một lời gọi vào driver mất {0:N0} µs, và lời gọi từ 2.000 µs trở lên là lời gọi cuối</value>
</data>
<data name="AdvDriverRead_Stalled" xml:space="preserve">
<value>đã dừng - một lời gọi vào driver không trả về</value>
</data>
<data name="AdvDriverRead_Unknown" xml:space="preserve">
<value>không được ghi</value>
</data>
<data name="AdvGroup_Board" xml:space="preserve">
<value>Bo mạch chủ</value>
</data>
@@ -676,6 +715,9 @@
<data name="AdvReach_Refused" xml:space="preserve">
<value>Không đọc: việc này khiến thư viện cảm biến dò mọi thiết bị USB</value>
</data>
<data name="AdvReach_RefusedRoute" xml:space="preserve">
<value>Không đọc: việc đó cần vá mã tại một địa chỉ chỉ tìm được khi game đang chạy, hoặc một lời gọi mà nhà cung cấp cấm thực hiện từ ngoài luồng của game - cả hai đều bị từ chối</value>
</data>
<data name="AdvReach_Spike" xml:space="preserve">
<value>Đang nghiên cứu; chưa quyết định</value>
</data>
@@ -727,6 +769,9 @@
<data name="AdvToken_dolby_vision" xml:space="preserve">
<value>Dolby Vision</value>
</data>
<data name="AdvToken_driver" xml:space="preserve">
<value>driver</value>
</data>
<data name="AdvToken_driver_default" xml:space="preserve">
<value>Mặc định của driver</value>
</data>
@@ -742,6 +787,9 @@
<data name="AdvToken_game_ready" xml:space="preserve">
<value>Game Ready</value>
</data>
<data name="AdvToken_gpu_render" xml:space="preserve">
<value>GPU vẽ</value>
</data>
<data name="AdvToken_gsync_module" xml:space="preserve">
<value>Mô-đun G-SYNC</value>
</data>
@@ -790,12 +838,21 @@
<data name="AdvToken_on_and_off" xml:space="preserve">
<value>Lúc bật, lúc tắt</value>
</data>
<data name="AdvToken_os_queue" xml:space="preserve">
<value>hàng đợi vẽ của hệ điều hành</value>
</data>
<data name="AdvToken_pci" xml:space="preserve">
<value>PCI</value>
</data>
<data name="AdvToken_pci_express" xml:space="preserve">
<value>PCI Express</value>
</data>
<data name="AdvToken_present" xml:space="preserve">
<value>present</value>
</data>
<data name="AdvToken_render_submit" xml:space="preserve">
<value>gửi lệnh vẽ</value>
</data>
<data name="AdvToken_rtx_new_feature" xml:space="preserve">
<value>Nhánh RTX tính năng mới</value>
</data>
@@ -805,12 +862,18 @@
<data name="AdvToken_scrgb_linear" xml:space="preserve">
<value>scRGB (tuyến tính)</value>
</data>
<data name="AdvToken_simulation" xml:space="preserve">
<value>mô phỏng</value>
</data>
<data name="AdvToken_srgb" xml:space="preserve">
<value>sRGB</value>
</data>
<data name="AdvToken_studio" xml:space="preserve">
<value>Studio</value>
</data>
<data name="AdvToken_total" xml:space="preserve">
<value>tổng, từ đầu mô phỏng tới khi GPU vẽ xong</value>
</data>
<data name="AdvToken_ulmb" xml:space="preserve">
<value>ULMB</value>
</data>
@@ -1115,7 +1178,7 @@
<value>Agent không phản hồi yêu cầu cập nhật quy tắc.</value>
</data>
<data name="Settings_Advanced_Body" xml:space="preserve">
<value>Đọc thêm từ driver đồ hoạ và các cảm biến phần cứng trong lúc ghi phiên - bộ nhớ và tải của card đồ hoạ ở mức chi tiết, từng quạt và điện áp, khả năng của màn hình, thiết lập của driver cho game - và, với game mà FrameLedger đo từ bên trong, những gì game đưa cho DLSS, Streamline và FSR (kích thước, preset, làm nét, phơi sáng, khoảng độ sâu, cách cấu hình frame generation - không bao giờ là vị trí camera). Tất cả được lưu cùng phiên. Tắt: không đọc và không lưu thêm gì, kể cả bên trong game. Áp dụng từ phiên kế tiếp; phiên đã ghi lúc tắt sẽ không được bổ sung về sau.</value>
<value>Đọc thêm từ driver đồ hoạ và các cảm biến phần cứng trong lúc ghi phiên - bộ nhớ và tải của card đồ hoạ ở mức chi tiết, từng quạt và điện áp, khả năng của màn hình, thiết lập của driver cho game - và, với game mà FrameLedger đo từ bên trong, những gì game đưa cho DLSS, Streamline và FSR (kích thước, preset, làm nét, phơi sáng, khoảng độ sâu, cách cấu hình frame generation - không bao giờ là vị trí camera). Với card NVIDIA, trong game Direct3D 12 có dùng thư viện của NVIDIA, FrameLedger còn hỏi driver đồ hoạ khoảng mỗi giây một lần, ngay bên trong game, xem từng chặng của một khung hình mất bao lâu - đây là lời gọi do chính FrameLedger thực hiện trên luồng hiển thị khung hình của game. Tất cả được lưu cùng phiên. Tắt: không đọc và không lưu thêm gì, kể cả bên trong game. Áp dụng từ phiên kế tiếp; phiên đã ghi lúc tắt sẽ không được bổ sung về sau.</value>
</data>
<data name="Settings_Advanced_Label" xml:space="preserve">
<value>Thông số nâng cao</value>
@@ -63,6 +63,16 @@ public static class AdvancedLabels
/// <summary>A token the driver's answer was mapped to; the token itself where this build has no word for it.</summary>
public static string Token(string token) => Lookup("AdvToken_" + token) ?? token;
/// <summary>
/// What became of the driver's latency report in a session, in words. A read stopped for being slow says how
/// slow: <paramref name="slowestUs"/> is the session's slowest call into the driver, in microseconds.
/// </summary>
public static string DriverRead(AdvancedDriverRead read, int? slowestUs)
{
string text = Lookup("AdvDriverRead_" + read) ?? read.ToString();
return read == AdvancedDriverRead.Slow ? string.Format(CultureInfo.CurrentCulture, text, slowestUs ?? 0) : text;
}
/// <summary>A number in its unit. A flag is yes or no; a count has no unit.</summary>
public static string Number(double value, AdvancedUnit unit)
{
@@ -90,7 +90,9 @@ public static class AdvancedPresenter
}
}
return owner is null ? (null, series) : (owner, AdvancedLabels.Member(AdvancedLabels.Of(owner), id[(owner.Id.Length + 1)..]));
// The member's own name, translated where it is one of ours (the spans of the driver's latency report) and
// shown as it is where it is the hardware's.
return owner is null ? (null, series) : (owner, AdvancedLabels.Member(AdvancedLabels.Of(owner), AdvancedLabels.Token(id[(owner.Id.Length + 1)..])));
}
/// <summary>Every series as it reads now, in the catalog's order: its value in its unit and the time it was read at.</summary>
@@ -223,6 +225,17 @@ public static class AdvancedPresenter
line += " " + more;
}
// The driver's latency report (train C): not one of the game's calls, so a sentence of its own - what became
// of the read FrameLedger makes itself, with the microseconds when it was stopped for being slow. A row
// stored before, and a session that says nothing about it, do not carry it.
if (sources.DriverLatency is { } driver && driver != AdvancedDriverRead.Unknown)
{
line += " " + string.Format(
CultureInfo.CurrentCulture,
Strings.Advanced_InGameDriverLine,
AdvancedLabels.DriverRead(driver, sources.DriverLatencySlowestUs));
}
return line;
}
@@ -269,6 +282,12 @@ public static class AdvancedPresenter
return Strings.Advanced_Status_InGame;
}
if (metric.Reach == AdvancedReach.GameDriver)
{
// Nor this: read inside a game being measured, by a call FrameLedger makes into the driver itself.
return Strings.Advanced_Status_InGameDriver;
}
AdvancedSourceStatus? state = now is null ? null : (metric.Source, metric.Reach) switch
{
(AdvancedSource.Nvapi, _) => now.Nvapi,
@@ -0,0 +1,47 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
namespace FrameLedger.Application.Advanced;
/// <summary>
/// What became, in one session, of the one thing FrameLedger reads inside a game that is not an argument of a call
/// it hooks: the graphics driver's latency report, which the part inside the game asks NVIDIA's driver for itself,
/// about once a second (Advanced metrics train C; owner decisions D132, D136, D138-D141; the entries of reach
/// <see cref="AdvancedReach.GameDriver"/>). Beside <see cref="AdvancedInGameCall"/> because the reasons a value is
/// absent are different ones: there is no hook to be in or out, and there is a driver that can refuse.
/// </summary>
public enum AdvancedDriverRead
{
/// <summary>Not stated: a row stored before this existed, or a session the part inside the game said nothing about.</summary>
Unknown = 0,
/// <summary>The driver was asked and reported frames.</summary>
Read = 1,
/// <summary>The driver was asked and reported no frame: the game does not use NVIDIA Reflex.</summary>
NothingReported = 2,
/// <summary>The game does not present through Direct3D 12, the one interface this is read on.</summary>
NoDirect3D12 = 3,
/// <summary>The game has not loaded NVIDIA's <c>nvapi64.dll</c>, and FrameLedger never loads it.</summary>
NoModule = 4,
/// <summary>The <c>nvapi64.dll</c> in the game sits in the game's own folder: a replacement, not the driver's (D140).</summary>
Refused = 5,
/// <summary>The module did not answer for the two functions.</summary>
NoGetter = 6,
/// <summary>The driver answered every read with an error.</summary>
Error = 7,
/// <summary>One call took two milliseconds or more: the read was switched off until the game exited (D141).</summary>
Slow = 8,
/// <summary>A call into the driver faulted: the read was switched off until the game exited.</summary>
Faulted = 9,
/// <summary>A call into the driver did not return.</summary>
Stalled = 10,
}
@@ -37,7 +37,7 @@ public sealed record AdvancedMetric(
public bool IsFamily { get; init; }
/// <summary>True when a build with the option on reads it: every other reach is a reason it reads N/A.</summary>
public bool IsRead => Reach is AdvancedReach.Agent or AdvancedReach.AgentElevated or AdvancedReach.Game;
public bool IsRead => Reach is AdvancedReach.Agent or AdvancedReach.AgentElevated or AdvancedReach.Game or AdvancedReach.GameDriver;
/// <summary>The name of its series in <c>sensor_blobs</c> — for a family, the stem of its instances' names; null when it is not a series.</summary>
public string? SeriesName => Scope == AdvancedScope.Series ? SeriesPrefix + Id : null;
@@ -182,10 +182,15 @@ public static class AdvancedMetricCatalog
Session("sl.init.preferences", Streamline, BeforeAttach, Text, Upscaling, "The preferences the game started Streamline with"),
Session("sl.constants.camera", Streamline, PlayerState, Text, Upscaling, "Camera position, axes and matrices"),
// ---- Inside the game: what the driver reports, asked for by the part inside the game itself (train C) ------
// Not an argument of a hooked call: two read-only getters of the driver, about once a second (D132, D136).
// What the GAME asked of Reflex - the mode, boost, the limit - is an argument of a function that is not an
// export: reading it needs a patch at an address learned at run time, the class refused on 2026-08-09.
Session("nvapi.reflex.mode", Nvapi, RefusedRoute, Text, Latency, "Reflex: low-latency mode, boost, the frame-rate limit"),
Session("nvapi.reflex.sleep_status", Nvapi, GameDriver, Table, Latency, "What the driver's low-latency state is"),
SampledFamily("nvapi.reflex.frame_report", Nvapi, GameDriver, Microseconds, Latency, "Latency per frame: simulation, render submit, present, driver, OS queue, GPU render"),
// ---- Inside the game: routes a spike decides ------------------------------------------------------------
Session("nvapi.reflex.mode", Nvapi, Spike, Text, Latency, "Reflex: low-latency mode, boost, the frame-rate limit"),
Session("nvapi.reflex.sleep_status", Nvapi, Spike, Text, Latency, "What the driver's low-latency state is"),
SampledFamily("nvapi.reflex.frame_report", Nvapi, Spike, Microseconds, Latency, "Latency per frame: simulation, render submit, present, driver, OS queue, GPU render"),
Session("sl.dlss.optimal_settings", Streamline, Spike, Text, Upscaling, "The render size and sharpness DLSS recommends"),
Sampled("sl.dlss.vram_estimate", Streamline, Spike, Mebibytes, Upscaling, "DLSS's own estimate of its video memory"),
Session("sl.dlssg.options", Streamline, Spike, Text, FrameGeneration, "DLSS frame generation: mode, frames to generate"),
@@ -195,7 +200,9 @@ public static class AdvancedMetricCatalog
Session("sl.dlssd.options", Streamline, Spike, Text, Upscaling, "Ray reconstruction's options"),
Session("sl.nis.options", Streamline, Spike, Text, Upscaling, "NVIDIA Image Scaling's options"),
Session("sl.deepdvc.options", Streamline, Spike, Text, Upscaling, "RTX Dynamic Vibrance's options"),
Session("sl.reflex.state", Streamline, Spike, Table, Latency, "Reflex through Streamline: availability and its frame reports"),
// A refused route (owner decision D133): the Overlay calling slReflexGetState itself breaks the thread
// contract the vendor's header states.
Session("sl.reflex.state", Streamline, RefusedRoute, Table, Latency, "Reflex through Streamline: availability and its frame reports"),
Sampled("sl.pcl.markers", Streamline, Spike, Count, Latency, "PC-latency markers the game sets"),
// ---- Closed by a licence --------------------------------------------------------------------------------
@@ -57,4 +57,20 @@ public enum AdvancedReach
/// instruction, and no hook is ever installed on a game's thread. Never read (owner decision D129).
/// </summary>
BeforeAttach = 13,
/// <summary>
/// Read inside a game FrameLedger measures, while the session records Advanced metrics — but not from a call the
/// game makes: the part inside the game asks the graphics driver itself, about once a second, for what the driver
/// reports (Advanced metrics train C; owner decisions D132, D136, D138). Only where the game presents through
/// Direct3D 12 and had already loaded the driver's library; <see cref="AdvancedDriverRead"/> says what became of
/// it in a session.
/// </summary>
GameDriver = 14,
/// <summary>
/// Reading it needs a route the project refused, whatever the source: a patch at an address learned at run time
/// (what a game asks of Reflex is an argument of a function no module exports), or a call the vendor's own header
/// forbids from a thread that is not the game's (owner decision D133). Never read.
/// </summary>
RefusedRoute = 15,
}
@@ -59,6 +59,21 @@ public sealed record AdvancedSources(
public AdvancedInGameCall? StreamlineShutdown { get; init; }
/// <summary>
/// What became of the graphics driver's latency report (the <c>nvapi.reflex.</c> entries of reach
/// <see cref="AdvancedReach.GameDriver"/>) in the session this describes (train C). Null where that is not a
/// question - the machine's live state, a session not measured inside the game, a game the part inside it
/// publishes nothing for - and in every row stored before.
/// </summary>
public AdvancedDriverRead? DriverLatency { get; init; }
/// <summary>
/// The slowest call into the driver the session saw, in microseconds; null with <see cref="DriverLatency"/> and
/// where no call was made. It is what tells a driver that held a call from a pause of the game's thread when
/// <see cref="DriverLatency"/> is <see cref="AdvancedDriverRead.Slow"/>.
/// </summary>
public int? DriverLatencySlowestUs { get; init; }
/// <summary>Nothing asked yet.</summary>
public static AdvancedSources Unknown { get; } = new(AdvancedSourceStatus.Unknown, NvapiCode: null, AdvancedSourceStatus.Unknown, AdvancedSourceStatus.Unknown);
}
@@ -38,8 +38,20 @@ public sealed class InGameAdvancedSampler
/// <summary>FSR's own video memory as it answered the game, in mebibytes — a point for each second the game asked.</summary>
public const string MemorySeries = AdvancedMetric.SeriesPrefix + "ffx.memory_usage";
/// <summary>
/// The stem of the seven series of the driver's latency report (train C): <c>adv.nvapi.reflex.frame_report.</c>
/// and one of <see cref="LatencySpans"/>. Each point is the mean, in microseconds, of the frames one read summed.
/// </summary>
public const string LatencySeriesStem = AdvancedMetric.SeriesPrefix + "nvapi.reflex.frame_report.";
private const double _mebibyte = 1024.0 * 1024.0;
// The spans of a frame the driver reports, in the order the capture side publishes their sums.
private static readonly string[] _latencySpans = ["simulation", "render_submit", "present", "driver", "os_queue", "gpu_render", "total"];
// NV_GET_SLEEP_STATUS_PARAMS's five switches, by bit: the vendor's own names, shown as they are.
private static readonly string[] _sleepSwitches = ["bLowLatencyMode", "bFsVrr", "bCplVsyncOn", "bUseGameSleep", "bFullscreenIFlip"];
// What the second row of a field of view over pi says (owner decision D128).
private const string _notRadians = "not_radians";
@@ -79,9 +91,15 @@ public sealed class InGameAdvancedSampler
/// switch seen over a session, the flags of the dispatch that have a name, "none", and what a field of view
/// that cannot be radians is said to be (D128). A flag bit nobody named is <c>bit_N</c> and is shown as it is.
/// </summary>
public static IReadOnlyList<string> Tokens { get; } = ["on", "off", "on_and_off", "none", _notRadians, .. _flagTokens];
public static IReadOnlyList<string> Tokens { get; } = ["on", "off", "on_and_off", "none", _notRadians, .. _flagTokens, .. _latencySpans];
/// <summary>The seven spans of a frame, as the last part of a series' name; the App translates each (<c>AdvToken_*</c>).</summary>
public static IReadOnlyList<string> LatencySpans => _latencySpans;
private InGameAdvanced? _last;
private FlLatencyState _latencyState;
private bool _latencyFrames;
private uint _latencySlowestUs;
private uint _memoryQueries;
private FactKey _key;
private uint _builtResets;
@@ -98,6 +116,37 @@ public sealed class InGameAdvancedSampler
public AdvancedInGameStatus Status(bool hooked) =>
!hooked ? AdvancedInGameStatus.NotHooked : SawAnything ? AdvancedInGameStatus.Reading : AdvancedInGameStatus.NothingSeen;
/// <summary>
/// What became of the driver's latency report (train C), for a session measured inside the game: null when it
/// was not, and when the capture side said nothing about it - a game it publishes no Advanced metrics for.
/// "Reported frames" wins over an error or a stop that came later: the series are there up to it, and the
/// stops say themselves.
/// </summary>
public AdvancedDriverRead? DriverRead(bool hooked)
{
if (!hooked)
{
return null;
}
return _latencyState switch
{
FlLatencyState.NoDevice => AdvancedDriverRead.NoDirect3D12,
FlLatencyState.NoModule => AdvancedDriverRead.NoModule,
FlLatencyState.Refused => AdvancedDriverRead.Refused,
FlLatencyState.NoGetter => AdvancedDriverRead.NoGetter,
FlLatencyState.Reading => _latencyFrames ? AdvancedDriverRead.Read : AdvancedDriverRead.NothingReported,
FlLatencyState.Error => _latencyFrames ? AdvancedDriverRead.Read : AdvancedDriverRead.Error,
FlLatencyState.Slow => AdvancedDriverRead.Slow,
FlLatencyState.Faulted => AdvancedDriverRead.Faulted,
FlLatencyState.Stalled => AdvancedDriverRead.Stalled,
_ => null,
};
}
/// <summary>The slowest call into the driver the publications carried, in microseconds; null while none was made.</summary>
public int? DriverSlowestUs => _latencySlowestUs == 0 ? null : (int)_latencySlowestUs;
/// <summary>
/// What became of the entries read from one call hooked only for Advanced metrics (0.1.0-beta.43):
/// <paramref name="group"/> is the bit a publication carries once the call was read, <paramref name="hookedIn"/>
@@ -156,12 +205,17 @@ public sealed class InGameAdvancedSampler
_last = published;
ref readonly FlAdvancedState s = ref published.State;
// The driver's latency report first, and whatever the mask says: where that read stands is published even
// when nothing was read, and it is not one of "the game's calls".
List<AdvancedReading>? readings = TakeLatency(published);
if (s.ValidMask == FlAdvancedValid.None)
{
return null;
return readings;
}
SawAnything = true;
// "The game's calls were read" is about the game's calls: the driver's report is not one of them.
SawAnything |= (s.ValidMask & ~FlAdvancedValid.Latency) != FlAdvancedValid.None;
_everValid |= s.ValidMask;
if (s.ValidMask.HasFlag(FlAdvancedValid.SlFeatures))
{
@@ -179,7 +233,7 @@ public sealed class InGameAdvancedSampler
_builtResets = s.SlResets;
}
var readings = new List<AdvancedReading>(2);
readings ??= new List<AdvancedReading>(2);
// The pair is drained by each publication: the dispatches of the second before it. A sum that saturated its
// word is not a mean of anything.
if (s.ValidMask.HasFlag(FlAdvancedValid.FfxUpscale) && s.FfxFrameTimeCount != 0 && s.FfxFrameTimeSumUs != uint.MaxValue)
@@ -197,6 +251,39 @@ public sealed class InGameAdvancedSampler
return readings.Count == 0 ? null : readings;
}
// The ten latency words of a publication (07_IPC, region 5): the state and the slowest call are kept; the frames
// and the sums are of ONE read and become one point a span - the mean over the frames that read summed. A span
// some summed frame did not report has no point: without a sleep mode the driver reports no driver span at all.
private List<AdvancedReading>? TakeLatency(InGameAdvanced published)
{
ref readonly FlAdvancedState s = ref published.State;
var state = (FlLatencyState)(s.LatState & FlAdvancedState.LatStateMask);
if (state != FlLatencyState.None)
{
_latencyState = state;
}
_latencySlowestUs = Math.Max(_latencySlowestUs, s.LatReads >> 16);
uint frames = s.LatFrames & 0xFFFFu;
if (!s.ValidMask.HasFlag(FlAdvancedValid.Latency) || frames == 0)
{
return null;
}
_latencyFrames = true;
uint[] sums = [s.LatSimulationSumUs, s.LatSubmitSumUs, s.LatPresentSumUs, s.LatDriverSumUs, s.LatOsQueueSumUs, s.LatGpuSumUs, s.LatTotalSumUs];
var readings = new List<AdvancedReading>(sums.Length);
for (int span = 0; span < sums.Length; span++)
{
if (sums[span] != FlAdvancedState.LatSumNone)
{
readings.Add(new AdvancedReading(LatencySeriesStem + _latencySpans[span], sums[span] / (double)frames));
}
}
return readings;
}
private static List<AdvancedFact> Build(InGameAdvanced published)
{
var facts = new List<AdvancedFact>(11);
@@ -230,9 +317,44 @@ public sealed class InGameAdvancedSampler
AddStreamlineFeatureState(published, facts);
}
if (published.State.ValidMask.HasFlag(FlAdvancedValid.Latency))
{
AddDriverSleepStatus(published, facts);
}
return facts;
}
// The driver's sleep status (train C): its five switches as seen over the session, by the vendor's own names, and
// the frame-generation multiplier it last gave. THE DRIVER'S WORDS: on the driver the probe ran against,
// bLowLatencyMode read off for a device whose game had just switched low latency on (spike-notes §31) - so this
// is never worded as "the game uses Reflex".
private static void AddDriverSleepStatus(InGameAdvanced published, List<AdvancedFact> facts)
{
ref readonly FlAdvancedState s = ref published.State;
uint on = (s.LatState >> FlAdvancedState.LatSleepSeenOnShift) & FlAdvancedState.LatSleepBits;
uint off = (s.LatState >> FlAdvancedState.LatSleepSeenOffShift) & FlAdvancedState.LatSleepBits;
if ((on | off) == 0)
{
return; // the report was read and the status never was
}
var rows = new List<AdvancedRow>(_sleepSwitches.Length + 1);
for (int bit = 0; bit < _sleepSwitches.Length; bit++)
{
// Bit 0 seen off, bit 1 seen on: the two bits AddSwitch reads.
AddSwitch(rows, _sleepSwitches[bit], ((off >> bit) & 1u) | (((on >> bit) & 1u) << 1));
}
uint multiplier = s.LatState >> FlAdvancedState.LatFgMultiplierShift;
if (multiplier != 0)
{
rows.Add(new AdvancedRow("fgMultiplier", multiplier.ToString(CultureInfo.InvariantCulture)));
}
facts.Add(Fact("nvapi.reflex.sleep_status", AdvancedValue.OfRows(rows)));
}
// Whether Streamline says each feature is supported and loaded, and what the game did with it while the session
// watched (0.1.0-beta.45): two facts, rows named as the versions' are. A refusal is the answer to "is it
// supported", so the result is said by the vendor's own name whatever it is. A count that reached 15 stopped there.
@@ -724,7 +846,8 @@ public sealed class InGameAdvancedSampler
ulong SlFov,
uint SlAspect,
ulong SlFlags,
ulong SlFeatures)
ulong SlFeatures,
uint DriverSleep)
{
public static FactKey Of(InGameAdvanced published)
{
@@ -765,7 +888,9 @@ public sealed class InGameAdvancedSampler
Pair(s.SlFovMinBits, s.SlFovMaxBits),
s.SlAspectBits,
Pair(s.SlFlagsSeenTrue, s.SlFlagsSeenFalse),
FeaturesHash(published));
FeaturesHash(published),
// The driver's sleep status as seen and its multiplier: what the one latency fact is made of.
s.ValidMask.HasFlag(FlAdvancedValid.Latency) ? s.LatState >> FlAdvancedState.LatSleepSeenOnShift : 0u);
}
// The feature slots as one number (FNV-1a over the words of the slots in use): an answer that arrives, or one
@@ -521,6 +521,8 @@ public sealed class SessionRecorder : ISessionRecorder
StreamlineAllocateResources = calls.AllocateResources,
StreamlineFreeResources = calls.FreeResources,
StreamlineShutdown = calls.Shutdown,
DriverLatency = calls.Driver,
DriverLatencySlowestUs = calls.DriverSlowestUs,
}));
}
@@ -548,7 +550,9 @@ public sealed class SessionRecorder : ISessionRecorder
_inGame.FeatureCall(InGameAdvancedSampler.FeatureSwitched, hooks.HasFlag(FlHookFamily.SlSetFeatureLoaded)),
_inGame.FeatureCall(InGameAdvancedSampler.FeatureAllocated, hooks.HasFlag(FlHookFamily.SlAllocateResources)),
_inGame.FeatureCall(InGameAdvancedSampler.FeatureFreed, hooks.HasFlag(FlHookFamily.SlFreeResources)),
_inGame.Call(FlAdvancedValid.SlShutdown, hooks.HasFlag(FlHookFamily.SlShutdown)));
_inGame.Call(FlAdvancedValid.SlShutdown, hooks.HasFlag(FlHookFamily.SlShutdown)),
_inGame.DriverRead(hooked: true),
_inGame.DriverSlowestUs);
}
/// <summary>The ten calls' states, compared as one value when deciding whether the session's context moved.</summary>
@@ -563,7 +567,9 @@ public sealed class SessionRecorder : ISessionRecorder
AdvancedInGameCall? SetFeatureLoaded,
AdvancedInGameCall? AllocateResources,
AdvancedInGameCall? FreeResources,
AdvancedInGameCall? Shutdown);
AdvancedInGameCall? Shutdown,
AdvancedDriverRead? Driver,
int? DriverSlowestUs);
/// <summary>
/// What the row says of the entries read inside the game: read, measured inside the game with none of their
+118 -3
View File
@@ -809,6 +809,51 @@ public enum FlAdvancedValid : uint
/// <summary>0.1.0-beta.45: <c>slShutdown</c> was seen; <see cref="FlAdvancedState.SlShutdowns"/> counts.</summary>
SlShutdown = 1u << 6,
/// <summary>
/// Train C (0.1.0-beta.47): a read of the driver's latency report returned OK for
/// this request. Not one of the game's calls: the Overlay makes this read itself, and
/// <see cref="FlAdvancedState.LatState"/> says where it stands even while this bit is clear.
/// </summary>
Latency = 1u << 7,
}
/// <summary>
/// The low byte of <see cref="FlAdvancedState.LatState"/> (<c>fl_shm.h</c>'s <c>FlLatencyState</c>).
/// <see cref="Refused"/>, <see cref="NoGetter"/>, <see cref="Slow"/>, <see cref="Faulted"/> and <see cref="Stalled"/>
/// are final for the process: nothing is retried, and a later session of the same process reads the same word.
/// </summary>
public enum FlLatencyState : uint
{
/// <summary>Not asked, or nothing looked at yet.</summary>
None = 0,
/// <summary>Asked; no Direct3D 12 device has been seen behind a hooked swap chain.</summary>
NoDevice = 1,
/// <summary>The game has not loaded <c>nvapi64.dll</c>.</summary>
NoModule = 2,
/// <summary>The <c>nvapi64.dll</c> in the process sits in the executable's own folder: not the driver's (D140).</summary>
Refused = 3,
/// <summary>The module does not answer for both getters, or answered with an address outside itself.</summary>
NoGetter = 4,
/// <summary>Resolved; a read is made about once a second.</summary>
Reading = 5,
/// <summary>The last read returned an NVAPI status that is not OK; reading goes on.</summary>
Error = 6,
/// <summary>One call took 2 ms or more: off until the game exits (D141).</summary>
Slow = 7,
/// <summary>A getter faulted: off until the game exits.</summary>
Faulted = 8,
/// <summary>A call had not returned after a second: nothing can stop it.</summary>
Stalled = 9,
}
/// <summary>
@@ -842,6 +887,24 @@ public unsafe struct FlAdvancedState
/// </summary>
public const uint FloatInfinite = 0x7F800000u;
/// <summary>The bits of <see cref="LatState"/> that hold the <see cref="FlLatencyState"/>.</summary>
public const uint LatStateMask = 0x000000FFu;
/// <summary>Bits 8..12 of <see cref="LatState"/>: sleep-status switches seen on, in the vendor struct's order.</summary>
public const int LatSleepSeenOnShift = 8;
/// <summary>Bits 16..20 of <see cref="LatState"/>: the same switches seen off.</summary>
public const int LatSleepSeenOffShift = 16;
/// <summary>The five switches of one group.</summary>
public const uint LatSleepBits = 0x1Fu;
/// <summary>Bits 24..31 of <see cref="LatState"/>: the last frame-generation multiplier the status gave, stopping at 255.</summary>
public const int LatFgMultiplierShift = 24;
/// <summary>A span sum: a summed frame did not report the span.</summary>
public const uint LatSumNone = 0xFFFFFFFFu;
/// <summary>How many feature slots <see cref="Features"/> holds.</summary>
public const int FeatureSlots = 12;
@@ -865,8 +928,42 @@ public unsafe struct FlAdvancedState
/// <summary>QueryPerformanceCounter at the last publication.</summary>
public ulong SampleQpc;
/// <summary>Must be zero.</summary>
public fixed uint ReservedHeader[10];
/// <summary>
/// Reflex latency (train C, 0.1.0-beta.47; the ten words that were <c>ReservedHeader</c>). The low byte is a
/// <see cref="FlLatencyState"/>; above it the driver's sleep status as seen (<see cref="LatSleepSeenOnShift"/>,
/// <see cref="LatSleepSeenOffShift"/>, <see cref="LatFgMultiplierShift"/>). Zero in a process nobody asked.
/// </summary>
public uint LatState;
/// <summary>Bits 0..15: reads made since the request. Bits 16..31: the slowest call, microseconds. Each stops at 65535.</summary>
public uint LatReads;
/// <summary>
/// Of the newest read not yet published: bits 0..15 frames summed, bits 16..31 frames refused. Zero when no read
/// was made since the publication before.
/// </summary>
public uint LatFrames;
/// <summary>Sum over the frames summed, microseconds, simulation start to end; <see cref="LatSumNone"/> = not reported.</summary>
public uint LatSimulationSumUs;
/// <summary>Render submit start to end.</summary>
public uint LatSubmitSumUs;
/// <summary>Present start to end.</summary>
public uint LatPresentSumUs;
/// <summary>Driver start to end.</summary>
public uint LatDriverSumUs;
/// <summary>OS render queue start to end.</summary>
public uint LatOsQueueSumUs;
/// <summary>GPU render start to end.</summary>
public uint LatGpuSumUs;
/// <summary>Simulation start to GPU render end.</summary>
public uint LatTotalSumUs;
/// <summary>The <c>structVersion</c> the game's <c>sl::DLSSOptions</c> declared; 0 = none seen.</summary>
public uint DlssStructVersion;
@@ -903,8 +1000,26 @@ public unsafe struct FlAdvancedState
/// <summary>Must be zero.</summary>
public fixed byte DlssPad[3];
/// <summary>
/// The driver's own active render time (<c>gpuActiveRenderTimeUs</c>) summed over the frames of the newest read
/// that gave one, microseconds (0.1.0-beta.48, D142; four words of this line's reserve, nothing of DLSS's).
/// </summary>
public uint LatGpuActiveSumUs;
/// <summary>The driver's own frame time at the graphics card (<c>gpuFrameTimeUs</c>), summed the same way.</summary>
public uint LatGpuFrameSumUs;
/// <summary>Bits 0..15: the frames in <see cref="LatGpuActiveSumUs"/>; bits 16..31: those in <see cref="LatGpuFrameSumUs"/>.</summary>
public uint LatGpuCounts;
/// <summary>
/// Bit n: the driver's sleep status gave frame-generation multiplier n since the request; bit 31 stands for 31
/// and more (D144).
/// </summary>
public uint LatMultipliersSeen;
/// <summary>Must be zero.</summary>
public fixed uint ReservedDlss[7];
public fixed uint ReservedDlss[3];
/// <summary>Upscale dispatches whose extras were read (wraps).</summary>
public uint FfxDispatches;
+83
View File
@@ -210,6 +210,79 @@ add_subdirectory(FrameLedger.VkLayer)
# -DFL_BUILD_TOOLS=ON -DFL_BUILD_TESTS=OFF a configuration error.
enable_testing()
# A TEST THAT WAS CUT SHORT IS NOT A PASS (2026-11-13).
#
# ctest calls a test passed when its process exits with 0. On 2026-11-13 the development PC's security software
# removed a freshly linked fl_guard_test.exe while the gate ran: the process ended early, with 0, and ctest printed
# "fl_guard ... Passed 0.66 sec" for a suite that takes three minutes. The gate went red only because the next test,
# fl_prescan, runs the same executable and could not find it -- by luck, not by design. An exit code cannot tell
# "finished and passed" from "stopped, and nobody complained".
#
# So every test in this tree must PRINT THE LINE IT ENDS ON, and ctest is told to look for it
# (PASS_REGULAR_EXPRESSION): the last thing the program writes when it has run to its end and passed. A run that
# stops before that line is red, whatever it returned.
#
# TWO THINGS ABOUT PASS_REGULAR_EXPRESSION, both learnt here before (tests/CMakeLists.txt, fl_nvapi_bridge): with it
# set ctest IGNORES THE EXIT CODE, so the line must be one the program prints only when it passed -- and where a
# program's summary can read "passed" beside a failure, FAIL_REGULAR_EXPRESSION names the failure. A SKIP_RETURN_CODE
# still wins: a test that says "cannot run here" is skipped, not failed for the line it never reached.
#
# fl_test_completes(<test> <regex>...) -- the test passes only if its output matches one of the expressions.
# fl_catch2_test_completes(<test>...) -- the same for a Catch2 executable: its own last line, or its summary row
# when a case was skipped, and never a row that names a failure.
# EVERY TEST MUST GO THROUGH ONE OF THE TWO: fl_require_every_test_completes(), at the end of this file, fails the
# CONFIGURE when a test in tests/ or tools/ has not -- a new test cannot be added without its last line.
function(fl_test_completes test)
if(ARGC LESS 2)
message(FATAL_ERROR "fl_test_completes(${test}): give the line the test ends on")
endif()
set_tests_properties(${test} PROPERTIES PASS_REGULAR_EXPRESSION "${ARGN}")
set_property(GLOBAL APPEND PROPERTY FL_TESTS_THAT_COMPLETE "${test}")
endfunction()
# Catch2's console reporter ends a run with "All tests passed (N assertions in M test cases)" when every case
# passed, and with a row "test cases: T | P passed | S skipped" when one was skipped (catch_reporter_helpers.cpp,
# printTestRunTotals: a count of zero has no column). A row with a failure has " | F failed" in it.
set(FL_CATCH2_COMPLETE "All tests passed \\(" "test cases: +[0-9]+ \\| +[0-9]+ passed \\| +[0-9]+ skipped")
set(FL_CATCH2_FAILED "\\| +[0-9]+ failed")
function(fl_catch2_test_completes)
foreach(test IN LISTS ARGN)
fl_test_completes(${test} ${FL_CATCH2_COMPLETE})
set_tests_properties(${test} PROPERTIES FAIL_REGULAR_EXPRESSION "${FL_CATCH2_FAILED}")
endforeach()
endfunction()
function(fl_collect_tests directory out)
get_property(found DIRECTORY "${directory}" PROPERTY TESTS)
get_property(subdirectories DIRECTORY "${directory}" PROPERTY SUBDIRECTORIES)
foreach(subdirectory IN LISTS subdirectories)
fl_collect_tests("${subdirectory}" nested)
list(APPEND found ${nested})
endforeach()
set(${out} "${found}" PARENT_SCOPE)
endfunction()
function(fl_require_every_test_completes)
get_property(complete GLOBAL PROPERTY FL_TESTS_THAT_COMPLETE)
set(missing "")
foreach(directory IN LISTS ARGN)
if(IS_DIRECTORY "${directory}")
fl_collect_tests("${directory}" tests)
foreach(test IN LISTS tests)
if(NOT test IN_LIST complete)
list(APPEND missing "${test}")
endif()
endforeach()
endif()
endforeach()
if(missing)
list(JOIN missing ", " names)
message(FATAL_ERROR
"These tests can be cut short and still pass: ${names}. Each needs the line it ends on -- "
"fl_test_completes() or fl_catch2_test_completes(), see the note above enable_testing().")
endif()
endfunction()
if(FL_BUILD_TESTS)
add_subdirectory(tests)
endif()
@@ -217,3 +290,13 @@ endif()
if(FL_BUILD_TOOLS)
add_subdirectory(tools)
endif()
# Last, when every test is registered: none may be left that passes on its exit code alone.
set(fl_test_directories "")
if(FL_BUILD_TESTS)
list(APPEND fl_test_directories "${CMAKE_CURRENT_SOURCE_DIR}/tests")
endif()
if(FL_BUILD_TOOLS)
list(APPEND fl_test_directories "${CMAKE_CURRENT_SOURCE_DIR}/tools")
endif()
fl_require_every_test_completes(${fl_test_directories})
@@ -34,6 +34,8 @@ add_dependencies(FrameLedger.Overlay fl_ac_floor_gen)
target_link_libraries(FrameLedger.Overlay PRIVATE fl_ac_floor)
target_link_libraries(FrameLedger.Overlay PRIVATE FrameLedger.Shm fl_dxgi_vtable fl_native_flags fl_hostile_env_flags minhook
fl_streamline_headers fl_fidelityfx_headers fl_fsr3_host_headers
# NVAPI's headers and NOT its library (third_party/CMakeLists.txt says why): fl_reflex.h's structs and ids.
fl_nvapi_headers
# Advapi32: the ring's DACL. User32: WindowFromDC / GetClientRect for the OpenGL
# output size. Shell32 + Ole32: SHGetKnownFolderPath for the native log's
# directory (§S21's resolution, not the environment), init/watchdog thread only.
@@ -15,6 +15,9 @@
// m const FfxApiEffectMemoryUsage& what ffxQuery wrote, after it answered OK
// q the memory query's descriptor (its out-pointer), and `desc`, its header (its type)
//
// (and since train C three more, for what the driver wrote into the Overlay's own buffers: `lr`, `lf` and `ls` --
// the section "REFLEX LATENCY" below says what they are and why they are here.)
//
// RULE 4. Each is an argument of a call the Overlay hooks, or what that call wrote
// through an out-pointer the game gave it. Nothing else is dereferenced: no
// resource, no command list, no callback, and never a camera's position, axes or
@@ -41,6 +44,7 @@
#include <atomic>
#include <bit>
#include <cstdint>
#include <fl_reflex.h>
#include <fl_shm.h>
#include <sl.h>
// After sl.h, as fl_sl_inputs.h explains: sl_dlss.h has no includes of its own.
@@ -640,6 +644,210 @@ inline void ObserveSlShutdown(Accumulators& a) noexcept {
NoteBits(a.validMask, FL_ADV_VALID_SL_SHUTDOWN);
}
// ---------------------------------------------------------------------------------------------------------------------
// REFLEX LATENCY (train C; owner decisions D132, D136, D138-D141; fl_reflex.h; fl_shm.h's latency words).
//
// THE ONE GROUP HERE THAT IS NOT AN ARGUMENT OF A HOOKED CALL. The two structs below are what the driver wrote into
// buffers the OVERLAY handed to its two read-only getters (fl_reflex.h makes the calls). The members read are on
// the same list as every other, through three more parameters with fixed names:
//
// lr const NV_LATENCY_RESULT_PARAMS& the report: sixty-four frames
// lf const NV_LATENCY_RESULT_PARAMS::FrameReport& one frame of it, handed on by index and never aliased
// ls const NV_GET_SLEEP_STATUS_PARAMS& the driver's sleep status
//
// WHAT IS NOT READ: inputSampleTime (the probe never saw it set, and "when the player pressed something" is nothing
// a frame-time tool needs), the camera, cross-adapter and frame-generation times, and the sleep interval -- it
// changes with every frame, so it is not a fact of a session.
//
// TWO TIMES THE DRIVER WORKS OUT ITSELF (0.1.0-beta.48, owner decision D142): gpuActiveRenderTimeUs -- the header:
// the GPU's start to its end "excluding the idles in between" -- and gpuFrameTimeUs, one frame's GPU end to the
// next's. In a real game the span between the two GPU marks was longer than the frame's whole (HANDOFF, item 45):
// it includes the waiting. They are members of the report already in hand; no call is added.
//
// THE RULES A GAME NEEDS (spike-notes §31). The newest frames of a report are not final -- one run read a span of
// half an hour in the newest -- so the two newest ids are never summed. A span whose end point is zero was not
// reported, which is not a fault of the frame: without a sleep mode the driver leaves driverStartTime zero in every
// frame. A span that runs backwards or lasts more than a second is one no frame can have, and that frame is
// refused whole; so is a frame with no total. Frame ids that go backwards are a game that started counting again.
//
// The caller owns the tally and the cursor (dllmain.cpp's gate says who that is at any moment): nothing here is
// atomic, and nothing here calls out.
// ---------------------------------------------------------------------------------------------------------------------
inline constexpr uint32_t kLatSpans =
7u; // simulation, submit, present, driver, OS queue, GPU, total: the region's order
inline constexpr uint32_t kLatTotal = 6u;
inline constexpr uint32_t kLatReportFrames = 64u;
inline constexpr uint64_t kLatSpanLimitUs = 1000000u;
static_assert(sizeof(NV_LATENCY_RESULT_PARAMS::frameReport) / sizeof(NV_LATENCY_RESULT_PARAMS::FrameReport) ==
kLatReportFrames);
// What one read of the report added up to.
struct LatencyTally {
uint32_t frames = 0; // frames summed
uint32_t refused = 0; // frames refused
uint32_t sumUs[kLatSpans]{}; // microseconds, over the frames summed
uint32_t lacking = 0; // bit n: a summed frame did not report span n
// The driver's two own times, each over the summed frames that gave one: a count apiece.
uint32_t activeSumUs = 0;
uint32_t activeFrames = 0;
uint32_t frameTimeSumUs = 0;
uint32_t frameTimeFrames = 0;
};
// Where the reader is in the game's frame ids: the newest one already summed or refused. 0 = none yet.
struct LatencyCursor {
uint64_t lastFrameId = 0;
};
inline constexpr uint32_t kLatSpanReported = 0u;
inline constexpr uint32_t kLatSpanAbsent = 1u;
inline constexpr uint32_t kLatSpanImpossible = 2u;
inline uint32_t LatencySpan(uint64_t start, uint64_t end, uint32_t& us) noexcept {
us = 0u;
if (start == 0u || end == 0u) {
return kLatSpanAbsent;
}
if (end < start || end - start > kLatSpanLimitUs) {
return kLatSpanImpossible;
}
us = static_cast<uint32_t>(end - start);
return kLatSpanReported;
}
// A slot of the report the driver put nothing in.
inline bool LatencyFrameIsEmpty(const NV_LATENCY_RESULT_PARAMS::FrameReport& lf) noexcept {
return lf.frameID == 0u && lf.simStartTime == 0u && lf.gpuRenderEndTime == 0u;
}
inline uint64_t LatencyFrameId(const NV_LATENCY_RESULT_PARAMS::FrameReport& lf) noexcept {
return lf.frameID;
}
// One of the driver's own times, of a frame that is summed. Zero is a frame the driver gave no such time for
// (an older driver leaves both zero, and so did the probe's frames, which had no work for the card); more than a
// second is a time no frame can have. Neither is summed, and neither refuses the frame: which frames the spans are
// made of does not depend on these.
inline void LatencyAddTime(uint32_t us, uint32_t& sumUs, uint32_t& frames) noexcept {
if (us != 0u && us <= kLatSpanLimitUs) {
sumUs += us;
++frames;
}
}
inline void ObserveLatencyFrame(const NV_LATENCY_RESULT_PARAMS::FrameReport& lf, LatencyTally& tally) noexcept {
uint32_t us[kLatSpans]{};
const uint32_t kind[kLatSpans] = {
LatencySpan(lf.simStartTime, lf.simEndTime, us[0]),
LatencySpan(lf.renderSubmitStartTime, lf.renderSubmitEndTime, us[1]),
LatencySpan(lf.presentStartTime, lf.presentEndTime, us[2]),
LatencySpan(lf.driverStartTime, lf.driverEndTime, us[3]),
LatencySpan(lf.osRenderQueueStartTime, lf.osRenderQueueEndTime, us[4]),
LatencySpan(lf.gpuRenderStartTime, lf.gpuRenderEndTime, us[5]),
LatencySpan(lf.simStartTime, lf.gpuRenderEndTime, us[kLatTotal]),
};
bool refuse = kind[kLatTotal] != kLatSpanReported; // no total, or one no frame can have
for (uint32_t i = 0; i < kLatTotal; ++i) {
refuse = refuse || kind[i] == kLatSpanImpossible;
}
if (refuse) {
++tally.refused;
return;
}
++tally.frames;
for (uint32_t i = 0; i < kLatSpans; ++i) {
if (kind[i] == kLatSpanAbsent) {
tally.lacking |= 1u << i;
} else {
tally.sumUs[i] += us[i];
}
}
LatencyAddTime(lf.gpuActiveRenderTimeUs, tally.activeSumUs, tally.activeFrames);
LatencyAddTime(lf.gpuFrameTimeUs, tally.frameTimeSumUs, tally.frameTimeFrames);
}
// One report: the frames newer than the cursor, the two newest left for the next read.
inline void ObserveLatencyReport(const NV_LATENCY_RESULT_PARAMS& lr, LatencyCursor& cursor,
LatencyTally& tally) noexcept {
tally = LatencyTally{};
uint64_t newest = 0u;
uint64_t second = 0u;
for (uint32_t i = 0; i < kLatReportFrames; ++i) {
if (LatencyFrameIsEmpty(lr.frameReport[i])) {
continue;
}
const uint64_t id = LatencyFrameId(lr.frameReport[i]);
if (id > newest) {
second = newest;
newest = id;
} else if (id > second && id != newest) {
second = id;
}
}
if (newest == 0u) {
return; // a report of nothing
}
if (newest < cursor.lastFrameId) {
cursor.lastFrameId = 0u; // the game's frame ids started again
}
uint64_t last = cursor.lastFrameId;
for (uint32_t i = 0; i < kLatReportFrames; ++i) {
if (LatencyFrameIsEmpty(lr.frameReport[i])) {
continue;
}
const uint64_t id = LatencyFrameId(lr.frameReport[i]);
if (id <= cursor.lastFrameId || id >= second) {
continue; // summed already, or one of the two newest
}
ObserveLatencyFrame(lr.frameReport[i], tally);
last = id > last ? id : last;
}
cursor.lastFrameId = last;
}
// The driver's sleep status: which of its five switches are on (bit n, in the struct's order -- fl_shm.h) and its
// frame-generation multiplier. The driver's words, not the game's: see FlLatencyState.
struct LatencySleep {
uint32_t on = 0;
uint32_t multiplier = 0; // its frame-generation multiplier
};
inline LatencySleep ObserveSleepStatus(const NV_GET_SLEEP_STATUS_PARAMS& ls) noexcept {
LatencySleep seen{};
seen.on = (ls.bLowLatencyMode != 0u ? 1u : 0u) | (ls.bFsVrr != 0u ? 2u : 0u) | (ls.bCplVsyncOn != 0u ? 4u : 0u) |
(ls.bUseGameSleep != 0u ? 8u : 0u) | (ls.bFullscreenIFlip != 0u ? 16u : 0u);
seen.multiplier = static_cast<uint32_t>(ls.fgMultiplier);
return seen;
}
// The bit of fl_shm.h's latMultipliersSeen for one multiplier the status gave: bit n for n, bit 31 for 31 and more.
inline uint32_t LatencyMultiplierBit(uint32_t value) noexcept {
return 1u << (value > 31u ? 31u : value);
}
// What the watchdog publishes of it. THE WATCHDOG'S: filled from what a read left behind while nobody is reading.
struct LatencyOut {
uint32_t state = FL_LAT_NONE; // FlLatencyState
uint32_t sleepSeenOn = 0; // switches the status showed on, since the request
uint32_t sleepSeenOff = 0; // ... and off
uint32_t multiplier = 0; // the last frame-generation multiplier the status gave
uint32_t multipliersSeen = 0; // every one it gave since the request (LatencyMultiplierBit)
uint32_t reads = 0; // reads made since the request
uint32_t worstUs = 0; // the slowest call since the request
LatencyTally tally; // of the newest read not yet published; Publish empties it
};
inline uint32_t LatencySum(const LatencyTally& tally, uint32_t span) noexcept {
if (tally.frames == 0u) {
return 0u;
}
return (tally.lacking & (1u << span)) != 0u ? FL_LAT_SUM_NONE : tally.sumUs[span];
}
inline uint32_t Stop16(uint32_t value) noexcept {
return value > 0xFFFFu ? 0xFFFFu : value;
}
// A NEW REQUEST: the summaries start afresh, so a session's ranges, masks and
// counts are its own and not those of the session before it in the same game.
// THE WATCHDOG'S. A detour running beside it loses nothing that matters: what it
@@ -718,7 +926,11 @@ inline void Reset(Accumulators& a) noexcept {
// WATCHDOG'S, and only the watchdog's: one writer, so the seqlock is odd -> stores
// -> even with no compare-exchange. The frame-time pair is drained, so each
// publication carries the dispatches since the last one.
inline void Publish(Accumulators& a, FlAdvancedState* region, uint32_t request, uint64_t qpc) noexcept {
//
// `latency` is the watchdog's summary of the driver's latency report, or null for a caller that has none: the
// fourteen latency words are then left as they are -- zero, in a region nobody else writes.
inline void Publish(Accumulators& a, FlAdvancedState* region, uint32_t request, uint64_t qpc,
LatencyOut* latency = nullptr) noexcept {
if (region == nullptr) {
return;
}
@@ -742,6 +954,28 @@ inline void Publish(Accumulators& a, FlAdvancedState* region, uint32_t request,
put32(region->request, request);
put64(region->sampleQpc, qpc);
if (latency != nullptr) {
LatencyOut& out = *latency;
put32(region->latState, (out.state & FL_LAT_STATE_MASK) |
((out.sleepSeenOn & FL_LAT_SLEEP_BITS) << FL_LAT_SLEEP_SEEN_ON_SHIFT) |
((out.sleepSeenOff & FL_LAT_SLEEP_BITS) << FL_LAT_SLEEP_SEEN_OFF_SHIFT) |
((out.multiplier > 255u ? 255u : out.multiplier) << FL_LAT_FG_MULTIPLIER_SHIFT));
put32(region->latReads, Stop16(out.reads) | (Stop16(out.worstUs) << 16));
put32(region->latFrames, Stop16(out.tally.frames) | (Stop16(out.tally.refused) << 16));
put32(region->latSimulationSumUs, LatencySum(out.tally, 0u));
put32(region->latSubmitSumUs, LatencySum(out.tally, 1u));
put32(region->latPresentSumUs, LatencySum(out.tally, 2u));
put32(region->latDriverSumUs, LatencySum(out.tally, 3u));
put32(region->latOsQueueSumUs, LatencySum(out.tally, 4u));
put32(region->latGpuSumUs, LatencySum(out.tally, 5u));
put32(region->latTotalSumUs, LatencySum(out.tally, kLatTotal));
put32(region->latGpuActiveSumUs, out.tally.activeSumUs);
put32(region->latGpuFrameSumUs, out.tally.frameTimeSumUs);
put32(region->latGpuCounts, Stop16(out.tally.activeFrames) | (Stop16(out.tally.frameTimeFrames) << 16));
put32(region->latMultipliersSeen, out.multipliersSeen);
out.tally = LatencyTally{}; // one publication carries one read: a reader never adds two up
}
put32(region->dlssStructVersion, a.dlssStructVersion.load(relaxed));
put32(region->dlssOptionsSeen, a.dlssOptionsSeen.load(relaxed));
put32(region->dlssOutputWidth, a.dlssOutputWidth.load(relaxed));
@@ -323,9 +323,11 @@ static_assert(kFamilySlConstants != kFamilyEvaluateFeature && kFamilySlConstants
// Vulkan extensions and features -- are never followed (fl_adv_fields.h; tools/overlay-fields-check.ps1).
//
// INSTALLED ONLY WHERE ASKED FOR, as slSetConstants is (D111), a row and a bit each. THEY ARE THE FIRST ROWS OF THE
// TABLE because a game asks while it starts: the watchdog patches the rows in the table's order, each patch stops
// the game's threads for a moment, and in a process that was asked these two are the ones that cannot wait. In a
// process never asked they are passed over before anything is resolved, and the order changes nothing.
// TABLE because a game asks while it starts: until 0.1.0-beta.46 the watchdog patched the rows one by one in the
// table's order, each patch stopped the game's threads for a moment, and in a process that was asked these two were
// the ones that could not wait. The rows a tick finds now go in together, under one stop of the threads (D134), and
// the table's order is the order of their log lines. In a process never asked they are passed over before anything
// is resolved.
inline constexpr uint32_t kFamilySlFeatureVersion = static_cast<uint32_t>(fl::FL_HOOK_SL_FEATURE_VERSION);
inline constexpr uint32_t kFamilySlFeatureRequirements = static_cast<uint32_t>(fl::FL_HOOK_SL_FEATURE_REQUIREMENTS);
static_assert(kFamilySlFeatureVersion != kFamilySlFeatureRequirements &&
@@ -57,7 +57,8 @@ enum class InstallResult : std::uint32_t {
CreateFailed =
4, // the hooker could not create the hook (MinHook: already created, unsupported prologue, memory)
EnableFailed = 5, // created, not enabled: no patch at the target
StoppedDuring = 6, // the stop ran while this patch went in; the installer took it out again
StoppedDuring = 6, // the stop ran while this patch went in; the installer took it out again, or never put it in
Pending = 7, // in a Batch, created and waiting for its Commit; never logged
};
template <std::uint32_t Capacity>
@@ -176,6 +177,241 @@ InstallResult Install(Registry<Capacity>& registry, const std::atomic<std::uint3
return InstallResult::Installed;
}
// ---------------------------------------------------------------------------------------------------------------------
// BATCHES (0.1.0-beta.46, owner decision D134): several patches in, or every patch out, for ONE stop of the process's
// threads instead of one a patch.
//
// WHY. MinHook stops every thread of the process to write a jump: a snapshot of the system's threads, then a suspend,
// a context read and a resume for each of this process's. Enabling or disabling ONE hook does all of that for one
// jump. In the owner's games of 2026-11-13 the thirteen Streamline patches took 0.7 s to 2.8 s of a game's start that
// way, 57 to 215 ms each, and a stop restored its patches at about 160 ms each. MinHook can queue: mark hooks to be
// enabled or disabled, then apply every mark under one stop of the threads.
//
// WHAT THE QUEUE IS, AND THE TWO THINGS IT MAKES DANGEROUS (hook.c, MH_ApplyQueued). The queue is ONE table for the
// process: applying it applies every hook whose mark differs from its state -- not the caller's marks, everybody's.
// So:
// 1. A mark may never be left standing. A hook marked "enable" that failed, left marked, would be enabled by the
// next apply -- the stop's own, if that came next. And a hook marked "disable" for a target that a foreign overlay
// has patched over would have OUR saved bytes written over THEIR jump by whoever applied next (§H7).
// 2. Two threads may not interleave their marks and applies: the installer's apply would execute the stop's marks
// and the other way round.
// Hence the GATE (`BeginQueue` / `EndQueue` on the engine): mark, apply and commit happen inside it, and when it is
// free no hook has a mark that differs from its state. The gate is held for one apply and never across anything that
// can take the loader's lock (resolving a symbol is done before, by the caller).
//
// A draft of this marked EVERYTHING for disabling and then un-marked the targets it must not restore. It was refused
// on review against hook.c: un-marking a hook that is already disabled marks it for ENABLING, and the stop's own apply
// would have put a patch back in after the stop. Nothing here marks "all", and nothing un-marks by marking the
// opposite except where the hook's state is known.
//
// THE ENGINE, beside Create: QueueEnable(target) / QueueDisable(target) -> bool (mark only); Apply() -> bool (every
// mark, one stop of the threads; false when any failed -- it stops at the first failure and does not say which);
// EnsureEnabled(target) / EnsureDisabled(target) -> bool (one hook, true when it is in that state afterwards);
// BeginQueue() / EndQueue().
// ---------------------------------------------------------------------------------------------------------------------
// HOW A BATCH'S ONE APPLY ENDED (owner decision D137). Two install batches in real games took 0.61 s and 1.26 s on
// 0.1.0-beta.46 where sixteen others took 0.08-0.26 s, and the log could not say whether either was one long stop of
// the threads or an apply that failed part-way and was finished one patch at a time: the fallback wrote a line only
// for a patch that failed for good. The caller logs this. `singly` counts the patches handed to the engine one at a
// time after the apply said it had failed -- attempts, not stops: the engine makes no stop for one the apply had
// already done.
struct BatchOutcome {
bool applied = true; // the one apply did all it was asked, or there was nothing to apply
std::uint32_t singly = 0; // patches then enabled -- or, in the stop, restored -- one at a time
};
// The stop's walk: every committed patch that is still OURS is restored, under one apply; a patch a foreign overlay
// has patched over is left exactly as it is (17_HOOK_ENGINE §Unhooking, §H7). The caller has already cleared the
// observing flag -- this is the read half of the pair described at the top of this file.
//
// `ours(target, detour)` -> bool: the bytes at the target are still the jump made for us (fl_patch_check.h).
// `report(name, target, wasOurs, restored)` is called once per committed patch, after the gate is released.
template <std::uint32_t Capacity, class Hooker, class Ours, class Report>
BatchOutcome RestoreAll(const Registry<Capacity>& registry, Hooker&& hooker, Ours&& ours, Report&& report) noexcept {
struct Entry {
void* target;
const char* name;
bool wasOurs;
bool marked;
bool restored;
};
Entry entries[Capacity];
std::uint32_t count = 0;
bool anyMarked = false;
hooker.BeginQueue();
registry.ForEachLive(
[&entries, &count, &anyMarked, &hooker, &ours](void* target, void* detour, const char* name) noexcept {
if (count >= Capacity) {
return;
}
// Only a patch that is still ours is ever marked. One that is not is not touched -- not marked, and not
// un-marked either: it has no mark to remove.
const bool mine = ours(target, detour);
const bool marked = mine && hooker.QueueDisable(target);
anyMarked = anyMarked || marked;
entries[count++] = Entry{target, name, mine, marked, false};
});
const bool applied = !anyMarked || hooker.Apply();
BatchOutcome outcome{applied, 0u};
for (std::uint32_t i = 0; i < count; ++i) {
Entry& e = entries[i];
if (!e.marked) {
continue;
}
outcome.singly += applied ? 0u : 1u;
// The apply stops at the first hook it cannot restore: the ones after it are taken out one at a time, as
// every patch was until 0.1.0-beta.46. One that will not come out at all has its mark removed -- it is
// enabled, so marking it "enable" leaves nothing to apply.
e.restored = applied || hooker.EnsureDisabled(e.target);
if (!e.restored) {
hooker.QueueEnable(e.target);
}
}
hooker.EndQueue();
for (std::uint32_t i = 0; i < count; ++i) {
report(entries[i].name, entries[i].target, entries[i].wasOurs, entries[i].restored);
}
return outcome;
}
// Several patches, registered before any can run, enabled under ONE stop of the threads, and none left in after a
// stop -- the sequence of Install, for a group. One thread fills and commits a batch (the Overlay's watchdog).
//
// Add: claim a slot and create the hook; nothing is at the target yet and nothing is marked. Commit: enable them all.
// After Commit every item carries its InstallResult, and the caller does what follows a patch (its log line, its
// family bit) for the ones that read Installed, in the order they were added.
template <std::uint32_t Capacity>
class Batch {
public:
struct Item {
void* target = nullptr;
void* detour = nullptr;
const char* name = nullptr;
void* context = nullptr; // the caller's: what to do once the patch is in
std::uint32_t word = 0; // the caller's
int slot = -1;
InstallResult result = InstallResult::NoTarget;
};
// Pending: the hook is created and waits for Commit. Anything else is final and nothing was added.
template <class Hooker>
InstallResult Add(Registry<Capacity>& registry, const std::atomic<std::uint32_t>& observing, Hooker&& hooker,
void* target, void* detour, void** original, const char* name, void* context,
std::uint32_t word) noexcept {
if (target == nullptr) {
return InstallResult::NoTarget;
}
if (observing.load(std::memory_order_seq_cst) == 0u) {
return InstallResult::Stopped;
}
if (count_ >= Capacity) {
return InstallResult::Full; // not reachable before the registry itself is full: one slot an item
}
const int slot = registry.Claim(target, detour, name);
if (slot < 0) {
return InstallResult::Full;
}
if (!hooker.Create(target, detour, original)) {
registry.Release(slot);
return InstallResult::CreateFailed;
}
items_[count_++] = Item{target, detour, name, context, word, slot, InstallResult::Pending};
return InstallResult::Pending;
}
// Returns how the apply that put the patches IN ended; the apply that takes them out again after a stop that
// landed meanwhile is not reported -- every item then reads StoppedDuring.
template <class Hooker, class Ours>
BatchOutcome Commit(Registry<Capacity>& registry, const std::atomic<std::uint32_t>& observing, Hooker&& hooker,
Ours&& ours) noexcept {
if (count_ == 0u) {
return BatchOutcome{};
}
hooker.BeginQueue();
if (observing.load(std::memory_order_seq_cst) == 0u) {
// The stop ran between Add and here. Nothing was marked and nothing is at any target: the slots go back,
// and the hooks stay created and disabled in the engine, as a hook that failed to enable always has.
for (std::uint32_t i = 0; i < count_; ++i) {
registry.Release(items_[i].slot);
items_[i].result = InstallResult::StoppedDuring;
}
hooker.EndQueue();
return BatchOutcome{};
}
for (std::uint32_t i = 0; i < count_; ++i) {
if (!hooker.QueueEnable(items_[i].target)) {
registry.Release(items_[i].slot);
items_[i].result = InstallResult::EnableFailed;
}
}
const bool applied = hooker.Apply();
BatchOutcome outcome{applied, 0u};
for (std::uint32_t i = 0; i < count_; ++i) {
Item& item = items_[i];
if (item.result != InstallResult::Pending) {
continue;
}
outcome.singly += applied ? 0u : 1u;
// The ENGINE says whether the hook is enabled, not the bytes at the target: a foreign overlay that
// patched over us a moment after the apply would read as "not in", and taking that for a failure would
// mark a restore nobody had compared (§H7). The apply stops at the first hook that fails, so the ones
// after it are enabled one at a time -- one bad patch costs one patch, as it always has.
if (applied || hooker.EnsureEnabled(item.target)) {
registry.Commit(item.slot);
item.result = InstallResult::Installed;
} else {
hooker.QueueDisable(item.target); // it is disabled: this removes the mark, and marks nothing
registry.Release(item.slot);
item.result = InstallResult::EnableFailed;
}
}
hooker.EndQueue();
if (observing.load(std::memory_order_seq_cst) != 0u) {
return outcome;
}
// The stop ran while the batch went in -- the re-read of Install, for the group. Its walk either saw the
// committed slots and restored the patches, and then they are no longer ours and nothing is marked, or it had
// passed them, and this takes them out. Compared first, as the stop compares: a patch something else has
// patched over in the meantime is left to it.
bool takeOut[Capacity]{};
bool anyMarked = false;
hooker.BeginQueue();
for (std::uint32_t i = 0; i < count_; ++i) {
const Item& item = items_[i];
if (item.result == InstallResult::Installed) {
takeOut[i] = ours(item.target, item.detour) && hooker.QueueDisable(item.target);
anyMarked = anyMarked || takeOut[i];
}
}
const bool out = !anyMarked || hooker.Apply();
for (std::uint32_t i = 0; i < count_; ++i) {
Item& item = items_[i];
if (item.result != InstallResult::Installed) {
continue;
}
if (takeOut[i] && !out && !hooker.EnsureDisabled(item.target)) {
hooker.QueueEnable(item.target); // enabled and staying so: no mark may be left standing
}
registry.Retire(item.slot);
item.result = InstallResult::StoppedDuring;
}
hooker.EndQueue();
return outcome;
}
std::uint32_t Count() const noexcept { return count_; }
const Item& At(std::uint32_t i) const noexcept { return items_[i]; }
void Clear() noexcept { count_ = 0u; }
private:
Item items_[Capacity]{};
std::uint32_t count_ = 0u;
};
} // namespace fl::patch
#endif // FRAMELEDGER_FL_PATCH_REGISTRY_H
@@ -0,0 +1,244 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
// The two calls the Overlay makes into NVIDIA's driver, and how it finds them (Advanced metrics train C; owner
// decisions D132, D136, D138-D141; docs/spike-notes §30, §31; 17_HOOK_ENGINE §Memory / latency).
//
// NOT A HOOK. Every other thing the Overlay learns in a game is an argument of a call it hooks. These are calls the
// Overlay MAKES: NvAPI_D3D_GetLatency and NvAPI_D3D_GetSleepStatus, the driver's two read-only latency getters, with
// the Direct3D 12 device behind the swap chain it hooks (rule 4's note of 2026-11-13). Getters only: no marker, no
// sleep mode, no sleep, nothing that changes what the driver does.
//
// THE GAME BROUGHT THE MODULE. nvapi64.dll is looked for by name among the modules the process ALREADY holds and is
// never loaded. This file is not linked against nvapi64.lib -- that static library loads the DLL itself -- and takes
// only the vendored MIT headers' ids (nvapi_interface.h) and structs (nvapi.h). tools/nvapi-readonly-check.ps1 holds
// that the two ids below are the only NVAPI ids in code loaded into a game.
//
// A MODULE IN THE EXECUTABLE'S OWN FOLDER IS REFUSED (D140). The driver's nvapi64.dll lives in Windows' own
// directories; one beside the game is a replacement somebody put there, and FrameLedger neither calls into it on a
// presenting thread nor records its numbers as NVIDIA's.
//
// WHERE THE TWO ADDRESSES ARE (measured by the probe, driver 32.0.16.2114). System32's nvapi64.dll is a shim: it
// answers the two ids with addresses inside ANOTHER image, nvapi64_impl.dll in the driver's own store. So an address
// is accepted when it is executable code of an image the process has loaded -- never the heap, never nowhere -- and
// a reference is kept on THAT image as well, because the addresses are only code for as long as it stays loaded and
// the game may unload NVAPI while a presenting thread is about to call.
//
// SHARED WITH THE PROBE (tools/fl-probe-reflex), which is built with the Overlay's flags and enforces Control Flow
// Guard: its ctest runs THIS sequence. hook-harness does not enforce it, so the injected tests say nothing about CFG.
// nvapi64_impl.dll IS a CFG image; its getters are valid call targets, which the probe's real runs show by having
// made the calls from an enforcing process. A target that were not would be a fast-fail no guard catches: in a game
// that enforces CFG, on a driver nobody has run the probe against, that is not excluded.
#ifndef FRAMELEDGER_FL_REFLEX_H
#define FRAMELEDGER_FL_REFLEX_H
#include <windows.h>
// nvapi.h declares its Direct3D structs only after a Direct3D header, and names DXGI's swap chain in passing.
#include <d3d12.h>
#include <dxgi.h>
#include <cstdint>
#include <cstring>
#include <nvapi.h>
namespace fl::reflex {
inline constexpr unsigned int kIdGetSleepStatus = 0xaef96ca1u; // nvapi_interface.h: NvAPI_D3D_GetSleepStatus
inline constexpr unsigned int kIdGetLatency = 0x1a587f9cu; // nvapi_interface.h: NvAPI_D3D_GetLatency
inline constexpr DWORD kPathCapacity = 520;
using QueryInterfaceFn = void*(__cdecl*)(unsigned int);
// The status type under a name of its own: tools/nvapi-readonly-check.ps1 takes an `NvAPI_` name followed by a
// parenthesis for a call by name, and code loaded into a game makes none.
using Status = NvAPI_Status;
using GetLatencyFn = Status(__cdecl*)(IUnknown*, NV_LATENCY_RESULT_PARAMS*);
using GetSleepStatusFn = Status(__cdecl*)(IUnknown*, NV_GET_SLEEP_STATUS_PARAMS*);
struct Api {
GetLatencyFn getLatency = nullptr;
GetSleepStatusFn getSleepStatus = nullptr;
HMODULE nvapi = nullptr; // the nvapi64.dll that was asked; one reference is held
HMODULE owner = nullptr; // the image GetLatency's address is in; references are held
wchar_t modulePath[kPathCapacity]{}; // where nvapi64.dll was loaded from, for the log
wchar_t ownerPath[kPathCapacity]{}; // ... and the image the getters are in
};
enum class Resolved : std::uint32_t {
Ok = 0,
NoModule = 1, // the process has not loaded nvapi64.dll: nothing was called and nothing was loaded
NoQueryInterface = 2, // a module of that name without the export
NoGetter = 3, // it does not answer for both getters, or answered with an address in no loaded image
Refused = 4, // it sits in the executable's own folder, or its path could not be read (D140)
Faulted = 5, // asking it for the getters faulted
};
// The Overlay's own filter (dllmain.cpp's FlFilter): a debugger's exceptions are not ours to swallow.
inline LONG Filter(DWORD code) noexcept {
if (code == EXCEPTION_BREAKPOINT || code == EXCEPTION_SINGLE_STEP) {
return EXCEPTION_CONTINUE_SEARCH;
}
return EXCEPTION_EXECUTE_HANDLER;
}
// The length of the directory part of a path, its last separator included; 0 when there is none.
inline DWORD DirectoryLength(const wchar_t* path, DWORD length) noexcept {
for (DWORD i = length; i > 0; --i) {
if (path[i - 1] == L'\\' || path[i - 1] == L'/') {
return i;
}
}
return 0;
}
// True when `nvapi` was loaded from the folder the process's executable is in -- or when either path cannot be read
// whole, which is refused the same way: what cannot be placed is not taken for the driver's.
inline bool InExecutableFolder(HMODULE nvapi, wchar_t* modulePath) noexcept {
wchar_t exePath[kPathCapacity]{};
const DWORD moduleLength = GetModuleFileNameW(nvapi, modulePath, kPathCapacity);
const DWORD exeLength = GetModuleFileNameW(nullptr, exePath, kPathCapacity);
if (moduleLength == 0 || moduleLength >= kPathCapacity || exeLength == 0 || exeLength >= kPathCapacity) {
return true;
}
const DWORD moduleDir = DirectoryLength(modulePath, moduleLength);
const DWORD exeDir = DirectoryLength(exePath, exeLength);
if (moduleDir == 0 || exeDir == 0) {
return true;
}
return CompareStringOrdinal(modulePath, static_cast<int>(moduleDir), exePath, static_cast<int>(exeDir), TRUE) ==
CSTR_EQUAL;
}
// The loaded image `address` is executable code of, with a reference taken on it -- or null. A getter's address
// comes from the module's own answer; this refuses one that is not code of an image before it is ever called, and
// keeps the image that holds it from being unloaded under a later call.
inline HMODULE OwnerImage(const void* address) noexcept {
MEMORY_BASIC_INFORMATION info{};
if (address == nullptr || VirtualQuery(address, &info, sizeof(info)) == 0) {
return nullptr;
}
const DWORD executable = PAGE_EXECUTE | PAGE_EXECUTE_READ | PAGE_EXECUTE_READWRITE | PAGE_EXECUTE_WRITECOPY;
if (info.Type != MEM_IMAGE || info.State != MEM_COMMIT || (info.Protect & executable) == 0u) {
return nullptr;
}
HMODULE owner = nullptr;
if (!GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS, static_cast<LPCWSTR>(address), &owner)) {
return nullptr;
}
return owner;
}
// The module's answers for the two ids, asked under a guard: the lookup runs the module's code.
inline bool AskForGetters(QueryInterfaceFn query, void*& latency, void*& sleepStatus, DWORD& faultCode) noexcept {
__try {
latency = query(kIdGetLatency);
sleepStatus = query(kIdGetSleepStatus);
return true;
} __except (Filter(GetExceptionCode())) {
faultCode = GetExceptionCode();
return false;
}
}
// Finds the two getters in a module the process ALREADY holds; never loads one.
//
// A REFERENCE IS TAKEN WHEN THE MODULE IS FOUND, and kept whatever is returned after that -- as the Overlay's
// ResolveScoped keeps the one on a module it patches -- so the caller must not call again once this has returned
// anything but NoModule: every other answer is final for the process. One more is taken on the image each getter is
// in. None is ever released: a presenting thread may be inside one of the calls.
inline Resolved Resolve(Api& api, DWORD& faultCode) noexcept {
api.getLatency = nullptr;
api.getSleepStatus = nullptr;
api.nvapi = nullptr;
api.owner = nullptr;
api.modulePath[0] = L'\0';
api.ownerPath[0] = L'\0';
faultCode = 0;
HMODULE nvapi = nullptr;
if (!GetModuleHandleExW(0, L"nvapi64.dll", &nvapi) || nvapi == nullptr) {
return Resolved::NoModule;
}
api.nvapi = nvapi;
if (InExecutableFolder(nvapi, api.modulePath)) {
return Resolved::Refused;
}
const auto query = reinterpret_cast<QueryInterfaceFn>(GetProcAddress(nvapi, "nvapi_QueryInterface"));
if (query == nullptr) {
return Resolved::NoQueryInterface;
}
void* latency = nullptr;
void* sleepStatus = nullptr;
if (!AskForGetters(query, latency, sleepStatus, faultCode)) {
return Resolved::Faulted;
}
const HMODULE latencyOwner = OwnerImage(latency);
const HMODULE statusOwner = OwnerImage(sleepStatus);
if (latencyOwner == nullptr || statusOwner == nullptr) {
return Resolved::NoGetter;
}
api.owner = latencyOwner;
if (const DWORD length = GetModuleFileNameW(latencyOwner, api.ownerPath, kPathCapacity);
length == 0 || length >= kPathCapacity) {
api.ownerPath[0] = L'\0';
}
api.getLatency = reinterpret_cast<GetLatencyFn>(latency);
api.getSleepStatus = reinterpret_cast<GetSleepStatusFn>(sleepStatus);
return Resolved::Ok;
}
inline Resolved Resolve(Api& api) noexcept {
DWORD faultCode = 0;
return Resolve(api, faultCode);
}
// What a read returns when the driver's code faulted under it: not one of NVAPI's own codes.
inline constexpr NvAPI_Status kFaulted = static_cast<NvAPI_Status>(-9999);
// One read of the driver's report. Guarded -- the first guard the Overlay puts around code that is not its own
// (17_HOOK_ENGINE §Fault policy says why this one is). A guard does not bound a call that never returns, and a
// caught fault does not give back a lock the driver held: the caller makes no second call after either.
inline NvAPI_Status ReadLatency(const Api& api, IUnknown* device, NV_LATENCY_RESULT_PARAMS& out,
DWORD& faultCode) noexcept {
std::memset(&out, 0, sizeof(out));
out.version = NV_LATENCY_RESULT_PARAMS_VER1;
if (api.getLatency == nullptr || device == nullptr) {
return NVAPI_INVALID_ARGUMENT;
}
__try {
return api.getLatency(device, &out);
} __except (Filter(GetExceptionCode())) {
faultCode = GetExceptionCode();
return kFaulted;
}
}
inline NvAPI_Status ReadSleepStatus(const Api& api, IUnknown* device, NV_GET_SLEEP_STATUS_PARAMS& out,
DWORD& faultCode) noexcept {
std::memset(&out, 0, sizeof(out));
out.version = NV_GET_SLEEP_STATUS_PARAMS_VER1;
if (api.getSleepStatus == nullptr || device == nullptr) {
return NVAPI_INVALID_ARGUMENT;
}
__try {
return api.getSleepStatus(device, &out);
} __except (Filter(GetExceptionCode())) {
faultCode = GetExceptionCode();
return kFaulted;
}
}
inline NvAPI_Status ReadLatency(const Api& api, IUnknown* device, NV_LATENCY_RESULT_PARAMS& out) noexcept {
DWORD faultCode = 0;
return ReadLatency(api, device, out, faultCode);
}
inline NvAPI_Status ReadSleepStatus(const Api& api, IUnknown* device, NV_GET_SLEEP_STATUS_PARAMS& out) noexcept {
DWORD faultCode = 0;
return ReadSleepStatus(api, device, out, faultCode);
}
} // namespace fl::reflex
#endif // FRAMELEDGER_FL_REFLEX_H
+479 -55
View File
@@ -164,6 +164,8 @@ enum FlLogCode : uint32_t {
kLogUpscaleRoute,
kLogRuntimeCensus,
kLogFfxConfigureType,
kLogPatchBatch,
kLogLatency,
};
const char* LogCodeName(uint32_t code) noexcept {
@@ -204,6 +206,10 @@ const char* LogCodeName(uint32_t code) noexcept {
return "RUNTIME_CENSUS";
case kLogFfxConfigureType:
return "FFX_CONFIGURE";
case kLogPatchBatch:
return "PATCH_BATCH";
case kLogLatency:
return "LATENCY";
default:
return "?";
}
@@ -395,15 +401,77 @@ static_assert(fl::inventory::kRowCount + kPatchSitesOutsideTheInventory <= kMaxP
"the patch registry cannot hold every patch this DLL may install -- raise kMaxPatches with the table");
fl::patch::Registry<kMaxPatches> g_patches;
// MinHook, as the engine fl::patch::Install drives.
// THE GATE around MinHook's queue (fl_patch_registry.h, BATCHES; 0.1.0-beta.46). MH_ApplyQueued applies every mark
// in the process's one table, so the watchdog's "mark, apply, commit" and the stop's "mark, apply" must not
// interleave. A slim reader/writer lock, taken exclusively: no allocation, no handle, nothing to initialise or tear
// down. Held for one apply -- one stop of the threads -- and never across a symbol lookup (the loader's lock).
//
// NOT IN ANY HOOK BODY. The one path from a hook to here is the stop itself -- MayObserve reading the Agent's request,
// or the third fault -- which already blocked for MinHook's own lock and a stop of the threads for every patch it
// restored. It waits here for at most the watchdog's one apply, once in a process's life.
//
// RE-ENTERED BY ITS OWNER WITHOUT WAITING: a slim lock taken twice by one thread never returns. The only way there is
// a stop that begins on the thread that is inside a batch -- a third fault in the LoadLibrary detour, if the engine
// loaded a module under the gate. That stop then runs with the marks the batch has made; the batch's own re-read of
// the flag takes out what it put in (fl_patch_registry.h, Batch::Commit).
SRWLOCK g_patchGate = SRWLOCK_INIT;
std::atomic<DWORD> g_patchGateOwner{0};
uint32_t g_patchGateDepth = 0; // the owner's alone
// MinHook, as the engine fl::patch::Install, Batch and RestoreAll drive.
struct MinHookEngine {
static bool Create(void* target, void* detour, void** original) noexcept {
return MH_CreateHook(target, detour, original) == MH_OK;
}
static bool Enable(void* target) noexcept { return MH_EnableHook(target) == MH_OK; }
static void Disable(void* target) noexcept { MH_DisableHook(target); }
static bool QueueEnable(void* target) noexcept { return MH_QueueEnableHook(target) == MH_OK; }
static bool QueueDisable(void* target) noexcept { return MH_QueueDisableHook(target) == MH_OK; }
static bool Apply() noexcept { return MH_ApplyQueued() == MH_OK; }
static bool EnsureEnabled(void* target) noexcept {
const MH_STATUS status = MH_EnableHook(target);
return status == MH_OK || status == MH_ERROR_ENABLED;
}
static bool EnsureDisabled(void* target) noexcept {
const MH_STATUS status = MH_DisableHook(target);
return status == MH_OK || status == MH_ERROR_DISABLED;
}
static void BeginQueue() noexcept {
const DWORD self = GetCurrentThreadId();
if (g_patchGateOwner.load(std::memory_order_acquire) == self) {
++g_patchGateDepth;
return;
}
AcquireSRWLockExclusive(&g_patchGate);
g_patchGateOwner.store(self, std::memory_order_release);
}
static void EndQueue() noexcept {
if (g_patchGateDepth != 0u) {
--g_patchGateDepth;
return;
}
g_patchGateOwner.store(0, std::memory_order_release);
ReleaseSRWLockExclusive(&g_patchGate);
}
};
// The performance counter, as a number. QuadPart is named in the initialiser so that it is the member the union
// holds when it is read back (SonarCloud's cpp:S6232 on a `{}` that initialises the other half).
int64_t QpcNow() noexcept {
LARGE_INTEGER now{.QuadPart = 0};
QueryPerformanceCounter(&now);
return now.QuadPart;
}
// Microseconds since `fromTicks` (QpcNow), for a PATCH_BATCH line; saturating, because the line's field is 32 bits.
uint32_t MicrosSince(int64_t fromTicks) noexcept {
const int64_t now = QpcNow();
const uint64_t ticks = now > fromTicks ? static_cast<uint64_t>(now - fromTicks) : 0u;
const uint64_t micros = g_logQpcFreq != 0u ? ticks * 1000000ull / g_logQpcFreq : 0u;
return micros > 0xFFFFFFFFull ? 0xFFFFFFFFu : static_cast<uint32_t>(micros);
}
// A patch that did not go in, said ONCE per target and reason: the lazy installers retry every second, and a line a
// second would push everything else out of a 256-event ring. Init and watchdog threads only, which never install at
// the same time (the watchdog starts after the init thread's last install), so a plain table.
@@ -515,6 +583,9 @@ struct SwapChainSlot {
uint32_t swapEffect = 0; // DXGI_SWAP_EFFECT + 1 (fl_shm.h §Region 4: DISCARD is 0); 0 = not read
uint32_t swapFlags = 0; // DXGI_SWAP_CHAIN_DESC.Flags
uint64_t displayQpc = 0; // the QPC of this chain's last display sample
// This chain's device is the one g_d3d12Device holds -- the first Direct3D 12 device seen, which is not "this
// chain's" for a title with two. The driver's latency report is read only at such a chain's present.
bool heldDevice = false;
};
// Region 4 (fl_shm.h, layout 4, beta.10): set in InitThread beside g_state, written only through PublishDisplay.
@@ -670,6 +741,277 @@ void PublishD3D12Device(ID3D12Device* device) noexcept {
}
}
// ---------------------------------------------------------------------------------------------------------------------
// REFLEX LATENCY: THE ONE CALL THE OVERLAY MAKES INTO A DRIVER (Advanced metrics train C; owner decisions D132, D136,
// D138-D141; fl_reflex.h; spike-notes §31; 17_HOOK_ENGINE §Memory / latency).
//
// While a session asks for Advanced metrics, and only then, the driver's two read-only latency getters are called
// about once a second with the Direct3D 12 device held above -- through an nvapi64.dll THE GAME had already loaded.
// Nothing is hooked for it and nothing is loaded for it.
//
// WHO DOES WHAT. The WATCHDOG finds the module and the two addresses, once for the process, and arms the gate at
// most once a second. A PRESENTING THREAD that finds the gate armed makes the read, after its frame's record is
// published: a call the driver holds stops the thread that made it, and the watchdog -- which supervises, installs
// and flushes -- must never be that thread (spike-notes §31, M2). So the call delays one present a second by its own
// length: 0.5-2.6 us measured, and one of 2 ms or more is the last one this process makes (D141).
//
// THE GATE, four states in one word, is what makes that safe without a lock:
// idle nobody is reading. g_latRead is the watchdog's: it takes what the last read left, then may arm.
// armed one read is wanted. Only the watchdog stores this.
// reading a presenting thread took `armed` by compare-exchange and is inside the read. g_latRead and
// g_latReport are that thread's. Two presenting threads cannot both be here, and the watchdog reads
// nothing of theirs while one is.
// off a read ended in a fault or took too long. Final for the process; g_latRead is the watchdog's again.
// A present pays one relaxed load for all of it.
//
// WHAT STOPS IT, each until the game exits: a fault in a getter (guarded, counted once in faultCount -- with the
// gate off it cannot be counted again, so it cannot reach the three that self-disable); a call of 2 ms or more; and
// a call that has not returned after two seconds, which nothing can stop -- that one is logged, flushed at once and
// published as stalled, and the gate is left where the stuck thread holds it.
// ---------------------------------------------------------------------------------------------------------------------
constexpr uint32_t kLatGateIdle = 0u;
constexpr uint32_t kLatGateArmed = 1u;
constexpr uint32_t kLatGateReading = 2u;
constexpr uint32_t kLatGateOff = 3u;
constexpr uint32_t kLatSlowMicros = 2000u; // owner decision D141
std::atomic<uint32_t> g_latGate{kLatGateIdle};
// Written by the watchdog before the gate is first armed, and never after.
fl::reflex::Api g_latApi;
// What one read left behind. Owned by whoever the gate says (above).
struct LatencyRead {
fl::adv::LatencyTally tally;
fl::adv::LatencyCursor cursor;
uint32_t fresh = 0; // a read finished since the watchdog last looked
uint32_t ok = 0; // its report came back NVAPI_OK
uint32_t state = 0; // FL_LAT_READING, _ERROR, _SLOW or _FAULTED after it
uint32_t micros = 0; // the slower of its two calls
uint32_t sleepValid = 0; // the sleep status came back NVAPI_OK
fl::adv::LatencySleep sleep;
};
LatencyRead g_latRead;
// 15.4 KB, in static storage: the report is never on a game thread's stack.
NV_LATENCY_RESULT_PARAMS g_latReport;
// The watchdog's own.
fl::adv::LatencyOut g_latOut;
bool g_latResolved = false; // the two addresses are in g_latApi
bool g_latFinal = false; // the module was looked at and will not be read; g_latOut.state says why
bool g_latStalled = false;
int64_t g_latArmedQpc = 0;
int64_t g_latReadingSinceQpc = 0;
uint32_t g_latLoggedState = FL_LAT_NONE;
// One read, on a presenting thread that found the gate armed. Not inlined: RecordPresent stays as small as it was.
__declspec(noinline) void ReadLatencyOnce() noexcept {
uint32_t armed = kLatGateArmed;
if (!g_latGate.compare_exchange_strong(armed, kLatGateReading, std::memory_order_acq_rel,
std::memory_order_relaxed)) {
return; // another presenting thread has it
}
auto* device = static_cast<IUnknown*>(g_d3d12Device.load(std::memory_order_acquire));
LatencyRead& read = g_latRead;
read.fresh = 1u;
read.ok = 0u;
read.sleepValid = 0u;
read.tally = fl::adv::LatencyTally{};
DWORD fault = 0;
const int64_t began = QpcNow();
const NvAPI_Status status = fl::reflex::ReadLatency(g_latApi, device, g_latReport, fault);
uint32_t micros = MicrosSince(began);
if (status == fl::reflex::kFaulted) {
read.state = FL_LAT_FAULTED;
read.micros = micros;
g_latGate.store(kLatGateOff, std::memory_order_release);
NoteFault(fault, "NvAPI_D3D_GetLatency (the driver's)");
return;
}
if (status == NVAPI_OK) {
fl::adv::ObserveLatencyReport(g_latReport, read.cursor, read.tally);
read.ok = 1u;
read.state = FL_LAT_READING;
} else {
read.state = FL_LAT_ERROR;
}
if (micros < kLatSlowMicros) {
NV_GET_SLEEP_STATUS_PARAMS sleepStatus; // 128 bytes
const int64_t beganStatus = QpcNow();
const NvAPI_Status second = fl::reflex::ReadSleepStatus(g_latApi, device, sleepStatus, fault);
const uint32_t microsStatus = MicrosSince(beganStatus);
micros = microsStatus > micros ? microsStatus : micros;
if (second == fl::reflex::kFaulted) {
read.state = FL_LAT_FAULTED;
read.micros = micros;
g_latGate.store(kLatGateOff, std::memory_order_release);
NoteFault(fault, "NvAPI_D3D_GetSleepStatus (the driver's)");
return;
}
if (second == NVAPI_OK) {
read.sleep = fl::adv::ObserveSleepStatus(sleepStatus);
read.sleepValid = 1u;
}
}
read.micros = micros;
if (micros >= kLatSlowMicros) {
read.state = FL_LAT_SLOW;
g_latGate.store(kLatGateOff, std::memory_order_release);
return;
}
g_latGate.store(kLatGateIdle, std::memory_order_release);
}
const char* LatencyStateName(uint32_t state) noexcept {
switch (state) {
case FL_LAT_NO_DEVICE:
return "no Direct3D 12 device behind a hooked swap chain";
case FL_LAT_NO_MODULE:
return "the game has not loaded nvapi64.dll";
case FL_LAT_REFUSED:
return "refused: nvapi64.dll is in the game's own folder";
case FL_LAT_NO_GETTER:
return "nvapi64.dll does not answer for the two getters";
case FL_LAT_READING:
return "reading the driver's latency report";
case FL_LAT_ERROR:
return "the driver answered with an error";
case FL_LAT_SLOW:
return "off: a call into the driver was slow";
case FL_LAT_FAULTED:
return "off: a call into the driver faulted";
case FL_LAT_STALLED:
return "off: a call into the driver has not returned";
default:
return "not asked";
}
}
// THE WATCHDOG'S HALF, once a tick while a session asks. `now` is this tick's QPC.
void TickLatency(bool newRequest, int64_t now) noexcept {
if (newRequest) {
// A session's counts are its own; where the read stands is the process's and stays.
g_latOut.reads = 0u;
g_latOut.worstUs = 0u;
g_latOut.sleepSeenOn = 0u;
g_latOut.sleepSeenOff = 0u;
g_latOut.multiplier = 0u;
g_latOut.multipliersSeen = 0u;
g_latOut.tally = fl::adv::LatencyTally{};
}
if (g_latStalled) {
return; // the gate belongs to a thread that is not coming back; nothing of g_latRead is read again
}
const uint32_t gate = g_latGate.load(std::memory_order_acquire);
if (gate == kLatGateReading) {
if (g_latReadingSinceQpc == 0) {
g_latReadingSinceQpc = now;
} else if (static_cast<uint64_t>(now - g_latReadingSinceQpc) >= 2u * g_logQpcFreq) {
g_latStalled = true;
g_latOut.state = FL_LAT_STALLED;
g_latLoggedState = FL_LAT_STALLED;
LogNote(kLogLatency, LatencyStateName(FL_LAT_STALLED), FL_LAT_STALLED, 0u);
FlushLog(); // the game is about to be closed by hand: what is known is written now
}
return;
}
g_latReadingSinceQpc = 0;
// A read that ended after the last tick of the request before this one was never taken -- nobody ticks while
// nobody asks. It is that session's: its frames are not this one's first point, and its multiplier is not one
// this session saw. (Armed is not expected here -- the request's end disarms -- and is left to its reader.)
if (newRequest && gate != kLatGateArmed) {
g_latRead.fresh = 0u;
}
// Idle, armed or off: nobody is reading. What the last read left is taken here.
if (gate != kLatGateArmed && g_latRead.fresh != 0u) {
g_latRead.fresh = 0u;
g_latOut.reads += 1u;
g_latOut.worstUs = g_latRead.micros > g_latOut.worstUs ? g_latRead.micros : g_latOut.worstUs;
g_latOut.state = g_latRead.state;
if (g_latRead.ok != 0u) {
g_latOut.tally = g_latRead.tally;
fl::adv::NoteBits(g_adv.validMask, FL_ADV_VALID_LATENCY);
}
if (g_latRead.sleepValid != 0u) {
g_latOut.sleepSeenOn |= g_latRead.sleep.on & FL_LAT_SLEEP_BITS;
g_latOut.sleepSeenOff |= ~g_latRead.sleep.on & FL_LAT_SLEEP_BITS;
g_latOut.multiplier = g_latRead.sleep.multiplier;
g_latOut.multipliersSeen |= fl::adv::LatencyMultiplierBit(g_latRead.sleep.multiplier);
}
if (g_latOut.state != g_latLoggedState) {
g_latLoggedState = g_latOut.state;
LogNote(kLogLatency, LatencyStateName(g_latOut.state), g_latOut.state, g_latRead.micros);
}
}
if (gate != kLatGateIdle || g_latFinal) {
return; // armed and waiting for a present, or off for good
}
if (!g_latResolved) {
uint32_t state = FL_LAT_NO_DEVICE;
if (g_d3d12Device.load(std::memory_order_acquire) != nullptr) {
DWORD fault = 0;
switch (fl::reflex::Resolve(g_latApi, fault)) {
case fl::reflex::Resolved::Ok:
g_latResolved = true;
state = FL_LAT_READING;
break;
case fl::reflex::Resolved::NoModule:
state = FL_LAT_NO_MODULE; // asked again next tick: a game may load it late
break;
case fl::reflex::Resolved::Refused:
g_latFinal = true;
state = FL_LAT_REFUSED;
break;
case fl::reflex::Resolved::Faulted:
g_latFinal = true;
state = FL_LAT_FAULTED;
NoteFault(fault, "nvapi_QueryInterface (the driver's)");
break;
case fl::reflex::Resolved::NoQueryInterface:
case fl::reflex::Resolved::NoGetter:
g_latFinal = true;
state = FL_LAT_NO_GETTER;
break;
}
}
g_latOut.state = state;
if (state != g_latLoggedState) {
g_latLoggedState = state;
LogNote(kLogLatency, LatencyStateName(state), state, reinterpret_cast<uint64_t>(g_latApi.nvapi));
// Where nvapi64.dll was loaded from, and the image its getters are in (the driver's own
// nvapi64_impl.dll on the driver the probe ran against): the end of each path, which is what fits a line.
const size_t room = sizeof(FlLogEvent::text) - 1u;
for (const wchar_t* path : {g_latApi.modulePath, g_latApi.ownerPath}) {
if (path[0] != L'\0') {
// Bounded by the buffer both paths live in (fl_reflex.h): never a walk off its end.
const size_t length = wcsnlen(path, fl::reflex::kPathCapacity);
LogNoteW(kLogLatency, path + (length > room ? length - room : 0u), state,
reinterpret_cast<uint64_t>(path == g_latApi.modulePath ? g_latApi.nvapi : g_latApi.owner));
}
}
}
if (!g_latResolved) {
return;
}
}
if (g_latArmedQpc == 0 || static_cast<uint64_t>(now - g_latArmedQpc) >= g_logQpcFreq) {
g_latArmedQpc = now;
g_latGate.store(kLatGateArmed, std::memory_order_release);
}
}
// The request went off: a read that was wanted and not yet made is not made in a session that never asked.
void DisarmLatency() noexcept {
uint32_t armed = kLatGateArmed;
g_latGate.compare_exchange_strong(armed, kLatGateIdle, std::memory_order_acq_rel, std::memory_order_relaxed);
}
// Which API this swapchain belongs to, asked of the swapchain itself.
//
// One hook sees every swapchain in the process, and a D3D11 title and a D3D12
@@ -685,7 +1027,8 @@ void PublishD3D12Device(ID3D12Device* device) noexcept {
// FL_API_UNKNOWN when neither answers. 0 is the honest value for "we could not
// tell", and it is what the enum reserves it for -- guessing D3D11 is how the
// field became wrong in the first place.
uint8_t ResolveApi(IDXGISwapChain* sc) noexcept {
uint8_t ResolveApi(IDXGISwapChain* sc, bool& heldDevice) noexcept {
heldDevice = false;
IUnknown* dev = nullptr;
if (FAILED(sc->GetDevice(__uuidof(IUnknown), reinterpret_cast<void**>(&dev))) || dev == nullptr) {
return FL_API_UNKNOWN;
@@ -711,6 +1054,7 @@ uint8_t ResolveApi(IDXGISwapChain* sc) noexcept {
// installer needs a live device to read a command list's vtable off, and it
// runs on the watchdog thread, which has no swapchain of its own.
PublishD3D12Device(d12);
heldDevice = g_d3d12Device.load(std::memory_order_acquire) == static_cast<void*>(d12);
d12->Release();
} else if (SUCCEEDED(dev->QueryInterface(__uuidof(ID3D12CommandQueue), reinterpret_cast<void**>(&queue))) &&
queue != nullptr) {
@@ -742,7 +1086,7 @@ SwapChainSlot* FindOrAdd(IDXGISwapChain* sc) noexcept {
if (SUCCEEDED(sc->GetDesc(&desc))) {
RememberDesc(s, desc);
}
s.api = ResolveApi(sc);
s.api = ResolveApi(sc, s.heldDevice);
// apiMask records what we have ACTUALLY seen present, not what the
// process happens to have loaded: a game can link d3d12.dll and
// present through D3D11.
@@ -917,9 +1261,15 @@ constexpr DWORD kWatchdogIntervalMs = 1000;
std::atomic<uint32_t> g_stopLogged{0};
void WakeWatchdog() noexcept;
// The `b` of a PATCH_BATCH line: the patches the batch put in or took out in the low half, the ones it had to do one
// at a time in the high half (0 for a batch that went under its one apply).
uint32_t PatchBatchWord(uint32_t done, uint32_t singly) noexcept {
return (done & 0xFFFFu) | ((singly & 0xFFFFu) << 16);
}
void StopObserving(uint32_t reason) noexcept {
// Compare-exchange, not a plain check-then-set: the watchdog and a game
// thread inside a hook body can both arrive here, and MH_DisableHook must run
// thread inside a hook body can both arrive here, and the restore must run
// exactly once. The loser returns without touching status, so the FIRST
// reason wins -- a self-disable already in flight is not overwritten by a
// safety stop that arrives a millisecond later, or the record of WHY we
@@ -939,14 +1289,29 @@ void StopObserving(uint32_t reason) noexcept {
// is restored only while the bytes at its target are still the jump MinHook
// wrote for us; otherwise it is left in place and our detour stays in the
// other overlay's chain doing nothing -- g_observing is 0, every body forwards.
g_patches.ForEachLive([](void* target, void* detour, const char* name) noexcept {
if (fl::patch::StillOurs(target, detour)) {
const bool ok = MH_DisableHook(target) == MH_OK;
LogNote(kLogUnhookRestored, name, ok ? 1u : 0u, reinterpret_cast<uint64_t>(target));
} else {
LogNote(kLogUnhookDeclined, name, 0u, reinterpret_cast<uint64_t>(target));
}
});
//
// ONE STOP OF THE GAME'S THREADS FOR ALL OF THEM (0.1.0-beta.46, owner decision D134). Each patch was restored by
// its own MH_DisableHook -- a snapshot of the system's threads and a suspend of every one of this process's, per
// patch: about 160 ms each, two to three seconds for a Streamline title, possibly on the thread that presents.
// RestoreAll marks the patches that are still ours and applies the marks together (fl_patch_registry.h says what
// may and may not be marked, and why). The lines below are written after the gate is released.
const int64_t began = QpcNow();
uint32_t restored = 0;
const fl::patch::BatchOutcome outcome = fl::patch::RestoreAll(
g_patches, MinHookEngine{},
[](const void* target, const void* detour) noexcept { return fl::patch::StillOurs(target, detour); },
[&restored](const char* name, void* target, bool wasOurs, bool ok) noexcept {
if (wasOurs) {
LogNote(kLogUnhookRestored, name, ok ? 1u : 0u, reinterpret_cast<uint64_t>(target));
restored += ok ? 1u : 0u;
} else {
LogNote(kLogUnhookDeclined, name, 0u, reinterpret_cast<uint64_t>(target));
}
});
// a = the microseconds the walk and its one apply took; b = how many patches it restored in its low half and, in
// its high half, how many had to be restored one at a time because the apply said it had failed (D137).
LogNote(kLogPatchBatch, outcome.applied ? "restore" : "restore singly", MicrosSince(began),
PatchBatchWord(restored, outcome.singly));
if (g_state != nullptr) {
std::atomic_ref<uint32_t> status{g_state->status};
status.store(reason, std::memory_order_release);
@@ -986,6 +1351,67 @@ bool PatchTarget(void* target, void* detour, void** original, const char* name)
return false;
}
// SEVERAL PATCHES FOR ONE STOP OF THE GAME'S THREADS (0.1.0-beta.46, owner decision D134). The lazy installers put a
// row's patch into the watchdog's batch instead of making it at once, and the batch goes in when the walk is done:
// thirteen Streamline rows were thirteen stops of every thread of the game, 0.7 s to 2.8 s of its start in the
// owner's logs of 2026-11-13. fl_patch_registry.h holds the sequence and what it must never do.
//
// WATCHDOG THREAD ONLY, and empty between two installers: each commits what it queued before it returns.
fl::patch::Batch<kMaxPatches> g_batch;
// What PatchTarget does, deferred: the slot is claimed and the hook created now; the patch, its HOOK_INSTALLED line,
// its family bit and its latch come at CommitPatchBatch -- in that order, and only if the patch went in. `family` is
// 0 for a row whose family is published elsewhere, once every row of it is in; `latch` is the row's "patched" word.
bool QueuePatch(void* target, void* detour, void** original, const char* name, uint32_t family,
std::atomic<uint32_t>* latch) noexcept {
const fl::patch::InstallResult result =
g_batch.Add(g_patches, g_observing, MinHookEngine{}, target, detour, original, name, latch, family);
if (result == fl::patch::InstallResult::Pending) {
return true;
}
if (result != fl::patch::InstallResult::NoTarget) {
NotePatchFailedOnce(target, result, name);
}
return false;
}
void CommitPatchBatch() noexcept {
const uint32_t count = g_batch.Count();
if (count == 0u) {
return;
}
const int64_t began = QpcNow();
const fl::patch::BatchOutcome outcome =
g_batch.Commit(g_patches, g_observing, MinHookEngine{}, [](const void* target, const void* detour) noexcept {
return fl::patch::StillOurs(target, detour);
});
const uint32_t micros = MicrosSince(began);
uint32_t installed = 0;
for (uint32_t i = 0; i < count; ++i) {
const auto& item = g_batch.At(i);
if (item.result != fl::patch::InstallResult::Installed) {
NotePatchFailedOnce(item.target, item.result, item.name);
continue;
}
LogNote(kLogHookInstalled, item.name, 0, reinterpret_cast<uint64_t>(item.target));
// The family, then the latch: PublishHookFamily's order, for a row that has both.
if (item.word != 0u && g_state != nullptr) {
std::atomic_ref<uint32_t> hooks{g_state->hooksInstalledMask};
hooks.fetch_or(item.word, std::memory_order_relaxed);
}
if (item.context != nullptr) {
static_cast<std::atomic<uint32_t>*>(item.context)->store(1u, std::memory_order_release);
}
++installed;
}
// a = the microseconds the one apply took; b = how many patches went in in its low half and, in its high half,
// how many were enabled one at a time because the apply said it had failed (D137). "install" is one stop of the
// game's threads; "install singly" is that stop and then up to one more for each of those.
LogNote(kLogPatchBatch, outcome.applied ? "install" : "install singly", micros,
PatchBatchWord(installed, outcome.singly));
g_batch.Clear();
}
// Returns false when we must not record this present.
//
// The supervision deadline is NOT here any more -- it is the watchdog's, which
@@ -2611,12 +3037,8 @@ bool InstallRow(const wchar_t* moduleName, const char* symbol, uint32_t family,
return false;
}
if (!PatchTarget(target, detour, original, name)) {
return false;
}
PublishHookFamily(family, live);
return true;
// Queued, not patched: the family is published and the latch set when the batch commits (CommitPatchBatch).
return QueuePatch(target, detour, original, name, family, &live);
}
// Bind a row's family bit to the detour that implements it.
@@ -2720,11 +3142,8 @@ bool InstallByFamily(const wchar_t* moduleName, const char* symbol, uint32_t fam
if (target == nullptr) {
return false; // not loaded, or a module of the name that does not speak ffx-api
}
if (!PatchTarget(target, FfxConfigureDetour(slot), reinterpret_cast<void**>(&g_origFfxConfigure[slot]), name)) {
return false;
}
g_ffxConfigurePatched[slot].store(1, std::memory_order_release);
return true;
return QueuePatch(target, FfxConfigureDetour(slot), reinterpret_cast<void**>(&g_origFfxConfigure[slot]), name,
0u, &g_ffxConfigurePatched[slot]);
}
if (family == fl::inventory::kFamilyEvaluateFeature) {
return InstallRow(moduleName, symbol, family, reinterpret_cast<void*>(&Hook_SlEvaluateFeature),
@@ -2753,11 +3172,7 @@ bool InstallByFamily(const wchar_t* moduleName, const char* symbol, uint32_t fam
frameRow ? reinterpret_cast<void*>(&Hook_SlSetTagForFrame) : reinterpret_cast<void*>(&Hook_SlSetTag);
void** original =
frameRow ? reinterpret_cast<void**>(&g_origSlSetTagForFrame) : reinterpret_cast<void**>(&g_origSlSetTag);
if (!PatchTarget(target, detour, original, name)) {
return false;
}
patched.store(1, std::memory_order_release);
return true;
return QueuePatch(target, detour, original, name, 0u, &patched);
}
if (family == static_cast<uint32_t>(fl::FL_HOOK_FG_EVALUATIONS)) {
return InstallRow(moduleName, symbol, family, reinterpret_cast<void*>(&Hook_SlGetNewFrameToken),
@@ -2793,12 +3208,8 @@ bool InstallByFamily(const wchar_t* moduleName, const char* symbol, uint32_t fam
if (target == nullptr) {
return false; // not loaded, or a module of the name that does not speak the 3.0 host ABI
}
if (!PatchTarget(target, reinterpret_cast<void*>(&Hook_FfxFsr3ContextDispatchUpscale),
reinterpret_cast<void**>(&g_origFfxFsr3DispatchUpscale), name)) {
return false;
}
g_fsr3HostPatched.store(1, std::memory_order_release);
return true;
return QueuePatch(target, reinterpret_cast<void*>(&Hook_FfxFsr3ContextDispatchUpscale),
reinterpret_cast<void**>(&g_origFfxFsr3DispatchUpscale), name, 0u, &g_fsr3HostPatched);
}
const auto slot = static_cast<uint32_t>(leaf);
if (g_ffxPatched[slot].load(std::memory_order_acquire) != 0) {
@@ -2808,11 +3219,8 @@ bool InstallByFamily(const wchar_t* moduleName, const char* symbol, uint32_t fam
if (target == nullptr) {
return false; // not loaded, or a module of the name that does not speak ffx-api
}
if (!PatchTarget(target, FfxDispatchDetour(slot), reinterpret_cast<void**>(&g_origFfxDispatch[slot]), name)) {
return false;
}
g_ffxPatched[slot].store(1, std::memory_order_release);
return true;
return QueuePatch(target, FfxDispatchDetour(slot), reinterpret_cast<void**>(&g_origFfxDispatch[slot]), name, 0u,
&g_ffxPatched[slot]);
}
if (family == fl::inventory::kFamilyFfxQuery) {
// FOUR ROWS, ONE ARM, the dispatch arm's shape: the row's MODULE picks the trampoline and the latch slot.
@@ -2829,11 +3237,8 @@ bool InstallByFamily(const wchar_t* moduleName, const char* symbol, uint32_t fam
if (target == nullptr) {
return false; // not loaded, or a module of the name that does not speak ffx-api
}
if (!PatchTarget(target, FfxQueryDetour(slot), reinterpret_cast<void**>(&g_origFfxQuery[slot]), name)) {
return false;
}
g_ffxQueryPatched[slot].store(1, std::memory_order_release);
return true;
return QueuePatch(target, FfxQueryDetour(slot), reinterpret_cast<void**>(&g_origFfxQuery[slot]), name, 0u,
&g_ffxQueryPatched[slot]);
}
return false;
}
@@ -2957,6 +3362,9 @@ bool InstallUpscalerHooks() noexcept {
}
FL_HOOK_INVENTORY(FL_INSTALL_ROW)
#undef FL_INSTALL_ROW
// Every row this tick found something to patch for goes in now, together -- and before the families that are
// published "when whole", which read the latches the commit sets.
CommitPatchBatch();
PublishParamsFamilyIfWhole();
PublishFfxFamilyIfWhole();
PublishFfxQueryFamilyIfWhole();
@@ -3088,20 +3496,21 @@ bool InstallRtHooks() noexcept {
const bool buildAgrees = directVtbl[fl::d3d12::kBuildRaytracingAccelerationStructureIndex] ==
computeVtbl[fl::d3d12::kBuildRaytracingAccelerationStructureIndex];
// The two go in together (0.1.0-beta.46): one stop of the game's threads, not two.
if (dispatchAgrees && g_rtDispatchLive.load(std::memory_order_acquire) == 0 &&
PatchTarget(directVtbl[fl::d3d12::kDispatchRaysIndex], reinterpret_cast<void*>(&Hook_DispatchRays),
reinterpret_cast<void**>(&g_origDispatchRays),
"d3d12!ID3D12GraphicsCommandList4::DispatchRays")) {
PublishHookFamily(static_cast<uint32_t>(fl::FL_HOOK_RT_DISPATCH), g_rtDispatchLive);
QueuePatch(directVtbl[fl::d3d12::kDispatchRaysIndex], reinterpret_cast<void*>(&Hook_DispatchRays),
reinterpret_cast<void**>(&g_origDispatchRays), "d3d12!ID3D12GraphicsCommandList4::DispatchRays",
static_cast<uint32_t>(fl::FL_HOOK_RT_DISPATCH), &g_rtDispatchLive)) {
installed = true;
}
if (buildAgrees && g_rtAsBuildLive.load(std::memory_order_acquire) == 0 &&
PatchTarget(directVtbl[fl::d3d12::kBuildRaytracingAccelerationStructureIndex],
reinterpret_cast<void*>(&Hook_BuildRtAs), reinterpret_cast<void**>(&g_origBuildRtAs),
"d3d12!ID3D12GraphicsCommandList4::BuildRaytracingAccelerationStructure")) {
PublishHookFamily(static_cast<uint32_t>(fl::FL_HOOK_RT_AS_BUILD), g_rtAsBuildLive);
QueuePatch(directVtbl[fl::d3d12::kBuildRaytracingAccelerationStructureIndex],
reinterpret_cast<void*>(&Hook_BuildRtAs), reinterpret_cast<void**>(&g_origBuildRtAs),
"d3d12!ID3D12GraphicsCommandList4::BuildRaytracingAccelerationStructure",
static_cast<uint32_t>(fl::FL_HOOK_RT_AS_BUILD), &g_rtAsBuildLive)) {
installed = true;
}
CommitPatchBatch();
}
// Closed before release: a command list left recording holds its allocator.
@@ -3161,7 +3570,8 @@ DWORD WatchdogLoop() noexcept {
// a count never spans two sessions of a game that kept running.
std::atomic_ref<uint32_t> advancedReq{g_control->advancedRequested};
const uint32_t advancedNow = advancedReq.load(std::memory_order_acquire);
if (advancedNow != 0u && advancedNow != g_advancedSeen) {
const bool advancedIsNew = advancedNow != 0u && advancedNow != g_advancedSeen;
if (advancedIsNew) {
fl::adv::Reset(g_adv);
g_advancedSeen = advancedNow;
}
@@ -3170,7 +3580,12 @@ DWORD WatchdogLoop() noexcept {
// Initialised through QuadPart, the member read below, so that it is the active one (cpp:S6232).
LARGE_INTEGER advancedQpc{.QuadPart = 0};
QueryPerformanceCounter(&advancedQpc);
fl::adv::Publish(g_adv, g_advanced, advancedNow, static_cast<uint64_t>(advancedQpc.QuadPart));
// The driver's latency report (train C): what the last read left is taken, and the next one armed,
// BEFORE the publication -- so the publication carries the read, and carries it once.
TickLatency(advancedIsNew, advancedQpc.QuadPart);
fl::adv::Publish(g_adv, g_advanced, advancedNow, static_cast<uint64_t>(advancedQpc.QuadPart), &g_latOut);
} else {
DisarmLatency();
}
// The in-process stop, for a title that is NOT presenting (menu, hung,
@@ -3267,7 +3682,9 @@ DWORD WatchdogLoop() noexcept {
// Twelve patches (the Streamline fixture until then) took 1.9 s and fitted; with three more rows the stop took 2.4 s,
// the flush gave up first, and the log ended "the stop was still writing" with the last three UNHOOK_RESTORED lines
// missing -- the patches were restored, the log did not say so. The wait ends the moment the stop is logged, so the
// longer bound costs nothing where the stop is quick.
// longer bound costs nothing where the stop is quick. Since 0.1.0-beta.46 the stop restores its patches under one
// stop of the threads and is quick; the bound stays for the case it was sized for -- an apply that fails and falls
// back to one restore a patch.
constexpr ULONGLONG kStopLogWaitMs = 250ull * kMaxPatches;
DWORD WINAPI WatchdogThread(LPVOID) noexcept {
@@ -3820,6 +4237,13 @@ void RecordPresent(IDXGISwapChain* sc, UINT syncInterval, UINT flags) noexcept {
// a writer that FORGETS is now honest by construction.
g_writer.Publish(rec);
// THE DRIVER'S LATENCY REPORT (train C), after the record: one relaxed load a present, and a call only when the
// watchdog armed one -- about once a second, while a session asks for Advanced metrics, at a chain whose device
// is the one held. See ReadLatencyOnce.
if (g_latGate.load(std::memory_order_relaxed) == kLatGateArmed && slot != nullptr && slot->heldDevice) {
ReadLatencyOnce();
}
}
// ---------------------------------------------------------------------------
+96 -14
View File
@@ -69,6 +69,16 @@
// moved from 0x100 to 0x6C0 to make room for it. What a hooked game told its upscaler is neither a frame fact nor a
// display fact, and no region had room. The region is sized ONCE for the three releases of train B (beta.40, .41,
// .42): a member a later release fills is declared here and stays zero until then, so those releases bump nothing.
//
// STILL 5 (2026-11-13, Advanced metrics train C, owner decisions D136 and D138): the ten reserved words that ended
// region 5's first line became the Reflex latency words (latState .. latTotalSumUs). No offset and no size moved, a
// reader of an older build finds zeros where it was told to expect zeros, and the build-id handshake refuses a
// mismatched pair before either reads the other -- the precedent is slShutdowns. A trial must also be removable
// without a layout 7.
//
// STILL 5 (2026-11-14, 0.1.0-beta.48, owner decisions D142 and D144): four of the seven reserved words that ended
// region 5's second line became four more latency words (latGpuActiveSumUs .. latMultipliersSeen) -- the first line
// was full. The same reasons, and three reserved words remain there.
#define FL_SHM_LAYOUT_VERSION 5u
#define FL_SHM_HANDSHAKE_OFFSET 0x00u
@@ -968,8 +978,48 @@ enum FlAdvancedValid : uint32_t {
FL_ADV_VALID_SL_CONSTANTS = 1u << 4, // (0.1.0-beta.43) slSetConstants seen
FL_ADV_VALID_SL_FEATURES = 1u << 5, // (0.1.0-beta.44) at least one feature slot filled
FL_ADV_VALID_SL_SHUTDOWN = 1u << 6, // (0.1.0-beta.45) slShutdown seen; slShutdowns counts
// (train C, declared 2026-11-13 and written by nothing until the Overlay reads the driver's latency report) a
// read of the driver's latency report returned OK for this request. NOT "the game's calls were read": this group
// comes from a call the Overlay makes itself, and latState says where that stands even while the bit is clear.
FL_ADV_VALID_LATENCY = 1u << 7,
};
// REFLEX LATENCY (train C; owner decisions D132, D136, D138-D141; spike-notes §31; 17_HOOK_ENGINE §Memory / latency).
// Not a hook and not an argument of one: while a session asks for Advanced metrics, the Overlay CALLS the NVIDIA
// driver's two read-only getters about once a second on the presenting thread, with the Direct3D 12 device behind
// the swap chain it hooks, and only through an nvapi64.dll the game had already loaded. These words are what it
// publishes -- by the watchdog, in the same seqlock as the rest of the region.
//
// FlAdvancedState.latState, bits 0..7. REFUSED, NO_GETTER, SLOW, FAULTED and STALLED are final for the process:
// nothing is retried, and a later session of the same process reads the same word.
enum FlLatencyState : uint32_t {
FL_LAT_NONE = 0, // not asked, or nothing looked at yet
FL_LAT_NO_DEVICE = 1, // asked; no Direct3D 12 device has been seen behind a hooked swap chain
FL_LAT_NO_MODULE = 2, // the game has not loaded nvapi64.dll (asked again each second: a game may load it late)
FL_LAT_REFUSED =
3, // the nvapi64.dll in the process sits in the executable's own folder: not the driver's (D140)
FL_LAT_NO_GETTER = 4, // the module does not answer for both getters, or answered with an address outside itself
FL_LAT_READING = 5, // resolved; a read is made about once a second
FL_LAT_ERROR = 6, // the last read returned an NVAPI status that is not OK; reading goes on
FL_LAT_SLOW = 7, // one call took 2 ms or more: off until the game exits (D141)
FL_LAT_FAULTED = 8, // a getter faulted: off until the game exits, and counted once in faultCount
FL_LAT_STALLED = 9, // a call had not returned after a second: nothing can stop it; reported and left
};
// latState, above the state: the driver's sleep status as SEEN -- a switch can be in both groups in one session.
// Bit n of each group, in the order of NV_GET_SLEEP_STATUS_PARAMS: low-latency mode, fullscreen VRR, the control
// panel's vsync, the game's own sleep, fullscreen independent flip. They are the DRIVER'S words: on the driver the
// spike ran against, low-latency mode read 0 for a device whose game had just switched it on.
#define FL_LAT_STATE_MASK 0x000000FFu
#define FL_LAT_SLEEP_SEEN_ON_SHIFT 8u // bits 8..12
#define FL_LAT_SLEEP_SEEN_OFF_SHIFT 16u // bits 16..20
#define FL_LAT_SLEEP_BITS 0x1Fu
#define FL_LAT_FG_MULTIPLIER_SHIFT 24u // bits 24..31: the last fgMultiplier the status gave, stopping at 255
// A span the driver did not report for a frame that was summed (an end point of zero): the whole sum reads this.
// Without a sleep mode the driver leaves driverStartTime zero in every frame; with one it fills it in.
#define FL_LAT_SUM_NONE 0xFFFFFFFFu
// A float nobody saw. An all-ones pattern is a NaN no detour stores: every value is checked finite first -- with the
// one exception below.
#define FL_ADV_FLOAT_NONE 0xFFFFFFFFu
@@ -1005,12 +1055,28 @@ enum FlAdvancedValid : uint32_t {
struct alignas(64) FlAdvancedState {
// ---- line 0: the header ------------------------------------------------------------------------------------
uint32_t seq; // @0 seqlock: odd while the watchdog is inside, +2 per publication
uint32_t validMask; // @4 FlAdvancedValid
uint32_t samples; // @8 publications (wraps)
uint32_t request; // @12 the FlControlBlock::advancedRequested this publication answers
uint64_t sampleQpc; // @16 QueryPerformanceCounter at the last publication
uint32_t reservedHeader[10]; // @24..63 must be zero
uint32_t seq; // @0 seqlock: odd while the watchdog is inside, +2 per publication
uint32_t validMask; // @4 FlAdvancedValid
uint32_t samples; // @8 publications (wraps)
uint32_t request; // @12 the FlControlBlock::advancedRequested this publication answers
uint64_t sampleQpc; // @16 QueryPerformanceCounter at the last publication
// Reflex latency (train C) -- the ten words that were reservedHeader. Written by nothing until the Overlay makes
// the read; all zero in a process nobody asked.
uint32_t latState; // @24 FlLatencyState, and the sleep status as seen (the masks above)
uint32_t latReads; // @28 bits 0..15 reads made since the request; bits 16..31 the slowest call
// in microseconds -- each stops at 65535
uint32_t latFrames; // @32 of the newest read not yet published: bits 0..15 frames summed,
// bits 16..31 frames refused (a span that runs backwards or lasts over a
// second, or no total). Zero when no read was made since the publication
// before.
// Sums over the frames summed, microseconds; FL_LAT_SUM_NONE = a summed frame did not report the span.
uint32_t latSimulationSumUs; // @36 simStartTime .. simEndTime
uint32_t latSubmitSumUs; // @40 renderSubmitStartTime .. renderSubmitEndTime
uint32_t latPresentSumUs; // @44 presentStartTime .. presentEndTime
uint32_t latDriverSumUs; // @48 driverStartTime .. driverEndTime
uint32_t latOsQueueSumUs; // @52 osRenderQueueStartTime .. osRenderQueueEndTime
uint32_t latGpuSumUs; // @56 gpuRenderStartTime .. gpuRenderEndTime
uint32_t latTotalSumUs; // @60 simStartTime .. gpuRenderEndTime
// ---- line 1: sl::DLSSOptions as last seen in slEvaluateFeature's inputs -----------------------------------
uint32_t dlssStructVersion; // @64 the structVersion the game's struct declared; 0 = none seen
@@ -1021,12 +1087,22 @@ struct alignas(64) FlAdvancedState {
uint32_t dlssExposureScaleBits; // @84
// sl::DLSSPreset PLUS ONE, in the header's order: DLAA, quality, balanced, performance, ultra performance,
// ultra quality (the last is struct version 2's - 0 where the game's struct is older).
uint8_t dlssPresets[6]; // @88..93
uint8_t dlssColorBuffersHdr; // @94 sl::Boolean PLUS ONE; 0 = not read
uint8_t dlssAutoExposure; // @95 (struct version 2)
uint8_t dlssAlphaUpscaling; // @96 (struct version 3)
uint8_t dlssPad[3]; // @97..99 must be zero
uint32_t reservedDlss[7]; // @100..127 must be zero
uint8_t dlssPresets[6]; // @88..93
uint8_t dlssColorBuffersHdr; // @94 sl::Boolean PLUS ONE; 0 = not read
uint8_t dlssAutoExposure; // @95 (struct version 2)
uint8_t dlssAlphaUpscaling; // @96 (struct version 3)
uint8_t dlssPad[3]; // @97..99 must be zero
// Reflex latency again (0.1.0-beta.48, D142 and D144): the first line was full, and this one had seven words
// spare. Nothing here is DLSS's. The two sums and their counts are of the newest read not yet published, as
// latFrames is; the two times are the driver's own figures, not spans between two of its marks, and each has
// a count of its own because a frame can give one and not the other. A frame that gives zero, or more than a
// second, is not in the sum and not in the count.
uint32_t latGpuActiveSumUs; // @100 gpuActiveRenderTimeUs over the frames that gave one, microseconds
uint32_t latGpuFrameSumUs; // @104 gpuFrameTimeUs over the frames that gave one
uint32_t latGpuCounts; // @108 bits 0..15 frames in the first sum, bits 16..31 in the second
uint32_t latMultipliersSeen; // @112 bit n: the sleep status gave fgMultiplier n since the request;
// bit 31 stands for 31 and more
uint32_t reservedDlss[3]; // @116..127 must be zero
// ---- line 2: the ffx upscale dispatch, beyond its two sizes ---------------------------------------------------
uint32_t ffxDispatches; // @128 upscale dispatches whose extras were read (wraps)
@@ -1335,13 +1411,19 @@ static_assert(offsetof(FlAdvancedState, seq) == 0);
static_assert(offsetof(FlAdvancedState, validMask) == 4);
static_assert(offsetof(FlAdvancedState, samples) == 8);
static_assert(offsetof(FlAdvancedState, sampleQpc) == 16);
static_assert(offsetof(FlAdvancedState, reservedHeader) == 24);
static_assert(offsetof(FlAdvancedState, latState) == 24);
static_assert(offsetof(FlAdvancedState, latFrames) == 32);
static_assert(offsetof(FlAdvancedState, latSimulationSumUs) == 36);
static_assert(offsetof(FlAdvancedState, latTotalSumUs) == 60);
static_assert(offsetof(FlAdvancedState, dlssStructVersion) == 64);
static_assert(offsetof(FlAdvancedState, dlssPreExposureBits) == 80);
static_assert(offsetof(FlAdvancedState, dlssPresets) == 88);
static_assert(offsetof(FlAdvancedState, dlssColorBuffersHdr) == 94);
static_assert(offsetof(FlAdvancedState, dlssAlphaUpscaling) == 96);
static_assert(offsetof(FlAdvancedState, reservedDlss) == 100);
static_assert(offsetof(FlAdvancedState, latGpuActiveSumUs) == 100);
static_assert(offsetof(FlAdvancedState, latGpuCounts) == 108);
static_assert(offsetof(FlAdvancedState, latMultipliersSeen) == 112);
static_assert(offsetof(FlAdvancedState, reservedDlss) == 116);
static_assert(offsetof(FlAdvancedState, ffxDispatches) == 128);
static_assert(offsetof(FlAdvancedState, ffxFrameTimeSumUs) == 188);
static_assert(offsetof(FlAdvancedState, ffxMemoryTotalBytes) == 192);
+59 -7
View File
@@ -8,6 +8,9 @@
add_executable(fl_shm_layout_test layout_test.cpp)
target_link_libraries(fl_shm_layout_test PRIVATE FrameLedger.Shm fl_native_flags)
add_test(NAME fl_shm_layout COMMAND fl_shm_layout_test)
# Not a Catch2 executable: its last line is its own (the note above enable_testing() in the top-level file -- a run
# cut short is not a pass).
fl_test_completes(fl_shm_layout "layout ok")
# The NVAPI bridge's C ABI (P2 PR-E2). Links the SHIPPED DLL rather than compiling its source in,
# because what the managed side loads is that DLL's export table; the DLL is copied beside the test
@@ -23,9 +26,14 @@ add_test(NAME fl_nvapi_bridge COMMAND fl_nvapi_bridge_test)
# The branch line is required AND a failed assertion fails the test (2026-09-25). PASS_REGULAR_EXPRESSION alone makes
# ctest ignore the exit code, and for as long as it stood alone the AVAILABLE branch's reference-counting check failed
# on every machine with an NVIDIA GPU while ctest reported Passed; CI, which has no driver, never takes that branch.
set_tests_properties(fl_nvapi_bridge PROPERTIES
PASS_REGULAR_EXPRESSION "BRANCH: (AVAILABLE|DEGRADED)"
FAIL_REGULAR_EXPRESSION "FAILED:;[0-9]+ failed")
#
# AND THE RUN MUST REACH ITS END (2026-11-13; the note above enable_testing() in the top-level file): the branch line is
# printed in the middle of the run, so by itself it passed a run that stopped right after it. The expression now
# needs the branch line AND, after it, Catch2's last line.
fl_test_completes(fl_nvapi_bridge
"BRANCH: (AVAILABLE|DEGRADED)(.|\n)*All tests passed \\("
"BRANCH: (AVAILABLE|DEGRADED)(.|\n)*test cases: +[0-9]+ \\| +[0-9]+ passed \\| +[0-9]+ skipped")
set_tests_properties(fl_nvapi_bridge PROPERTIES FAIL_REGULAR_EXPRESSION "FAILED:;[0-9]+ failed")
# The process-memory reader's C ABI (beta.12, D43). Same shape as the bridge above: the SHIPPED DLL, copied beside
# the test, a branch line that says which machine this is (a CI runner has no hardware adapter, so the video half
@@ -38,9 +46,10 @@ add_custom_command(TARGET fl_process_stats_test POST_BUILD
COMMAND ${CMAKE_COMMAND} -E copy_if_different
$<TARGET_FILE:FrameLedger.ProcessStats> $<TARGET_FILE_DIR:fl_process_stats_test>)
add_test(NAME fl_process_stats COMMAND fl_process_stats_test)
set_tests_properties(fl_process_stats PROPERTIES
PASS_REGULAR_EXPRESSION "BRANCH: (GPU_INSTANCE|NO_GPU_INSTANCE)"
FAIL_REGULAR_EXPRESSION "FAILED:;[0-9]+ failed")
fl_test_completes(fl_process_stats
"BRANCH: (GPU_INSTANCE|NO_GPU_INSTANCE)(.|\n)*All tests passed \\("
"BRANCH: (GPU_INSTANCE|NO_GPU_INSTANCE)(.|\n)*test cases: +[0-9]+ \\| +[0-9]+ passed \\| +[0-9]+ skipped")
set_tests_properties(fl_process_stats PROPERTIES FAIL_REGULAR_EXPRESSION "FAILED:;[0-9]+ failed")
# The safety-guard matrix. 20_OPEN_QUESTIONS §S13(a) put the guard in C++, which
# made Catch2 a PREREQUISITE of the guard rather than a later nicety: 14_TESTING
@@ -139,14 +148,19 @@ target_compile_definitions(fl_guard_test PRIVATE
FL_STUB_SL_INTERPOSER=L"$<TARGET_FILE:fl_stub_sl_interposer>"
# The ffx-api loader stub, so a test can read one of its exports' first bytes out of a target (0.1.0-beta.43).
FL_STUB_FFX_LOADER=L"$<TARGET_FILE:fl_stub_ffx_loader>"
# The stand-in nvapi64.dll (train C): the target loads it, and the tests turn its knobs and read its call counts
# through the named section fl_stub_nvapi_shared.h describes.
FL_STUB_NVAPI64=L"$<TARGET_FILE:fl_stub_nvapi64>"
FL_OVERLAY_DLL=L"${FL_STAGED_OVERLAY}"
# The un-staged original, so a test can prove the check discriminates on
# DIRECTORY rather than on filename: same bytes, same name, wrong place.
FL_OVERLAY_DLL_ELSEWHERE=L"$<TARGET_FILE:FrameLedger.Overlay>"
)
add_dependencies(fl_guard_test hook-harness FrameLedger.Overlay fl_stage_overlay_payload)
add_dependencies(fl_guard_test hook-harness FrameLedger.Overlay fl_stage_overlay_payload fl_stub_nvapi64)
target_include_directories(fl_guard_test PRIVATE "${CMAKE_SOURCE_DIR}/tools/vendor-stubs")
add_test(NAME fl_guard COMMAND fl_guard_test)
fl_catch2_test_completes(fl_guard)
# The Vulkan layer's capture side (P1 item 3), driven by a FAKE loader chain --
# no registry, no loader, no GPU -- so it is merge-gated. Three ctests, three
@@ -179,6 +193,19 @@ target_link_libraries(fl_unhook_inline_test PRIVATE fl_native_flags minhook Catc
target_compile_options(fl_unhook_inline_test PRIVATE /EHsc)
target_compile_definitions(fl_unhook_inline_test PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX)
add_test(NAME fl_unhook_inline COMMAND fl_unhook_inline_test)
fl_catch2_test_completes(fl_unhook_inline)
# fl_adv_fields.h's reader of the driver's latency report (Advanced metrics train C): the header the Overlay
# compiles, on reports written by hand -- the two newest frames held back, a span the driver did not report, a span
# no frame can have, frame ids that start again, and the ten words of a publication.
add_executable(fl_reflex_summary_test reflex_summary_test.cpp)
target_include_directories(fl_reflex_summary_test PRIVATE "${CMAKE_SOURCE_DIR}/FrameLedger.Overlay/include")
target_link_libraries(fl_reflex_summary_test PRIVATE FrameLedger.Shm fl_native_flags fl_streamline_headers
fl_fidelityfx_headers fl_nvapi_headers Catch2::Catch2WithMain)
target_compile_options(fl_reflex_summary_test PRIVATE /EHsc)
target_compile_definitions(fl_reflex_summary_test PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX)
add_test(NAME fl_reflex_summary COMMAND fl_reflex_summary_test)
fl_catch2_test_completes(fl_reflex_summary)
# fl_ffx_types.h (0.1.0-beta.42, D121): the descriptor types an ffx-api module was handed, kept by the detours for
# the native log. The header the Overlay compiles, driven without the Overlay -- including from eight threads.
@@ -188,6 +215,7 @@ target_link_libraries(fl_ffx_types_test PRIVATE fl_native_flags Catch2::Catch2Wi
target_compile_options(fl_ffx_types_test PRIVATE /EHsc)
target_compile_definitions(fl_ffx_types_test PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX)
add_test(NAME fl_ffx_types COMMAND fl_ffx_types_test)
fl_catch2_test_completes(fl_ffx_types)
add_test(NAME fl_vklayer COMMAND fl_vklayer_test "[vklayer]")
add_test(NAME fl_vklayer_supervision COMMAND fl_vklayer_test "[vklayer-deadline]")
@@ -195,12 +223,14 @@ add_test(NAME fl_vklayer_supervision COMMAND fl_vklayer_test "[vklayer-deadline]
# presentable device -- CI, per the §S29(d) census -- and runs on a dev box.
add_test(NAME fl_vklayer_real COMMAND fl_vklayer_test "[vklayer-real]")
set_tests_properties(fl_vklayer_real PROPERTIES SKIP_RETURN_CODE 4)
fl_catch2_test_completes(fl_vklayer fl_vklayer_supervision fl_vklayer_real)
# Check 4's fail-closed matrix, as its own ctest name so a regression in the
# static pre-scan is legible in the ctest summary rather than buried in
# fl_guard's total. Same binary, selected by tag — duplicating the evidence
# fakes into a second target would be a second set of seams to keep in step.
add_test(NAME fl_prescan COMMAND fl_guard_test "[prescan]")
fl_catch2_test_completes(fl_prescan)
# The rules file we actually SHIP, against the parser that has to read it.
#
@@ -230,6 +260,7 @@ target_compile_definitions(fl_rules_budget_test PRIVATE
)
add_test(NAME fl_rules_budget COMMAND fl_rules_budget_test)
fl_catch2_test_completes(fl_rules_budget)
# The SPSC ring (14_TESTING §Native unit tests). Half of the TODO that used to
# sit here; the fault-policy suite lands with the hook bodies it guards, since a
@@ -244,6 +275,27 @@ add_executable(fl_ring_test ring_test.cpp)
target_link_libraries(fl_ring_test PRIVATE FrameLedger.Shm fl_native_flags Catch2::Catch2WithMain)
target_compile_options(fl_ring_test PRIVATE /EHsc)
add_test(NAME fl_ring COMMAND fl_ring_test)
fl_catch2_test_completes(fl_ring)
# THE RULE ABOVE, MADE TO FAIL ON PURPOSE (2026-11-13). "A run that is cut short is red" is a property of two
# regular expressions, and a gate that has never been seen red is this project's own recurring defect
# (20_OPEN_QUESTIONS, gates that cannot fail). Four runs that print what a Catch2 executable would, through the very
# function the real tests use:
# - nothing at all, exit 0 -- the run of 2026-11-13 -- must be RED;
# - Catch2's last line must be green;
# - its summary row with a skipped case must be green (a test that skips one case and passes the rest);
# - a row that names a failure must be RED even beside a line that says passed.
# WILL_FAIL turns "red" into this test's pass, so the suite is green exactly while the rule holds.
add_test(NAME fl_canary_cut_short_is_red COMMAND "${CMAKE_COMMAND}" -E true)
add_test(NAME fl_canary_complete_is_green
COMMAND "${CMAKE_COMMAND}" -E echo "All tests passed (1 assertion in 1 test case)")
add_test(NAME fl_canary_skipped_case_is_green
COMMAND "${CMAKE_COMMAND}" -E echo "test cases: 3 | 2 passed | 1 skipped")
add_test(NAME fl_canary_failure_is_red
COMMAND "${CMAKE_COMMAND}" -E echo "All tests passed ( test cases: 3 | 2 passed | 1 failed")
fl_catch2_test_completes(fl_canary_cut_short_is_red fl_canary_complete_is_green fl_canary_skipped_case_is_green
fl_canary_failure_is_red)
set_tests_properties(fl_canary_cut_short_is_red fl_canary_failure_is_red PROPERTIES WILL_FAIL TRUE)
# STILL NO FAULT-POLICY SUITE, and the reason is worth more than the TODO it
# replaces. The three-fault self-disable is NFR-3's entire mechanism and the
+541 -2
View File
@@ -32,6 +32,7 @@
#include <memory>
#include <set>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
@@ -1842,6 +1843,7 @@ TEST_CASE(
// to, which is the only part of this suite that has a live Overlay to inspect.
#include <fl_ring.h>
#include <fl_shm.h>
#include <fl_stub_nvapi_shared.h>
#include <fl_tolerance.h>
// The compiled floor, so the early-stop case computes the family index the Overlay
// publishes from the same table rather than asserting a literal.
@@ -7416,6 +7418,7 @@ TEST_CASE("region 5 carries what a Streamline title chains into its evaluation,
}
// ---- 2. ASKED: the patches go in on the tick that sees the request, and the next publications carry the groups.
const ULONGLONG askedAt = GetTickCount64();
SetAdvancedRequest(r, 1u);
REQUIRE(WaitForHookFamily(r.st, slConstants));
REQUIRE(WaitForHookFamily(r.st, static_cast<uint32_t>(fl::FL_HOOK_SL_FEATURE_VERSION)));
@@ -7426,6 +7429,9 @@ TEST_CASE("region 5 carries what a Streamline title chains into its evaluation,
REQUIRE(WaitForHookFamily(r.st, static_cast<uint32_t>(fl::FL_HOOK_SL_ALLOCATE_RESOURCES)));
REQUIRE(WaitForHookFamily(r.st, static_cast<uint32_t>(fl::FL_HOOK_SL_FREE_RESOURCES)));
REQUIRE(WaitForHookFamily(r.st, static_cast<uint32_t>(fl::FL_HOOK_SL_SHUTDOWN)));
// Measured, not asserted: a tick's wait (up to a second) and then the nine patches. Printed so that a pull request
// which changes how patches go in can say what it did to this (0.1.0-beta.46).
WARN("asked -> the nine Advanced-only families published: " << (GetTickCount64() - askedAt) << " ms");
REQUIRE(ReadTargetExportBytes(child.pi.dwProcessId, FL_STUB_SL_INTERPOSER, "slSetConstants", now));
CHECK(std::memcmp(pristine, now, sizeof(now)) != 0); // patched now
for (int i = 0; i < kFeatureExports; ++i) {
@@ -7557,12 +7563,15 @@ TEST_CASE("region 5 carries what a Streamline title chains into its evaluation,
// ---- 4. STOPPED: the export's first bytes are the file's again, and the log says which patch was restored.
// The status is written after the last patch is restored, and a restore is some 160 ms: fifteen patches in this
// target since 0.1.0-beta.45, so the wait is ten seconds where three were enough for twelve.
const ULONGLONG stopAt = GetTickCount64();
r.ctl->unhookRequested = 1;
for (int i = 0; i < 200 && r.st->status != fl::FL_STATUS_UNHOOKED; ++i) {
for (int i = 0; i < 1000 && r.st->status != fl::FL_STATUS_UNHOOKED; ++i) {
++r.ctl->guardTicks;
Sleep(50);
Sleep(10);
}
REQUIRE(r.st->status == fl::FL_STATUS_UNHOOKED);
// Measured, not asserted: the request is read within a frame, then every patch is restored.
WARN("unhook requested -> UNHOOKED: " << (GetTickCount64() - stopAt) << " ms");
std::wstring log;
std::string text;
for (int i = 0; i < 100; ++i) {
@@ -7587,4 +7596,534 @@ TEST_CASE("region 5 carries what a Streamline title chains into its evaluation,
}
CHECK(text.find("UNHOOK_DECLINED") == std::string::npos);
CHECK(text.find("PATCH_FAILED") == std::string::npos);
// 0.1.0-beta.46 (owner decision D134): the rows go in by the batch -- one stop of the target's threads for the rows
// a tick found, not one a row -- and the stop takes every patch out under one. The log says so: a PATCH_BATCH line
// an apply, `b` the number of patches it covered. Counted from the log, not written here as numbers: the rows
// that install unasked go in on an earlier tick than the nine that wait for the request, so there are at least two
// install lines, and every HOOK_INSTALLED that is not one of init's own (DXGI, the loader, OpenGL) is under one.
const auto eachLine = [&text](const char* needle, const auto& visit) {
std::size_t at = 0;
while ((at = text.find(needle, at)) != std::string::npos) {
const std::size_t end = text.find('\n', at);
visit(text.substr(at, end == std::string::npos ? std::string::npos : end - at));
at = end == std::string::npos ? text.size() : end;
}
};
const auto field = [](const std::string& line, std::string_view key, int base) {
const std::size_t at = line.find(key);
return at == std::string::npos ? 0ull : std::strtoull(line.c_str() + at + key.size(), nullptr, base);
};
unsigned long long installBatches = 0;
unsigned long long installedByBatch = 0;
unsigned long long restoreBatches = 0;
unsigned long long restoredByBatch = 0;
unsigned long long restoreMicros = 0;
unsigned long long installedLazily = 0;
unsigned long long restoredLines = 0;
// `b` holds the patches in its low half; its high half counts the ones a failed apply left to be done one at a
// time (owner decision D137), and the line then reads "install singly" / "restore singly". Neither happens here.
eachLine("PATCH_BATCH install", [&](const std::string& line) {
++installBatches;
installedByBatch += field(line, " b=0x", 16) & 0xFFFFull;
CHECK((field(line, " b=0x", 16) >> 16) == 0ull);
WARN("an install batch put " << (field(line, " b=0x", 16) & 0xFFFFull) << " patches in, in "
<< field(line, " a=", 10) << " us");
});
eachLine("PATCH_BATCH restore", [&](const std::string& line) {
++restoreBatches;
restoredByBatch += field(line, " b=0x", 16) & 0xFFFFull;
CHECK((field(line, " b=0x", 16) >> 16) == 0ull);
restoreMicros += field(line, " a=", 10);
});
CHECK(text.find("install singly") == std::string::npos);
CHECK(text.find("restore singly") == std::string::npos);
eachLine("HOOK_INSTALLED ", [&](const std::string& line) {
if (line.find("dxgi!") == std::string::npos && line.find("kernelbase!") == std::string::npos &&
line.find("opengl32!") == std::string::npos) {
++installedLazily;
}
});
eachLine("UNHOOK_RESTORED ", [&](const std::string&) { ++restoredLines; });
CHECK(installBatches >= 2u);
CHECK(installedByBatch == installedLazily);
CHECK(installedLazily >= 10u); // slSetConstants and the eight feature exports among them
CHECK(restoreBatches == 1u);
CHECK(restoredByBatch == restoredLines);
// One stop of the threads, not one a patch: restoring these one by one took 1.3 s to 1.5 s on the development PC
// (0.1.0-beta.45, eighteen patches). A bound a slow runner still meets, and the old way did not.
WARN("the stop's one apply restored " << restoredByBatch << " patches in " << restoreMicros << " us");
CHECK(restoreMicros < 1000000ull);
}
// =====================================================================================================================
// REFLEX LATENCY (Advanced metrics train C; owner decisions D132, D136, D138-D141; fl_reflex.h; fl_shm.h's latency
// words). The one thing the Overlay does in a game that is not reading a hooked call's arguments: a call of its own
// into the driver, once a second, on the presenting thread. Against a Direct3D 12 target that has loaded a stand-in
// nvapi64.dll (tools/vendor-stubs/stub_nvapi64.cpp), whose knobs and call counts the test reads from outside through
// the stub's named section -- so "the driver was not called" is a count, not an inference.
//
// NOT PROVEN HERE: anything about Control Flow Guard (hook-harness does not enforce it; ctest fl_reflex_probe_stub
// runs the same header in a process that does), and anything about a real driver.
// =====================================================================================================================
namespace {
struct StubNv {
HANDLE section = nullptr;
fl::stubnv::Shared* words = nullptr;
~StubNv() {
if (words != nullptr) {
UnmapViewOfFile(words);
}
if (section != nullptr) {
CloseHandle(section);
}
}
};
bool OpenStubNv(DWORD pid, StubNv& stub) {
wchar_t name[64]{};
if (_snwprintf_s(name, _TRUNCATE, fl::stubnv::kSectionFormat, pid) <= 0) {
return false;
}
for (int i = 0; i < 100 && stub.section == nullptr; ++i) {
stub.section = OpenFileMappingW(FILE_MAP_READ | FILE_MAP_WRITE, FALSE, name);
if (stub.section == nullptr) {
Sleep(50);
}
}
if (stub.section == nullptr) {
return false;
}
stub.words = static_cast<fl::stubnv::Shared*>(
MapViewOfFile(stub.section, FILE_MAP_READ | FILE_MAP_WRITE, 0, 0, sizeof(fl::stubnv::Shared)));
return stub.words != nullptr;
}
uint32_t StubWord(const uint32_t& word) {
return std::atomic_ref<const uint32_t>{word}.load(std::memory_order_relaxed);
}
void SetStubWord(uint32_t& word, uint32_t value) {
std::atomic_ref<uint32_t>{word}.store(value, std::memory_order_relaxed);
}
struct LatencyTarget {
Child child;
MappedRing r;
StubNv stub;
};
// The harness -- `exe`, or the built one -- started with `args`, injected, its ring opened; and the stub's section
// opened when the target was told to load one.
bool StartLatencyTarget(LatencyTarget& t, const std::wstring& args, bool withStub,
const wchar_t* exe = FL_HARNESS_EXE) {
std::wstring cmd = std::wstring(L"\"") + exe + L"\" " + args;
STARTUPINFOW si{};
si.cb = sizeof(si);
if (!CreateProcessW(exe, cmd.data(), nullptr, nullptr, FALSE, CREATE_NO_WINDOW, nullptr, nullptr, &si,
&t.child.pi)) {
return false;
}
Sleep(800);
if (WaitForSingleObject(t.child.pi.hProcess, 0) != WAIT_TIMEOUT) {
return false;
}
if (withStub && !OpenStubNv(t.child.pi.dwProcessId, t.stub)) {
return false;
}
ResetFake();
g.modules = {"kernel32.dll"};
g.scanSet = {t.child.pi.dwProcessId};
if (!GuardedInjectWithSources(t.child.pi.dwProcessId, FL_OVERLAY_DLL, FakeSources()).Allowed()) {
return false;
}
return OpenRingFor(t.child.pi.dwProcessId, t.r) && t.r.st != nullptr && t.r.ctl != nullptr;
}
std::wstring LatencyArgs(const wchar_t* presenting) {
return std::wstring(L"--real --load \"") + FL_STUB_NVAPI64 + L"\" " + presenting;
}
uint32_t LatStateOf(const fl::FlAdvancedState& a) {
return a.latState & FL_LAT_STATE_MASK;
}
// A consistent copy of region 5 as it is now, or false while the watchdog is inside it.
bool CopyAdvanced(const MappedRing& r, fl::FlAdvancedState& out) {
fl::FlAdvancedState* region = RegionFive(r);
std::atomic_ref<uint32_t> seq{region->seq};
const uint32_t before = seq.load(std::memory_order_acquire);
if (before == 0u || (before & 1u) != 0u) {
return false;
}
fl::FlAdvancedState copy{};
std::memcpy(&copy, region, sizeof(copy));
std::atomic_thread_fence(std::memory_order_seq_cst);
if (seq.load(std::memory_order_acquire) != before) {
return false;
}
out = copy;
return true;
}
// Waits, bounded, for a publication that answers `request` and whose latency state is `want`.
bool WaitForLatState(const MappedRing& r, uint32_t request, uint32_t want, fl::FlAdvancedState& out) {
uint32_t after = 0u;
for (int i = 0; i < 14; ++i) {
fl::FlAdvancedState a{};
if (!ReadAdvanced(r, request, a, after)) {
return false;
}
after = a.samples;
if (LatStateOf(a) == want) {
out = a;
return true;
}
}
return false;
}
// What a run of publications showed: every one that carried frames carried the stub's numbers.
struct LatencySeen {
uint32_t withFrames = 0;
uint32_t reads = 0;
uint32_t state = 0;
bool framesRight = true;
bool sumsRight = true;
bool driverSpanAbsent = false;
};
void WatchLatency(const MappedRing& r, uint32_t request, int ms, LatencySeen& seen) {
uint32_t lastSamples = 0u;
for (int waited = 0; waited < ms; waited += 50) {
++r.ctl->guardTicks;
fl::FlAdvancedState a{};
if (CopyAdvanced(r, a) && a.request == request && a.samples != lastSamples) {
lastSamples = a.samples;
seen.state = LatStateOf(a);
seen.reads = a.latReads & 0xFFFFu;
const uint32_t frames = a.latFrames & 0xFFFFu;
if (frames != 0u) {
++seen.withFrames;
// Sixty-four frames less the two newest the first time; after that the ten the stub moved on by.
seen.framesRight = seen.framesRight && (frames == 62u || frames == fl::stubnv::kFrameIdStep) &&
(a.latFrames >> 16) == 0u;
seen.driverSpanAbsent = seen.driverSpanAbsent || a.latDriverSumUs == FL_LAT_SUM_NONE;
seen.sumsRight =
seen.sumsRight && a.latSimulationSumUs == frames * fl::stubnv::kSimulationUs &&
a.latSubmitSumUs == frames * fl::stubnv::kSubmitUs &&
a.latPresentSumUs == frames * fl::stubnv::kPresentUs &&
(a.latDriverSumUs == frames * fl::stubnv::kDriverUs || a.latDriverSumUs == FL_LAT_SUM_NONE) &&
a.latOsQueueSumUs == frames * fl::stubnv::kOsQueueUs &&
a.latGpuSumUs == frames * fl::stubnv::kGpuUs && a.latTotalSumUs == frames * fl::stubnv::kTotalUs &&
// The driver's two own times: every frame of the stub gives both.
a.latGpuActiveSumUs == frames * fl::stubnv::kGpuActiveUs &&
a.latGpuFrameSumUs == frames * fl::stubnv::kGpuFrameUs &&
a.latGpuCounts == (frames | (frames << 16));
}
}
Sleep(50);
}
}
// The present hook is recording: these targets load no upscaler, so there is no hook family to wait for.
bool WaitForRecords(const MappedRing& r) {
for (int i = 0; i < 120; ++i) {
++r.ctl->guardTicks;
if (r.st->writeIndex >= 10u) {
return true;
}
Sleep(50);
}
return false;
}
bool TargetHasModule(HANDLE process, const wchar_t* leaf) {
HMODULE modules[1024]{};
DWORD needed = 0;
if (!EnumProcessModules(process, modules, sizeof(modules), &needed)) {
return false;
}
const DWORD count = needed / sizeof(HMODULE) < 1024u ? needed / sizeof(HMODULE) : 1024u;
for (DWORD i = 0; i < count; ++i) {
wchar_t name[MAX_PATH]{};
if (GetModuleBaseNameW(process, modules[i], name, MAX_PATH) != 0 && _wcsicmp(name, leaf) == 0) {
return true;
}
}
return false;
}
} // namespace
TEST_CASE("the driver's latency report is read only while a session asks, once a second, and stops with the request "
"and with the hooks",
"[guard][inject][shm][advanced][latency]") {
LatencyTarget t;
REQUIRE(StartLatencyTarget(t, LatencyArgs(L"--hold-presenting-d3d12 45"), true));
const MappedRing& r = t.r;
fl::stubnv::Shared* stub = t.stub.words;
if (stub == nullptr || r.st == nullptr || r.ctl == nullptr) {
return; // not reached after the REQUIRE; said in the form a static analyser follows (cpp:S2259)
}
REQUIRE(WaitForRecords(r));
// ---- 1. NOT ASKED. The module is there, the device is there, the chain presents -- and nothing is asked of the
// module, not even for the two addresses.
const std::uint64_t atHooks = r.st->writeIndex;
TickFor(r, 3200);
REQUIRE(r.st->writeIndex > atHooks + 30u);
CHECK(RegionFiveIsZero(r));
CHECK(StubWord(stub->queries) == 0u);
CHECK(StubWord(stub->latencyCalls) == 0u);
CHECK(StubWord(stub->sleepStatusCalls) == 0u);
// ---- 2. ASKED. The first publication with the bit carries a read.
SetAdvancedRequest(r, 7u);
fl::FlAdvancedState a{};
REQUIRE(ReadAdvanced(r, 7u, a, 0u, fl::FL_ADV_VALID_LATENCY));
CHECK(LatStateOf(a) == fl::FL_LAT_READING);
CHECK(((a.latState >> FL_LAT_SLEEP_SEEN_ON_SHIFT) & FL_LAT_SLEEP_BITS) == (1u | 8u)); // the stub's status
CHECK(((a.latState >> FL_LAT_SLEEP_SEEN_OFF_SHIFT) & FL_LAT_SLEEP_BITS) == (2u | 4u | 16u));
CHECK((a.latState >> FL_LAT_FG_MULTIPLIER_SHIFT) == 2u);
CHECK(a.latMultipliersSeen == (1u << fl::stubnv::kFgMultiplier)); // the one multiplier the status has given
CHECK((a.latReads >> 16) < 2000u); // no call of two milliseconds: that would have been the last one
LatencySeen seen;
WatchLatency(r, 7u, 5200, seen);
INFO("publications with frames " << seen.withFrames << ", reads " << seen.reads << ", stub calls "
<< StubWord(stub->latencyCalls) << ", state " << seen.state);
CHECK(seen.state == fl::FL_LAT_READING);
CHECK(seen.withFrames >= 2u);
CHECK(seen.framesRight);
CHECK(seen.sumsRight);
// ABOUT ONCE A SECOND: some seven seconds since the request. Not ten, and not hundreds.
CHECK(seen.reads >= 3u);
CHECK(seen.reads <= 9u);
// Every read the Overlay counts is a call the stub received, and at most one more is on its way to be counted.
const uint32_t calls = StubWord(stub->latencyCalls);
CHECK(calls >= seen.reads);
CHECK(calls <= seen.reads + 2u);
CHECK(StubWord(stub->queries) == 2u); // the two addresses, asked for once
CHECK(r.st->faultCount == 0u);
CHECK(r.st->status == fl::FL_STATUS_READY);
REQUIRE(ReadAdvanced(r, 7u, a, a.samples));
WARN("the slowest of " << (a.latReads & 0xFFFFu) << " reads took " << (a.latReads >> 16) << " us");
// ---- 3. A span the driver does not report reads "none", and its frames are still summed; an error is an error,
// and reading goes on after it.
SetStubWord(stub->mode, fl::stubnv::kModeNoDriverSpan);
LatencySeen withoutDriverSpan;
WatchLatency(r, 7u, 3200, withoutDriverSpan);
CHECK(withoutDriverSpan.driverSpanAbsent);
CHECK(withoutDriverSpan.sumsRight);
SetStubWord(stub->mode, fl::stubnv::kModeError);
REQUIRE(WaitForLatState(r, 7u, fl::FL_LAT_ERROR, a));
CHECK((a.validMask & fl::FL_ADV_VALID_LATENCY) != 0u); // a read did return OK in this session
SetStubWord(stub->mode, fl::stubnv::kModeReports);
REQUIRE(WaitForLatState(r, 7u, fl::FL_LAT_READING, a));
// ---- 3b. THE MULTIPLIERS SEEN: the status now gives 3. The last one is 3, and the session saw both.
SetStubWord(stub->fgMultiplier, 3u);
bool sawBoth = false;
for (int i = 0; i < 8 && !sawBoth; ++i) {
REQUIRE(ReadAdvanced(r, 7u, a, a.samples));
sawBoth = a.latMultipliersSeen == ((1u << 2) | (1u << 3));
}
CHECK(sawBoth);
CHECK((a.latState >> FL_LAT_FG_MULTIPLIER_SHIFT) == 3u);
// ---- 4. NOT ASKED AGAIN. No further call.
SetAdvancedRequest(r, 0u);
TickFor(r, 2500); // the watchdog has seen the zero, and a read already under way has ended
const uint32_t callsWhenOff = StubWord(stub->latencyCalls);
TickFor(r, 3000);
CHECK(StubWord(stub->latencyCalls) == callsWhenOff);
// ---- 5. A SECOND SESSION of a target that kept running: its count is its own, and the module is not asked for
// the addresses again.
SetAdvancedRequest(r, 9u);
REQUIRE(ReadAdvanced(r, 9u, a, 0u, fl::FL_ADV_VALID_LATENCY));
CHECK(LatStateOf(a) == fl::FL_LAT_READING);
CHECK((a.latReads & 0xFFFFu) <= 3u);
CHECK(StubWord(stub->queries) == 2u);
// ... and so is what it saw: the 2 of the session before is not in it, whether as a multiplier that session
// was given or as a read it left behind.
CHECK(a.latMultipliersSeen == (1u << 3));
// ---- 6. THE STOP while a session asks: nothing is called after it.
r.ctl->unhookRequested = 1;
for (int i = 0; i < 100 && r.st->status != fl::FL_STATUS_UNHOOKED; ++i) {
Sleep(50);
}
REQUIRE(r.st->status == fl::FL_STATUS_UNHOOKED);
Sleep(300); // a read that was under way when the stop landed
const uint32_t callsWhenStopped = StubWord(stub->latencyCalls);
Sleep(2500);
CHECK(StubWord(stub->latencyCalls) == callsWhenStopped);
CHECK(r.st->faultCount == 0u);
}
TEST_CASE("a call into the driver that takes fifty milliseconds is the last one, and the game goes on",
"[guard][inject][shm][advanced][latency]") {
LatencyTarget t;
REQUIRE(StartLatencyTarget(t, LatencyArgs(L"--hold-presenting-d3d12 16"), true));
const MappedRing& r = t.r;
fl::stubnv::Shared* stub = t.stub.words;
if (stub == nullptr || r.st == nullptr || r.ctl == nullptr) {
return;
}
REQUIRE(WaitForRecords(r));
SetStubWord(stub->blockMs, 50u);
SetAdvancedRequest(r, 7u);
fl::FlAdvancedState a{};
REQUIRE(WaitForLatState(r, 7u, fl::FL_LAT_SLOW, a)); // owner decision D141: one call of 2 ms or more
CHECK((a.latReads >> 16) >= 40000u); // the microseconds it took are published
CHECK(StubWord(stub->latencyCalls) == 1u);
CHECK(StubWord(stub->sleepStatusCalls) == 0u); // nor the second getter after a slow first
const std::uint64_t index = r.st->writeIndex;
TickFor(r, 3000);
CHECK(StubWord(stub->latencyCalls) == 1u);
CHECK(r.st->writeIndex > index + 30u); // presents are still recorded
CHECK(r.st->status == fl::FL_STATUS_READY);
CHECK(r.st->faultCount == 0u);
fl::FlAdvancedState later{};
REQUIRE(ReadAdvanced(r, 7u, later, a.samples));
CHECK(LatStateOf(later) == fl::FL_LAT_SLOW);
}
TEST_CASE("a fault inside the driver's getter is caught, counted once, and ends the reads; the hooks stay",
"[guard][inject][shm][advanced][latency]") {
LatencyTarget t;
REQUIRE(StartLatencyTarget(t, LatencyArgs(L"--hold-presenting-d3d12 16"), true));
const MappedRing& r = t.r;
fl::stubnv::Shared* stub = t.stub.words;
if (stub == nullptr || r.st == nullptr || r.ctl == nullptr) {
return;
}
REQUIRE(WaitForRecords(r));
SetStubWord(stub->mode, fl::stubnv::kModeFault);
SetAdvancedRequest(r, 7u);
fl::FlAdvancedState a{};
REQUIRE(WaitForLatState(r, 7u, fl::FL_LAT_FAULTED, a));
CHECK((a.validMask & fl::FL_ADV_VALID_LATENCY) == 0u); // no read ever returned OK
CHECK(r.st->faultCount == 1u);
CHECK(StubWord(stub->latencyCalls) == 1u);
const std::uint64_t index = r.st->writeIndex;
TickFor(r, 3200);
CHECK(StubWord(stub->latencyCalls) == 1u); // not called again: one fault cannot become three
CHECK(r.st->faultCount == 1u);
CHECK(r.st->status == fl::FL_STATUS_READY); // the Overlay did not disable itself
CHECK(r.st->writeIndex > index + 30u);
}
TEST_CASE("a module that does not answer for the getters is asked once and never called",
"[guard][inject][shm][advanced][latency]") {
LatencyTarget t;
REQUIRE(StartLatencyTarget(t, LatencyArgs(L"--hold-presenting-d3d12 14"), true));
const MappedRing& r = t.r;
fl::stubnv::Shared* stub = t.stub.words;
if (stub == nullptr || r.st == nullptr || r.ctl == nullptr) {
return;
}
REQUIRE(WaitForRecords(r));
SetStubWord(stub->hideGetters, 1u);
SetAdvancedRequest(r, 7u);
fl::FlAdvancedState a{};
REQUIRE(WaitForLatState(r, 7u, fl::FL_LAT_NO_GETTER, a));
CHECK(StubWord(stub->queries) == 2u);
SetStubWord(stub->hideGetters, 0u); // too late, by design: the answer was final for the process
TickFor(r, 2600);
CHECK(StubWord(stub->queries) == 2u);
CHECK(StubWord(stub->latencyCalls) == 0u);
REQUIRE(ReadAdvanced(r, 7u, a, a.samples));
CHECK(LatStateOf(a) == fl::FL_LAT_NO_GETTER);
CHECK(r.st->faultCount == 0u);
}
TEST_CASE("a game that has not loaded nvapi64.dll is not given one", "[guard][inject][shm][advanced][latency]") {
LatencyTarget t;
REQUIRE(StartLatencyTarget(t, L"--real --hold-presenting-d3d12 12", false));
const MappedRing& r = t.r;
if (r.st == nullptr || r.ctl == nullptr) {
return;
}
REQUIRE(WaitForRecords(r));
REQUIRE_FALSE(TargetHasModule(t.child.pi.hProcess, L"nvapi64.dll")); // or this case proves nothing
SetAdvancedRequest(r, 7u);
fl::FlAdvancedState a{};
REQUIRE(WaitForLatState(r, 7u, fl::FL_LAT_NO_MODULE, a));
CHECK((a.validMask & fl::FL_ADV_VALID_LATENCY) == 0u);
TickFor(r, 2200);
CHECK_FALSE(TargetHasModule(t.child.pi.hProcess, L"nvapi64.dll")); // asked for by name, never loaded
CHECK(r.st->faultCount == 0u);
}
TEST_CASE("an nvapi64.dll in the executable's own folder is refused and never asked anything",
"[guard][inject][shm][advanced][latency]") {
// Owner decision D140. The driver's module lives in Windows' own directories; one beside the game is a
// replacement. A copy of the harness with a copy of the stand-in beside it is that arrangement.
FILETIME started{};
GetSystemTimeAsFileTime(&started);
wchar_t temp[MAX_PATH]{};
REQUIRE(GetTempPathW(MAX_PATH, temp) != 0);
const std::wstring dir = std::wstring(temp) + L"fl-latency-" + std::to_wstring(GetCurrentProcessId()) + L"-" +
std::to_wstring(GetTickCount64());
REQUIRE(CreateDirectoryW(dir.c_str(), nullptr));
const std::wstring exe = dir + L"\\hook-harness.exe";
const std::wstring beside = dir + L"\\nvapi64.dll";
REQUIRE(CopyFileW(FL_HARNESS_EXE, exe.c_str(), TRUE));
REQUIRE(CopyFileW(FL_STUB_NVAPI64, beside.c_str(), TRUE));
{
LatencyTarget t;
REQUIRE(
StartLatencyTarget(t, L"--real --load \"" + beside + L"\" --hold-presenting-d3d12 12", true, exe.c_str()));
const MappedRing& r = t.r;
fl::stubnv::Shared* stub = t.stub.words;
if (stub != nullptr && r.st != nullptr && r.ctl != nullptr) {
REQUIRE(WaitForRecords(r));
SetAdvancedRequest(r, 7u);
fl::FlAdvancedState a{};
CHECK(WaitForLatState(r, 7u, fl::FL_LAT_REFUSED, a));
TickFor(r, 2200);
CHECK(StubWord(stub->queries) == 0u); // not even asked for the addresses
CHECK(StubWord(stub->latencyCalls) == 0u);
CHECK(r.st->faultCount == 0u);
}
} // the target is gone before its files are removed
// The run's sweep removes the logs of THIS BUILD'S harness by its path; this copy has another, so its log is
// removed here -- or it would be left in the real data folder, which tools/test-artifacts-check.ps1 fails.
if (std::wstring logs; fl::testing::RealOverlayLogsDir(logs)) {
static_cast<void>(fl::testing::SweepHarnessLogs(logs, started, exe));
}
DeleteFileW(beside.c_str());
DeleteFileW(exe.c_str());
RemoveDirectoryW(dir.c_str());
}
TEST_CASE("a Direct3D 11 title is not read: the Overlay holds no device of its",
"[guard][inject][shm][advanced][latency]") {
LatencyTarget t;
REQUIRE(StartLatencyTarget(t, LatencyArgs(L"--hold-presenting 12"), true));
const MappedRing& r = t.r;
fl::stubnv::Shared* stub = t.stub.words;
if (stub == nullptr || r.st == nullptr || r.ctl == nullptr) {
return;
}
REQUIRE(WaitForRecords(r));
SetAdvancedRequest(r, 7u);
fl::FlAdvancedState a{};
REQUIRE(WaitForLatState(r, 7u, fl::FL_LAT_NO_DEVICE, a));
TickFor(r, 2600);
CHECK(StubWord(stub->queries) == 0u);
CHECK(StubWord(stub->latencyCalls) == 0u);
CHECK((a.validMask & fl::FL_ADV_VALID_LATENCY) == 0u);
}
+312
View File
@@ -0,0 +1,312 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
// fl_adv_fields.h's reader of the driver's latency report (Advanced metrics train C; spike-notes §31), driven
// without the Overlay and without a driver: the header the Overlay compiles, on reports written here by hand.
//
// What it holds is what a real report made necessary. The newest frames of a report are not final -- one run of the
// probe read a span of half an hour in the newest -- so the two newest are never summed. An end point of zero is a
// span the driver did not report, not a fault of the frame: without a sleep mode it leaves driverStartTime zero in
// every frame, and a reader that refused those frames would refuse every frame of such a game. A span that runs
// backwards or lasts over a second is refused with its frame. And a game whose frame ids start again must not be
// read as a game that has stopped.
#include <catch2/catch_test_macros.hpp>
#include <cstdint>
#include <fl_adv_fields.h>
#include <memory>
namespace {
using Frame = NV_LATENCY_RESULT_PARAMS::FrameReport;
// A frame as the stand-in module writes one: every span reported, 7500 us from simulation start to the GPU's end.
Frame Whole(std::uint64_t id) {
Frame f{};
const std::uint64_t t = 1'000'000ull + id * 4200ull;
f.frameID = id;
f.simStartTime = t + 100u;
f.simEndTime = t + 900u; // 800
f.renderSubmitStartTime = t + 950u;
f.renderSubmitEndTime = t + 2100u; // 1150
f.presentStartTime = t + 2150u;
f.presentEndTime = t + 2300u; // 150
f.driverStartTime = t + 2300u;
f.driverEndTime = t + 2700u; // 400
f.osRenderQueueStartTime = t + 2700u;
f.osRenderQueueEndTime = t + 3900u; // 1200
f.gpuRenderStartTime = t + 3900u;
f.gpuRenderEndTime = t + 7600u; // 3700; total 7500
return f;
}
// The report is 15 KB: on the heap here, as it is in static storage in the Overlay.
std::unique_ptr<NV_LATENCY_RESULT_PARAMS> Report(std::uint64_t firstId, std::uint32_t frames = 64u) {
auto report = std::make_unique<NV_LATENCY_RESULT_PARAMS>();
for (std::uint32_t i = 0; i < frames; ++i) {
report->frameReport[64u - frames + i] = Whole(firstId + i); // the newest last, as the driver writes it
}
return report;
}
} // namespace
TEST_CASE("a report's two newest frames are left for the next read, and a frame is summed once", "[latency]") {
fl::adv::LatencyCursor cursor;
fl::adv::LatencyTally tally;
auto first = Report(5000u);
fl::adv::ObserveLatencyReport(*first, cursor, tally);
CHECK(tally.frames == 62u); // 5000..5061; 5062 and 5063 are not final yet
CHECK(tally.refused == 0u);
CHECK(tally.lacking == 0u);
CHECK(tally.sumUs[0] == 62u * 800u);
CHECK(tally.sumUs[1] == 62u * 1150u);
CHECK(tally.sumUs[2] == 62u * 150u);
CHECK(tally.sumUs[3] == 62u * 400u);
CHECK(tally.sumUs[4] == 62u * 1200u);
CHECK(tally.sumUs[5] == 62u * 3700u);
CHECK(tally.sumUs[fl::adv::kLatTotal] == 62u * 7500u);
CHECK(cursor.lastFrameId == 5061u);
// The same report again: nothing is new.
fl::adv::ObserveLatencyReport(*first, cursor, tally);
CHECK(tally.frames == 0u);
CHECK(tally.refused == 0u);
CHECK(cursor.lastFrameId == 5061u);
// Ten frames further on: the two that were held back and eight more, and again not the two newest.
auto second = Report(5010u);
fl::adv::ObserveLatencyReport(*second, cursor, tally);
CHECK(tally.frames == 10u); // 5062..5071
CHECK(tally.sumUs[fl::adv::kLatTotal] == 10u * 7500u);
CHECK(cursor.lastFrameId == 5071u);
}
TEST_CASE("a report of nothing, of one frame and of two sums nothing", "[latency]") {
fl::adv::LatencyCursor cursor;
fl::adv::LatencyTally tally;
tally.frames = 9u; // whatever was there is replaced, not added to
auto empty = Report(0u, 0u);
fl::adv::ObserveLatencyReport(*empty, cursor, tally);
CHECK(tally.frames == 0u);
CHECK(cursor.lastFrameId == 0u);
auto one = Report(700u, 1u);
fl::adv::ObserveLatencyReport(*one, cursor, tally);
CHECK(tally.frames == 0u);
auto two = Report(700u, 2u);
fl::adv::ObserveLatencyReport(*two, cursor, tally);
CHECK(tally.frames == 0u);
CHECK(tally.refused == 0u);
auto three = Report(700u, 3u);
fl::adv::ObserveLatencyReport(*three, cursor, tally);
CHECK(tally.frames == 1u); // 700; 701 and 702 wait
CHECK(cursor.lastFrameId == 700u);
}
TEST_CASE("an end point of zero is a span the driver did not report: the frame is summed and the span reads none",
"[latency]") {
fl::adv::LatencyCursor cursor;
fl::adv::LatencyTally tally;
auto report = Report(100u);
for (auto& f : report->frameReport) {
f.driverStartTime = 0u; // what the driver gives a game that sets markers and no sleep mode
}
fl::adv::ObserveLatencyReport(*report, cursor, tally);
CHECK(tally.frames == 62u);
CHECK(tally.refused == 0u);
CHECK(tally.lacking == (1u << 3));
CHECK(tally.sumUs[3] == 0u);
CHECK(tally.sumUs[fl::adv::kLatTotal] == 62u * 7500u);
// What is published for it: the sum of a span some summed frame lacked is all ones, never a smaller number.
CHECK(fl::adv::LatencySum(tally, 3u) == FL_LAT_SUM_NONE);
CHECK(fl::adv::LatencySum(tally, 0u) == 62u * 800u);
CHECK(fl::adv::LatencySum(fl::adv::LatencyTally{}, 0u) == 0u); // no frame: zero, not "none"
}
TEST_CASE("a span no frame can have refuses the frame whole, and so does a frame with no total", "[latency]") {
fl::adv::LatencyCursor cursor;
fl::adv::LatencyTally tally;
auto report = Report(100u);
report->frameReport[0].presentEndTime = report->frameReport[0].presentStartTime - 50u; // backwards
report->frameReport[1].gpuRenderEndTime = report->frameReport[1].simStartTime + 1'844'674'519ull; // half an hour
report->frameReport[2].gpuRenderEndTime = 0u; // no total
report->frameReport[3].simStartTime = 0u; // no total
report->frameReport[4].osRenderQueueEndTime = report->frameReport[4].osRenderQueueStartTime + 1'000'001ull;
report->frameReport[5].osRenderQueueEndTime = report->frameReport[5].osRenderQueueStartTime + 1'000'000ull;
fl::adv::ObserveLatencyReport(*report, cursor, tally);
CHECK(tally.refused == 5u);
CHECK(tally.frames == 57u); // 62 that are not the two newest, less the five; frame 5's second is still a span
CHECK(tally.lacking == 0u);
CHECK(tally.sumUs[2] == 57u * 150u); // the backwards present added nothing
CHECK(tally.sumUs[4] == 56u * 1200u + 1'000'000u); // exactly a second is allowed; a microsecond more is not
CHECK(cursor.lastFrameId == 161u); // a refused frame is not looked at again either
}
TEST_CASE("frame ids that start again restart the reader instead of silencing it", "[latency]") {
fl::adv::LatencyCursor cursor;
fl::adv::LatencyTally tally;
auto late = Report(90'000u);
fl::adv::ObserveLatencyReport(*late, cursor, tally);
REQUIRE(cursor.lastFrameId == 90'061u);
auto again = Report(1u); // the game went back to its menu and counts from one
fl::adv::ObserveLatencyReport(*again, cursor, tally);
CHECK(tally.frames == 62u);
CHECK(cursor.lastFrameId == 62u);
}
TEST_CASE("the frames are found whatever order the driver left them in", "[latency]") {
fl::adv::LatencyCursor cursor;
fl::adv::LatencyTally tally;
auto report = Report(300u);
const Frame newest = report->frameReport[63];
report->frameReport[63] = report->frameReport[10];
report->frameReport[10] = newest; // the newest id is in the middle now
fl::adv::ObserveLatencyReport(*report, cursor, tally);
CHECK(tally.frames == 62u);
CHECK(cursor.lastFrameId == 361u); // 362 and 363 are the two newest wherever they sit
}
TEST_CASE("the sleep status is the driver's five switches and its multiplier, and nothing else of it", "[latency]") {
NV_GET_SLEEP_STATUS_PARAMS status{};
CHECK(fl::adv::ObserveSleepStatus(status).on == 0u);
status.bLowLatencyMode = 1;
status.bCplVsyncOn = 1;
status.bFullscreenIFlip = 1;
status.fgMultiplier = 3;
status.sleepIntervalUs = 4166u; // changes with every frame: not kept
const fl::adv::LatencySleep seen = fl::adv::ObserveSleepStatus(status);
CHECK(seen.on == (1u | 4u | 16u));
CHECK(seen.multiplier == 3u);
status = NV_GET_SLEEP_STATUS_PARAMS{};
status.bFsVrr = 1;
status.bUseGameSleep = 1;
CHECK(fl::adv::ObserveSleepStatus(status).on == (2u | 8u));
}
TEST_CASE("the driver's two own times are summed over the frames that gave one, each with its own count", "[latency]") {
fl::adv::LatencyCursor cursor;
fl::adv::LatencyTally tally;
// Twelve frames, 5000..5011: ten are summed, the two newest wait.
auto report = Report(5000u, 12u);
for (std::uint32_t i = 52u; i < 64u; ++i) {
report->frameReport[i].gpuActiveRenderTimeUs = 3500u;
report->frameReport[i].gpuFrameTimeUs = 4200u;
}
report->frameReport[52].gpuActiveRenderTimeUs = 0u; // 5000: the driver gave no active time
report->frameReport[53].gpuFrameTimeUs = 1'000'001u; // 5001: a frame time no frame can have
report->frameReport[54].gpuActiveRenderTimeUs = 1'000'000u; // 5002: a second, to the microsecond, is kept
fl::adv::ObserveLatencyReport(*report, cursor, tally);
CHECK(tally.frames == 10u); // neither of the two refuses a frame
CHECK(tally.refused == 0u);
CHECK(tally.sumUs[fl::adv::kLatTotal] == 10u * 7500u);
CHECK(tally.lacking == 0u);
CHECK(tally.activeFrames == 9u);
CHECK(tally.activeSumUs == 8u * 3500u + 1'000'000u);
CHECK(tally.frameTimeFrames == 9u);
CHECK(tally.frameTimeSumUs == 9u * 4200u);
// A frame that is refused gives neither, and a driver that fills in neither leaves both counts at zero.
cursor = fl::adv::LatencyCursor{};
auto refused = Report(6000u, 3u);
refused->frameReport[61].gpuActiveRenderTimeUs = 3500u;
refused->frameReport[61].gpuFrameTimeUs = 4200u;
refused->frameReport[61].presentEndTime = refused->frameReport[61].presentStartTime - 50u;
fl::adv::ObserveLatencyReport(*refused, cursor, tally);
CHECK(tally.frames == 0u);
CHECK(tally.refused == 1u);
CHECK(tally.activeFrames == 0u);
CHECK(tally.frameTimeFrames == 0u);
cursor = fl::adv::LatencyCursor{};
auto older = Report(7000u);
fl::adv::ObserveLatencyReport(*older, cursor, tally);
CHECK(tally.frames == 62u);
CHECK(tally.activeFrames == 0u);
CHECK(tally.activeSumUs == 0u);
CHECK(tally.frameTimeFrames == 0u);
}
TEST_CASE("a multiplier the status gave has a bit of its own, and thirty-one and more share the last", "[latency]") {
CHECK(fl::adv::LatencyMultiplierBit(0u) == 1u);
CHECK(fl::adv::LatencyMultiplierBit(1u) == 2u);
CHECK(fl::adv::LatencyMultiplierBit(4u) == 16u);
CHECK(fl::adv::LatencyMultiplierBit(31u) == 0x80000000u);
CHECK(fl::adv::LatencyMultiplierBit(255u) == 0x80000000u);
}
TEST_CASE("a publication carries one read, packed as fl_shm.h says, and carries it once", "[latency]") {
fl::adv::Accumulators a;
fl::FlAdvancedState region{};
fl::adv::LatencyOut out;
out.state = fl::FL_LAT_READING;
out.sleepSeenOn = 1u | 8u;
out.sleepSeenOff = 2u | 4u | 16u;
out.multiplier = 2u;
out.multipliersSeen = (1u << 1) | (1u << 2);
out.reads = 70'000u; // stops at 65535
out.worstUs = 66u;
out.tally.frames = 10u;
out.tally.refused = 1u;
for (std::uint32_t i = 0; i < fl::adv::kLatSpans; ++i) {
out.tally.sumUs[i] = 1000u * (i + 1u);
}
out.tally.lacking = 1u << 3;
out.tally.activeSumUs = 31'500u;
out.tally.activeFrames = 9u;
out.tally.frameTimeSumUs = 42'000u;
out.tally.frameTimeFrames = 10u;
fl::adv::Publish(a, &region, 7u, 1234u, &out);
CHECK((region.latState & FL_LAT_STATE_MASK) == fl::FL_LAT_READING);
CHECK(((region.latState >> FL_LAT_SLEEP_SEEN_ON_SHIFT) & FL_LAT_SLEEP_BITS) == (1u | 8u));
CHECK(((region.latState >> FL_LAT_SLEEP_SEEN_OFF_SHIFT) & FL_LAT_SLEEP_BITS) == (2u | 4u | 16u));
CHECK((region.latState >> FL_LAT_FG_MULTIPLIER_SHIFT) == 2u);
CHECK((region.latReads & 0xFFFFu) == 0xFFFFu);
CHECK((region.latReads >> 16) == 66u);
CHECK((region.latFrames & 0xFFFFu) == 10u);
CHECK((region.latFrames >> 16) == 1u);
CHECK(region.latSimulationSumUs == 1000u);
CHECK(region.latSubmitSumUs == 2000u);
CHECK(region.latPresentSumUs == 3000u);
CHECK(region.latDriverSumUs == FL_LAT_SUM_NONE);
CHECK(region.latOsQueueSumUs == 5000u);
CHECK(region.latGpuSumUs == 6000u);
CHECK(region.latTotalSumUs == 7000u);
CHECK(region.latGpuActiveSumUs == 31'500u);
CHECK(region.latGpuFrameSumUs == 42'000u);
CHECK((region.latGpuCounts & 0xFFFFu) == 9u);
CHECK((region.latGpuCounts >> 16) == 10u);
CHECK(region.latMultipliersSeen == ((1u << 1) | (1u << 2)));
CHECK(region.request == 7u);
// The next publication, with no read in between: the state stands, the frames and the sums are gone.
fl::adv::Publish(a, &region, 7u, 1235u, &out);
CHECK((region.latState & FL_LAT_STATE_MASK) == fl::FL_LAT_READING);
CHECK(region.latFrames == 0u);
CHECK(region.latTotalSumUs == 0u);
CHECK(region.latDriverSumUs == 0u);
CHECK(region.latGpuActiveSumUs == 0u);
CHECK(region.latGpuFrameSumUs == 0u);
CHECK(region.latGpuCounts == 0u);
CHECK(region.latMultipliersSeen == ((1u << 1) | (1u << 2))); // the session's, like the switches
CHECK((region.latReads >> 16) == 66u);
// A caller with no latency summary leaves the latency words alone.
fl::FlAdvancedState untouched{};
fl::adv::Publish(a, &untouched, 7u, 1236u);
CHECK(untouched.latState == 0u);
CHECK(untouched.latReads == 0u);
CHECK(untouched.latTotalSumUs == 0u);
CHECK(untouched.latGpuActiveSumUs == 0u);
CHECK(untouched.latGpuCounts == 0u);
CHECK(untouched.latMultipliersSeen == 0u);
}
+463
View File
@@ -367,3 +367,466 @@ TEST_CASE("a patch that failed gives its slot back, and a slot is not seen by th
registry.Retire(-3);
CHECK(registry.LiveCount() == 0u);
}
// --- batches (0.1.0-beta.46, owner decision D134) --------------------------------------------------------------------
// Several patches for ONE stop of the process's threads, and every patch out the same way. Driven twice: against real
// MinHook, for what is at the target, and against a MODEL of MinHook's table (hook.c: each hook has a state and a
// mark, and an apply executes every hook whose two differ, stopping at the first that fails), for the things real
// MinHook cannot be made to do on demand -- an apply that fails halfway, a stop that lands inside one.
namespace {
// MinHook with its queue, as dllmain.cpp's MinHookEngine hands it to Batch and RestoreAll. The gate is the Overlay's;
// one thread patches here.
struct RealQueue {
static bool Create(void* target, void* detour, void** original) noexcept {
return MH_CreateHook(target, detour, original) == MH_OK;
}
static bool QueueEnable(void* target) noexcept { return MH_QueueEnableHook(target) == MH_OK; }
static bool QueueDisable(void* target) noexcept { return MH_QueueDisableHook(target) == MH_OK; }
static bool Apply() noexcept { return MH_ApplyQueued() == MH_OK; }
static bool EnsureEnabled(void* target) noexcept {
const MH_STATUS status = MH_EnableHook(target);
return status == MH_OK || status == MH_ERROR_ENABLED;
}
static bool EnsureDisabled(void* target) noexcept {
const MH_STATUS status = MH_DisableHook(target);
return status == MH_OK || status == MH_ERROR_DISABLED;
}
static void BeginQueue() noexcept {}
static void EndQueue() noexcept {}
};
bool RealOurs(const void* target, const void* detour) noexcept {
return fl::patch::StillOurs(target, detour);
}
struct Model {
static constexpr int kMax = 8;
void* target[kMax]{};
bool enabled[kMax]{};
bool marked[kMax]{}; // MinHook's queueEnable: the state the next apply gives the hook
bool foreign[kMax]{}; // somebody else patched over this one
int count = 0;
void* neverEnables = nullptr; // the hook at this target cannot be enabled
bool applyFails = false; // the apply does nothing and says so
std::atomic<std::uint32_t>* stopsDuringApply = nullptr;
int applies = 0;
int gate = 0;
bool touchedOutsideTheGate = false;
bool wroteOverAForeignPatch = false;
int Find(const void* t) const noexcept {
for (int i = 0; i < count; ++i) {
if (target[i] == t) {
return i;
}
}
return -1;
}
bool AMarkIsStanding() const noexcept {
for (int i = 0; i < count; ++i) {
if (enabled[i] != marked[i]) {
return true;
}
}
return false;
}
bool Enabled(const void* t) const noexcept {
const int i = Find(t);
return i >= 0 && enabled[i];
}
void Set(int i, bool on) noexcept {
if (i < 0 || i >= count) {
return;
}
if (!on && enabled[i] && foreign[i]) {
wroteOverAForeignPatch = true; // our saved bytes over their jump: what §H7 forbids
}
enabled[i] = on;
marked[i] = on;
}
// Somebody else patched over the hook at `t`.
void PatchOver(const void* t) noexcept {
const int i = Find(t);
if (i >= 0) {
foreign[i] = true;
}
}
};
struct ModelEngine {
Model* m;
bool Create(void* target, void*, void**) const noexcept {
if (m->Find(target) >= 0 || m->count == Model::kMax) {
return false;
}
m->target[m->count++] = target;
return true;
}
bool Mark(void* target, bool on) const noexcept {
const int i = m->Find(target);
if (i < 0) {
return false;
}
m->touchedOutsideTheGate = m->touchedOutsideTheGate || m->gate == 0;
m->marked[i] = on;
return true;
}
bool QueueEnable(void* target) const noexcept { return Mark(target, true); }
bool QueueDisable(void* target) const noexcept { return Mark(target, false); }
bool Apply() const noexcept {
++m->applies;
m->touchedOutsideTheGate = m->touchedOutsideTheGate || m->gate == 0;
if (m->stopsDuringApply != nullptr) {
m->stopsDuringApply->store(0u);
}
if (m->applyFails) {
return false;
}
for (int i = 0; i < m->count; ++i) {
if (m->enabled[i] == m->marked[i]) {
continue;
}
if (m->marked[i] && m->target[i] == m->neverEnables) {
return false; // hook.c: the first failure ends the apply, the rest keep their marks
}
m->Set(i, m->marked[i]);
}
return true;
}
bool EnsureEnabled(void* target) const noexcept {
const int i = m->Find(target);
if (i < 0 || target == m->neverEnables) {
return false;
}
m->Set(i, true);
return true;
}
bool EnsureDisabled(void* target) const noexcept {
const int i = m->Find(target);
if (i < 0) {
return false;
}
m->Set(i, false);
return true;
}
void BeginQueue() const noexcept { ++m->gate; }
void EndQueue() const noexcept { --m->gate; }
};
// "Still ours", for the model: in, and nobody patched over it.
struct ModelOurs {
const Model* m;
bool operator()(const void* target, const void*) const noexcept {
const int i = m->Find(target);
return i >= 0 && m->enabled[i] && !m->foreign[i];
}
};
int g_a = 0;
int g_b = 0;
int g_c = 0;
int g_detour = 0;
} // namespace
TEST_CASE("a batch puts three patches in under one apply, and the stop takes them out under one",
"[unhook][registry][batch]") {
using fl::patch::InstallResult;
fl::patch::Registry<3> registry;
fl::patch::Batch<3> batch;
std::atomic<std::uint32_t> observing{1u};
void* first = reinterpret_cast<void*>(&First);
void* second = reinterpret_cast<void*>(&Second);
void* third = reinterpret_cast<void*>(&Third);
const int firstPlain = First(3);
const int secondPlain = Second(3);
const int thirdPlain = Third(3);
REQUIRE(MH_Initialize() == MH_OK);
CHECK(batch.Add(registry, observing, RealQueue{}, first, reinterpret_cast<void*>(&DetourFirst),
reinterpret_cast<void**>(&g_origFirst), "first", nullptr, 0u) == InstallResult::Pending);
CHECK(batch.Add(registry, observing, RealQueue{}, second, reinterpret_cast<void*>(&DetourSecond),
reinterpret_cast<void**>(&g_origSecond), "second", nullptr, 0u) == InstallResult::Pending);
// The same target a second time: the engine refuses it, its slot goes back, and the others are not held up.
CHECK(batch.Add(registry, observing, RealQueue{}, second, reinterpret_cast<void*>(&DetourSecond),
reinterpret_cast<void**>(&g_origSecond), "second again", nullptr,
0u) == InstallResult::CreateFailed);
CHECK(batch.Add(registry, observing, RealQueue{}, third, reinterpret_cast<void*>(&DetourThird),
reinterpret_cast<void**>(&g_origThird), "third", nullptr, 7u) == InstallResult::Pending);
CHECK(batch.Add(registry, observing, RealQueue{}, nullptr, first, nullptr, "nothing", nullptr, 0u) ==
InstallResult::NoTarget);
REQUIRE(batch.Count() == 3u);
// Added is not patched: nothing is at any target, and the stop's walk has nothing to see.
CHECK(First(3) == firstPlain);
CHECK(Third(3) == thirdPlain);
CHECK(registry.LiveCount() == 0u);
const fl::patch::BatchOutcome in = batch.Commit(registry, observing, RealQueue{}, RealOurs);
CHECK(in.applied); // one apply did it (D137: the caller's log line says so)
CHECK(in.singly == 0u);
for (std::uint32_t i = 0; i < batch.Count(); ++i) {
CHECK(batch.At(i).result == InstallResult::Installed);
}
CHECK(batch.At(2).word == 7u); // what the caller attached comes back with the item
CHECK(First(3) == firstPlain + 1000000);
CHECK(Second(3) == secondPlain + 2000000);
CHECK(Third(3) == thirdPlain + 3000000);
CHECK(registry.LiveCount() == 3u);
batch.Clear();
CHECK(batch.Count() == 0u);
// The stop: one walk, one apply, every patch reported as ours and restored.
observing.store(0u);
int restored = 0;
int declined = 0;
const fl::patch::BatchOutcome out = fl::patch::RestoreAll(
registry, RealQueue{}, RealOurs, [&restored, &declined](const char*, void*, bool wasOurs, bool ok) noexcept {
restored += (wasOurs && ok) ? 1 : 0;
declined += wasOurs ? 0 : 1;
});
CHECK(out.applied);
CHECK(out.singly == 0u);
CHECK(restored == 3);
CHECK(declined == 0);
CHECK(First(3) == firstPlain);
CHECK(Second(3) == secondPlain);
CHECK(Third(3) == thirdPlain);
// Stopping is one-way for a batch as for a single patch: nothing is created after it.
CHECK(batch.Add(registry, observing, RealQueue{}, first, reinterpret_cast<void*>(&DetourFirst),
reinterpret_cast<void**>(&g_origFirst), "first", nullptr, 0u) == InstallResult::Stopped);
MH_Uninitialize();
}
TEST_CASE("the stop's batch leaves a patch a foreign overlay patched over exactly as it is, and restores the others",
"[unhook][registry][batch]") {
using fl::patch::InstallResult;
fl::patch::Registry<2> registry;
fl::patch::Batch<2> batch;
std::atomic<std::uint32_t> observing{1u};
void* first = reinterpret_cast<void*>(&First);
void* second = reinterpret_cast<void*>(&Second);
const int secondPlain = Second(3);
REQUIRE(MH_Initialize() == MH_OK);
REQUIRE(batch.Add(registry, observing, RealQueue{}, first, reinterpret_cast<void*>(&DetourFirst),
reinterpret_cast<void**>(&g_origFirst), "first", nullptr, 0u) == InstallResult::Pending);
REQUIRE(batch.Add(registry, observing, RealQueue{}, second, reinterpret_cast<void*>(&DetourSecond),
reinterpret_cast<void**>(&g_origSecond), "second", nullptr, 0u) == InstallResult::Pending);
batch.Commit(registry, observing, RealQueue{}, RealOurs);
REQUIRE(registry.LiveCount() == 2u);
// A foreign overlay patches First after us.
std::uint8_t* foreignRelay = MakeRelay(reinterpret_cast<void*>(&ForeignDetour), first);
std::int32_t savedRel = 0;
RepointJump(first, foreignRelay, &savedRel);
std::uint8_t theirs[5]{};
std::memcpy(theirs, first, sizeof(theirs));
REQUIRE(First(5) == 4); // their hook is what runs
observing.store(0u);
int restored = 0;
int declined = 0;
fl::patch::RestoreAll(registry, RealQueue{}, RealOurs,
[&restored, &declined](const char*, void*, bool wasOurs, bool ok) noexcept {
restored += (wasOurs && ok) ? 1 : 0;
declined += wasOurs ? 0 : 1;
});
CHECK(restored == 1);
CHECK(declined == 1);
CHECK(std::memcmp(theirs, first, sizeof(theirs)) == 0); // not one byte of theirs was written
CHECK(First(5) == 4);
CHECK(Second(3) == secondPlain);
// ...and no mark was left on the declined one: an apply by anybody afterwards still does not touch it.
CHECK(MH_ApplyQueued() == MH_OK);
CHECK(std::memcmp(theirs, first, sizeof(theirs)) == 0);
RestoreJump(first, savedRel); // the foreign overlay goes away before MinHook is torn down
MH_Uninitialize();
VirtualFree(foreignRelay, 0, MEM_RELEASE);
}
TEST_CASE("an apply that fails halfway costs one patch, and leaves no mark for a later apply to act on",
"[unhook][registry][batch]") {
using fl::patch::InstallResult;
fl::patch::Registry<3> registry;
fl::patch::Batch<3> batch;
std::atomic<std::uint32_t> observing{1u};
Model model;
model.neverEnables = &g_b;
const ModelEngine engine{&model};
REQUIRE(batch.Add(registry, observing, engine, &g_a, &g_detour, nullptr, "a", nullptr, 0u) ==
InstallResult::Pending);
REQUIRE(batch.Add(registry, observing, engine, &g_b, &g_detour, nullptr, "b", nullptr, 0u) ==
InstallResult::Pending);
REQUIRE(batch.Add(registry, observing, engine, &g_c, &g_detour, nullptr, "c", nullptr, 0u) ==
InstallResult::Pending);
CHECK_FALSE(model.AMarkIsStanding()); // adding marks nothing
const fl::patch::BatchOutcome outcome = batch.Commit(registry, observing, engine, ModelOurs{&model});
// D137: the apply said it failed, so all three were handed to the engine one at a time -- a, which the apply had
// already put in, among them: the count is of attempts, and the engine makes no stop for a patch that is in.
CHECK_FALSE(outcome.applied);
CHECK(outcome.singly == 3u);
CHECK(batch.At(0).result == InstallResult::Installed);
CHECK(batch.At(1).result == InstallResult::EnableFailed);
CHECK(batch.At(2).result == InstallResult::Installed); // the apply stopped at b; c went in by itself
CHECK(model.Enabled(&g_a));
CHECK_FALSE(model.Enabled(&g_b));
CHECK(model.Enabled(&g_c));
CHECK(registry.LiveCount() == 2u);
CHECK(model.applies == 1);
CHECK_FALSE(model.AMarkIsStanding());
CHECK_FALSE(model.touchedOutsideTheGate);
CHECK(model.gate == 0);
// The stop's apply -- anybody's apply -- must not be what puts b in.
model.neverEnables = nullptr;
CHECK(engine.Apply());
CHECK_FALSE(model.Enabled(&g_b));
// b's slot went back: the third slot can be claimed again.
CHECK(registry.Claim(&g_b, &g_detour, "b again") >= 0);
}
TEST_CASE("an apply that does nothing at all still gets every patch in, one at a time", "[unhook][registry][batch]") {
using fl::patch::InstallResult;
fl::patch::Registry<2> registry;
fl::patch::Batch<2> batch;
std::atomic<std::uint32_t> observing{1u};
Model model;
model.applyFails = true; // MinHook could not stop the threads: nothing applied, one status for all
const ModelEngine engine{&model};
REQUIRE(batch.Add(registry, observing, engine, &g_a, &g_detour, nullptr, "a", nullptr, 0u) ==
InstallResult::Pending);
REQUIRE(batch.Add(registry, observing, engine, &g_b, &g_detour, nullptr, "b", nullptr, 0u) ==
InstallResult::Pending);
const fl::patch::BatchOutcome in = batch.Commit(registry, observing, engine, ModelOurs{&model});
CHECK_FALSE(in.applied); // what the Overlay logs as "install singly", with the two in the line's high half
CHECK(in.singly == 2u);
CHECK(batch.At(0).result == InstallResult::Installed);
CHECK(batch.At(1).result == InstallResult::Installed);
CHECK(registry.LiveCount() == 2u);
CHECK_FALSE(model.AMarkIsStanding());
// And the stop, with the same failing apply, still takes both out.
observing.store(0u);
int restored = 0;
const fl::patch::BatchOutcome out = fl::patch::RestoreAll(
registry, engine, ModelOurs{&model},
[&restored](const char*, void*, bool wasOurs, bool ok) noexcept { restored += (wasOurs && ok) ? 1 : 0; });
CHECK_FALSE(out.applied); // "restore singly"
CHECK(out.singly == 2u);
CHECK(restored == 2);
CHECK_FALSE(model.Enabled(&g_a));
CHECK_FALSE(model.Enabled(&g_b));
CHECK_FALSE(model.AMarkIsStanding());
CHECK_FALSE(model.touchedOutsideTheGate);
}
TEST_CASE("a stop before the batch commits enables nothing; a stop inside its apply is undone by the batch itself",
"[unhook][registry][batch]") {
using fl::patch::InstallResult;
Model model;
const ModelEngine engine{&model};
SECTION("the stop ran between the adds and the commit") {
fl::patch::Registry<2> registry;
fl::patch::Batch<2> batch;
std::atomic<std::uint32_t> observing{1u};
REQUIRE(batch.Add(registry, observing, engine, &g_a, &g_detour, nullptr, "a", nullptr, 0u) ==
InstallResult::Pending);
REQUIRE(batch.Add(registry, observing, engine, &g_b, &g_detour, nullptr, "b", nullptr, 0u) ==
InstallResult::Pending);
observing.store(0u);
const fl::patch::BatchOutcome outcome = batch.Commit(registry, observing, engine, ModelOurs{&model});
CHECK(outcome.applied); // nothing was asked of an apply, so nothing failed
CHECK(outcome.singly == 0u);
CHECK(batch.At(0).result == InstallResult::StoppedDuring);
CHECK(batch.At(1).result == InstallResult::StoppedDuring);
CHECK(model.applies == 0); // nothing was marked, nothing applied
CHECK_FALSE(model.Enabled(&g_a));
CHECK_FALSE(model.Enabled(&g_b));
CHECK(registry.LiveCount() == 0u);
CHECK(registry.Claim(&g_a, &g_detour, "free again") >= 0); // never live, so not retired
}
SECTION("the stop ran while the apply was putting them in") {
fl::patch::Registry<2> registry;
fl::patch::Batch<2> batch;
std::atomic<std::uint32_t> observing{1u};
model.stopsDuringApply = &observing;
REQUIRE(batch.Add(registry, observing, engine, &g_a, &g_detour, nullptr, "a", nullptr, 0u) ==
InstallResult::Pending);
REQUIRE(batch.Add(registry, observing, engine, &g_b, &g_detour, nullptr, "b", nullptr, 0u) ==
InstallResult::Pending);
batch.Commit(registry, observing, engine, ModelOurs{&model});
CHECK(batch.At(0).result == InstallResult::StoppedDuring);
CHECK(batch.At(1).result == InstallResult::StoppedDuring);
CHECK_FALSE(model.Enabled(&g_a)); // put in, and taken out again by the installer
CHECK_FALSE(model.Enabled(&g_b));
CHECK(model.applies == 2); // one in, one out
CHECK(registry.LiveCount() == 0u);
CHECK(registry.Claim(&g_a, &g_detour, "again") == -1); // they were live: the slots are never reused
CHECK_FALSE(model.AMarkIsStanding());
CHECK_FALSE(model.touchedOutsideTheGate);
CHECK(model.gate == 0);
}
}
TEST_CASE("the stop marks only what is still ours: a foreign patch is not written, a restored patch is not put back",
"[unhook][registry][batch]") {
using fl::patch::InstallResult;
fl::patch::Registry<3> registry;
fl::patch::Batch<3> batch;
std::atomic<std::uint32_t> observing{1u};
Model model;
const ModelEngine engine{&model};
REQUIRE(batch.Add(registry, observing, engine, &g_a, &g_detour, nullptr, "a", nullptr, 0u) ==
InstallResult::Pending);
REQUIRE(batch.Add(registry, observing, engine, &g_b, &g_detour, nullptr, "b", nullptr, 0u) ==
InstallResult::Pending);
REQUIRE(batch.Add(registry, observing, engine, &g_c, &g_detour, nullptr, "c", nullptr, 0u) ==
InstallResult::Pending);
batch.Commit(registry, observing, engine, ModelOurs{&model});
REQUIRE(registry.LiveCount() == 3u);
model.PatchOver(&g_a); // a: somebody patched over us
// c: committed, and already taken out -- an installer between its own disable and its Retire. The draft that
// marked everything and then un-marked what it must not restore marked THIS one for enabling, and the stop's own
// apply put the patch back in after the stop.
model.Set(model.Find(&g_c), false);
model.applies = 0;
observing.store(0u);
int ours = 0;
int notOurs = 0;
fl::patch::RestoreAll(registry, engine, ModelOurs{&model},
[&ours, &notOurs](const char*, void*, bool wasOurs, bool ok) noexcept {
ours += (wasOurs && ok) ? 1 : 0;
notOurs += wasOurs ? 0 : 1;
});
CHECK(ours == 1); // b
CHECK(notOurs == 2); // a and c
CHECK(model.applies == 1);
CHECK(model.Enabled(&g_a)); // theirs: still in
CHECK_FALSE(model.wroteOverAForeignPatch);
CHECK_FALSE(model.Enabled(&g_b));
CHECK_FALSE(model.Enabled(&g_c)); // stayed out
CHECK_FALSE(model.AMarkIsStanding());
CHECK_FALSE(model.touchedOutsideTheGate);
CHECK(model.gate == 0);
// Nothing of ours left: a second stop's walk marks nothing and applies nothing.
model.applies = 0;
fl::patch::RestoreAll(registry, engine, ModelOurs{&model}, [](const char*, void*, bool, bool) noexcept {});
CHECK(model.applies == 0);
}
+10
View File
@@ -156,6 +156,16 @@ add_library(fl_nvapi INTERFACE)
target_include_directories(fl_nvapi SYSTEM INTERFACE
"${CMAKE_CURRENT_SOURCE_DIR}/nvapi"
)
# THE HEADERS ALONE, for code that is loaded into a game (Advanced metrics train C, owner decision D136). The Overlay
# calls two of the driver's getters through an nvapi64.dll the GAME had already loaded (fl_reflex.h); it takes the
# vendored MIT headers' structs and ids and must never link nvapi64.lib, whose first call loads the DLL. So this is
# the include directory and nothing else. tools/hookinventory-check.ps1 Pass C reads the built Overlay's import table
# for an nvapi module, and tools/nvapi-readonly-check.ps1 holds which ids the Overlay may name.
add_library(fl_nvapi_headers INTERFACE)
target_include_directories(fl_nvapi_headers SYSTEM INTERFACE
"${CMAKE_CURRENT_SOURCE_DIR}/nvapi"
)
target_link_libraries(fl_nvapi INTERFACE
"${CMAKE_CURRENT_SOURCE_DIR}/nvapi/amd64/nvapi64.lib"
)
+1
View File
@@ -8,4 +8,5 @@ add_subdirectory(fl-probe-processstats)
add_subdirectory(fl-probe-signer)
add_subdirectory(fl-probe-vklayer)
add_subdirectory(vendor-stubs)
add_subdirectory(fl-probe-reflex)
add_subdirectory(hook-harness)
@@ -30,3 +30,5 @@ add_dependencies(fl-baseline-probe FrameLedger.Guard)
# process reports nothing, a planted module IS detected, and the answer flips
# back after unload rather than latching.
add_test(NAME fl_baseline_probe COMMAND fl-baseline-probe --self-test)
# The self-test's last line (the note above enable_testing() in the top-level file: a run cut short is not a pass).
fl_test_completes(fl_baseline_probe "\\[PASS\\] after unload the scan reports no capability loaded again")
+14 -1
View File
@@ -115,7 +115,16 @@ int main() {
FL_ADV_FIELD(samples);
FL_ADV_FIELD(request);
FL_ADV_FIELD(sampleQpc);
FL_ADV_FIELD(reservedHeader);
FL_ADV_FIELD(latState);
FL_ADV_FIELD(latReads);
FL_ADV_FIELD(latFrames);
FL_ADV_FIELD(latSimulationSumUs);
FL_ADV_FIELD(latSubmitSumUs);
FL_ADV_FIELD(latPresentSumUs);
FL_ADV_FIELD(latDriverSumUs);
FL_ADV_FIELD(latOsQueueSumUs);
FL_ADV_FIELD(latGpuSumUs);
FL_ADV_FIELD(latTotalSumUs);
FL_ADV_FIELD(dlssStructVersion);
FL_ADV_FIELD(dlssOptionsSeen);
FL_ADV_FIELD(dlssOutputWidth);
@@ -127,6 +136,10 @@ int main() {
FL_ADV_FIELD(dlssAutoExposure);
FL_ADV_FIELD(dlssAlphaUpscaling);
FL_ADV_FIELD(dlssPad);
FL_ADV_FIELD(latGpuActiveSumUs);
FL_ADV_FIELD(latGpuFrameSumUs);
FL_ADV_FIELD(latGpuCounts);
FL_ADV_FIELD(latMultipliersSeen);
FL_ADV_FIELD(reservedDlss);
FL_ADV_FIELD(ffxDispatches);
FL_ADV_FIELD(ffxSharpenSeen);
@@ -19,3 +19,5 @@ target_compile_definitions(fl-probe-guard PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX)
# is ACCESS_DENIED on a service, which the probe reports as NOT MEASURED
# rather than leaving to be assumed.
add_test(NAME fl_guard_apis COMMAND fl-probe-guard)
# Its last line when every probe passed (a run cut short is not a pass -- the top-level file, above enable_testing()).
fl_test_completes(fl_guard_apis "GUARD PROBE OK \\(")
@@ -15,3 +15,5 @@ target_link_libraries(fl-probe-hookprofile PRIVATE FrameLedger.Shm fl_native_fla
target_compile_definitions(fl-probe-hookprofile PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX)
add_test(NAME fl_hook_profile COMMAND fl-probe-hookprofile)
# Its last line when every probe passed (a run cut short is not a pass -- the top-level file, above enable_testing()).
fl_test_completes(fl_hook_profile "ALL PROBES PASSED \\(")
@@ -51,3 +51,6 @@ target_compile_definitions(fl-probe-interposer PRIVATE WIN32_LEAN_AND_MEAN NOMIN
# Run part 2 deliberately, like --probe-cost:
# fl-probe-interposer --interposer "D:\...\Cyberpunk 2077\bin\x64"
add_test(NAME fl_vtable_identity_control COMMAND fl-probe-interposer)
# Part 1's last line: printed only once the control passed, just before the probe returns (a run cut short is not a
# pass -- the top-level file, above enable_testing()).
fl_test_completes(fl_vtable_identity_control "control: [0-9]+/[0-9]+ checks passed")
@@ -40,6 +40,9 @@ add_test(NAME fl_nvapi_probe COMMAND fl-probe-nvapi)
# probe returns in ~0.01 s against ~1.4 s on the dev box — but inferable is not
# observed, and docs/18_GPU_VENDOR_APIS.md §L3 says so rather than claiming the
# stronger thing.
set_tests_properties(fl_nvapi_probe PROPERTIES
PASS_REGULAR_EXPRESSION "BRANCH: (AVAILABLE|DEGRADED)"
)
#
# THE BRANCH LINE AND, AFTER IT, THE PROBE'S LAST LINE (2026-11-13). The branch line alone passed a run that stopped
# right after printing it -- and, because a pass expression makes ctest ignore the exit code, a run that went on to
# print FAILED. "OK (available branch)" / "OK (degraded branch)" is what the probe ends on when nothing failed.
fl_test_completes(fl_nvapi_probe
"BRANCH: (AVAILABLE|DEGRADED)(.|\n)*OK \\((available|degraded) branch\\)")
@@ -0,0 +1,26 @@
# fl-probe-reflex -- the instrument of docs/spike-notes §31 (Reflex route D, owner decision D132). A tool, NOT
# SHIPPED, and it touches no game.
#
# BUILT WITH THE OVERLAY'S OWN FLAGS (fl_hostile_env_flags), as fl-probe-hookprofile is, AND FROM THE OVERLAY'S OWN
# HEADER: the call sequence is FrameLedger.Overlay/include/fl_reflex.h since the owner said go (D136), and this probe
# includes it. So its ctest runs what ships, with Control Flow Guard enforced -- which hook-harness, the target of
# the injected tests, does not enforce.
#
# THE NVAPI HEADERS, NOT THE NVAPI LIBRARY. The include directory of the vendored MIT headers is taken by itself;
# fl_nvapi -- which also links nvapi64.lib -- is deliberately not: the static library loads nvapi64.dll itself, from
# a trusted location, with a signature check, and route D's shape is that the process already has the module.
add_executable(fl-probe-reflex main.cpp)
target_link_libraries(fl-probe-reflex PRIVATE fl_native_flags fl_hostile_env_flags d3d11 d3d12 dxgi)
target_link_libraries(fl-probe-reflex PRIVATE fl_nvapi_headers)
target_include_directories(fl-probe-reflex PRIVATE "${CMAKE_SOURCE_DIR}/FrameLedger.Overlay/include")
target_compile_definitions(fl-probe-reflex PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX UNICODE _UNICODE)
add_dependencies(fl-probe-reflex fl_stub_nvapi64)
# The half a build machine can run: the candidate against the stand-in module -- absent, without its getters, a
# report of nothing, an error, sixty-four reports, both device kinds, a call that does not come back for a while.
# Software devices; exit 77 where there is no Direct3D 11 at all. `--real` (the installed driver, an NVIDIA adapter)
# is a measurement the note records, never a test.
add_test(NAME fl_reflex_probe_stub COMMAND fl-probe-reflex --stub "$<TARGET_FILE:fl_stub_nvapi64>")
set_tests_properties(fl_reflex_probe_stub PROPERTIES SKIP_RETURN_CODE 77)
# Its last line when nothing failed (a run cut short is not a pass -- the top-level file, above enable_testing()).
fl_test_completes(fl_reflex_probe_stub "STUB OK: 0 failure\\(s\\)")
@@ -0,0 +1,47 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
// What the probe adds to the call sequence it measures (docs/spike-notes §30, §31).
//
// THE SEQUENCE ITSELF MOVED. Until the owner said go (D136) the candidate lived here and nowhere that ships; it is now
// FrameLedger.Overlay/include/fl_reflex.h, the header the Overlay is built from, and this probe includes that one --
// so its ctest keeps running the shipped sequence, under the Overlay's flags and with Control Flow Guard enforced.
// What stays here is the probe's own way of printing a report, which the Overlay does not use: its reader is
// fl_adv_fields.h's, with the rules a game needs (the newest frames are not final, an impossible span is refused).
#ifndef FRAMELEDGER_FL_REFLEX_CANDIDATE_H
#define FRAMELEDGER_FL_REFLEX_CANDIDATE_H
#include <fl_reflex.h>
namespace fl::reflex {
// What a report holds, in numbers: how many of its sixty-four frames carry anything, and the newest one's id and
// two spans in the report's own unit -- simulation start to present end (the game's side) and to the end of GPU work.
struct Digest {
std::uint32_t valid = 0;
std::uint64_t newestFrameId = 0;
std::uint64_t newestSimToPresentEnd = 0;
std::uint64_t newestSimToGpuEnd = 0;
std::uint32_t newestGpuActiveUs = 0;
};
inline Digest Summarise(const NV_LATENCY_RESULT_PARAMS& report) noexcept {
Digest d{};
for (int i = 0; i < 64; ++i) {
const auto& r = report.frameReport[i];
if (r.frameID == 0u && r.simStartTime == 0u && r.gpuRenderEndTime == 0u) {
continue;
}
++d.valid;
d.newestFrameId = r.frameID;
d.newestSimToPresentEnd = r.presentEndTime >= r.simStartTime ? r.presentEndTime - r.simStartTime : 0u;
d.newestSimToGpuEnd = r.gpuRenderEndTime >= r.simStartTime ? r.gpuRenderEndTime - r.simStartTime : 0u;
d.newestGpuActiveUs = r.gpuActiveRenderTimeUs;
}
return d;
}
} // namespace fl::reflex
#endif // FRAMELEDGER_FL_REFLEX_CANDIDATE_H
+933
View File
@@ -0,0 +1,933 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
// fl-probe-reflex -- the instrument of docs/spike-notes §31 (Reflex route D, owner decision D132). NOT SHIPPED, and it
// touches no game: it runs the call sequence of fl_reflex_candidate.h in its own process, against two things.
//
// --stub <path> a stand-in nvapi64.dll (tools/vendor-stubs/stub_nvapi64.cpp): the module absent, a getter absent,
// a report of nothing, an error, sixty-four reports, both device kinds, and a call that does not come
// back for seconds. ctest fl_reflex_probe_stub. Software devices are enough: the stub does not look.
// --real the installed driver, on this PC's NVIDIA adapter, with the probe playing the game's part: it
// loads nvapi64.dll itself, initialises it, and SETS LATENCY MARKERS ON ITS OWN DEVICE for a few
// hundred frames -- a write, made here because a getter has nothing to return without it, in a
// process that is nobody's game. Then it measures what route D would do: the two getters. A
// measurement, not a test: exit 77 where there is no NVIDIA adapter.
//
// Built with the Overlay's own flags, because the candidate is the Overlay's code-to-be.
#include <windows.h>
#include <d3d11.h>
#include <d3d12.h>
#include <dxgi1_4.h>
#include <atomic>
#include <cstdint>
#include <cstdio>
#include <cstring>
#include "fl_reflex_candidate.h"
namespace {
int g_failures = 0;
void Check(bool ok, const char* what) noexcept {
std::printf("%s %s\n", ok ? "PASS" : "FAIL", what);
if (!ok) {
++g_failures;
}
}
template <class T>
void ReleaseIf(T*& p) noexcept {
if (p != nullptr) {
p->Release();
p = nullptr;
}
}
double QpcSeconds() noexcept {
// QuadPart named in the initialiser, so the member read back is the one the union holds (cpp:S6232).
LARGE_INTEGER f{.QuadPart = 0};
LARGE_INTEGER c{.QuadPart = 0};
QueryPerformanceFrequency(&f);
QueryPerformanceCounter(&c);
return static_cast<double>(c.QuadPart) / static_cast<double>(f.QuadPart);
}
// ---------------------------------------------------------------------------------------------------------------------
// Devices. `nvidia` picks this PC's NVIDIA adapter (vendor 0x10DE) or fails; otherwise the software adapter.
// ---------------------------------------------------------------------------------------------------------------------
IDXGIAdapter1* FindAdapter(IDXGIFactory4* factory, bool nvidia) noexcept {
if (!nvidia) {
IDXGIAdapter1* warp = nullptr;
factory->EnumWarpAdapter(__uuidof(IDXGIAdapter1), reinterpret_cast<void**>(&warp));
return warp;
}
for (UINT i = 0;; ++i) {
IDXGIAdapter1* adapter = nullptr;
if (factory->EnumAdapters1(i, &adapter) != S_OK) {
return nullptr;
}
DXGI_ADAPTER_DESC1 desc{};
if (SUCCEEDED(adapter->GetDesc1(&desc)) && desc.VendorId == 0x10DEu &&
(desc.Flags & DXGI_ADAPTER_FLAG_SOFTWARE) == 0u) {
return adapter;
}
adapter->Release();
}
}
struct Dx11 {
ID3D11Device* device = nullptr;
ID3D11DeviceContext* context = nullptr;
IDXGISwapChain1* chain = nullptr;
ID3D11RenderTargetView* target = nullptr;
};
bool MakeDx11(IDXGIFactory4* factory, IDXGIAdapter1* adapter, Dx11& out) noexcept {
if (FAILED(D3D11CreateDevice(adapter, D3D_DRIVER_TYPE_UNKNOWN, nullptr, D3D11_CREATE_DEVICE_BGRA_SUPPORT, nullptr,
0, D3D11_SDK_VERSION, &out.device, nullptr, &out.context))) {
return false;
}
DXGI_SWAP_CHAIN_DESC1 desc{};
desc.Width = 256;
desc.Height = 256;
desc.Format = DXGI_FORMAT_B8G8R8A8_UNORM;
desc.SampleDesc.Count = 1;
desc.BufferUsage = DXGI_USAGE_RENDER_TARGET_OUTPUT;
desc.BufferCount = 2;
desc.SwapEffect = DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL;
desc.AlphaMode = DXGI_ALPHA_MODE_PREMULTIPLIED;
if (FAILED(factory->CreateSwapChainForComposition(out.device, &desc, nullptr, &out.chain))) {
return false;
}
ID3D11Texture2D* back = nullptr;
if (FAILED(out.chain->GetBuffer(0, __uuidof(ID3D11Texture2D), reinterpret_cast<void**>(&back)))) {
return false;
}
const HRESULT hr = out.device->CreateRenderTargetView(back, nullptr, &out.target);
back->Release();
return SUCCEEDED(hr);
}
void FreeDx11(Dx11& d) noexcept {
ReleaseIf(d.target);
ReleaseIf(d.chain);
ReleaseIf(d.context);
ReleaseIf(d.device);
}
struct Dx12 {
ID3D12Device* device = nullptr;
ID3D12CommandQueue* queue = nullptr;
IDXGISwapChain1* chain = nullptr;
};
bool MakeDx12(IDXGIFactory4* factory, IDXGIAdapter1* adapter, Dx12& out) noexcept {
if (FAILED(D3D12CreateDevice(adapter, D3D_FEATURE_LEVEL_11_0, __uuidof(ID3D12Device),
reinterpret_cast<void**>(&out.device)))) {
return false;
}
D3D12_COMMAND_QUEUE_DESC q{};
q.Type = D3D12_COMMAND_LIST_TYPE_DIRECT;
if (FAILED(
out.device->CreateCommandQueue(&q, __uuidof(ID3D12CommandQueue), reinterpret_cast<void**>(&out.queue)))) {
return false;
}
DXGI_SWAP_CHAIN_DESC1 desc{};
desc.Width = 256;
desc.Height = 256;
desc.Format = DXGI_FORMAT_B8G8R8A8_UNORM;
desc.SampleDesc.Count = 1;
desc.BufferUsage = DXGI_USAGE_RENDER_TARGET_OUTPUT;
desc.BufferCount = 2;
desc.SwapEffect = DXGI_SWAP_EFFECT_FLIP_SEQUENTIAL;
desc.AlphaMode = DXGI_ALPHA_MODE_PREMULTIPLIED;
return SUCCEEDED(factory->CreateSwapChainForComposition(out.queue, &desc, nullptr, &out.chain));
}
void FreeDx12(Dx12& d) noexcept {
ReleaseIf(d.chain);
ReleaseIf(d.queue);
ReleaseIf(d.device);
}
// ---------------------------------------------------------------------------------------------------------------------
// --stub
// ---------------------------------------------------------------------------------------------------------------------
using SetU32Fn = void(__cdecl*)(std::uint32_t);
using GetU32Fn = std::uint32_t(__cdecl*)();
using GetPtrFn = void*(__cdecl*)();
struct BlockedCall {
fl::reflex::Api api;
IUnknown* device;
NvAPI_Status status;
};
DWORD WINAPI BlockedCallThread(LPVOID p) noexcept {
auto* call = static_cast<BlockedCall*>(p);
static NV_LATENCY_RESULT_PARAMS report; // 15 KB: not on a new thread's stack for no reason
call->status = fl::reflex::ReadLatency(call->api, call->device, report);
return 0;
}
// A stand-in for the Overlay's watchdog: a loop that ticks every 50 ms and, when told, makes the call ITSELF.
struct Ticker {
std::atomic<std::uint32_t> ticks{0};
std::atomic<std::uint32_t> callNow{0};
std::atomic<std::uint32_t> quit{0};
fl::reflex::Api api;
IUnknown* device = nullptr;
};
DWORD WINAPI TickerThread(LPVOID p) noexcept {
auto* t = static_cast<Ticker*>(p);
static NV_LATENCY_RESULT_PARAMS report;
while (t->quit.load(std::memory_order_acquire) == 0u) {
if (t->callNow.exchange(0u, std::memory_order_acq_rel) != 0u) {
fl::reflex::ReadLatency(t->api, t->device, report);
}
t->ticks.fetch_add(1u, std::memory_order_relaxed);
Sleep(50);
}
return 0;
}
int RunStub(const wchar_t* stubPath) noexcept {
using fl::reflex::Resolved;
fl::reflex::Api api{};
// 1. The module is not in the process: nothing is called, and nothing gets loaded by asking.
Check(GetModuleHandleW(L"nvapi64.dll") == nullptr, "before: no nvapi64.dll in this process");
Check(fl::reflex::Resolve(api) == Resolved::NoModule, "module absent -> NoModule");
Check(GetModuleHandleW(L"nvapi64.dll") == nullptr, "resolving loaded nothing");
Check(api.getLatency == nullptr && api.getSleepStatus == nullptr, "no address was kept");
HMODULE stub = LoadLibraryExW(stubPath, nullptr, LOAD_WITH_ALTERED_SEARCH_PATH);
if (stub == nullptr) {
std::printf("FAIL the stub did not load (%lu)\n", GetLastError());
return 1;
}
const auto setMode = reinterpret_cast<SetU32Fn>(GetProcAddress(stub, "FlStubNvSetMode"));
const auto setBlock = reinterpret_cast<SetU32Fn>(GetProcAddress(stub, "FlStubNvSetBlockMs"));
const auto hide = reinterpret_cast<SetU32Fn>(GetProcAddress(stub, "FlStubNvHideGetters"));
const auto latencyCalls = reinterpret_cast<GetU32Fn>(GetProcAddress(stub, "FlStubNvLatencyCalls"));
const auto lastDevice = reinterpret_cast<GetPtrFn>(GetProcAddress(stub, "FlStubNvLastDevice"));
if (setMode == nullptr || setBlock == nullptr || hide == nullptr || latencyCalls == nullptr ||
lastDevice == nullptr) {
std::printf("FAIL the module at that path is not the stub\n");
return 1;
}
// 2. A module that does not have the getters.
hide(1u);
Check(fl::reflex::Resolve(api) == Resolved::NoGetter, "a getter the module does not have -> NoGetter");
Check(api.getLatency == nullptr, "and nothing half-resolved is kept");
hide(0u);
Check(fl::reflex::Resolve(api) == Resolved::Ok, "both getters resolved by interface id");
IDXGIFactory4* factory = nullptr;
if (FAILED(CreateDXGIFactory1(__uuidof(IDXGIFactory4), reinterpret_cast<void**>(&factory)))) {
std::printf("SKIP no DXGI factory\n");
return 77;
}
IDXGIAdapter1* adapter = FindAdapter(factory, false);
Dx11 dx11{};
Dx12 dx12{};
const bool have11 = MakeDx11(factory, adapter, dx11);
const bool have12 = MakeDx12(factory, adapter, dx12);
if (!have11) {
std::printf("SKIP no Direct3D 11 device here\n");
return 77;
}
static NV_LATENCY_RESULT_PARAMS report;
NV_GET_SLEEP_STATUS_PARAMS sleep{};
// 3. Sixty-four reports, read as the header lays them out, with the device handed through untouched.
setMode(0u);
Check(fl::reflex::ReadLatency(api, dx11.device, report) == NVAPI_OK, "D3D11: the report is read");
fl::reflex::Digest d = fl::reflex::Summarise(report);
Check(d.valid == 64u && d.newestFrameId == 5063u, "sixty-four frames, the newest last");
Check(d.newestSimToPresentEnd == 2200u && d.newestSimToGpuEnd == 7500u && d.newestGpuActiveUs == 3500u,
"the spans are the ones the stub wrote");
Check(lastDevice() == dx11.device, "the driver was handed the device, and only the device");
if (have12) {
Check(fl::reflex::ReadLatency(api, dx12.device, report) == NVAPI_OK && lastDevice() == dx12.device,
"D3D12: the same call with the ID3D12Device the Overlay already holds");
} else {
std::printf("NOTE no Direct3D 12 device here; that half is not run\n");
}
Check(fl::reflex::ReadSleepStatus(api, dx11.device, sleep) == NVAPI_OK && sleep.bLowLatencyMode != 0 &&
sleep.sleepIntervalUs == 4166u && sleep.fgMultiplier == 2,
"the sleep status is read");
// 4. A game that set no marker (nvapi.h: every frame comes back zero), and a driver that says no.
setMode(1u);
Check(fl::reflex::ReadLatency(api, dx11.device, report) == NVAPI_OK && fl::reflex::Summarise(report).valid == 0u,
"a report of nothing is zero frames, not sixty-four");
setMode(2u);
Check(fl::reflex::ReadLatency(api, dx11.device, report) == NVAPI_ERROR, "an error is returned as the error");
Check(fl::reflex::ReadSleepStatus(api, dx11.device, sleep) == NVAPI_ERROR, "for the sleep status as well");
Check(fl::reflex::ReadLatency(api, nullptr, report) == NVAPI_INVALID_ARGUMENT &&
latencyCalls() == (have12 ? 4u : 3u),
"no device, no call: the driver was not entered");
setMode(0u);
// 5. A call that does not come back for a while. On a thread of its own, nothing else waits for it...
setBlock(1500u);
Ticker ticker{};
ticker.api = api;
ticker.device = dx11.device;
HANDLE tick = CreateThread(nullptr, 0, &TickerThread, &ticker, 0, nullptr);
Sleep(300);
BlockedCall blocked{api, dx11.device, NVAPI_ERROR};
const std::uint32_t before = ticker.ticks.load();
const double began = QpcSeconds();
HANDLE caller = CreateThread(nullptr, 0, &BlockedCallThread, &blocked, 0, nullptr);
Sleep(1000);
const std::uint32_t during = ticker.ticks.load() - before;
Check(during >= 10u, "a call blocked on its own thread: the ticking thread went on (>= 10 ticks in the second)");
WaitForSingleObject(caller, 5000);
const double took = QpcSeconds() - began;
Check(blocked.status == NVAPI_OK && took >= 1.4, "and the blocked call came back with its report");
std::printf("NOTE the blocked call took %.2f s; the other thread ticked %u times in its first second\n", took,
during);
CloseHandle(caller);
// ...and made BY the ticking thread, that thread stands still for as long as the driver keeps it.
const std::uint32_t before2 = ticker.ticks.load();
ticker.callNow.store(1u);
Sleep(1000);
const std::uint32_t during2 = ticker.ticks.load() - before2;
Check(during2 <= 3u, "the same call made by the ticking thread: it stopped ticking while the driver held it");
std::printf("NOTE made by the ticking thread itself, it ticked %u times in that second\n", during2);
Sleep(1000);
ticker.quit.store(1u);
WaitForSingleObject(tick, 3000);
CloseHandle(tick);
setBlock(0u);
FreeDx12(dx12);
FreeDx11(dx11);
ReleaseIf(adapter);
ReleaseIf(factory);
std::printf("%s: %d failure(s)\n", g_failures == 0 ? "STUB OK" : "STUB FAILED", g_failures);
return g_failures == 0 ? 0 : 1;
}
// ---------------------------------------------------------------------------------------------------------------------
// --real: the installed driver. The probe is the "game" here: it loads NVAPI, initialises it and sets markers.
// ---------------------------------------------------------------------------------------------------------------------
constexpr unsigned int kIdInitialize = 0x0150e828u; // nvapi_interface.h: NvAPI_Initialize
constexpr unsigned int kIdUnload = 0xd22bdd7eu; // NvAPI_Unload
constexpr unsigned int kIdSetLatencyMarker = 0xd9984c05u; // NvAPI_D3D_SetLatencyMarker -- the game's call
using PlainFn = NvAPI_Status(__cdecl*)();
using SetMarkerFn = NvAPI_Status(__cdecl*)(IUnknown*, NV_LATENCY_MARKER_PARAMS*);
struct Game {
SetMarkerFn setMarker = nullptr;
IUnknown* markerDevice = nullptr;
std::uint64_t frame = 0;
std::uint32_t markerErrors = 0;
NvAPI_Status lastMarkerStatus = NVAPI_OK;
};
void Mark(Game& g, NV_LATENCY_MARKER_TYPE type) noexcept {
NV_LATENCY_MARKER_PARAMS p{};
p.version = NV_LATENCY_MARKER_PARAMS_VER1;
p.frameID = g.frame;
p.markerType = type;
const NvAPI_Status s = g.setMarker(g.markerDevice, &p);
if (s != NVAPI_OK) {
++g.markerErrors;
g.lastMarkerStatus = s;
}
}
void Frame11(Game& g, Dx11& dx, bool markers) noexcept {
++g.frame;
if (markers) {
Mark(g, SIMULATION_START);
Mark(g, SIMULATION_END);
Mark(g, RENDERSUBMIT_START);
}
const float colour[4] = {static_cast<float>(g.frame % 255u) / 255.0f, 0.2f, 0.4f, 1.0f};
dx.context->OMSetRenderTargets(1, &dx.target, nullptr);
dx.context->ClearRenderTargetView(dx.target, colour);
if (markers) {
Mark(g, RENDERSUBMIT_END);
Mark(g, PRESENT_START);
}
dx.chain->Present(0, 0);
if (markers) {
Mark(g, PRESENT_END);
}
}
void Frame12(Game& g, Dx12& dx) noexcept {
++g.frame;
Mark(g, SIMULATION_START);
Mark(g, SIMULATION_END);
Mark(g, RENDERSUBMIT_START);
Mark(g, RENDERSUBMIT_END);
Mark(g, PRESENT_START);
dx.chain->Present(0, 0);
Mark(g, PRESENT_END);
}
void PrintDigest(const char* label, NvAPI_Status status, const NV_LATENCY_RESULT_PARAMS& report) noexcept {
const fl::reflex::Digest d = fl::reflex::Summarise(report);
std::printf("%-46s status %d, frames with anything %u, newest id %llu, sim->presentEnd %llu, sim->gpuEnd %llu, "
"gpuActive %u us\n",
label, static_cast<int>(status), d.valid, static_cast<unsigned long long>(d.newestFrameId),
static_cast<unsigned long long>(d.newestSimToPresentEnd),
static_cast<unsigned long long>(d.newestSimToGpuEnd), d.newestGpuActiveUs);
}
struct Poller {
fl::reflex::Api api;
IUnknown* device = nullptr;
std::atomic<std::uint32_t> quit{0};
std::atomic<std::uint32_t> paused{0};
std::atomic<std::uint32_t> intervalMs{250}; // 0: one read after another, as fast as the driver answers
std::uint32_t calls = 0;
std::uint32_t notOk = 0;
std::uint32_t faults = 0;
double worstSeconds = 0.0;
std::uint32_t emptyReports = 0;
std::uint32_t atLeast1Ms = 0; // reads that took a millisecond or more, and two (R6)
std::uint32_t atLeast2Ms = 0;
};
DWORD WINAPI PollerThread(LPVOID p) noexcept {
auto* poll = static_cast<Poller*>(p);
static NV_LATENCY_RESULT_PARAMS report;
NV_GET_SLEEP_STATUS_PARAMS sleep{};
while (poll->quit.load(std::memory_order_acquire) == 0u) {
if (poll->paused.load(std::memory_order_acquire) != 0u) {
Sleep(50);
continue;
}
const double t0 = QpcSeconds();
const NvAPI_Status a = fl::reflex::ReadLatency(poll->api, poll->device, report);
const NvAPI_Status b = fl::reflex::ReadSleepStatus(poll->api, poll->device, sleep);
const double took = QpcSeconds() - t0;
++poll->calls;
poll->notOk += (a != NVAPI_OK || b != NVAPI_OK) ? 1u : 0u;
poll->faults += (a == fl::reflex::kFaulted || b == fl::reflex::kFaulted) ? 1u : 0u;
poll->emptyReports += (a == NVAPI_OK && fl::reflex::Summarise(report).valid == 0u) ? 1u : 0u;
if (took > poll->worstSeconds) {
poll->worstSeconds = took;
}
poll->atLeast1Ms += took >= 0.001 ? 1u : 0u;
poll->atLeast2Ms += took >= 0.002 ? 1u : 0u;
const std::uint32_t interval = poll->intervalMs.load(std::memory_order_relaxed);
if (interval != 0u) {
Sleep(interval);
}
}
return 0;
}
// Microseconds a call, over `n` calls: the mean, the median and the worst.
struct Cost {
double mean = 0.0;
double median = 0.0;
double worst = 0.0;
};
template <class Call>
Cost Measure(int n, const Call& call) noexcept {
static double samples[4096];
if (n <= 0) {
return Cost{};
}
if (n > 4096) {
n = 4096;
}
double sum = 0.0;
for (int i = 0; i < n; ++i) {
const double t0 = QpcSeconds();
call();
samples[i] = (QpcSeconds() - t0) * 1e6;
sum += samples[i];
}
for (int i = 1; i < n; ++i) { // insertion sort: a few thousand doubles, once
const double v = samples[i];
int j = i - 1;
while (j >= 0 && samples[j] > v) {
samples[j + 1] = samples[j];
--j;
}
samples[j + 1] = v;
}
return Cost{sum / n, samples[n / 2], samples[n - 1]};
}
double FramesPerSecond11(Game& g, Dx11& dx, double seconds) noexcept {
const double t0 = QpcSeconds();
std::uint32_t frames = 0;
while (QpcSeconds() - t0 < seconds) {
Frame11(g, dx, true);
++frames;
}
return static_cast<double>(frames) / (QpcSeconds() - t0);
}
// ---------------------------------------------------------------------------------------------------------------------
// R6 (owner decision D139; spike-notes §31, "The leg with a sleep"): THE GETTERS WHILE THE GAME SLEEPS.
// No run above set a sleep mode or called NvAPI_D3D_Sleep, and a game that uses Reflex does both every frame. If the
// driver makes a getter wait behind the game's sleep, a read on the presenting thread holds a present for as long as
// the sleep lasts. The probe is the game once more: BOTH CALLS BELOW ARE WRITES, made on the probe's own device in its
// own process; no shipped binary contains either, and the mode is switched back off before the device goes.
// ---------------------------------------------------------------------------------------------------------------------
constexpr unsigned int kIdSetSleepMode = 0xac1ca9e0u; // nvapi_interface.h: NvAPI_D3D_SetSleepMode -- the game's call
constexpr unsigned int kIdSleep = 0x852cd1d2u; // NvAPI_D3D_Sleep -- the game's call
constexpr unsigned int kSleepIntervalUs = 4166u; // a 240-a-second limit: every frame really sleeps
using SetSleepModeFn = NvAPI_Status(__cdecl*)(IUnknown*, NV_SET_SLEEP_MODE_PARAMS*);
using SleepFn = NvAPI_Status(__cdecl*)(IUnknown*);
struct Sleeper {
SleepFn sleep = nullptr;
IUnknown* device = nullptr;
bool on = false;
std::uint32_t errors = 0;
std::uint32_t calls = 0;
double seconds = 0.0; // spent inside NvAPI_D3D_Sleep
};
// One frame of a game that uses Reflex: the sleep first, then the markers and the present.
void SleepingFrame12(Game& g, Dx12& dx, Sleeper& s) noexcept {
if (s.on) {
const double t0 = QpcSeconds();
if (s.sleep(s.device) != NVAPI_OK) {
++s.errors;
}
s.seconds += QpcSeconds() - t0;
++s.calls;
}
Frame12(g, dx);
}
struct Beside {
std::uint32_t calls = 0;
std::uint32_t notOk = 0;
std::uint32_t faults = 0;
std::uint32_t atLeast1Ms = 0;
std::uint32_t atLeast2Ms = 0;
double worstUs = 0.0;
double framesPerSecond = 0.0;
};
// The getters on another thread every `intervalMs` (0: without a pause) for `seconds`, while this thread is the game.
Beside PollBeside(const fl::reflex::Api& api, Game& g, Dx12& dx, Sleeper& s, std::uint32_t intervalMs,
double seconds) noexcept {
Poller poll{};
poll.api = api;
poll.device = dx.device;
poll.intervalMs.store(intervalMs);
HANDLE thread = CreateThread(nullptr, 0, &PollerThread, &poll, 0, nullptr);
const double t0 = QpcSeconds();
std::uint32_t frames = 0;
while (QpcSeconds() - t0 < seconds) {
SleepingFrame12(g, dx, s);
++frames;
}
const double took = QpcSeconds() - t0;
poll.quit.store(1u);
if (thread != nullptr) {
WaitForSingleObject(thread, 5000);
CloseHandle(thread);
}
Beside out{};
out.calls = poll.calls;
out.notOk = poll.notOk;
out.faults = poll.faults;
out.atLeast1Ms = poll.atLeast1Ms;
out.atLeast2Ms = poll.atLeast2Ms;
out.worstUs = poll.worstSeconds * 1e6;
out.framesPerSecond = static_cast<double>(frames) / took;
return out;
}
void PrintBeside(const char* label, const Beside& b) noexcept {
std::printf(
"%-52s %u reads, %u not OK, %u faulted, worst %.1f us, >= 1 ms: %u, >= 2 ms: %u; %.0f frames a second\n", label,
b.calls, b.notOk, b.faults, b.worstUs, b.atLeast1Ms, b.atLeast2Ms, b.framesPerSecond);
}
void RunSleepLeg(IDXGIFactory4* factory, IDXGIAdapter1* adapter, const fl::reflex::Api& api,
fl::reflex::QueryInterfaceFn query, SetMarkerFn setMarker) noexcept {
const auto setMode = reinterpret_cast<SetSleepModeFn>(query(kIdSetSleepMode));
Sleeper sleeper{};
sleeper.sleep = reinterpret_cast<SleepFn>(query(kIdSleep));
Dx12 dx{};
if (setMode == nullptr || sleeper.sleep == nullptr || !MakeDx12(factory, adapter, dx)) {
std::printf("R6 SKIPPED: no sleep functions from this nvapi64.dll, or no Direct3D 12 device\n");
FreeDx12(dx);
return;
}
sleeper.device = dx.device;
Game game{};
game.setMarker = setMarker;
game.markerDevice = dx.device;
game.frame = 300000;
static NV_LATENCY_RESULT_PARAMS report;
NV_GET_SLEEP_STATUS_PARAMS status{};
// THE CONTROL: the same device, the same two pollers, before any sleep mode.
for (int i = 0; i < 300; ++i) {
SleepingFrame12(game, dx, sleeper);
}
const Beside controlSlow = PollBeside(api, game, dx, sleeper, 250u, 20.0);
const Beside controlFast = PollBeside(api, game, dx, sleeper, 0u, 10.0);
PrintBeside("R6 control, no sleep mode, 4 reads a second:", controlSlow);
PrintBeside("R6 control, no sleep mode, reads without a pause:", controlFast);
// S1. THE GAME SETS A SLEEP MODE AND SLEEPS EVERY FRAME.
NV_SET_SLEEP_MODE_PARAMS mode{};
mode.version = NV_SET_SLEEP_MODE_PARAMS_VER1;
mode.bLowLatencyMode = 1;
mode.minimumIntervalUs = kSleepIntervalUs;
mode.bUseMarkersToOptimize = 1;
const NvAPI_Status set = setMode(dx.device, &mode);
sleeper.on = set == NVAPI_OK;
const double began = QpcSeconds();
for (int i = 0; i < 600; ++i) {
SleepingFrame12(game, dx, sleeper);
}
const double frameUs = (QpcSeconds() - began) / 600.0 * 1e6;
const NvAPI_Status s1 = fl::reflex::ReadSleepStatus(api, dx.device, status);
std::printf("S1 SetSleepMode %d; 600 frames: %.1f us a frame, %.1f us of it inside Sleep, %u sleep error(s)\n",
static_cast<int>(set), frameUs,
sleeper.calls != 0u ? sleeper.seconds / static_cast<double>(sleeper.calls) * 1e6 : 0.0, sleeper.errors);
std::printf("S1 sleep status %d: lowLatency %u, fsVrr %u, cplVsync %u, interval %u us, gameSleep %u, iFlip %u, "
"fgMultiplier %u\n",
static_cast<int>(s1), static_cast<unsigned>(status.bLowLatencyMode),
static_cast<unsigned>(status.bFsVrr), static_cast<unsigned>(status.bCplVsyncOn),
static_cast<unsigned>(status.sleepIntervalUs), static_cast<unsigned>(status.bUseGameSleep),
static_cast<unsigned>(status.bFullscreenIFlip), static_cast<unsigned>(status.fgMultiplier));
// S4. What the report holds once the game sleeps.
PrintDigest("S4 D3D12, sleeping, 600 frames:", fl::reflex::ReadLatency(api, dx.device, report), report);
{
std::uint32_t input = 0;
std::uint32_t driverStart = 0;
std::uint32_t gpuEnd = 0;
for (const auto& r : report.frameReport) {
input += r.inputSampleTime != 0u ? 1u : 0u;
driverStart += r.driverStartTime != 0u ? 1u : 0u;
gpuEnd += r.gpuRenderEndTime != 0u ? 1u : 0u;
}
std::printf("S4 of 64 frames: inputSampleTime in %u, driverStartTime in %u, gpuRenderEndTime in %u\n", input,
driverStart, gpuEnd);
}
// S2. THE GETTERS ON THE THREAD THAT SLEEPS AND PRESENTS: one read after each frame's present -- where the Overlay
// would make it -- and then back to back.
{
static double samples[2000];
double sum = 0.0;
double worst = 0.0;
std::uint32_t slow = 0;
for (double& sample : samples) {
SleepingFrame12(game, dx, sleeper);
const double t0 = QpcSeconds();
fl::reflex::ReadLatency(api, dx.device, report);
sample = (QpcSeconds() - t0) * 1e6;
sum += sample;
worst = sample > worst ? sample : worst;
slow += sample >= 2000.0 ? 1u : 0u;
}
for (int i = 1; i < 2000; ++i) { // insertion sort, as Measure does
const double v = samples[i];
int j = i - 1;
while (j >= 0 && samples[j] > v) {
samples[j + 1] = samples[j];
--j;
}
samples[j + 1] = v;
}
std::printf("S2 GetLatency after each of 2000 sleeping frames, us: mean %.2f, median %.2f, worst %.2f, "
">= 2 ms: %u\n",
sum / 2000.0, samples[1000], worst, slow);
}
const Cost latency = Measure(2000, [&]() noexcept { fl::reflex::ReadLatency(api, dx.device, report); });
const Cost sleepStatus = Measure(2000, [&]() noexcept { fl::reflex::ReadSleepStatus(api, dx.device, status); });
std::printf("S2 GetLatency back to back, us: mean %.2f, median %.2f, worst %.2f (2000 calls)\n", latency.mean,
latency.median, latency.worst);
std::printf("S2 GetSleepStatus back to back, us: mean %.2f, median %.2f, worst %.2f (2000 calls)\n",
sleepStatus.mean, sleepStatus.median, sleepStatus.worst);
// S3. THE GETTERS ON ANOTHER THREAD WHILE THIS ONE SLEEPS AND PRESENTS -- a game's sleep is often on a thread that
// is not the one that presents.
const Beside sleepSlow = PollBeside(api, game, dx, sleeper, 250u, 20.0);
const Beside sleepFast = PollBeside(api, game, dx, sleeper, 0u, 10.0);
PrintBeside("S3 sleeping, 4 reads a second:", sleepSlow);
PrintBeside("S3 sleeping, reads without a pause:", sleepFast);
std::printf("S3 marker errors %u (last status %d), sleep errors %u\n", game.markerErrors,
static_cast<int>(game.lastMarkerStatus), sleeper.errors);
// The mode goes back off before the device does.
NV_SET_SLEEP_MODE_PARAMS off{};
off.version = NV_SET_SLEEP_MODE_PARAMS_VER1;
std::printf("R6 SetSleepMode back off: %d\n", static_cast<int>(setMode(dx.device, &off)));
FreeDx12(dx);
}
int RunReal(int pollSeconds) noexcept {
IDXGIFactory4* factory = nullptr;
if (FAILED(CreateDXGIFactory1(__uuidof(IDXGIFactory4), reinterpret_cast<void**>(&factory)))) {
std::printf("SKIP no DXGI factory\n");
return 77;
}
IDXGIAdapter1* adapter = FindAdapter(factory, true);
if (adapter == nullptr) {
std::printf("SKIP no NVIDIA adapter on this PC\n");
return 77;
}
DXGI_ADAPTER_DESC1 desc{};
adapter->GetDesc1(&desc);
std::printf("adapter: %ls\n", desc.Description);
// THE GAME'S PART: nvapi64.dll from the system directory, by full path, and NvAPI_Initialize.
wchar_t path[MAX_PATH]{};
const UINT n = GetSystemDirectoryW(path, MAX_PATH);
if (n == 0 || n + 16 > MAX_PATH) {
return 77;
}
wcscat_s(path, L"\\nvapi64.dll");
fl::reflex::Api api{};
std::printf("before the game loaded it: Resolve = %u (1 = NoModule)\n",
static_cast<unsigned>(fl::reflex::Resolve(api)));
HMODULE nvapi = LoadLibraryExW(path, nullptr, LOAD_WITH_ALTERED_SEARCH_PATH);
if (nvapi == nullptr) {
std::printf("SKIP %ls did not load (%lu)\n", path, GetLastError());
return 77;
}
const auto query = reinterpret_cast<fl::reflex::QueryInterfaceFn>(GetProcAddress(nvapi, "nvapi_QueryInterface"));
const auto initialize = query != nullptr ? reinterpret_cast<PlainFn>(query(kIdInitialize)) : nullptr;
const auto unload = query != nullptr ? reinterpret_cast<PlainFn>(query(kIdUnload)) : nullptr;
Game game{};
game.setMarker = query != nullptr ? reinterpret_cast<SetMarkerFn>(query(kIdSetLatencyMarker)) : nullptr;
if (initialize == nullptr || game.setMarker == nullptr) {
std::printf("SKIP this nvapi64.dll does not answer the ids\n");
return 77;
}
Dx11 dx11{};
if (!MakeDx11(factory, adapter, dx11)) {
std::printf("SKIP no Direct3D 11 device on the NVIDIA adapter\n");
return 77;
}
static NV_LATENCY_RESULT_PARAMS report;
NV_GET_SLEEP_STATUS_PARAMS sleep{};
// WHERE THE TWO ADDRESSES ARE. The module answers with addresses that need not be its own: the image each one
// lies in is printed, because the Overlay refuses an address that is in no image at all (fl_reflex.h, InImage).
const unsigned int getterIds[2] = {fl::reflex::kIdGetLatency, fl::reflex::kIdGetSleepStatus};
for (const unsigned int id : getterIds) {
const void* address = query(id);
MEMORY_BASIC_INFORMATION info{};
wchar_t owner[MAX_PATH]{};
if (address != nullptr && VirtualQuery(address, &info, sizeof(info)) != 0) {
GetModuleFileNameW(static_cast<HMODULE>(info.AllocationBase), owner, MAX_PATH);
}
std::printf("id 0x%08x -> %p: type 0x%lx, protect 0x%lx, in %ls%s\n", id, address,
static_cast<unsigned long>(info.Type), static_cast<unsigned long>(info.Protect),
owner[0] != 0 ? owner : L"(no image)",
info.AllocationBase == static_cast<void*>(nvapi) ? " (nvapi64.dll itself)" : "");
}
// R0. THE GETTERS BEFORE NvAPI_Initialize -- a game that has the module but has not initialised it.
std::printf("Resolve with the module loaded: %u (0 = Ok)\n", static_cast<unsigned>(fl::reflex::Resolve(api)));
PrintDigest("R0 before NvAPI_Initialize:", fl::reflex::ReadLatency(api, dx11.device, report), report);
std::printf("NvAPI_Initialize: %d\n", static_cast<int>(initialize()));
// R1. Initialised, no marker ever set: what a game that does not use Reflex gives.
for (int i = 0; i < 120; ++i) {
Frame11(game, dx11, false);
}
PrintDigest("R1 D3D11, 120 frames, no marker:", fl::reflex::ReadLatency(api, dx11.device, report), report);
const NvAPI_Status s1 = fl::reflex::ReadSleepStatus(api, dx11.device, sleep);
std::printf(" sleep status %d: lowLatency %u, fsVrr %u, cplVsync %u, interval %u us, gameSleep %u, iFlip %u, "
"fgMultiplier %u\n",
static_cast<int>(s1), static_cast<unsigned>(sleep.bLowLatencyMode), static_cast<unsigned>(sleep.bFsVrr),
static_cast<unsigned>(sleep.bCplVsyncOn), static_cast<unsigned>(sleep.sleepIntervalUs),
static_cast<unsigned>(sleep.bUseGameSleep), static_cast<unsigned>(sleep.bFullscreenIFlip),
static_cast<unsigned>(sleep.fgMultiplier));
// R2. The game sets markers: 300 frames.
game.markerDevice = dx11.device;
const double began = QpcSeconds();
for (int i = 0; i < 300; ++i) {
Frame11(game, dx11, true);
}
const double frameSeconds = (QpcSeconds() - began) / 300.0;
std::printf("markers: %u error(s), last status %d; a frame took %.1f us by this probe's clock\n", game.markerErrors,
static_cast<int>(game.lastMarkerStatus), frameSeconds * 1e6);
PrintDigest("R2 D3D11, 300 frames with markers:", fl::reflex::ReadLatency(api, dx11.device, report), report);
{
// The unit of the report's times: the gap between two neighbouring frames' simStartTime against the probe's
// own measured frame time.
const auto& a = report.frameReport[62];
const auto& b = report.frameReport[63];
std::printf(" frames 62,63: id %llu,%llu simStart %llu,%llu (gap %llu) gpuFrameTimeUs %u\n",
static_cast<unsigned long long>(a.frameID), static_cast<unsigned long long>(b.frameID),
static_cast<unsigned long long>(a.simStartTime), static_cast<unsigned long long>(b.simStartTime),
static_cast<unsigned long long>(b.simStartTime - a.simStartTime),
static_cast<unsigned>(b.gpuFrameTimeUs));
// Every time of the last four frames, as its distance from that frame's simStartTime ("-" where the driver
// left the field zero): which fields a report fills in, and when a frame's report is complete.
for (int i = 60; i < 64; ++i) {
const auto& r = report.frameReport[i];
const std::uint64_t fields[] = {r.inputSampleTime, r.simEndTime, r.renderSubmitStartTime,
r.renderSubmitEndTime, r.presentStartTime, r.presentEndTime,
r.driverStartTime, r.driverEndTime, r.osRenderQueueStartTime,
r.osRenderQueueEndTime, r.gpuRenderStartTime, r.gpuRenderEndTime};
static const char* const names[] = {"input", "simEnd", "subStart", "subEnd", "presStart", "presEnd",
"drvStart", "drvEnd", "osqStart", "osqEnd", "gpuStart", "gpuEnd"};
std::printf(" frame %d id %llu:", i, static_cast<unsigned long long>(r.frameID));
for (int f = 0; f < 12; ++f) {
if (fields[f] == 0u) {
std::printf(" %s -", names[f]);
} else {
std::printf(" %s %lld", names[f],
static_cast<long long>(fields[f]) - static_cast<long long>(r.simStartTime));
}
}
std::printf(" | gpuActive %u gpuFrame %u\n", static_cast<unsigned>(r.gpuActiveRenderTimeUs),
static_cast<unsigned>(r.gpuFrameTimeUs));
}
}
// R3. What a call costs, on the thread that presents, between two frames.
const Cost latency = Measure(2000, [&]() noexcept { fl::reflex::ReadLatency(api, dx11.device, report); });
const Cost status = Measure(2000, [&]() noexcept { fl::reflex::ReadSleepStatus(api, dx11.device, sleep); });
std::printf("R3 GetLatency us a call: mean %.2f, median %.2f, worst %.2f (2000 calls)\n", latency.mean,
latency.median, latency.worst);
std::printf("R3 GetSleepStatus us a call: mean %.2f, median %.2f, worst %.2f (2000 calls)\n", status.mean,
status.median, status.worst);
// R4. The getters on ANOTHER thread, four times a second, while this one presents and sets markers.
// LEGS OF TEN SECONDS, ALTERNATING -- alone, beside the poller, alone, ... -- because one long leg against one
// short one measures the drift of an uncapped loop over a minute, not the poller (the first run of this probe
// compared 5 s alone with 60 s beside and read 1.3 % apart).
Poller poll{};
poll.api = api;
poll.device = dx11.device;
poll.paused.store(1u);
HANDLE thread = CreateThread(nullptr, 0, &PollerThread, &poll, 0, nullptr);
double aloneSum = 0.0;
double besideSum = 0.0;
const int legs = pollSeconds / 10 > 0 ? pollSeconds / 10 : 1;
for (int leg = 0; leg < legs; ++leg) {
poll.paused.store(1u);
const double alone = FramesPerSecond11(game, dx11, 10.0);
poll.paused.store(0u);
const double beside = FramesPerSecond11(game, dx11, 10.0);
aloneSum += alone;
besideSum += beside;
std::printf("R4 leg %d: frames a second %.0f alone, %.0f beside the poller (%+.2f %%)\n", leg + 1, alone,
beside, (beside - alone) * 100.0 / alone);
}
const std::uint32_t slowCalls = poll.calls;
const std::uint32_t slowNotOk = poll.notOk;
const double slowWorst = poll.worstSeconds;
// THE SAME WITH THE POLLER READING WITHOUT A PAUSE -- hundreds of thousands of reads a second where route D would
// make four. The legs above cannot tell half a percent from the loop's own drift; a dose this large can be seen,
// and what four reads a second cost is that, scaled down by the ratio of the two rates.
poll.intervalMs.store(0u);
double aloneFast = 0.0;
double besideFast = 0.0;
std::uint32_t fastCallsBefore = poll.calls;
for (int leg = 0; leg < 3; ++leg) {
poll.paused.store(1u);
const double alone = FramesPerSecond11(game, dx11, 10.0);
poll.paused.store(0u);
const double beside = FramesPerSecond11(game, dx11, 10.0);
aloneFast += alone;
besideFast += beside;
std::printf("R4b leg %d: frames a second %.0f alone, %.0f beside a poller that never pauses (%+.2f %%)\n",
leg + 1, alone, beside, (beside - alone) * 100.0 / alone);
}
poll.quit.store(1u);
WaitForSingleObject(thread, 5000);
CloseHandle(thread);
std::printf("R4b 30 s beside a poller that never pauses: %u reads (%.0f a second), %u not OK, %u faulted, worst "
"read %.1f us; frames a second %.0f alone, %.0f beside it (%+.2f %%); marker errors %u\n",
poll.calls - fastCallsBefore, static_cast<double>(poll.calls - fastCallsBefore) / 30.0,
poll.notOk - slowNotOk, poll.faults, poll.worstSeconds * 1e6, aloneFast / 3.0, besideFast / 3.0,
(besideFast - aloneFast) * 100.0 / aloneFast, game.markerErrors);
poll.calls = slowCalls;
poll.notOk = slowNotOk;
poll.worstSeconds = slowWorst;
std::printf("R4 %d s beside a poller in %d legs: %u reads, %u not OK, %u faulted, %u empty, worst read %.1f us; "
"frames a second %.0f alone, %.0f beside it (%+.2f %%); marker errors %u\n",
legs * 10, legs, poll.calls, poll.notOk, poll.faults, poll.emptyReports, poll.worstSeconds * 1e6,
aloneSum / legs, besideSum / legs, (besideSum - aloneSum) * 100.0 / aloneSum, game.markerErrors);
// R5. Direct3D 12: which object the driver wants -- the device (what the Overlay holds) or the queue.
Dx12 dx12{};
if (MakeDx12(factory, adapter, dx12)) {
Game game12{};
game12.setMarker = game.setMarker;
game12.markerDevice = dx12.device;
game12.frame = 100000;
for (int i = 0; i < 300; ++i) {
Frame12(game12, dx12);
}
std::printf("R5 D3D12, markers on the DEVICE: %u error(s), last status %d\n", game12.markerErrors,
static_cast<int>(game12.lastMarkerStatus));
PrintDigest("R5 D3D12, read with the device:", fl::reflex::ReadLatency(api, dx12.device, report), report);
PrintDigest("R5 D3D12, read with the queue:", fl::reflex::ReadLatency(api, dx12.queue, report), report);
const NvAPI_Status s12 = fl::reflex::ReadSleepStatus(api, dx12.device, sleep);
std::printf(" sleep status with the device %d, with the queue %d\n", static_cast<int>(s12),
static_cast<int>(fl::reflex::ReadSleepStatus(api, dx12.queue, sleep)));
Game queue12{};
queue12.setMarker = game.setMarker;
queue12.markerDevice = dx12.queue;
queue12.frame = 200000;
for (int i = 0; i < 300; ++i) {
Frame12(queue12, dx12);
}
std::printf("R5 D3D12, markers on the QUEUE: %u error(s), last status %d\n", queue12.markerErrors,
static_cast<int>(queue12.lastMarkerStatus));
PrintDigest("R5 D3D12, read with the device after that:", fl::reflex::ReadLatency(api, dx12.device, report),
report);
FreeDx12(dx12);
} else {
std::printf("R5 no Direct3D 12 device on the NVIDIA adapter\n");
}
// R6. The getters while the game sleeps (D139).
RunSleepLeg(factory, adapter, api, query, game.setMarker);
FreeDx11(dx11);
if (unload != nullptr) {
std::printf("NvAPI_Unload: %d\n", static_cast<int>(unload()));
}
ReleaseIf(adapter);
ReleaseIf(factory);
return 0;
}
} // namespace
int wmain(int argc, wchar_t** argv) {
if (argc >= 3 && wcscmp(argv[1], L"--stub") == 0) {
return RunStub(argv[2]);
}
if (argc >= 2 && wcscmp(argv[1], L"--real") == 0) {
return RunReal(argc >= 3 ? _wtoi(argv[2]) : 60);
}
std::printf("usage: fl-probe-reflex --stub <path to the stub nvapi64.dll> | --real [seconds beside a poller]\n");
return 2;
}
@@ -24,5 +24,7 @@ target_compile_definitions(fl-probe-signer PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX)
# load-bearing: a machine with no .NET shared framework must not be red for being
# itself, and an unrun leg is reported as unrun rather than as a negative.
add_test(NAME fl_signer_probe COMMAND fl-probe-signer)
set_tests_properties(fl_signer_probe PROPERTIES
PASS_REGULAR_EXPRESSION "BLOCKER: (FOUND|NOT PRESENT)")
# AND IT MUST REACH ITS LAST LINE (2026-11-13: a run cut short is not a pass -- the top-level file, above
# enable_testing()). The last line is "OK - N failure(s)" or "FAILURES - N failure(s)"; either is accepted, because
# this test's criterion was always that the answers are PRINTED, not that the machine agrees with them.
fl_test_completes(fl_signer_probe "BLOCKER: (FOUND|NOT PRESENT)(.|\n)*(OK|FAILURES) [^\n]*[0-9]+ failure\\(s\\)")
@@ -43,3 +43,5 @@ target_compile_definitions(fl-probe-vklayer PRIVATE
# blocked case would then pass for the wrong reason. The probe says so and
# exits 0.
add_test(NAME fl_vklayer_selfscan COMMAND fl-probe-vklayer)
# Its last line when nothing failed (a run cut short is not a pass -- the top-level file, above enable_testing()).
fl_test_completes(fl_vklayer_selfscan "VKLAYER SELF-SCAN OK \\(")
+11 -1
View File
@@ -19,7 +19,7 @@ add_executable(hook-harness main.cpp vk_hold.cpp gl_hold.cpp hwnd_hold.cpp proxy
# --probe-upscaler-resolve calls the OVERLAY'S resolver, not a copy of it, or it
# would prove a fact about GetProcAddress.
target_link_libraries(hook-harness PRIVATE FrameLedger.Shm fl_dxgi_vtable fl_native_flags fl_streamline_headers
fl_fidelityfx_headers fl_fsr3_host_headers fl_vulkan_headers opengl32 gdi32)
fl_fidelityfx_headers fl_fsr3_host_headers fl_vulkan_headers fl_nvapi_headers opengl32 gdi32)
target_include_directories(hook-harness PRIVATE "${CMAKE_SOURCE_DIR}/FrameLedger.Overlay/include")
target_compile_definitions(hook-harness PRIVATE WIN32_LEAN_AND_MEAN NOMINMAX)
@@ -175,3 +175,13 @@ add_test(NAME fl_unhook_preserves_foreign COMMAND hook-harness --probe-unhook)
# timing threshold on a shared CI runner fails for reasons that have nothing to
# do with the code. Run it deliberately: hook-harness --probe-cost
# EVERY TEST ABOVE ENDS ON THE SAME LINE: main() prints "HARNESS OK (0 failure(s))" when every probe it was asked for
# passed, and that line is what ctest looks for -- a run cut short is not a pass (the top-level file, above
# enable_testing(); 2026-11-13).
foreach(fl_harness_test IN ITEMS
fl_vtable_indices fl_frame_identity fl_d3d12_acquisition fl_proxy_swapchain
fl_d3d12_vtable_indices fl_dxr_probe fl_dxr_inputs fl_upscaler_resolve
fl_sl_abi_guard fl_ffx_resolve fl_sl_inputs fl_adv_fields
fl_sl_seen fl_dxgi_count fl_unhook_preserves_foreign)
fl_test_completes(${fl_harness_test} "HARNESS OK \\(")
endforeach()
@@ -84,3 +84,20 @@ fl_add_vendor_stub(fl_stub_ffx_loader "amd_fidelityfx_loader_dx12" stub_amd_fide
# is therefore hookinventory-check Pass C's SECOND positive control for the export
# parser, beside the ffx-api leaf.
fl_add_vendor_stub(fl_stub_ffx_fsr3_host "ffx_fsr3_x64" stub_ffx_fsr3_x64.cpp)
# --- NVIDIA NVAPI, for the spike of Reflex route D (docs/spike-notes §31, owner decision D132) ---
#
# A stand-in for nvapi64.dll: the real module's one way in (nvapi_QueryInterface) answering the two getters route D
# would call, with knobs for what a driver cannot be made to do on demand -- a missing getter, a report of nothing,
# an error, a call that does not return for seconds. Used by fl-probe-reflex only; the Overlay is not involved and
# no inventory row names it, so it takes the vendored NVAPI headers (the include directory alone -- nvapi64.lib is
# not linked) and nothing of the hook inventory.
#
# ITS OWN SUBDIRECTORY for its outputs: a file called nvapi64.lib beside the other stubs' import libraries would be
# one careless link line away from being taken for the vendored one.
fl_add_vendor_stub(fl_stub_nvapi64 "nvapi64" stub_nvapi64.cpp)
target_include_directories(fl_stub_nvapi64 SYSTEM PRIVATE "${CMAKE_SOURCE_DIR}/third_party/nvapi")
set_target_properties(fl_stub_nvapi64 PROPERTIES
RUNTIME_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/nvapi"
LIBRARY_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/nvapi"
ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/nvapi")
@@ -0,0 +1,61 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
// The knobs and counters of the stand-in nvapi64.dll (stub_nvapi64.cpp), as a named section another process can open.
//
// WHY A SECTION. The probe loads the stub into itself and calls its exports. The injected tests cannot: the stub is
// in the harness's process, and a test that asks "did the Overlay call the driver at all" has to read the stub's
// count from outside -- the harness's output is not captured. The stub creates `Local\FrameLedger.StubNvapi.<pid>`
// when it is loaded and keeps every knob and count in it; the exports the probe calls write the same words.
//
// A TEST FIXTURE'S, in a fixture's own namespace of names. Nothing shipped opens it.
#ifndef FRAMELEDGER_FL_STUB_NVAPI_SHARED_H
#define FRAMELEDGER_FL_STUB_NVAPI_SHARED_H
#include <cstdint>
namespace fl::stubnv {
// What GetLatency does (`mode`).
enum Mode : std::uint32_t {
kModeReports = 0, // sixty-four frames, their ids ten further on at every call
kModeNothing = 1, // OK and a report of nothing: a game that sets no marker
kModeError = 2, // NVAPI_ERROR, from both getters
kModeFault = 3, // an access violation inside GetLatency
kModeNoDriverSpan = 4, // reports whose driverStartTime is zero: what the driver gives without a sleep mode
kModeImpossible = 5, // reports whose present ends before it starts
};
// One frame of kModeReports, in microseconds: every frame has these spans.
inline constexpr std::uint32_t kSimulationUs = 800u;
inline constexpr std::uint32_t kSubmitUs = 1150u;
inline constexpr std::uint32_t kPresentUs = 150u;
inline constexpr std::uint32_t kDriverUs = 400u;
inline constexpr std::uint32_t kOsQueueUs = 1200u;
inline constexpr std::uint32_t kGpuUs = 3700u;
inline constexpr std::uint32_t kTotalUs = 7500u;
// The two times a driver works out itself, of every frame: the card at work, and one frame's GPU end to the next's.
inline constexpr std::uint32_t kGpuActiveUs = 3500u;
inline constexpr std::uint32_t kGpuFrameUs = 4200u;
inline constexpr std::uint32_t kFgMultiplier = 2u; // what GetSleepStatus gives while `fgMultiplier` is zero
inline constexpr std::uint32_t kFirstFrameId = 5000u;
inline constexpr std::uint32_t kFrameIdStep = 10u; // how far the ids move on at each call
// Plain words, read and written with interlocked operations on both sides.
struct Shared {
std::uint32_t mode; // Mode
std::uint32_t blockMs; // GetLatency sleeps this long before it answers
std::uint32_t hideGetters; // nvapi_QueryInterface answers null for both getters
std::uint32_t queries; // nvapi_QueryInterface calls
std::uint32_t latencyCalls; // GetLatency calls
std::uint32_t sleepStatusCalls; // GetSleepStatus calls
std::uint32_t fgMultiplier; // the multiplier GetSleepStatus gives; zero = kFgMultiplier
std::uint32_t reserved[1];
};
inline constexpr wchar_t kSectionFormat[] = L"Local\\FrameLedger.StubNvapi.%lu";
} // namespace fl::stubnv
#endif // FRAMELEDGER_FL_STUB_NVAPI_SHARED_H
@@ -0,0 +1,204 @@
// SPDX-License-Identifier: GPL-3.0-only
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
// A stand-in for NVIDIA's nvapi64.dll, for Reflex route D (docs/spike-notes §31; owner decisions D132, D136).
//
// NOT A VENDOR LIBRARY AND NOT SHIPPED. It carries the one name the real module's callers resolve everything through
// -- nvapi_QueryInterface -- and answers two interface ids, the two getters route D calls:
// NvAPI_D3D_GetLatency and NvAPI_D3D_GetSleepStatus. The ids and the structs are the vendored MIT headers' own
// (nvapi_interface.h, nvapi.h), so its callers and this stub cannot disagree about either.
//
// WHAT IT IS FOR: the things a real driver cannot be made to do on demand. A getter that is not there, a report of
// nothing, an error, a fault, a span the driver did not report, a span no frame can have, and a call that does not
// come back for a while -- so that each can be shown harmless before anything is tried against a driver, and long
// before anything is tried in a game.
//
// TWO CALLERS. The probe (tools/fl-probe-reflex) loads it into itself and turns its knobs through the exports
// below. The injected tests load it into hook-harness and turn the same knobs, and read the same counts, through the
// named section fl_stub_nvapi_shared.h describes.
#include <windows.h>
#include <d3d11.h>
#include <atomic>
#include <cstdint>
#include <cstdio>
#include <cstring>
#include <fl_stub_nvapi_shared.h>
#include <nvapi.h>
namespace {
constexpr unsigned int kIdInitialize = 0x0150e828u;
constexpr unsigned int kIdGetSleepStatus = 0xaef96ca1u;
constexpr unsigned int kIdGetLatency = 0x1a587f9cu;
// The section when it could be made, this otherwise: the stub works either way, only nobody outside can see it.
fl::stubnv::Shared g_local{};
fl::stubnv::Shared* g_shared = &g_local;
HANDLE g_section = nullptr;
std::atomic<void*> g_lastDevice{nullptr};
std::uint32_t Get(const std::uint32_t& word) noexcept {
return std::atomic_ref<const std::uint32_t>{word}.load(std::memory_order_relaxed);
}
std::uint32_t Bump(std::uint32_t& word) noexcept {
return std::atomic_ref<std::uint32_t>{word}.fetch_add(1u, std::memory_order_relaxed);
}
void Put(std::uint32_t& word, std::uint32_t value) noexcept {
std::atomic_ref<std::uint32_t>{word}.store(value, std::memory_order_relaxed);
}
void OpenSection() noexcept {
wchar_t name[64]{};
if (_snwprintf_s(name, _TRUNCATE, fl::stubnv::kSectionFormat, GetCurrentProcessId()) <= 0) {
return;
}
g_section = CreateFileMappingW(INVALID_HANDLE_VALUE, nullptr, PAGE_READWRITE, 0, sizeof(fl::stubnv::Shared), name);
if (g_section == nullptr) {
return;
}
void* view = MapViewOfFile(g_section, FILE_MAP_READ | FILE_MAP_WRITE, 0, 0, sizeof(fl::stubnv::Shared));
if (view != nullptr) {
g_shared = static_cast<fl::stubnv::Shared*>(view);
}
}
NvAPI_Status __cdecl StubInitialize() {
return NVAPI_OK;
}
NvAPI_Status __cdecl StubGetLatency(IUnknown* device, NV_LATENCY_RESULT_PARAMS* out) {
const std::uint32_t call = Bump(g_shared->latencyCalls); // 0 for the first call
g_lastDevice.store(device, std::memory_order_relaxed);
if (out == nullptr) {
return NVAPI_INVALID_ARGUMENT;
}
if (out->version != NV_LATENCY_RESULT_PARAMS_VER1) {
return NVAPI_INCOMPATIBLE_STRUCT_VERSION;
}
const std::uint32_t block = Get(g_shared->blockMs);
if (block != 0u) {
Sleep(block);
}
const std::uint32_t mode = Get(g_shared->mode);
if (mode == fl::stubnv::kModeError) {
return NVAPI_ERROR;
}
if (mode == fl::stubnv::kModeNothing) {
return NVAPI_OK; // the caller's zeros are left as they are
}
if (mode == fl::stubnv::kModeFault) {
volatile std::uint32_t* nowhere = nullptr;
*nowhere = 1u; // the fault a driver cannot be asked for
}
// Sixty-four frames a little over four milliseconds apart, the newest last (nvapi.h: "element 63"), and ten
// frames further on at every call -- so a caller that reads twice finds ten new frames, not the same sixty-four.
const std::uint64_t firstId =
fl::stubnv::kFirstFrameId + static_cast<std::uint64_t>(call) * fl::stubnv::kFrameIdStep;
for (std::uint32_t i = 0; i < 64u; ++i) {
auto& r = out->frameReport[i];
const std::uint64_t id = firstId + i;
const std::uint64_t t = 1'000'000ull + (id - fl::stubnv::kFirstFrameId) * 4200ull;
r.frameID = id;
r.inputSampleTime = t;
r.simStartTime = t + 100u;
r.simEndTime = t + 900u;
r.renderSubmitStartTime = t + 950u;
r.renderSubmitEndTime = t + 2100u;
r.presentStartTime = t + 2150u;
r.presentEndTime = t + 2300u;
r.driverStartTime = t + 2300u;
r.driverEndTime = t + 2700u;
r.osRenderQueueStartTime = t + 2700u;
r.osRenderQueueEndTime = t + 3900u;
r.gpuRenderStartTime = t + 3900u;
r.gpuRenderEndTime = t + 7600u;
r.gpuActiveRenderTimeUs = fl::stubnv::kGpuActiveUs;
r.gpuFrameTimeUs = fl::stubnv::kGpuFrameUs;
if (mode == fl::stubnv::kModeNoDriverSpan) {
r.driverStartTime = 0u;
}
if (mode == fl::stubnv::kModeImpossible) {
r.presentEndTime = r.presentStartTime - 50u;
}
}
return NVAPI_OK;
}
NvAPI_Status __cdecl StubGetSleepStatus(IUnknown* device, NV_GET_SLEEP_STATUS_PARAMS* out) {
Bump(g_shared->sleepStatusCalls);
g_lastDevice.store(device, std::memory_order_relaxed);
if (out == nullptr) {
return NVAPI_INVALID_ARGUMENT;
}
if (out->version != NV_GET_SLEEP_STATUS_PARAMS_VER1) {
return NVAPI_INCOMPATIBLE_STRUCT_VERSION;
}
if (Get(g_shared->mode) == fl::stubnv::kModeError) {
return NVAPI_ERROR;
}
out->bLowLatencyMode = 1;
out->sleepIntervalUs = 4166u;
out->bUseGameSleep = 1;
const std::uint32_t multiplier = Get(g_shared->fgMultiplier);
out->fgMultiplier = static_cast<NvU8>(multiplier == 0u ? fl::stubnv::kFgMultiplier : multiplier);
return NVAPI_OK;
}
} // namespace
BOOL WINAPI DllMain(HINSTANCE, DWORD reason, LPVOID) {
if (reason == DLL_PROCESS_ATTACH) {
OpenSection(); // kernel32 only, and nothing that takes another module's lock
}
return TRUE;
}
extern "C" {
// The real module's one way in: an address for an interface id, or null for one it does not have.
__declspec(dllexport) void* __cdecl nvapi_QueryInterface(unsigned int id) {
Bump(g_shared->queries);
if (id == kIdInitialize) {
return reinterpret_cast<void*>(&StubInitialize);
}
if (Get(g_shared->hideGetters) != 0u) {
return nullptr;
}
if (id == kIdGetLatency) {
return reinterpret_cast<void*>(&StubGetLatency);
}
if (id == kIdGetSleepStatus) {
return reinterpret_cast<void*>(&StubGetSleepStatus);
}
return nullptr;
}
// The probe's knobs and counters. Names nobody else exports.
__declspec(dllexport) void __cdecl FlStubNvSetMode(std::uint32_t mode) {
Put(g_shared->mode, mode);
}
__declspec(dllexport) void __cdecl FlStubNvSetBlockMs(std::uint32_t milliseconds) {
Put(g_shared->blockMs, milliseconds);
}
__declspec(dllexport) void __cdecl FlStubNvHideGetters(std::uint32_t hide) {
Put(g_shared->hideGetters, hide);
}
__declspec(dllexport) std::uint32_t __cdecl FlStubNvQueries() {
return Get(g_shared->queries);
}
__declspec(dllexport) std::uint32_t __cdecl FlStubNvLatencyCalls() {
return Get(g_shared->latencyCalls);
}
__declspec(dllexport) std::uint32_t __cdecl FlStubNvSleepStatusCalls() {
return Get(g_shared->sleepStatusCalls);
}
__declspec(dllexport) void* __cdecl FlStubNvLastDevice() {
return g_lastDevice.load(std::memory_order_relaxed);
}
} // extern "C"
@@ -397,4 +397,64 @@ public sealed class AdvancedPresenterTests
}
private static string Label(string id) => AdvancedLabels.Of(AdvancedMetricCatalog.Find(id)!);
// ---- The driver's latency report (train C): a call FrameLedger makes itself, so words of its own -------------
[Fact]
public void TheDriversLatencyReportHasASentenceOfItsOwnAndARowStoredBeforeHasNone()
{
AdvancedSources before = AdvancedSources.Unknown with { InGame = AdvancedInGameStatus.Reading };
string without = AdvancedPresenter.SourcesLine(before);
string read = AdvancedPresenter.SourcesLine(before with { DriverLatency = AdvancedDriverRead.Read, DriverLatencySlowestUs = 3 });
read.Should().StartWith(without, "what was said before is said as before");
read.Should().EndWith(string.Format(CultureInfo.CurrentCulture, Strings.Advanced_InGameDriverLine, Strings.AdvDriverRead_Read));
// Stopped for being slow says how slow: that number is what tells a driver that held a call from a pause.
string slow = AdvancedPresenter.SourcesLine(before with { DriverLatency = AdvancedDriverRead.Slow, DriverLatencySlowestUs = 2400 });
slow.Should().Contain(2400.ToString("N0", CultureInfo.CurrentCulture));
slow.Should().NotContain("{0");
// A row that says nothing about it - stored before, or a game the capture side publishes nothing for.
AdvancedPresenter.SourcesLine(before with { DriverLatency = AdvancedDriverRead.Unknown }).Should().Be(without);
AdvancedPresenter.SourcesLine(before with { DriverLatency = null }).Should().Be(without);
}
[Theory]
[InlineData("en")]
[InlineData("vi")]
[InlineData("ja")]
public void EveryOutcomeOfTheDriversReadHasItsWordsInEveryLanguage(string culture)
{
CultureInfo c = CultureInfo.GetCultureInfo(culture);
foreach (AdvancedDriverRead outcome in Enum.GetValues<AdvancedDriverRead>())
{
string? words = Strings.ResourceManager.GetString("AdvDriverRead_" + outcome, c);
words.Should().NotBeNullOrEmpty(outcome.ToString());
(words ?? string.Empty).Contains("{0", StringComparison.Ordinal).Should().Be(outcome == AdvancedDriverRead.Slow, "only the slow stop carries its microseconds");
}
Strings.ResourceManager.GetString(nameof(Strings.Advanced_InGameDriverLine), c).Should().Contain("{0}");
Strings.ResourceManager.GetString(nameof(Strings.Advanced_Status_InGameDriver), c).Should().NotBeNullOrEmpty();
}
[Fact]
public void TheSevenSpansOfTheDriversReportAreSeriesOfOneEntryLabelledInWords()
{
(AdvancedMetric? metric, string label) = AdvancedPresenter.Resolve("adv.nvapi.reflex.frame_report.os_queue", []);
metric!.Id.Should().Be("nvapi.reflex.frame_report");
label.Should().Be(AdvancedLabels.Member(AdvancedLabels.Of(metric), Strings.AdvToken_os_queue));
label.Should().NotContain("os_queue", "the member is one of ours and is said in words");
// Seven lines of one entry: within what a chart can show, so no band.
string[] series = [.. InGameAdvancedSampler.LatencySpans.Select(static span => InGameAdvancedSampler.LatencySeriesStem + span)];
AdvancedPresenter.Metrics(series, []).Should().ContainSingle().Which.Id.Should().Be("nvapi.reflex.frame_report");
series.Length.Should().BeLessThanOrEqualTo(AdvancedPresenter.MaxLines);
// On the Sources tab the two entries say where they are read, and it is not "when the game makes the call".
AdvancedPresenter.Sources(now: null)
.Where(static row => string.Equals(row.Label, AdvancedLabels.Of(AdvancedMetricCatalog.Find("nvapi.reflex.frame_report")!), StringComparison.Ordinal))
.Should().ContainSingle().Which.Status.Should().Be(Strings.Advanced_Status_InGameDriver);
}
}
@@ -233,6 +233,8 @@ public sealed class AdvancedJsonTests
StreamlineAllocateResources = AdvancedInGameCall.Read,
StreamlineFreeResources = AdvancedInGameCall.NotHooked,
StreamlineShutdown = AdvancedInGameCall.NeverCalled,
DriverLatency = AdvancedDriverRead.Slow,
DriverLatencySlowestUs = 2400,
};
string json = AdvancedJson.OfSession([], written);
@@ -248,6 +250,8 @@ public sealed class AdvancedJsonTests
older.StreamlineFeatureRequirements.Should().Be(AdvancedInGameCall.Read);
older.StreamlineFeatureSupported.Should().BeNull("a row that never said is not a row that said the hook was not in");
older.StreamlineShutdown.Should().BeNull();
older.DriverLatency.Should().BeNull("a row stored before train C says nothing about the driver's report");
older.DriverLatencySlowestUs.Should().BeNull();
}
[Theory]
@@ -86,12 +86,33 @@ public sealed partial class AdvancedMetricCatalogTests
[Fact]
public void OnlyWhatTheAgentOrTheOverlayReadsCountsAsRead()
{
_all.Where(static m => m.IsRead).Should().OnlyContain(static m => m.Reach == AdvancedReach.Agent || m.Reach == AdvancedReach.AgentElevated || m.Reach == AdvancedReach.Game);
_all.Where(static m => !m.IsRead).Should().NotContain(static m => m.Reach == AdvancedReach.Agent || m.Reach == AdvancedReach.AgentElevated || m.Reach == AdvancedReach.Game);
_all.Where(static m => m.IsRead).Should().OnlyContain(static m => m.Reach == AdvancedReach.Agent || m.Reach == AdvancedReach.AgentElevated || m.Reach == AdvancedReach.Game || m.Reach == AdvancedReach.GameDriver);
_all.Where(static m => !m.IsRead).Should().NotContain(static m => m.Reach == AdvancedReach.Agent || m.Reach == AdvancedReach.AgentElevated || m.Reach == AdvancedReach.Game || m.Reach == AdvancedReach.GameDriver);
_all.Should().Contain(static m => m.IsRead);
_all.Should().Contain(static m => !m.IsRead);
}
[Fact]
public void WhatThePartInsideAGameAsksTheDriverForItselfIsTwoEntriesOfNvapiAndNothingMore()
{
// Train C (owner decisions D132, D136, D138): the one reach that is not an argument of a hooked call. The
// Overlay calls NVIDIA's two read-only latency getters; tools/nvapi-readonly-check.ps1 holds that those two
// are the only NVAPI functions code loaded into a game may name. Two entries, and they stay two until an
// owner's ruling of the same kind names another.
string[] driver = [.. _all.Where(static m => m.Reach == AdvancedReach.GameDriver).Select(static m => m.Id)];
driver.Should().Equal("nvapi.reflex.sleep_status", "nvapi.reflex.frame_report");
_all.Where(static m => m.Reach == AdvancedReach.GameDriver).Should().OnlyContain(static m => m.Source == AdvancedSource.Nvapi && m.IsRead);
_all.Where(static m => m.Reach == AdvancedReach.GameDriver).Should().OnlyContain(static m => m.Scope != AdvancedScope.MachineFact, "what a driver says of a game's frames is of a session");
AdvancedMetricCatalog.Find("nvapi.reflex.frame_report")!.IsFamily.Should().BeTrue("seven series, one a span");
AdvancedMetricCatalog.Find("nvapi.reflex.frame_report")!.Unit.Should().Be(AdvancedUnit.Microseconds);
// What the GAME asked of Reflex, and Reflex through Streamline, are not read and will not be: each needs a
// route that was refused (a patch at a run-time address; a call from a thread the vendor forbids - D133).
AdvancedMetricCatalog.Find("nvapi.reflex.mode")!.Reach.Should().Be(AdvancedReach.RefusedRoute);
AdvancedMetricCatalog.Find("sl.reflex.state")!.Reach.Should().Be(AdvancedReach.RefusedRoute);
_all.Where(static m => m.Reach == AdvancedReach.RefusedRoute).Should().OnlyContain(static m => !m.IsRead);
}
[Fact]
public void TheElevatedReachIsLibreHardwareMonitorsAlone()
{
@@ -581,4 +581,149 @@ public sealed class InGameAdvancedSamplerTests
AdvancedJson.Storable(sampler.Facts).Should().HaveCount(sampler.Facts.Count, "what the game said may be stored");
readings.Select(static r => AdvancedMetricCatalog.Find(r.Series[AdvancedMetric.SeriesPrefix.Length..])!.Reach).Should().OnlyContain(static reach => reach == AdvancedReach.Game);
}
// ---- The driver's latency report (train C): not one of the game's calls --------------------------------------
private static FlAdvancedState Latency(FlLatencyState state, uint frames = 0, uint samples = 1, uint slowestUs = 3) =>
InGameStates.Empty() with
{
Samples = samples,
ValidMask = frames == 0 ? FlAdvancedValid.None : FlAdvancedValid.Latency,
// The stand-in driver's status: low-latency mode and the game's sleep on, the other three off, x2.
LatState = (uint)state | ((1u | 8u) << FlAdvancedState.LatSleepSeenOnShift) | ((2u | 4u | 16u) << FlAdvancedState.LatSleepSeenOffShift) | (2u << FlAdvancedState.LatFgMultiplierShift),
LatReads = 1u | (slowestUs << 16),
LatFrames = frames,
LatSimulationSumUs = frames * 800,
LatSubmitSumUs = frames * 1150,
LatPresentSumUs = frames * 150,
LatDriverSumUs = frames * 400,
LatOsQueueSumUs = frames * 1200,
LatGpuSumUs = frames * 3700,
LatTotalSumUs = frames * 7500,
};
[Fact]
public void OneReadOfTheDriversReportIsOnePointASpanTheMeanOfTheFramesItSummed()
{
var sampler = new InGameAdvancedSampler();
IReadOnlyList<AdvancedReading> readings = sampler.Take(new InGameAdvanced(Latency(FlLatencyState.Reading, frames: 62)))!;
readings.Should().Equal(
new AdvancedReading("adv.nvapi.reflex.frame_report.simulation", 800.0),
new AdvancedReading("adv.nvapi.reflex.frame_report.render_submit", 1150.0),
new AdvancedReading("adv.nvapi.reflex.frame_report.present", 150.0),
new AdvancedReading("adv.nvapi.reflex.frame_report.driver", 400.0),
new AdvancedReading("adv.nvapi.reflex.frame_report.os_queue", 1200.0),
new AdvancedReading("adv.nvapi.reflex.frame_report.gpu_render", 3700.0),
new AdvancedReading("adv.nvapi.reflex.frame_report.total", 7500.0));
readings.Select(static r => r.Series).Should().OnlyContain(static name => name.StartsWith(InGameAdvancedSampler.LatencySeriesStem, StringComparison.Ordinal));
InGameAdvancedSampler.LatencySpans.Should().HaveCount(7);
sampler.DriverRead(hooked: true).Should().Be(AdvancedDriverRead.Read);
sampler.DriverSlowestUs.Should().Be(3);
// A publication with no read since the one before carries no frames: no point, and not a zero.
sampler.Take(new InGameAdvanced(Latency(FlLatencyState.Reading, frames: 62, samples: 2) with { LatFrames = 0 })).Should().BeNull();
}
[Fact]
public void ASpanTheDriverDidNotReportHasNoPointAndTheOthersDo()
{
var sampler = new InGameAdvancedSampler();
// Without a sleep mode the driver reports no driver span: the capture side publishes all ones for its sum.
IReadOnlyList<AdvancedReading> readings = sampler.Take(new InGameAdvanced(
Latency(FlLatencyState.Reading, frames: 10) with { LatDriverSumUs = FlAdvancedState.LatSumNone }))!;
readings.Should().HaveCount(6);
readings.Should().NotContain(static r => r.Series.EndsWith(".driver", StringComparison.Ordinal));
readings.Should().Contain(new AdvancedReading("adv.nvapi.reflex.frame_report.total", 7500.0));
}
[Fact]
public void TheDriversReportIsNotOneOfTheGamesCalls()
{
var sampler = new InGameAdvancedSampler();
sampler.Take(new InGameAdvanced(Latency(FlLatencyState.Reading, frames: 62)));
// "The game's calls were read" stays false: FrameLedger made this read, the game made no call.
sampler.SawAnything.Should().BeFalse();
sampler.Status(hooked: true).Should().Be(AdvancedInGameStatus.NothingSeen);
// ...and the one fact is the driver's five switches by the vendor's own names, as seen, and its multiplier.
Rows(Fact(sampler, "nvapi.reflex.sleep_status")).Should().Equal(
"bLowLatencyMode=on", "bFsVrr=off", "bCplVsyncOn=off", "bUseGameSleep=on", "bFullscreenIFlip=off", "fgMultiplier=2");
sampler.Facts.Should().ContainSingle();
}
[Theory]
[InlineData(FlLatencyState.NoDevice, AdvancedDriverRead.NoDirect3D12)]
[InlineData(FlLatencyState.NoModule, AdvancedDriverRead.NoModule)]
[InlineData(FlLatencyState.Refused, AdvancedDriverRead.Refused)]
[InlineData(FlLatencyState.NoGetter, AdvancedDriverRead.NoGetter)]
[InlineData(FlLatencyState.Reading, AdvancedDriverRead.NothingReported)]
[InlineData(FlLatencyState.Error, AdvancedDriverRead.Error)]
[InlineData(FlLatencyState.Slow, AdvancedDriverRead.Slow)]
[InlineData(FlLatencyState.Faulted, AdvancedDriverRead.Faulted)]
[InlineData(FlLatencyState.Stalled, AdvancedDriverRead.Stalled)]
public void WhereTheReadStandsIsTakenEvenFromAPublicationThatReadNothing(FlLatencyState state, AdvancedDriverRead expected)
{
var sampler = new InGameAdvancedSampler();
// No bit of the mask: nothing was read. The state is published all the same, and is why.
sampler.Take(new InGameAdvanced(Latency(state) with { LatState = (uint)state })).Should().BeNull();
sampler.DriverRead(hooked: true).Should().Be(expected);
sampler.DriverRead(hooked: false).Should().BeNull("a session not measured inside the game has no such question");
sampler.Facts.Should().BeEmpty();
sampler.SawAnything.Should().BeFalse();
}
[Fact]
public void ASessionTheCaptureSideSaidNothingAboutHasNoAnswerAndAStopAfterFramesStillSaysItStopped()
{
var silent = new InGameAdvancedSampler();
silent.Take(new InGameAdvanced(InGameStates.Empty()));
silent.DriverRead(hooked: true).Should().BeNull();
silent.DriverSlowestUs.Should().BeNull();
// Frames were reported, then one call took 2,400 microseconds: the series are there, and the state is the stop.
var stopped = new InGameAdvancedSampler();
stopped.Take(new InGameAdvanced(Latency(FlLatencyState.Reading, frames: 62)));
stopped.Take(new InGameAdvanced(Latency(FlLatencyState.Slow, frames: 10, samples: 2, slowestUs: 2400)));
stopped.DriverRead(hooked: true).Should().Be(AdvancedDriverRead.Slow);
stopped.DriverSlowestUs.Should().Be(2400);
// An error after frames is still "read": the series are the answer, and reading went on.
var erred = new InGameAdvancedSampler();
erred.Take(new InGameAdvanced(Latency(FlLatencyState.Reading, frames: 62)));
erred.Take(new InGameAdvanced(Latency(FlLatencyState.Error, samples: 2) with { ValidMask = FlAdvancedValid.Latency }));
erred.DriverRead(hooked: true).Should().Be(AdvancedDriverRead.Read);
}
[Fact]
public void TheGamesCallsAndTheDriversReportAreTakenFromOnePublication()
{
var sampler = new InGameAdvancedSampler();
FlAdvancedState both = InGameStates.Ffx(samples: 1) with
{
ValidMask = InGameStates.Ffx().ValidMask | FlAdvancedValid.Latency,
LatState = (uint)FlLatencyState.Reading,
LatFrames = 10,
LatTotalSumUs = 75_000,
LatSimulationSumUs = FlAdvancedState.LatSumNone,
LatSubmitSumUs = FlAdvancedState.LatSumNone,
LatPresentSumUs = FlAdvancedState.LatSumNone,
LatDriverSumUs = FlAdvancedState.LatSumNone,
LatOsQueueSumUs = FlAdvancedState.LatSumNone,
LatGpuSumUs = FlAdvancedState.LatSumNone,
};
IReadOnlyList<AdvancedReading> readings = sampler.Take(new InGameAdvanced(both))!;
readings.Should().Contain(new AdvancedReading("adv.nvapi.reflex.frame_report.total", 7500.0));
readings.Should().Contain(static r => r.Series == InGameAdvancedSampler.FrameTimeSeries);
sampler.SawAnything.Should().BeTrue("the FSR dispatch is one of the game's calls");
sampler.Facts.Should().NotContain(static f => f.Id == "nvapi.reflex.sleep_status", "no switch of the sleep status was seen");
}
}
+6 -1
View File
@@ -186,7 +186,10 @@ function Get-ImportName([string]$DumpbinText) {
function Get-ForbiddenImport([string[]]$ImportNames) {
$bad = @()
foreach ($n in $ImportNames) {
if ($n -match '^(sl\.|_?nvngx|libxess|ffx_|amd_fidelityfx)') { $bad += $n }
# `nvapi` since Advanced metrics train C: the Overlay calls two getters of an nvapi64.dll the GAME loaded and
# must never be what loads it - linking nvapi64.lib would not show here (it is static and loads the DLL at
# its first call; tools/nvapi-readonly-check.ps1 refuses the call tokens), a real import would.
if ($n -match '^(sl\.|_?nvngx|libxess|ffx_|amd_fidelityfx|nvapi)') { $bad += $n }
}
return , $bad
}
@@ -270,6 +273,8 @@ if ($SelfTest) {
Got = ((Get-ImportName " Summary`r`n`r`n 1000 .data`r`n").Count -eq 0); Want = $true }
@{ Name = 'a clean import list is clean'
Got = ((Get-ForbiddenImport @('KERNEL32.dll', 'd3d11.dll', 'd3d12.dll', 'dxgi.dll')).Count -eq 0); Want = $true }
@{ Name = 'an imported nvapi64.dll is caught, and a module that only ends in the name is not'
Got = (((Get-ForbiddenImport @('KERNEL32.dll', 'nvapi64.dll', 'NVAPI64.DLL', 'mynvapi.dll')) -join ',') -eq 'nvapi64.dll,NVAPI64.DLL'); Want = $true }
@{ Name = 'a LINKED sl.interposer.dll is caught - the whole reason Pass C exists'
Got = ((Get-ForbiddenImport @('KERNEL32.dll', 'sl.interposer.dll')) -contains 'sl.interposer.dll'); Want = $true }
@{ Name = 'the driver-store NGX core is caught despite its leading underscore'
+126 -7
View File
@@ -28,9 +28,13 @@
WHAT IT DOES NOT DO. It reads names, not arguments: an entry point that reads or writes depending on a command
argument (NvAPI_Disp_ColorControl, NvAPI_Disp_HdrColorControl) could not be told apart by it, which is why rule 3
refuses every name ending in Control outright. It does not look at the other native targets: no other shipped
target links nvapi64.lib (the Overlay links none of it - tools/vendor-exports and the package closure hold that),
and the probe tools are not shipped.
refuses every name ending in Control outright. No other shipped target links nvapi64.lib, and the probe tools
are not shipped.
THE OVERLAY, since Advanced metrics train C (owner decisions D132, D136): it links none of NVAPI and calls two
of the driver's getters through addresses it asks an already-loaded nvapi64.dll for, by interface id. Rules 5 to
7, above Test-Overlay, hold which ids code loaded into a game may name - against tools/overlay-nvapi-allowed.txt
and the vendored nvapi_interface.h.
-SelfTest proves every rule in both directions on in-memory sources.
#>
@@ -47,14 +51,16 @@ $ErrorActionPreference = 'Stop'
# end after it. So "SetSetting", "ClientRegisterFor..." and "ColorControl" match, and "GetThermalSettings",
# "LoadSettings", "GetSetting" and "GetAllClockFrequencies" do not. It errs towards red: a noun that happens to end
# in one of these words is refused until it is named below.
$script:WriterVerb = '(Set|Save|Restore|Delete|Remove|Register|Unregister|Reset|Enable|Disable|Flash|Write|Apply|Lock|Unlock|Create|Destroy|Control)(?=[A-Z_]|$)'
# `Sleep` since train C: NvAPI_D3D_Sleep stops the calling thread, and the Overlay's list is judged by this too.
$script:WriterVerb = '(Set|Save|Restore|Delete|Remove|Register|Unregister|Reset|Enable|Disable|Flash|Write|Apply|Lock|Unlock|Create|Destroy|Control|Sleep)(?=[A-Z_]|$)'
# The names the verb rule would refuse and that are reads. Named here one by one, each with its reason - never by a
# pattern, so an exemption cannot grow to cover a writer.
$script:WriterExempt = @(
'NvAPI_DRS_CreateSession', # the handle of a settings session that is only ever read from
'NvAPI_DRS_DestroySession', # ... and its release
'NvAPI_SYS_GetChipSetInfo' # "ChipSet" is a noun: the chipset's vendor and name
'NvAPI_SYS_GetChipSetInfo', # "ChipSet" is a noun: the chipset's vendor and name
'NvAPI_D3D_GetSleepStatus' # reads what the driver's low-latency state is; it sets none and sleeps nobody
)
# D104. NVAPI's entry points that return something identifying a device, a person or another program.
@@ -110,6 +116,70 @@ function Test-Bridge([string]$Source, [string]$ListText) {
return , @($problems)
}
# ---------------------------------------------------------------------------------------------------------------------
# THE OVERLAY (Advanced metrics train C; owner decisions D132, D136). Code loaded into a game links no NVAPI and
# calls no NvAPI_* function by name: it asks an nvapi64.dll the game had already loaded for two addresses, by
# interface id (FrameLedger.Overlay/include/fl_reflex.h). A call through such an address carries no NvAPI_ token, so
# the bridge's rules cannot see it. These can:
#
# 5. no NvAPI_* call token in any Overlay or Vulkan-layer source;
# 6. every 8-digit hex literal there that IS one of the vendored nvapi_interface.h's ids belongs to a name on
# tools/overlay-nvapi-allowed.txt, and every name on that list has its id in the sources;
# 7. the names on that list are judged as the bridge's are - no writer, no identifier - and, for code inside a
# game, `Sleep` is a writer verb too: NvAPI_D3D_Sleep stops the thread that calls it.
#
# WHAT IT DOES NOT DO: it cannot see an id that is computed, or one written in another base. No code does either.
# ---------------------------------------------------------------------------------------------------------------------
# name -> id (lower-case hex, no prefix), from the vendored nvapi_interface.h: { "NvAPI_X", 0x........ },
function Read-InterfaceTable([string]$Text) {
$byId = @{}
foreach ($m in [regex]::Matches($Text, '\{\s*"(NvAPI_\w+)"\s*,\s*0x([0-9A-Fa-f]{1,8})\s*\}')) {
$id = $m.Groups[2].Value.ToLowerInvariant().PadLeft(8, '0')
if (-not $byId.ContainsKey($id)) { $byId[$id] = [System.Collections.Generic.List[string]]::new() }
$byId[$id].Add($m.Groups[1].Value)
}
return $byId
}
# $Sources: file name -> source, for every Overlay and Vulkan-layer source.
function Test-Overlay([hashtable]$Sources, [string]$InterfaceText, [string]$ListText) {
$problems = [System.Collections.Generic.List[string]]::new()
$list = Read-AllowedList $ListText
foreach ($p in $list.Problems) { $problems.Add($p) }
$allowed = $list.Names
$byId = Read-InterfaceTable $InterfaceText
if ($byId.Count -eq 0) { $problems.Add('no interface id was read from nvapi_interface.h: the check read the wrong file, or nothing') }
$found = [System.Collections.Generic.SortedSet[string]]::new([StringComparer]::Ordinal)
foreach ($key in ($Sources.Keys | Sort-Object)) {
foreach ($name in (Get-NvapiCall $Sources[$key])) {
$problems.Add("$key calls $name by name: code loaded into a game links no NVAPI")
}
$code = [regex]::Replace($Sources[$key], '/\*.*?\*/', ' ', 'Singleline')
$code = [regex]::Replace($code, '//[^\r\n]*', ' ')
$code = [regex]::Replace($code, '"(\\.|[^"\\\r\n])*"', '""')
foreach ($m in [regex]::Matches($code, '(?<![\w])0[xX]([0-9A-Fa-f]{8})(?![0-9A-Fa-f])')) {
$id = $m.Groups[1].Value.ToLowerInvariant()
if (-not $byId.ContainsKey($id)) { continue }
foreach ($name in $byId[$id]) {
[void]$found.Add($name)
if ($allowed -cnotcontains $name) { $problems.Add("$key names the interface id of $name (0x$id), which the Overlay's list does not allow") }
}
}
}
foreach ($name in $allowed) {
if (-not $found.Contains($name)) { $problems.Add("the Overlay's list allows $name, whose interface id is in no Overlay source") }
if ($name -cmatch $script:WriterVerb -and $script:WriterExempt -cnotcontains $name) {
$problems.Add("$name changes something (its name carries '$($Matches[1])'): nothing loaded into a game calls a writer, whatever the list says")
}
if ($name -cmatch $script:Identifier) {
$problems.Add("$name returns an identifier ('$($Matches[1])'): never read (D104), whatever the list says")
}
}
return , @($problems)
}
if ($SelfTest) {
$failed = 0
$goodSource = @'
@@ -148,8 +218,34 @@ int Read() {
Write-Host (" {0,-4} {1}{2}" -f ($(if ($ok) { 'ok' } else { 'FAIL' })), $c.Name, ($(if (-not $ok) { " -> $($problems.Count): $($problems -join '; ')" } else { '' }))) -ForegroundColor ($(if ($ok) { 'DarkGray' } else { 'Red' }))
if (-not $ok) { $failed++ }
}
# The Overlay's rules, on a table of four ids and sources written here.
$table = @'
{ "NvAPI_D3D_GetLatency", 0x1a587f9c },
{ "NvAPI_D3D_GetSleepStatus", 0xaef96ca1 },
{ "NvAPI_D3D_SetSleepMode", 0xac1ca9e0 },
{ "NvAPI_D3D_Sleep", 0x852cd1d2 },
'@
$goodOverlay = @{ 'fl_reflex.h' = "// 0xac1ca9e0 is NvAPI_D3D_SetSleepMode and is never asked for`ninline constexpr unsigned int kA = 0x1a587f9cu; inline constexpr unsigned int kB = 0xAEF96CA1u; const uint32_t none = 0xFFFFFFFFu; Log(`"0x852cd1d2`");" }
$goodOverlayList = "# the two getters`nNvAPI_D3D_GetLatency`nNvAPI_D3D_GetSleepStatus`n"
$overlayCases = @(
@{ Name = 'the two getters by id, a setter''s id only in a comment and a string, pass'; Sources = $goodOverlay; List = $goodOverlayList; Expect = 0 },
@{ Name = 'the id of a setter in Overlay code FAILS'; Sources = @{ 'fl_reflex.h' = $goodOverlay['fl_reflex.h']; 'dllmain.cpp' = 'void* p = query(0xac1ca9e0u);' }; List = $goodOverlayList; Expect = 1 },
@{ Name = 'the id of the sleep FAILS when it is listed: a writer verb, whatever the list says'; Sources = @{ 'fl_reflex.h' = $goodOverlay['fl_reflex.h'] + ' void* s = query(0x852cd1d2);' }; List = $goodOverlayList + "NvAPI_D3D_Sleep`n"; Expect = 1 },
@{ Name = 'a setter FAILS even when it is listed and its id is named'; Sources = @{ 'fl_reflex.h' = $goodOverlay['fl_reflex.h'] + ' void* s = query(0xac1ca9e0);' }; List = $goodOverlayList + "NvAPI_D3D_SetSleepMode`n"; Expect = 1 },
@{ Name = 'a name on the list whose id nothing names FAILS'; Sources = @{ 'fl_reflex.h' = 'inline constexpr unsigned int kA = 0x1a587f9cu;' }; List = $goodOverlayList; Expect = 1 },
@{ Name = 'an NvAPI function called by name in the Overlay FAILS'; Sources = @{ 'fl_reflex.h' = $goodOverlay['fl_reflex.h']; 'dllmain.cpp' = 'void X() { NvAPI_D3D_GetLatency(dev, &out); }' }; List = $goodOverlayList; Expect = 1 },
@{ Name = 'a hex literal that is no interface id passes'; Sources = @{ 'fl_reflex.h' = $goodOverlay['fl_reflex.h']; 'layer.cpp' = 'const uint32_t magic = 0x7F800000u; const uint64_t wide = 0x1a587f9c00000000ull;' }; List = $goodOverlayList; Expect = 0 },
@{ Name = 'an interface table nobody could read FAILS'; Sources = $goodOverlay; List = $goodOverlayList; Table = '// nothing'; Expect = 3 }
)
foreach ($c in $overlayCases) {
$tableText = if ($c.ContainsKey('Table')) { $c.Table } else { $table }
$problems = Test-Overlay $c.Sources $tableText $c.List
$ok = $problems.Count -eq $c.Expect
Write-Host (" {0,-4} {1}{2}" -f ($(if ($ok) { 'ok' } else { 'FAIL' })), $c.Name, ($(if (-not $ok) { " -> $($problems.Count): $($problems -join '; ')" } else { '' }))) -ForegroundColor ($(if ($ok) { 'DarkGray' } else { 'Red' }))
if (-not $ok) { $failed++ }
}
if ($failed -gt 0) { Write-Host "nvapi-readonly-check self-test FAILED ($failed)" -ForegroundColor Red; exit 1 }
Write-Host "nvapi-readonly-check self-test: $($cases.Count) cases, both directions" -ForegroundColor Green
Write-Host "nvapi-readonly-check self-test: $($cases.Count + $overlayCases.Count) cases, both directions" -ForegroundColor Green
exit 0
}
@@ -165,5 +261,28 @@ if ($problems.Count -gt 0) {
exit 1
}
$count = (Get-NvapiCall (Get-Content -LiteralPath $sourcePath -Raw)).Count
Write-Host "nvapi-readonly-check OK - the bridge calls $count NVAPI entry points, each on the list, none a writer or an identifier" -ForegroundColor Green
# The Overlay and the Vulkan layer: what is loaded into a game.
$interfacePath = Join-Path $RepoRoot 'src/native/third_party/nvapi/nvapi_interface.h'
$overlayListPath = Join-Path $RepoRoot 'tools/overlay-nvapi-allowed.txt'
foreach ($path in $interfacePath, $overlayListPath) {
if (-not (Test-Path -LiteralPath $path)) { Write-Host "NVAPI READ-ONLY CHECK FAILED: $path is missing" -ForegroundColor Red; exit 1 }
}
$overlaySources = @{}
foreach ($dir in 'src/native/FrameLedger.Overlay', 'src/native/FrameLedger.VkLayer') {
$root = Join-Path $RepoRoot $dir
if (-not (Test-Path -LiteralPath $root)) { Write-Host "NVAPI READ-ONLY CHECK FAILED: $root is missing" -ForegroundColor Red; exit 1 }
foreach ($file in Get-ChildItem -LiteralPath $root -Recurse -File -Include '*.cpp', '*.h', '*.inl') {
$overlaySources[[IO.Path]::GetRelativePath($RepoRoot, $file.FullName).Replace('\', '/')] = Get-Content -LiteralPath $file.FullName -Raw
}
}
if ($overlaySources.Count -eq 0) { Write-Host 'NVAPI READ-ONLY CHECK FAILED: no Overlay or Vulkan-layer source was found' -ForegroundColor Red; exit 1 }
$overlayProblems = Test-Overlay $overlaySources (Get-Content -LiteralPath $interfacePath -Raw) (Get-Content -LiteralPath $overlayListPath -Raw)
if ($overlayProblems.Count -gt 0) {
Write-Host 'NVAPI READ-ONLY CHECK FAILED (the Overlay):' -ForegroundColor Red
foreach ($p in $overlayProblems) { Write-Host " - $p" -ForegroundColor Red }
exit 1
}
$overlayNames = (Read-AllowedList (Get-Content -LiteralPath $overlayListPath -Raw)).Names
Write-Host "nvapi-readonly-check OK - the bridge calls $count NVAPI entry points, each on the list, none a writer or an identifier; the Overlay names $($overlayNames.Count) interface ids ($($overlayNames -join ', ')), calls no NvAPI function by name, and $($overlaySources.Count) of its sources were read" -ForegroundColor Green
exit 0
+29
View File
@@ -92,3 +92,32 @@ ffxQueryDescHeader::type
ffxQueryDescUpscaleGetGPUMemoryUsage::gpuMemoryUsageUpscaler
FfxApiEffectMemoryUsage::totalUsageInBytes
FfxApiEffectMemoryUsage::aliasableUsageInBytes
# NVIDIA's latency report and sleep status (parameters `lr`, `lf`, `ls`; Advanced metrics train C, owner decisions
# D132, D136). NOT arguments of a hooked call: what the driver wrote into buffers the Overlay handed to its two
# read-only getters (fl_reflex.h). Of a frame: its id, the six pairs of times the spans are made of and, since
# 0.1.0-beta.48 (owner decision D142), the two times the driver works out itself -- the GPU's active render time and
# its frame time. Not read: `inputSampleTime`, the camera, frame-generation and cross-adapter times. Of the sleep
# status: the five switches and the frame-generation multiplier; the sleep interval is not read.
NV_LATENCY_RESULT_PARAMS::frameReport
NV_LATENCY_RESULT_PARAMS::FrameReport::frameID
NV_LATENCY_RESULT_PARAMS::FrameReport::simStartTime
NV_LATENCY_RESULT_PARAMS::FrameReport::simEndTime
NV_LATENCY_RESULT_PARAMS::FrameReport::renderSubmitStartTime
NV_LATENCY_RESULT_PARAMS::FrameReport::renderSubmitEndTime
NV_LATENCY_RESULT_PARAMS::FrameReport::presentStartTime
NV_LATENCY_RESULT_PARAMS::FrameReport::presentEndTime
NV_LATENCY_RESULT_PARAMS::FrameReport::driverStartTime
NV_LATENCY_RESULT_PARAMS::FrameReport::driverEndTime
NV_LATENCY_RESULT_PARAMS::FrameReport::osRenderQueueStartTime
NV_LATENCY_RESULT_PARAMS::FrameReport::osRenderQueueEndTime
NV_LATENCY_RESULT_PARAMS::FrameReport::gpuRenderStartTime
NV_LATENCY_RESULT_PARAMS::FrameReport::gpuRenderEndTime
NV_LATENCY_RESULT_PARAMS::FrameReport::gpuActiveRenderTimeUs
NV_LATENCY_RESULT_PARAMS::FrameReport::gpuFrameTimeUs
NV_GET_SLEEP_STATUS_PARAMS::bLowLatencyMode
NV_GET_SLEEP_STATUS_PARAMS::bFsVrr
NV_GET_SLEEP_STATUS_PARAMS::bCplVsyncOn
NV_GET_SLEEP_STATUS_PARAMS::bUseGameSleep
NV_GET_SLEEP_STATUS_PARAMS::bFullscreenIFlip
NV_GET_SLEEP_STATUS_PARAMS::fgMultiplier
+13 -2
View File
@@ -60,6 +60,11 @@ $script:Parameter = [ordered]@{
g = 'ffxConfigureDescFrameGeneration'
fv = 'sl::FeatureVersion'
fr = 'sl::FeatureRequirements'
# Train C: what NVIDIA's driver wrote into the Overlay's own buffers (fl_reflex.h makes the two calls). `lf` is
# one frame of the report, handed on by index - `lr.frameReport[i]` - and never bound to a name of its own.
lr = 'NV_LATENCY_RESULT_PARAMS'
lf = 'NV_LATENCY_RESULT_PARAMS::FrameReport'
ls = 'NV_GET_SLEEP_STATUS_PARAMS'
desc = 'ffxQueryDescHeader'
}
@@ -81,7 +86,9 @@ $script:CameraStruct = @('sl::Constants', 'ffxDispatchDescFrameGenerationPrepare
# Member names every struct has. The header's reads of them are held to the list like any other; what rule 3 cannot do
# is refuse them elsewhere, where they are members of the Overlay's own structs and of descriptors read since 0.1.0.
$script:SharedMember = @('structVersion', 'type', 'flags', 'reset')
# `frameID` joined them with train C: the driver's latency report has one, and so has the frame-generation prepare
# descriptor the Overlay has read since 0.1.0 (dllmain.cpp counts application frames by it).
$script:SharedMember = @('structVersion', 'type', 'flags', 'reset', 'frameID')
# A C++ source without its comments and string literals: a camera named in the comment that says it is never read is
# not a read.
@@ -112,7 +119,7 @@ function Get-HeaderRead([string]$Code) {
$reads = [System.Collections.Generic.SortedSet[string]]::new([StringComparer]::Ordinal)
$problems = [System.Collections.Generic.List[string]]::new()
foreach ($m in [regex]::Matches($Code, '(?<![\w.>:])(o|d|m|q|k|g|fv|fr)\b(\s*\.\s*([A-Za-z_]\w*))?')) {
foreach ($m in [regex]::Matches($Code, '(?<![\w.>:])(o|d|m|q|k|g|fv|fr|lr|lf|ls)\b(\s*\.\s*([A-Za-z_]\w*))?')) {
$name = $m.Groups[1].Value
if ($m.Groups[3].Success) {
[void]$reads.Add("$($script:Parameter[$name])::$($m.Groups[3].Value)")
@@ -234,6 +241,10 @@ inline void Publish(Accumulators& a, FlAdvancedState* region) noexcept { region-
@{ Name = 'the adapter a game asks about, forwarded by its parameter and never looked into, passes'; Header = $goodHeader; List = $goodList; Other = @{ 'dllmain.cpp' = 'sl::Result Hook(sl::Feature feature, const sl::AdapterInfo& adapterInfo) { return g_orig(feature, adapterInfo); } // never adapterInfo.deviceLUID' }; Expect = 0 },
@{ Name = 'the adapter''s LUID read in the detour FAILS'; Header = $goodHeader; List = $goodList; Other = @{ 'dllmain.cpp' = 'sl::Result Hook(sl::Feature feature, const sl::AdapterInfo& adapterInfo) { Keep(adapterInfo.deviceLUID[0]); return g_orig(feature, adapterInfo); }' }; Expect = 1 },
@{ Name = 'a Vulkan physical device taken from the adapter in the layer FAILS'; Header = $goodHeader; List = $goodList; Other = @{ 'layer.cpp' = 'void* device = info->vkPhysicalDevice;' }; Expect = 1 },
@{ Name = 'the driver''s latency report read through its parameters, a frame handed on by index, passes'; Header = $goodHeader + "`ninline uint64_t IdOf(const NV_LATENCY_RESULT_PARAMS::FrameReport& lf) noexcept { return lf.frameID + lf.simStartTime; }`ninline void ObserveL(const NV_LATENCY_RESULT_PARAMS& lr, Tally& t) noexcept { t.n += IdOf(lr.frameReport[3]); }`ninline uint32_t ObserveS(const NV_GET_SLEEP_STATUS_PARAMS& ls) noexcept { return ls.bLowLatencyMode; }"; List = $goodList + "NV_LATENCY_RESULT_PARAMS::frameReport`nNV_LATENCY_RESULT_PARAMS::FrameReport::frameID`nNV_LATENCY_RESULT_PARAMS::FrameReport::simStartTime`nNV_GET_SLEEP_STATUS_PARAMS::bLowLatencyMode`n"; Other = $goodOther; Expect = 0 },
@{ Name = 'a member of a latency frame the list does not allow FAILS'; Header = $goodHeader + "`ninline uint64_t IdOf(const NV_LATENCY_RESULT_PARAMS::FrameReport& lf) noexcept { return lf.frameID + lf.inputSampleTime; }"; List = $goodList + "NV_LATENCY_RESULT_PARAMS::FrameReport::frameID`n"; Other = $goodOther; Expect = 1 },
@{ Name = 'a frame of the report bound to a name of its own FAILS'; Header = $goodHeader + "`ninline void ObserveL(const NV_LATENCY_RESULT_PARAMS& lr) noexcept { const auto& f = lr.frameReport[0]; Keep(f.simStartTime); const auto& whole = lr; Keep(whole); }"; List = $goodList + "NV_LATENCY_RESULT_PARAMS::frameReport`n"; Other = $goodOther; Expect = 1 },
@{ Name = 'the frame id, which the prepare descriptor has too, is read outside the header; a time of the report is not'; Header = $goodHeader + "`ninline uint64_t IdOf(const NV_LATENCY_RESULT_PARAMS::FrameReport& lf) noexcept { return lf.frameID + lf.simStartTime; }"; List = $goodList + "NV_LATENCY_RESULT_PARAMS::FrameReport::frameID`nNV_LATENCY_RESULT_PARAMS::FrameReport::simStartTime`n"; Other = @{ 'dllmain.cpp' = 'void Hook() { Keep(prep->frameID); Keep(report.frameReport); Keep(r.simStartTime); }' }; Expect = 1 },
@{ Name = 'a header with no read at all FAILS'; Header = '// o.outputWidth is somewhere else'; List = "# nothing`n"; Other = $goodOther; Expect = 1 }
)
foreach ($c in $cases) {
+10
View File
@@ -0,0 +1,10 @@
# The NVAPI interface ids that code loaded into a game may name (Advanced metrics train C; owner decisions D132,
# D136; rule 4's note of 2026-11-13). The Overlay links no NVAPI: it asks an nvapi64.dll the game had already
# loaded for these two addresses, by the ids nvapi_interface.h gives them, and calls them with the Direct3D 12
# device behind the swap chain it hooks (FrameLedger.Overlay/include/fl_reflex.h).
#
# tools/nvapi-readonly-check.ps1 fails the build when an Overlay or Vulkan-layer source names the id of any other
# NVAPI function, when a name here has no id in those sources, or when a name here is a writer - a setter, a
# marker, a sleep - or returns an identifier. Getters only.
NvAPI_D3D_GetLatency
NvAPI_D3D_GetSleepStatus