- FrameLedger.ProcessStats.dll (C++20, loaded by the Agent, never into a game): the game process's dedicated and shared
GPU memory from the documented `GPU Process Memory` performance counters (no handle to the game, every instance of the
pid summed) and its private working set / working set / commit from GetProcessMemoryInfo (EX2, falling back to EX)
through PROCESS_QUERY_LIMITED_INFORMATION only (a sentinel refuses an EX2 answer whose private working set was not
filled). Not D3DKMTQueryStatistics ("Reserved for system use").
ctest fl_process_stats (GPU_INSTANCE on a hardware adapter, NO_GPU_INSTANCE on CI) and fl-probe-processstats.
- Measured first, decision table in spike-notes §16 written before the runs: +512.0 MiB for a 512 MiB buffer,
private working set equal to Windows' own counter, 0.1 ms per read, nothing leaked over 600 reads; dedicated reads a
constant 4.5 MiB above DXGI's local usage, so it is never compared with a budget.
- NativeProcessStats (third facade), GameMemoryReader: a pinned session reads through its held handle; an unpinned
Tier-2 hold opens each process of the executable for the read, refuses a reused pid, sums. CaptureSession tells the
observer which process (ICaptureObserver.Measuring), the recorder forwards it to the poller (ITelemetryPoller.Follow).
- TelemetrySample.Game; five sensor series; schema 0018 (game_vram_dedicated_*, game_ram_private_*, ..., sensor_stats_json);
SeriesAggregates gains Median and Min; a wide .partial sensors chunk (type 8) with type 4 still read; SessionProgress
and SessionHeld carry the game's memory live.
- notice-check accepts a contributor's own copyright line in the same form.
- Tests: the two classes that open a LibreHardwareMonitor Computer run one at a time - GenericCpu.Update threw a
NullReferenceException in the local gate when they ran in parallel (the Agent's own read is already contained).
- Docs corrected in place: 03_METRICS, 18_GPU_VENDOR_APIS, 17_HOOK_ENGINE, 20_OPEN_QUESTIONS (§M7, §H10, new §M11),
04_CAPTURE, 19_SAFETY, 06_DATA_MODEL, 07_IPC, 02_SPEC, 01_ARCHITECTURE, 12_BUILD, CLAUDE.md; the accuracy block and
LIMITATIONS.md.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
202 lines
8.3 KiB
C#
202 lines
8.3 KiB
C#
// SPDX-License-Identifier: GPL-3.0-only
|
|
// Copyright (C) 2026 poli0981 - additional terms under GPLv3 section 7: see NOTICE
|
|
|
|
using System.Runtime.InteropServices;
|
|
using FluentAssertions;
|
|
using FrameLedger.Application.Capture;
|
|
using FrameLedger.Application.Telemetry;
|
|
using FrameLedger.Infrastructure.Capture;
|
|
using FrameLedger.Infrastructure.Telemetry;
|
|
using Microsoft.Win32.SafeHandles;
|
|
|
|
namespace FrameLedger.Infrastructure.Tests.Telemetry;
|
|
|
|
/// <summary>
|
|
/// <see cref="GameMemoryReader"/> over a scripted <see cref="IProcessStats"/> (beta.12, D43): what it may open, what it
|
|
/// sums, and what it refuses to read — the rules <c>03_METRICS</c> §Game process memory states.
|
|
/// </summary>
|
|
public sealed class GameMemoryReaderTests
|
|
{
|
|
private const double _mib = 1024.0 * 1024.0;
|
|
|
|
private sealed class ScriptedStats : IProcessStats
|
|
{
|
|
public Dictionary<uint, ProcessStatsSample> Answers { get; } = [];
|
|
|
|
public List<(uint Pid, ulong Created, bool Held)> Reads { get; } = [];
|
|
|
|
public int Opens { get; private set; }
|
|
|
|
public int Collects { get; private set; }
|
|
|
|
public bool OpenFails { get; set; }
|
|
|
|
public IntPtr Open()
|
|
{
|
|
Opens++;
|
|
return OpenFails ? IntPtr.Zero : new IntPtr(1);
|
|
}
|
|
|
|
public int Collect(IntPtr reader)
|
|
{
|
|
Collects++;
|
|
return 0;
|
|
}
|
|
|
|
public int Read(IntPtr reader, uint pid, ulong creationTime, SafeHandle? process, ref ProcessStatsSample sample)
|
|
{
|
|
ObjectDisposedException.ThrowIf(process is { IsClosed: true }, process!);
|
|
Reads.Add((pid, creationTime, process is not null));
|
|
sample = Answers.TryGetValue(pid, out ProcessStatsSample a) ? a : new ProcessStatsSample { RamStatus = 1 };
|
|
return 0;
|
|
}
|
|
|
|
public void Close(IntPtr reader)
|
|
{
|
|
}
|
|
}
|
|
|
|
private sealed class HeldPin(SafeHandle handle) : ITargetLiveness, IHeldProcessHandle
|
|
{
|
|
public SafeHandle ProcessHandle => handle;
|
|
|
|
public bool HasExited => false;
|
|
|
|
public int? ExitCode => null;
|
|
|
|
public bool IsForeground => true;
|
|
|
|
public void Dispose() => handle.Dispose();
|
|
}
|
|
|
|
private static ProcessStatsSample Full(double dedicatedMib, double privateMib) => new()
|
|
{
|
|
Present = 0x01 | 0x02 | 0x04 | 0x08 | 0x10,
|
|
GpuDedicatedBytes = (ulong)(dedicatedMib * _mib),
|
|
GpuSharedBytes = (ulong)(64 * _mib),
|
|
PrivateWorkingSetBytes = (ulong)(privateMib * _mib),
|
|
WorkingSetBytes = (ulong)((privateMib + 100) * _mib),
|
|
CommitBytes = (ulong)((privateMib + 200) * _mib),
|
|
GpuInstances = 1,
|
|
};
|
|
|
|
[Fact]
|
|
public void NothingFollowedReadsNothingAndOpensNothing()
|
|
{
|
|
var stats = new ScriptedStats();
|
|
using var reader = new GameMemoryReader(stats);
|
|
|
|
reader.TryRead(out ProcessReading reading).Should().BeFalse();
|
|
reading.IsEmpty.Should().BeTrue();
|
|
stats.Opens.Should().Be(0, "no session has a process yet: the counter query is not even opened");
|
|
}
|
|
|
|
[Fact]
|
|
public void APinnedGameIsReadThroughTheHandleTheSessionHolds()
|
|
{
|
|
var stats = new ScriptedStats();
|
|
stats.Answers[4242] = Full(9216, 6000);
|
|
using var reader = new GameMemoryReader(stats);
|
|
using var handle = new SafeProcessHandle(new IntPtr(-1), ownsHandle: false);
|
|
using var pin = new HeldPin(handle);
|
|
|
|
reader.Follow(GameProcess.Pinned(4242, pin));
|
|
reader.TryRead(out ProcessReading r).Should().BeTrue();
|
|
|
|
stats.Reads.Should().ContainSingle().Which.Should().Be((4242u, 0ul, true), "the pin's own handle; no creation-time check is needed while it is held");
|
|
r.VramDedicatedMb.Should().BeApproximately(9216, 0.001);
|
|
r.VramSharedMb.Should().BeApproximately(64, 0.001);
|
|
r.RamPrivateMb.Should().BeApproximately(6000, 0.001);
|
|
r.RamWorkingSetMb.Should().BeApproximately(6100, 0.001);
|
|
r.CommitMb.Should().BeApproximately(6200, 0.001);
|
|
r.Processes.Should().Be(1);
|
|
r.Sources.Should().Be(ProcessReadingSources.Counters | ProcessReadingSources.PrivateWorkingSetRead | ProcessReadingSources.HeldHandle);
|
|
stats.Collects.Should().Be(1, "one counter collection per tick");
|
|
}
|
|
|
|
[Fact]
|
|
public void AnUnpinnedHoldSumsItsVerifiedProcessesAndLeavesOutAReusedOrRefusedPid()
|
|
{
|
|
var stats = new ScriptedStats();
|
|
stats.Answers[100] = Full(1000, 500);
|
|
stats.Answers[200] = Full(2000, 700);
|
|
stats.Answers[300] = Full(4000, 900) with { RamStatus = 2 }; // FL_PS_RAM_PID_REUSED: another process now
|
|
// 400 has no answer: the scripted DLL says OPEN_DENIED.
|
|
using var reader = new GameMemoryReader(stats);
|
|
DateTimeOffset t = DateTimeOffset.FromFileTime(133_000_000_000_000_000);
|
|
|
|
reader.Follow(GameProcess.Unpinned([new(100, t), new(200, t.AddSeconds(1)), new(300, t), new(400, t)]));
|
|
reader.TryRead(out ProcessReading r).Should().BeTrue();
|
|
|
|
stats.Reads.Select(static x => x.Held).Should().AllBeEquivalentTo(false, "a hold that never pinned the game opens each process for the read");
|
|
stats.Reads.First(static x => x.Pid == 200).Created.Should().Be((ulong)t.AddSeconds(1).ToFileTime(), "the snapshot's creation time is what the DLL checks");
|
|
r.Processes.Should().Be(2, "only the two processes whose identity was verified count");
|
|
r.VramDedicatedMb.Should().BeApproximately(3000, 0.001, "1000 + 2000 — never the reused pid's 4000");
|
|
r.RamPrivateMb.Should().BeApproximately(1200, 0.001);
|
|
r.Sources.Should().HaveFlag(ProcessReadingSources.TransientHandle);
|
|
}
|
|
|
|
[Fact]
|
|
public void AFieldNoProcessAnsweredStaysNullAndAnEmptyReadingIsNotAReading()
|
|
{
|
|
var stats = new ScriptedStats();
|
|
stats.Answers[7] = new ProcessStatsSample { Present = 0x01 | 0x04, WorkingSetBytes = (ulong)(300 * _mib), CommitBytes = (ulong)(400 * _mib) };
|
|
using var reader = new GameMemoryReader(stats);
|
|
using var handle = new SafeProcessHandle(new IntPtr(-1), ownsHandle: false);
|
|
using var pin = new HeldPin(handle);
|
|
|
|
reader.Follow(GameProcess.Pinned(7, pin));
|
|
reader.TryRead(out ProcessReading r).Should().BeTrue();
|
|
|
|
r.VramDedicatedMb.Should().BeNull("no counter instance named the process: N/A, never 0");
|
|
r.RamPrivateMb.Should().BeNull("Windows without PROCESS_MEMORY_COUNTERS_EX2: the private working set is N/A");
|
|
r.RamWorkingSetMb.Should().BeApproximately(300, 0.001);
|
|
r.Sources.Should().HaveFlag(ProcessReadingSources.WorkingSetReadOnly);
|
|
|
|
stats.Answers[7] = default;
|
|
reader.TryRead(out ProcessReading none).Should().BeFalse();
|
|
none.IsEmpty.Should().BeTrue();
|
|
}
|
|
|
|
[Fact]
|
|
public void APinReleasedBeforeTheReadIsNothingToSayAndNeverAThrow()
|
|
{
|
|
var stats = new ScriptedStats();
|
|
stats.Answers[9] = Full(100, 100);
|
|
using var reader = new GameMemoryReader(stats);
|
|
using var handle = new SafeProcessHandle(new IntPtr(-1), ownsHandle: true);
|
|
using (var pin = new HeldPin(handle))
|
|
{
|
|
reader.Follow(GameProcess.Pinned(9, pin));
|
|
}
|
|
|
|
reader.TryRead(out ProcessReading r).Should().BeFalse();
|
|
r.IsEmpty.Should().BeTrue();
|
|
}
|
|
|
|
[Fact]
|
|
public void AReaderThatCouldNotOpenTriesAgainOnlyEveryFewTicksAndNoneIsFollowedAfterward()
|
|
{
|
|
var stats = new ScriptedStats { OpenFails = true };
|
|
using var reader = new GameMemoryReader(stats);
|
|
using var handle = new SafeProcessHandle(new IntPtr(-1), ownsHandle: false);
|
|
using var pin = new HeldPin(handle);
|
|
reader.Follow(GameProcess.Pinned(5, pin));
|
|
|
|
for (int i = 0; i < GameMemoryReader.ReopenEvery; i++)
|
|
{
|
|
reader.TryRead(out _).Should().BeFalse();
|
|
}
|
|
|
|
stats.Opens.Should().Be(1, "the DLL is absent or out of memory: asking again every tick would only repeat the answer");
|
|
stats.OpenFails = false;
|
|
stats.Answers[5] = Full(10, 10);
|
|
reader.TryRead(out ProcessReading r).Should().BeTrue("the back-off is over: the reader opens and reads");
|
|
stats.Opens.Should().Be(2);
|
|
r.VramDedicatedMb.Should().BeApproximately(10, 0.001);
|
|
|
|
reader.Follow(GameProcess.None);
|
|
reader.TryRead(out _).Should().BeFalse("the session let the process go");
|
|
}
|
|
}
|