From 9a763e06acd220bc8e406915cd05a035a4129403 Mon Sep 17 00:00:00 2001 From: leroy ketelaars Date: Thu, 12 Nov 2026 15:39:41 +0000 Subject: [PATCH 1/2] Retire idle detail resources and detach optional ARAM caching --- docs/aram-residency.md | 137 +++++++++ docs/measurements/aram/engine-dolphin.json | 289 ++++++++++++++++++ docs/measurements/memory/world-payload.json | 32 +- docs/memory-reduction-audit.md | 35 ++- samples/Validation/Program.cs | 6 +- src/Hypercube.Core/ResourceScheduler.cs | 11 +- src/Hypercube.GameCube/AramCache.cs | 64 +++- src/Hypercube.GameCube/TexturePool.cs | 46 ++- src/Hypercube.GameCube/WorldStreamer.cs | 140 +++++++-- .../AramCacheChecks.cs | 74 ++++- .../Hypercube.GameCube.Tests.csproj | 2 + tests/Hypercube.GameCube.Tests/Program.cs | 22 +- .../StreamingChecks.cs | 206 +++++++++++++ .../StreamingTextureMock.cs | 43 +++ .../TexturePoolChecks.cs | 45 +++ tests/test_dolphin_memory_validation.py | 37 +++ tests/test_memory_audit.py | 10 +- tools/dolphin_validation.py | 19 +- tools/memory_audit.py | 17 +- 19 files changed, 1154 insertions(+), 81 deletions(-) create mode 100644 docs/aram-residency.md create mode 100644 docs/measurements/aram/engine-dolphin.json create mode 100644 tests/Hypercube.GameCube.Tests/StreamingChecks.cs create mode 100644 tests/Hypercube.GameCube.Tests/StreamingTextureMock.cs create mode 100644 tests/Hypercube.GameCube.Tests/TexturePoolChecks.cs create mode 100644 tests/test_dolphin_memory_validation.py diff --git a/docs/aram-residency.md b/docs/aram-residency.md new file mode 100644 index 0000000..cfa2a43 --- /dev/null +++ b/docs/aram-residency.md @@ -0,0 +1,137 @@ +# Cold resource residency + +The V1 world streamer now reclaims genuinely unused detailed native resources +and can retain their verified packed source bytes in ARAM. Coarse world patches, +coarse textures and decoded movement data remain available while detail restores. +ARAM cannot be rendered directly; cache hits still need native creation or +texture staging before publication. + +## Defaults and controls + +`WorldStreamer` retains both existing constructor signatures. Normal pumping +uses these public controls: + +```csharp +streamer.RetireIdleResources = true; +streamer.IdleResourceFrames = 120; +streamer.IdleTextureFrames = 120; +streamer.MaximumIdleReleases = 2; +streamer.WarmTextureHighBytes = 32768; +streamer.WarmTextureLowBytes = 16384; +``` + +At 60 frames per second, the default demand dwell is two seconds. Detailed meshes +and texture mappings must remain undemanded throughout that window, and their +last submitted frame must have completed before retirement. Re-demand resets +the dwell. Collision residents are excluded from automatic idle retirement; +normal budget-pressure eviction and movement-readiness checks remain in force. + +Retiring a mesh frees its native geometry. Retiring a texture mapping leaves its +physical pair available for fast reuse. When idle texture bytes exceed the high +watermark, physical trimming starts after the separate texture dwell and continues +to the low watermark. Each pump retires at most the configured number of logical +residents and trims at most that many texture pairs. Pending texture copies and +GPU readers prevent reuse and trimming. These controls allow bounded warm reuse +for camera reversals rather than allocating on every visibility change. + +Set `RetireIdleResources=false` for a fixed-policy comparison. This disables +automatic dwell-based reclamation, while preserving the existing hard residency +budget and pressure eviction. A frame count is a policy input, not a hardware +timing guarantee; callers supply monotonic `Frame` and actual `CompletedFrame` +values and pump between graphics frames. + +## Optional cold writes + +`UseAram` remains opt-in. The validation's ARAM and fault scenarios enable it; +other scenarios remain useful storage controls. A verified, admitted record may +be copied into one lazy 16 KiB native cold-write buffer using the world's existing +decode scratch. One optional upload can be outstanding at a time. Further writes +are skipped while that buffer is busy, or when a record exceeds its capacity. +Large records remain recoverable from the pack on storage. No second full-size +read buffer is allocated. + +Cold writes no longer retain the main read/upload source or keep its batch active. +A subsequent visible batch can progress while the separate cold buffer is owned +by DMA. The cold buffer is never overwritten or freed before its task completes. +The SDK transfer queue still owns the native holds; completion releases them. +Copy, allocation and asynchronous cache failures only disable that optional +cache entry. A synchronous admission failure backs off for 120 frames rather +than repeatedly allocating on every record. + +The cache now exposes `Missing`, `Filling`, `Ready` and `Failed`. `Has` only +returns true for `Ready`. Polling observes completion, releases failed or +cancelled allocations exactly once, and permits a later retry. Filling entries +cannot be fetched, replaced, evicted or removed. Cache disposal requires uploads +to drain; existing clear-and-reuse behavior is retained. Native holds allow an +already-issued fetch to finish after the ready entry is removed. + +`Stop()` drains both foreground work and optional cold writes without starting +new work. `Dispose()` rejects undrained owners. Optional writes do not gate +ordinary foreground batches, but shutdown must still preserve their source +lifetime. + +## Mixed cache hits and publication + +An all-storage batch retains its coalesced read. A batch containing any ready +cache entry fetches hits from ARAM and coalesces consecutive misses into storage +runs. Cached entries split those runs. One miss no longer discards the other +records' cache benefit, and several adjacent misses need only one media read. +Cache-transfer +failure invalidates that entry and falls back to storage. Cached data that fails +the ordinary CRC check is removed so subsequent retries use the source of truth. + +Generations, stale cancellation, source/upload drain, checksums and explicit +texture publication remain authoritative. An ARAM hit is never exposed directly +to a material, and a cancelled or failed upload cannot publish visible content. + +## Accounting and performance limits + +`PhysicalBytes` retains its dynamic-native-residency meaning, including reusable +idle texture pairs. `Policy.ResidentBytes` only counts logical residents. +`StagingBytes` remains the original read-source allocation. +`ColdStagingBytes` separately reports the lazy 16 KiB cold buffer. The validation +includes both staging allocations in native baselines and teardown checks. + +Cold ARAM allocations and metadata are separate. Active cache metadata adds one +`Task?[recordCount+1]` array; it is absent while the cache has never admitted an +allocation. The idle-residency policy adds bounded bookkeeping for 128 resources +and 48 texture pairs. These managed fields/arrays do not reduce the SDK's reserved +managed heap. Compare actual reclaimed native bytes against the extra cold buffer +and metadata rather than treating cache bytes as MEM1 savings. + +`ColdWriteBytes` and `Cold.StoreBytes` report aligned requested upload bytes; +they include submitted requests that later fail. `AramBytes` counts requested +aligned fetch bytes. `PartialCacheBatches`, `ColdWriteSkips`, `ColdWriteFailures`, +`ColdReadFailures`, `ColdReleases` and `ColdTextureTrims` expose policy activity. +The DMA service can split requests internally; these are not hardware bus-byte +measurements or queue-latency statistics. + +The frame budget still cannot preempt an individual native allocation, copy or +free. The extra source snapshot copies at most 16 KiB twice on the application +executor. The pinned SDK routes the compatible copy calls through its shared +native DMA broker: cache restores use demand priority and optional writes use +background priority. It reconsiders priority at each DMA boundary of at most +16 KiB, with round-robin service for independent equal-priority requests. +Conflicting ARAM or MEM1 ranges preserve submission order, and an active DMA +must drain before another can begin. Chunk bounds therefore do not guarantee +restoration deadlines; queue wait, dependent snapshots and bus contention still +need measurement. The engine retains the original public copy signatures. + +Acceptance requires matching scene quality, request replay and cold/warm state, +then comparing native high water, selected-detail readiness, allocations and +p95/p99 frame times with audio active. Camera reversals, rapid movement, ARAM +exhaustion and storage fallback are required cases. Host/AOT/Dolphin ownership +checks do not establish original-console throughput or zero contention. + +## Recorded fixture acceptance + +The [Release Dolphin evidence](measurements/aram/engine-dolphin.json) records the +SDK revision, tested working-tree source hashes and immutable DOL/data-disc +hashes. All eleven scenarios completed with mask 2047. The occlusion comparison +matched all 199,680 tested pixels, and the DSP capture contains 188.656 seconds +of continuous audio with no quiet windows. Native accounting returned to its +544 KiB baseline after leaving the two scenarios with a 16 KiB cold source. + +This software-rendered Dolphin run verifies functional behavior and ownership. +It is not a stock-console performance benchmark, and its quantized guest frame +counters do not establish zero overhead or matched-quality throughput. diff --git a/docs/measurements/aram/engine-dolphin.json b/docs/measurements/aram/engine-dolphin.json new file mode 100644 index 0000000..bb47f30 --- /dev/null +++ b/docs/measurements/aram/engine-dolphin.json @@ -0,0 +1,289 @@ +{ + "schema": 1, + "kind": "host-dolphin-fixture-acceptance", + "hardwareValidation": false, + "source": { + "engineBase": "a5d2eea566c0521aa5a91a8b177ebdd11df49518", + "engineSourceWasUncommitted": true, + "sdkRevision": "a219fa35b2cd0aea725976461cdc0e5444b040d2", + "sha256": { + "src/Hypercube.Core/AssetCatalog.cs": "860dec978853f27ae5663b8e9d364953b0768c4b9641f3f10a97db16cb92819c", + "src/Hypercube.Core/CameraFrustum.cs": "4fa9c9bb5b68a0fe0c95d2b4bdd489343c8c181ec1071c59f3a0da3651f54c24", + "src/Hypercube.Core/DemandPlan.cs": "19a724c9f62afd54cf797c82186ff80ac002b8e1f9095116159ffb06d19b054c", + "src/Hypercube.Core/FrameMetrics.cs": "639a5fc2d1144fe2f3ea61e29a1a4ea70fdc1d59292b58a2f4d674e83991d3b2", + "src/Hypercube.Core/FrameProfile.cs": "7397adebe6aa26ff97c2859182328eb013ed1e1a1931e08ee3881884c0885477", + "src/Hypercube.Core/MaterialMotion.cs": "dbe53eecf906530d5e832d9926e84992b5921f5153df59068ba9dfb8e6940f90", + "src/Hypercube.Core/OpaqueDrawQueue.cs": "d57f6f8b44199bf1ecff51ce258c1c893710a819135ea796aa9a3eba284457ca", + "src/Hypercube.Core/RenderCounters.cs": "f5ac676b4274b0fab838a95df24bbd8b3c3de6b92d9d80036182c414103abd00", + "src/Hypercube.Core/ResourceLeases.cs": "bf63bc89400f6243f4ec8135ce06ba34f6111bba75a52412a1dbb9ea0f73da06", + "src/Hypercube.Core/ResourceScheduler.cs": "fb1ffe07b77d9489503abeb4c7d9bfdb788d34c598242442670dc00f0be2d84c", + "src/Hypercube.Core/ScenePolicy.cs": "4e7093b317cecbaa9f41a40ac21c97104e331af1c9fedadb1be38065c5ffb100", + "src/Hypercube.Core/SceneTree.cs": "3977897cfe31068c9d3683a798a725736e1e8508179a1968fbf91ef404997934", + "src/Hypercube.Core/StreamingBufferPolicy.cs": "fe4d0dd1d4ec6c6466fbfb9265d20818048d00f80219b0b3ceb43184d0dc6eae", + "src/Hypercube.Core/TelemetryRuns.cs": "2b0876b8ed39e6f59ca8cc2fcc59e11577187ba38bdc38102c33b5aa446b8bdd", + "src/Hypercube.Core/TextureFamilies.cs": "9fb7c1e039305b0c5fcc009579c086f2fbc21509dbee5bc6a99ee61427e5f904", + "src/Hypercube.Core/TextureLodPolicy.cs": "092c28c09cdab261c3ba5b40feed30d6240877716ac24c1cf7cf5864bf14697f", + "src/Hypercube.Core/Visibility.cs": "e8632395ae11de52199a63ee323596307ff7a24186e22a6f83cefad8f0e19a00", + "src/Hypercube.GameCube/AramCache.cs": "b4997af1f3a54dfc7fa84a82c25e0ba27602d766ccb3bffcf35469acd04ee9b7", + "src/Hypercube.GameCube/WorldStreamer.cs": "b50d0ccdafd7806534e3490b606bdc450defe9e0f3fb605cc92bce01bd93f051", + "src/Hypercube.GameCube/TexturePool.cs": "848c0943c606067de8a7e2461b296005cf886d36171d55324f3ba6851926357a", + "src/Hypercube.GameCube/PackedWorld.cs": "e96e81d532323369c7c23cb6c9b48f5c6db2bd3f7c6e764a15fcb9ede5c7844e", + "samples/Validation/Program.cs": "ba2666bd8c1a3a78675fb2521609422015f3cfe04461987f306bc2987a68c8bf" + } + }, + "artifacts": [ + { + "path": "Game.dol", + "bytes": 1678368, + "sha256": "cab41823659016c63f9df5cdb7e7fad8432eafdfab1fb6e67d091765535c9e0f" + }, + { + "path": "world.iso", + "bytes": 2191360, + "sha256": "e882962d95064eabebe9d4c5d522c44036fe1a7c5deb1aba85c01bc453c65de4" + }, + { + "path": "world.hcp", + "bytes": 2156768, + "sha256": "0a782f8137b426528a185cb8bbb5a67ae50d8fc5448ef6a88d56016daec49024" + } + ], + "execution": { + "containerImage": "animaltown-title-dolphin:local", + "dsp": "LLE", + "configuration": "Release", + "wallRecordingSeconds": 480, + "sampledFrames": 377, + "sampleRateHz": 2 + }, + "acceptance": { + "completedScenarios": 11, + "completedMask": 2047, + "guestFrame": 11282, + "occlusionComparison": { + "referenceDraws": 28, + "culledDraws": 26, + "comparedPixels": 199680, + "changedPixels": 0, + "maxChannelDifference": 0 + }, + "audio": [ + { + "file": "ID-Game_2026-11-12_15-22-33_dspdump1.wav", + "seconds": 188.65603014029392, + "activeWindows": 1887, + "longestQuietMs": 0 + } + ], + "baselineResourceKiB": 544, + "coldStagingCapacityBytes": 16384, + "nativeExcessKiBByScenario": [ + { + "scenario": 0, + "minimumExcessKiB": 0, + "maximumExcessKiB": 0 + }, + { + "scenario": 1, + "minimumExcessKiB": 0, + "maximumExcessKiB": 0 + }, + { + "scenario": 2, + "minimumExcessKiB": 0, + "maximumExcessKiB": 0 + }, + { + "scenario": 3, + "minimumExcessKiB": 0, + "maximumExcessKiB": 0 + }, + { + "scenario": 4, + "minimumExcessKiB": 0, + "maximumExcessKiB": 1 + }, + { + "scenario": 5, + "minimumExcessKiB": 0, + "maximumExcessKiB": 0 + }, + { + "scenario": 6, + "minimumExcessKiB": 16, + "maximumExcessKiB": 17 + }, + { + "scenario": 7, + "minimumExcessKiB": 16, + "maximumExcessKiB": 16 + }, + { + "scenario": 8, + "minimumExcessKiB": 0, + "maximumExcessKiB": 0 + }, + { + "scenario": 9, + "minimumExcessKiB": 0, + "maximumExcessKiB": 0 + }, + { + "scenario": 10, + "minimumExcessKiB": 0, + "maximumExcessKiB": 0 + } + ], + "completedCases": [ + { + "scenario": 0, + "frame": 673, + "caseFrames": 673, + "completedMask": 1, + "nativeKiB": 927, + "dynamicKiB": 383, + "residentKiB": 383, + "aramKiB": 0, + "aramHits": 0, + "failures": 0, + "cancelled": 831 + }, + { + "scenario": 1, + "frame": 1362, + "caseFrames": 671, + "completedMask": 3, + "nativeKiB": 898, + "dynamicKiB": 354, + "residentKiB": 304, + "aramKiB": 0, + "aramHits": 0, + "failures": 0, + "cancelled": 685 + }, + { + "scenario": 2, + "frame": 2051, + "caseFrames": 664, + "completedMask": 7, + "nativeKiB": 694, + "dynamicKiB": 150, + "residentKiB": 142, + "aramKiB": 0, + "aramHits": 0, + "failures": 0, + "cancelled": 694 + }, + { + "scenario": 3, + "frame": 2771, + "caseFrames": 690, + "completedMask": 15, + "nativeKiB": 694, + "dynamicKiB": 150, + "residentKiB": 140, + "aramKiB": 0, + "aramHits": 0, + "failures": 0, + "cancelled": 738 + }, + { + "scenario": 4, + "frame": 3460, + "caseFrames": 688, + "completedMask": 31, + "nativeKiB": 718, + "dynamicKiB": 174, + "residentKiB": 161, + "aramKiB": 0, + "aramHits": 0, + "failures": 0, + "cancelled": 273 + }, + { + "scenario": 5, + "frame": 4149, + "caseFrames": 686, + "completedMask": 63, + "nativeKiB": 743, + "dynamicKiB": 199, + "residentKiB": 199, + "aramKiB": 0, + "aramHits": 0, + "failures": 0, + "cancelled": 169 + }, + { + "scenario": 6, + "frame": 4839, + "caseFrames": 685, + "completedMask": 127, + "nativeKiB": 740, + "dynamicKiB": 180, + "residentKiB": 167, + "aramKiB": 180, + "aramHits": 74, + "failures": 0, + "cancelled": 277 + }, + { + "scenario": 7, + "frame": 5528, + "caseFrames": 683, + "completedMask": 255, + "nativeKiB": 722, + "dynamicKiB": 162, + "residentKiB": 150, + "aramKiB": 98, + "aramHits": 37, + "failures": 30, + "cancelled": 385 + }, + { + "scenario": 8, + "frame": 6217, + "caseFrames": 680, + "completedMask": 511, + "nativeKiB": 591, + "dynamicKiB": 47, + "residentKiB": 47, + "aramKiB": 0, + "aramHits": 0, + "failures": 25, + "cancelled": 464 + }, + { + "scenario": 9, + "frame": 6907, + "caseFrames": 675, + "completedMask": 1023, + "nativeKiB": 544, + "dynamicKiB": 0, + "residentKiB": 0, + "aramKiB": 0, + "aramHits": 0, + "failures": 0, + "cancelled": 0 + }, + { + "scenario": 10, + "frame": 11282, + "caseFrames": 4359, + "completedMask": 2047, + "nativeKiB": 544, + "dynamicKiB": 0, + "residentKiB": 0, + "aramKiB": 0, + "aramHits": 0, + "failures": 0, + "cancelled": 0 + } + ] + }, + "limits": [ + "Functional ownership, rendering, movement, fault and audio acceptance in software-rendered Dolphin.", + "Source hashes identify the working-tree runtime tested before the final dependency-pin commit.", + "Native excess permits one KiB of independent native/resident integer rounding; the 16 KiB cold source occurs only in scenarios 6 and 7 and is gone in scenario 8.", + "This is not an original-console or matched-replay performance benchmark; quantized guest frame counters do not prove zero overhead." + ] +} diff --git a/docs/measurements/memory/world-payload.json b/docs/measurements/memory/world-payload.json index cb9c4a0..045ba80 100644 --- a/docs/measurements/memory/world-payload.json +++ b/docs/measurements/memory/world-payload.json @@ -3,6 +3,7 @@ "Selected array element payload only; object field changes, headers and allocator rounding excluded.", "Managed heap reservation is unchanged; these are occupancy reductions.", "Cold ARAM, permanent geometry, active/idle texture pairs, framebuffers and SDK heaps are separate.", + "The optional cold-write ring is extra MEM1; only physically retired residents create further savings.", "Unsupported large records retain their existing demand-time rejection." ], "hardwareMeasurement": false, @@ -13,12 +14,24 @@ "saved": 5200 }, "enabledAfterFirstStore": { - "after": 5200, + "after": 7800, "before": 5200, - "saved": 0 + "saved": -2600 }, "targetPointerBytes": 4 }, + "idleLifecycleArrayPayload": { + "cachedReadFlagsBytes": 8, + "change": { + "after": 904, + "before": 32, + "saved": -872 + }, + "idleResourceFramesBytes": 512, + "poolIdleAndFenceBytes": 384, + "removedStoreTaskReferencesBytes": 32, + "targetPointerBytes": 4 + }, "largestSupportedStreamRecord": 73984, "maximumReadBatchBytes": 65536, "nativeStagingBytes": { @@ -26,6 +39,15 @@ "before": 131072, "saved": 57088 }, + "optionalColdWriteStaging": { + "allocatedLazily": true, + "bufferBytes": 16384, + "sourceAndColdBuffers": { + "after": 90368, + "before": 131072, + "saved": 40704 + } + }, "records": 649, "retainedManagedPayload": { "catalogIds": { @@ -40,8 +62,12 @@ "saved": 1300 } }, - "schema": 1, + "schema": 2, "scope": "validated-v1-world-payload-accounting", + "selectedManagedArraySavings": { + "coldCacheActive": 690, + "coldCacheUnused": 8490 + }, "sourceSha256": "0a782f8137b426528a185cb8bbb5a67ae50d8fc5448ef6a88d56016daec49024", "transientCatalogTailPayload": { "after": 192, diff --git a/docs/memory-reduction-audit.md b/docs/memory-reduction-audit.md index 48fc805..2ae383b 100644 --- a/docs/memory-reduction-audit.md +++ b/docs/memory-reduction-audit.md @@ -20,11 +20,21 @@ not a physical-console trace. | Catalog ID indexes/links, retained managed payload | 5,724 B | 2,862 B | 2,862 B | | Scheduler ID-to-slot lookup, retained managed payload | 2,600 B | 1,300 B | 1,300 B | | ARAM metadata while unused, managed payload on 32-bit target | 5,200 B | 0 B | 5,200 B | +| ARAM metadata once active, including pending transfer references | 5,200 B | 7,800 B | -2,600 B | +| Selected idle/fence/read-state arrays, replacing store-task references | 32 B | 904 B | -872 B | +| Optional cold-write native buffer, allocated lazily | 0 B | 16,384 B | -16,384 B | | Temporary catalog mesh-tail payload | 384 B | 192 B | 192 B | -The native staging reduction is **57,088 bytes**. The selected retained arrays -save **9,362 B of element payload** while the cold cache is unused, or 4,162 B -after its first successful cold allocation. These figures exclude object field +The read-source reduction remains **57,088 bytes**. Once the optional cold-write +buffer is allocated, the two native buffers together save **40,704 bytes** over +the baseline source buffer. Additional native savings depend on actually +retiring unused resident geometry and texture pairs; retaining a cold copy alone +does not free their MEM1 allocations. See [cold residency](aram-residency.md). + +After the new idle/fence bookkeeping and pending-transfer references, the selected +retained arrays save **8,490 B of element payload** while the cold cache is unused, +or **690 B** once it is active. The catalog/scheduler index arrays themselves +still save 4,162 B. These figures exclude object field changes, object/array headers and allocator rounding; they are not a whole managed-heap net total. The SDK's reserved managed heap is unchanged: lower live occupancy reduces pressure but does not automatically return that reservation to the @@ -71,8 +81,10 @@ An unused `AramCache` no longer reserves per-record entry/age arrays. Metadata i created only after the first native cold allocation succeeds; empty probes, over-budget stores and failed native allocation do not allocate it. Once active, the cache uses the same bounds and LRU/protected-ID behavior. On the -32-bit target this avoids `8*(recordCount+1)` payload bytes while unused, up to -32,776 B at 4,096 records. This one-time first-use allocation may occur during +32-bit target this avoids the baseline's `8*(recordCount+1)` payload bytes while +unused, up to 32,776 B at 4,096 records. The active cache now also tracks pending +store tasks, charging `12*(recordCount+1)` bytes instead of the baseline's eight +bytes per entry. This one-time first-use allocation may occur during streaming; normal stores already allocate transfer/ARAM ownership. Callers still drain transfers before disposal. Zero-ID entries are now evicted and freed correctly. @@ -89,11 +101,14 @@ partial ownership is released. ## DolphinDotNet audit -The SDK changes are delivered separately in -[DolphinDotNet PR #171](https://github.com/capz/DolphinDotNet/pull/171). This engine -keeps its source pin and published NuGet dependency on SDK 318 until a matching -SDK release is available; source and package consumers must use the same reviewed -SDK revision. The engine reductions above work with SDK 318 independently. +The original SDK allocation reductions were delivered in +[DolphinDotNet PR #171](https://github.com/capz/DolphinDotNet/pull/171). The later +cold-residency work uses the shared broker from +[DolphinDotNet PR #173](https://github.com/capz/DolphinDotNet/pull/173). The source +pin in `.sdk-revision` and the published dependency in `Directory.Build.props` +must identify the same reviewed SDK revision. The original compact indexes and +bounded source buffer remain compatible with SDK 318 APIs; prioritized DMA is +provided by the newer broker. The SDK renderer previously reserved two 4,096-entry model submission tables, although it admits at most 4,096 submissions in total. A shared table preserves diff --git a/samples/Validation/Program.cs b/samples/Validation/Program.cs index 0f0e722..b9be928 100644 --- a/samples/Validation/Program.cs +++ b/samples/Validation/Program.cs @@ -101,7 +101,7 @@ internal ProbeScene(string path) DebugOverlay.WriteLine("BOOT: AUDIO LOADED"); streamer=new WorldStreamer(world,path,Budget);Configure(); DebugOverlay.WriteLine("BOOT: STREAMER READY"); - baseline=device.NativeBytes-streamer.PhysicalBytes; + baseline=device.NativeBytes-streamer.PhysicalBytes-streamer.ColdStagingBytes; caseAt=lastTick=Clock.Timestamp; device.BeginFrame(new Color32(8,10,19));device.EndFrame(); } @@ -152,6 +152,8 @@ private void Transition() { streamer.Frame=frame; if(!streamer.Stop())return; + // baseline contains the read source; the lazy cold source is charged + // separately in the per-frame assertion and must also disappear here. int stagingBytes=streamer.StagingBytes;streamer.Dispose(); if(device.NativeBytes!=baseline-stagingBytes)throw new InvalidOperationException("Native resources leaked across a scenario transition."); if(Aram.Statistics.AllocatedBytes!=0)throw new InvalidOperationException("ARAM transfers or allocations leaked across a scenario transition."); @@ -297,7 +299,7 @@ internal void Present() if(ProfilingSuite)RecordProfilePump(pumpAt,decodeBefore,createBefore); prepareAt=ProfilingSuite?Clock.Timestamp:0; actorTransform.LocalPosition=new Vector3(actorX,actorY,actorZ); - if(device.NativeBytes!=baseline+streamer.PhysicalBytes||streamer.PhysicalBytes>streamer.Policy.BudgetBytes) + if(device.NativeBytes!=baseline+streamer.PhysicalBytes+streamer.ColdStagingBytes||streamer.PhysicalBytes>streamer.Policy.BudgetBytes) throw new InvalidOperationException("Native resource accounting or dynamic budget failed."); if(!voice.IsPlaying)throw new InvalidOperationException("Audio voice stopped during streaming."); #if HYPERCUBE_ONEMS diff --git a/src/Hypercube.Core/ResourceScheduler.cs b/src/Hypercube.Core/ResourceScheduler.cs index 195f590..8c27767 100644 --- a/src/Hypercube.Core/ResourceScheduler.cs +++ b/src/Hypercube.Core/ResourceScheduler.cs @@ -36,6 +36,7 @@ public ResourceScheduler(AssetCatalog catalog, int capacity, int budgetBytes) public int Generation(int slot) => generations[slot]; public ResourceState State(int slot) => states[slot]; public ResourcePriority Priority(int slot) => (ResourcePriority)priorities[slot]; + public bool IsDemanded(int slot) => references[slot] > 0; public int Find(int id) { if(id<=0||id>=lookup.Length)return -1; @@ -168,16 +169,16 @@ public void Publish(int slot, int physicalBytes) public int EvictionCandidate(int completedFrame, ResourcePriority incoming = ResourcePriority.Optional) { int best = -1; - for (int i = 0; i < ids.Length; i++) if (states[i] == ResourceState.Resident && - (references[i] == 0 || priorities[i] > (int)incoming) && - fences[i] <= completedFrame && + for (int i = 0; i < ids.Length; i++) if (CanEvict(i,completedFrame,incoming) && (best < 0 || priorities[i] > priorities[best] || priorities[i] == priorities[best] && touched[i] < touched[best])) best = i; return best; } + public bool CanEvict(int slot,int completedFrame,ResourcePriority incoming=ResourcePriority.Optional) + => states[slot]==ResourceState.Resident && + (references[slot]==0 || priorities[slot]>(int)incoming) && fences[slot]<=completedFrame; public void Evict(int slot, int completedFrame, ResourcePriority incoming = ResourcePriority.Optional) { - if (states[slot] != ResourceState.Resident || references[slot] != 0 && priorities[slot] <= (int)incoming || - fences[slot] > completedFrame) + if (!CanEvict(slot,completedFrame,incoming)) throw new InvalidOperationException("Resource is demanded or in flight."); ResidentBytes -= pins[slot]; pins[slot] = 0; Missing(slot); generations[slot] = nextGeneration++; Evicted++; diff --git a/src/Hypercube.GameCube/AramCache.cs b/src/Hypercube.GameCube/AramCache.cs index 43443cc..0b26c00 100644 --- a/src/Hypercube.GameCube/AramCache.cs +++ b/src/Hypercube.GameCube/AramCache.cs @@ -5,6 +5,10 @@ namespace Hypercube.GameCube; +public enum AramCacheState { Missing, Filling, Ready, Failed } + +// Application-executor owner. Store borrows its MEM1 source until the returned +// task completes; callers must drain pending stores before clearing the cache. public sealed class AramCache : IDisposable { private readonly int capacity; @@ -12,15 +16,52 @@ public sealed class AramCache : IDisposable // a native cold allocation succeeds, not for Has probes or rejected stores. private AramBuffer?[]? buffers; private int[]? touched; + private Task?[]? pending; private int order; public int Bytes {get;private set;} + public int PendingStores {get;private set;} + public int FailedStores {get;private set;} + // Requested aligned upload bytes, including failed/cancelled requests. + public long StoreBytes {get;private set;} public int Hits,Stores,Evictions; public int Budget {get;} public AramCache(int records,int budget) {if(records<0||records==int.MaxValue||budget<0)throw new ArgumentOutOfRangeException("records");capacity=records+1;Budget=budget;} private void ValidateId(int id) {if((uint)id>=(uint)capacity)throw new IndexOutOfRangeException();} - public bool Has(int id){ValidateId(id);return buffers!=null&&buffers[id]!=null;} + private void Release(int id) + {Bytes-=buffers![id]!.Length;buffers[id]!.Dispose();buffers[id]=null;} + private void Observe(int id) + { + var task=pending![id]; + if(task==null||!task.IsCompleted)return; + pending[id]=null;PendingStores--; + try{task.GetAwaiter().GetResult();} + catch + { + // A partial/cancelled upload must never become a cache hit. The + // native transfer owner has drained before completing this task. + Release(id);touched![id]=-1;FailedStores++; + } + } + public void Pump() + {if(PendingStores==0)return;for(int i=0;iState(id)==AramCacheState.Ready; + // A filling entry keeps its allocation and source hold until it settles. + public bool Remove(int id) + { + if(State(id)==AramCacheState.Filling)return false; + if(buffers==null||buffers[id]==null)return false; + Release(id);touched![id]=0;return true; + } public Task Fetch(int id,NativeBuffer target,int targetOffset,int bytes) { if(!Has(id))throw new InvalidOperationException("ARAM cache miss."); @@ -30,6 +71,8 @@ public Task Fetch(int id,NativeBuffer target,int targetOffset,int bytes) public Task? Store(int id,NativeBuffer source,int sourceOffset,int bytes,int[] protectedIds,int count) { ValidateId(id); + if(count<0||count>protectedIds.Length)throw new ArgumentOutOfRangeException("count"); + Pump(); if(buffers!=null&&buffers[id]!=null)return null; if(bytes<1||bytes>int.MaxValue-31)throw new ArgumentOutOfRangeException("bytes"); int size=(bytes+31)&~31; @@ -37,32 +80,37 @@ public Task Fetch(int id,NativeBuffer target,int targetOffset,int bytes) while(size>Budget-Bytes) { int victim=-1; - for(int i=0;iExtraBytes(r,int.MaxValue); + public int ExtraBytes(AssetRecord r,int completedFrame) { - for(int i=0;iTrimFree(int.MaxValue); + public int TrimFree(int completedFrame) { - for(int i=0;i!used[slot]&&textures[slot]!=null&&!textures[slot]!.HasPendingUpload&&lastFrame[slot]<=completedFrame; + private int Trim(int slot) + {textures[slot]!.Dispose();textures[slot]=null;PhysicalBytes-=bytes[slot];return bytes[slot];} + /// Keep a bounded warm pool, with byte hysteresis and an idle dwell. + /// Pending copies and GPU readers always take precedence over reclamation. + public int TrimCold(int frame,int completedFrame,int idleFrames,int highBytes,int lowBytes,int maximumReleases) { - for(int i=0;ihighBytes)trimming=true; + if(idle<=lowBytes)trimming=false; + for(int i=0;i=idleFrames) + {idle-=Trim(i);released++;if(idle<=lowBytes)trimming=false;} + return released; + } + public int Acquire(AssetRecord r)=>Acquire(r,int.MaxValue); + public int Acquire(AssetRecord r,int completedFrame) + { + for(int i=0;itextures[slot]!; - public void Unbind(int slot)=>used[slot]=false; + public void Unbind(int slot)=>Unbind(slot,0); + public void Unbind(int slot,int frame){used[slot]=false;idleAt[slot]=frame;} + public void Pin(int slot,int frame){if(frame>lastFrame[slot])lastFrame[slot]=frame;} public void Dispose() { for(int i=0;i? reading; private int count,batchOffset,batchLength,actualRead,verifyRecord,verifyAt,holdUntil,sequence,textureStages,otherBytes; private uint checksum; private bool stopping; public int Frame,CompletedFrame,Group=1,Format=14,ReadBatchBytes=32768,MaxBatchRecords=4; + // Retain recently unused resources for camera reversals, then reclaim a + // bounded number between frames. Collision and coarse fallbacks stay hot. + public int IdleResourceFrames=120,IdleTextureFrames=120,MaximumIdleReleases=2; + public int WarmTextureHighBytes=32768,WarmTextureLowBytes=16384; + public bool RetireIdleResources=true; public bool UseAram,InjectFaults,AdaptiveFallback,CoarseFirst,TexturesOnly,ProfileReads; private long readAt; private DemandPlan? demandPlan; @@ -48,6 +60,8 @@ public sealed class WorldStreamer : IDisposable public int ReadOperations,StorageBytes,AramBytes,Failures,ChecksumFailures,ShortReads,Corruptions,Delays,Batches,MaxBatch, MultiplePublications,CancelledUploads,UploadedBytes,ChecksumUs,MaxUploadUs,MaxPumpUs,MeshTriangles,Deferred,Publications; public int PhysicalBytes=>Textures.PhysicalBytes+otherBytes; + public int ColdStagingBytes=>disposed||coldStaging==null?0:coldStaging.Length; + public int ColdWriteSkips,ColdWriteFailures,ColdReadFailures,ColdWriteBytes,ColdReleases,ColdTextureTrims,PartialCacheBatches; public int Active=>count; public int MaximumReadBatchBytes {get;} public int StagingBytes=>disposed?0:staging.Length; @@ -64,7 +78,7 @@ public WorldStreamer(PackedWorld world,string path,int budgetBytes,int maximumRe MaximumReadBatchBytes=maximumReadBatchBytes; Policy=new ResourceScheduler(catalog,ResourceCapacity,budgetBytes); Cold=new AramCache(catalog.Count,256*1024); - for(int i=0;i=0&&Policy.State(slot)==ResourceState.Resident&&textureSlots[slot]>=0?Textures.Get(textureSlots[slot]).Texture:null; } - public void Pin(int id){int slot=Policy.Find(id);if(slot>=0)Policy.Pin(slot,Frame);} + public void Pin(int id) + { + int slot=Policy.Find(id);if(slot<0)return; + Policy.Pin(slot,Frame); + if(textureSlots[slot]>=0)Textures.Pin(textureSlots[slot],Frame); + } public float Ground(int cell,float x,float z) { float u=(x-(cell%6)*4)/2,v=(z-(cell/6)*4)/2; @@ -142,17 +161,17 @@ public float Ground(int cell,float x,float z) private void Release(int slot,ResourcePriority incoming) { var r=catalog.Get(Policy.Id(slot)); - if(textureSlots[slot]>=0){Textures.Unbind(textureSlots[slot]);textureSlots[slot]=-1;} + if(textureSlots[slot]>=0){Textures.Unbind(textureSlots[slot],Frame);textureSlots[slot]=-1;} if(meshes[slot]!=null){meshes[slot]!.Dispose();meshes[slot]=null;otherBytes-=owned[slot];} if(collisionBuffers[slot]!=null) {collisionBuffers[slot]!.Dispose();collisionBuffers[slot]=null;otherBytes-=owned[slot];Cells.CollisionMissing(r.Cell);} - owned[slot]=0;Policy.Evict(slot,CompletedFrame,incoming); + owned[slot]=0;idleSince[slot]=-1;Policy.Evict(slot,CompletedFrame,incoming); } private bool Room(int extra,ResourcePriority priority) { while(PhysicalBytes+extra>Policy.BudgetBytes) { - if(Textures.TrimFree()>0)continue; + if(Textures.TrimFree(CompletedFrame)>0)continue; int victim=Policy.EvictionCandidate(CompletedFrame,priority); if(victim<0)return false; Release(victim,priority); @@ -161,11 +180,11 @@ private bool Room(int extra,ResourcePriority priority) } private bool TextureRoom(AssetRecord record,ResourcePriority priority) { - while(PhysicalBytes+Textures.ExtraBytes(record)>Policy.BudgetBytes) + while(PhysicalBytes+Textures.ExtraBytes(record,CompletedFrame)>Policy.BudgetBytes) { int victim=Policy.EvictionCandidate(CompletedFrame,priority); if(victim>=0){Release(victim,priority);continue;} - if(Textures.TrimFree()>0)continue; + if(Textures.TrimFree(CompletedFrame)>0)continue; return false; } return true; @@ -181,36 +200,56 @@ private void Queue() // in bounded chunks. Adjacent small records still share one logical read. batchLength=(batchLength+31)&~31; for(int i=0;i0){PartialCacheBatches++;reading=ReadMixed();} + else{StorageBytes+=batchLength;ReadOperations++;reading=stream.ReadAtAsync(batchOffset,staging,0,batchLength);} sequence++;Batches++;if(count>MaxBatch)MaxBatch=count; verifyRecord=verifyAt=0;checksum=0;actualRead=-1; holdUntil=InjectFaults&&sequence%5==0?Frame+12:Frame; if(holdUntil>Frame)Delays++; } - private async Task ReadCold() + private async Task ReadMixed() { for(int i=0;iMaxUploadUs)MaxUploadUs=cost; } + private void PollColdStore() + { + Cold.Pump(); + if(coldWrite==null||!coldWrite.IsCompleted)return; + try{coldWrite.GetAwaiter().GetResult();} + catch{ColdWriteFailures++;} + coldWrite=null; + } + private void TryColdStore(AssetRecord record,int relative) + { + if(!UseAram||stopping||Cold.Has(record.Id))return; + int bytes=(record.Length+31)&~31; + if(coldWrite!=null||bytes>ColdWriteCapacity||bytes>scratch.Length||Frame=IdleResourceFrames&&Policy.CanEvict(i,CompletedFrame)) + {Release(i,ResourcePriority.Optional);released++;ColdReleases++;} + } + ColdTextureTrims+=Textures.TrimCold(Frame,CompletedFrame,IdleTextureFrames, + WarmTextureHighBytes,WarmTextureLowBytes,MaximumIdleReleases); + } public void Pump() { long pumpAt=Clock.Timestamp; @@ -257,6 +345,7 @@ public void Pump() private void PumpWork(long pumpAt) { int publishedBefore=Publications; + PollColdStore();RetireCold(); Policy.CancelUnneeded(); if(count==0){if(!stopping)Queue();return;} if(actualRead<0) @@ -271,7 +360,7 @@ private void PumpWork(long pumpAt) } reading=null; if(InjectFaults&&sequence%7==3) - {var r=catalog.Get(batchIds[count-1]);actualRead=r.Offset-batchOffset+r.Length-1;ShortReads++;} + {var r=catalog.Get(batchIds[count-1]);actualRead=Math.Min(actualRead,r.Offset-batchOffset+r.Length-1);ShortReads++;} if(InjectFaults&&sequence%7==5) {var r=catalog.Get(batchIds[count-1]);staging.Read(one,r.Offset-batchOffset,0,1);one[0]^=128;staging.Write(one,0,r.Offset-batchOffset,1);Corruptions++;} } @@ -289,7 +378,8 @@ private void PumpWork(long pumpAt) long at=Clock.Timestamp;checksum=staging.ComputeCrc32(r.Offset-batchOffset+verifyAt,bytes,checksum); ChecksumUs+=(int)(Clock.Timestamp-at);verifyAt+=bytes;work-=bytes; if(verifyAt1)MultiplePublications++; if(done)count=0; @@ -330,13 +418,15 @@ private void PumpWork(long pumpAt) public bool Stop() { stopping=true;Policy.BeginDemand();Policy.CancelUnneeded(); - if(count!=0){Pump();return false;}return true; + if(count!=0||coldWrite!=null||Cold.PendingStores!=0){Pump();return false;}return true; } public void Dispose() { if(disposed)return; if(count!=0)throw new InvalidOperationException("Drain streaming work before disposal."); + PollColdStore(); + if(coldWrite!=null||Cold.PendingStores!=0)throw new InvalidOperationException("Drain optional cold writes before disposal."); for(int i=0;iData.Length; + public NativeBuffer(int size){Data=new byte[size];LiveBytes+=size;Allocations++;} + public static NativeBuffer Allocate(int bytes)=>new NativeBuffer(bytes); + internal void Hold(){if(disposed)throw new Exception("Holding a disposed native buffer.");holds++;} + internal void Release(){if(--holds<0)throw new Exception("Unbalanced native buffer hold.");} + internal void EnsureWritable(){if(disposed||holds!=0)throw new Exception("Overwriting a held or disposed native buffer.");} + public void Write(byte[] source,int sourceOffset=0,int destinationOffset=0,int count=-1){EnsureWritable();if(count<0)count=source.Length-sourceOffset;Array.Copy(source,sourceOffset,Data,destinationOffset,count);} + public void Read(byte[] target,int sourceOffset=0,int destinationOffset=0,int count=-1){if(disposed)throw new Exception("Reading a disposed native buffer.");if(count<0)count=target.Length-destinationOffset;Array.Copy(Data,sourceOffset,target,destinationOffset,count);} + public uint ComputeCrc32(int offset,int count,uint initial=0){if(disposed)throw new Exception("Checksumming a disposed native buffer.");return Hypercube.Binary.Crc(Data,offset,count,initial);} + public void Dispose(){if(disposed||holds!=0)throw new Exception("Disposing a held or disposed native buffer.");disposed=true;LiveBytes-=Length;} } } namespace Dolphin.Memory { public sealed class AramBuffer : IDisposable { - internal readonly byte[] Data;private bool disposed; + internal readonly byte[] Data;private bool disposed;private int holds; public int Length=>Data.Length; internal AramBuffer(int size){Data=new byte[size];Aram.LiveBytes+=size;} - public void Dispose(){if(disposed)throw new Exception("ARAM allocation disposed twice.");disposed=true;Aram.LiveBytes-=Length;} + internal void Hold(){if(disposed)throw new Exception("Holding a disposed ARAM allocation.");holds++;} + internal void Release(){if(--holds<0)throw new Exception("Unbalanced ARAM hold.");if(disposed&&holds==0)Aram.LiveBytes-=Length;} + public void Dispose(){if(disposed)throw new Exception("ARAM allocation disposed twice.");disposed=true;if(holds==0)Aram.LiveBytes-=Length;} } public static class Aram { @@ -84,10 +121,31 @@ public static bool TryAllocate(int bytes,out AramBuffer allocation) } public static class AramTransferQueue { - public static bool Fail;public static int LastBytes; + public static bool Fail,Delay;public static int LastBytes; + private sealed class Transfer { + internal readonly TaskCompletionSource Completion=new TaskCompletionSource(); + internal AramBuffer Owner=null!;internal Dolphin.Graphics.NativeBuffer Native=null!; + internal byte[] Source=null!,Target=null!;internal int SourceOffset,TargetOffset,Bytes; + } + private static readonly System.Collections.Generic.List pending=new System.Collections.Generic.List(); + public static bool HasPending=>pending.Count!=0; + private static Task Copy(AramBuffer owner,Dolphin.Graphics.NativeBuffer native,byte[] source,int sourceOffset,byte[] target,int targetOffset,int bytes) + { + LastBytes=bytes; + if(!Delay){Array.Copy(source,sourceOffset,target,targetOffset,bytes);return Task.CompletedTask;} + owner.Hold();native.Hold();var transfer=new Transfer{Owner=owner,Native=native,Source=source,SourceOffset=sourceOffset,Target=target,TargetOffset=targetOffset,Bytes=bytes}; + pending.Add(transfer);return transfer.Completion.Task; + } + public static void Complete(Exception? error=null) + { + if(pending.Count==0)throw new Exception("No transfer to complete.");var transfer=pending[0];pending.RemoveAt(0); + if(error==null)Array.Copy(transfer.Source,transfer.SourceOffset,transfer.Target,transfer.TargetOffset,transfer.Bytes); + transfer.Owner.Release();transfer.Native.Release(); + if(error is OperationCanceledException)transfer.Completion.SetCanceled();else if(error!=null)transfer.Completion.SetException(error);else transfer.Completion.SetResult(transfer.Bytes); + } public static Task CopyToAramAsync(Dolphin.Graphics.NativeBuffer source,int sourceOffset,AramBuffer target,int targetOffset,int bytes) - {if(Fail)throw new InvalidOperationException("Injected copy failure.");LastBytes=bytes;Array.Copy(source.Data,sourceOffset,target.Data,targetOffset,bytes);return Task.CompletedTask;} + {if(Fail)throw new InvalidOperationException("Injected copy failure.");return Copy(target,source,source.Data,sourceOffset,target.Data,targetOffset,bytes);} public static Task CopyToMainAsync(AramBuffer source,int sourceOffset,Dolphin.Graphics.NativeBuffer target,int targetOffset,int bytes) - {LastBytes=bytes;Array.Copy(source.Data,sourceOffset,target.Data,targetOffset,bytes);return Task.CompletedTask;} + {return Copy(source,target,source.Data,sourceOffset,target.Data,targetOffset,bytes);} } } diff --git a/tests/Hypercube.GameCube.Tests/Hypercube.GameCube.Tests.csproj b/tests/Hypercube.GameCube.Tests/Hypercube.GameCube.Tests.csproj index 6c781da..f5112a2 100644 --- a/tests/Hypercube.GameCube.Tests/Hypercube.GameCube.Tests.csproj +++ b/tests/Hypercube.GameCube.Tests/Hypercube.GameCube.Tests.csproj @@ -4,5 +4,7 @@ + + diff --git a/tests/Hypercube.GameCube.Tests/Program.cs b/tests/Hypercube.GameCube.Tests/Program.cs index dbffd08..20d13a4 100644 --- a/tests/Hypercube.GameCube.Tests/Program.cs +++ b/tests/Hypercube.GameCube.Tests/Program.cs @@ -18,6 +18,8 @@ try{cache.Commit(vertices,3,indices,3,4);throw new Exception("Disposed cache reused");}catch(ObjectDisposedException){} Console.WriteLine("Indexed cache: exact prefixes, revision/count invalidation, allocation-free hits, failed replacement and disposal passed."); PackedWorldChecks.Run(); +TexturePoolChecks.Run(); +StreamingChecks.Run(); namespace Dolphin.Graphics { public readonly struct Vector2 {public readonly float X,Y;public Vector2(float x,float y){X=x;Y=y;}} public readonly struct Vector3 {public readonly float X,Y,Z;public Vector3(float x,float y,float z){X=x;Y=y;Z=z;}} @@ -26,9 +28,12 @@ public struct VertexPositionNormalColorTexture {public VertexPositionNormalColor public enum NativeTextureFormat {Cmpr=14} public sealed class Texture2D:IDisposable { public static int Live,Uploads,FailOnUpload=-1;private bool disposed; - private Texture2D(){Live++;} - public static Texture2D CreateNative(int width,int height,NativeTextureFormat format,bool linear)=>new Texture2D(); - public void ReplaceNative(byte[] data){Uploads++;if(Uploads==FailOnUpload)throw new InvalidOperationException("Injected texture upload failure.");} + internal readonly byte[] Data; + public int NativeBytes=>Data.Length; + private Texture2D(int bytes){Data=new byte[bytes];Live++;} + public static Texture2D CreateNative(int width,int height,NativeTextureFormat format,bool linear) + =>new Texture2D(format==NativeTextureFormat.Cmpr?((width+3)/4)*((height+3)/4)*8:width*height*4); + public void ReplaceNative(byte[] data){Uploads++;if(Uploads==FailOnUpload)throw new InvalidOperationException("Injected texture upload failure.");Array.Copy(data,Data,Data.Length);} public void Dispose(){if(disposed)throw new Exception("Texture disposed twice");disposed=true;Live--;} } public sealed class Mesh:IDisposable { @@ -42,10 +47,19 @@ public sealed class Mesh:IDisposable { namespace Dolphin.Storage { public sealed class AssetStream:IDisposable { public static int Open;private FileStream? stream; + public int Reads,RequestedBytes;public readonly List ReadSizes=new List(); + public bool FailNextRead;public int ShortReadNext=-1; public AssetStream(string path){stream=new FileStream(path,FileMode.Open,FileAccess.Read,FileShare.Read);Open++;} + public Task ReadAtAsync(int offset,Dolphin.Graphics.NativeBuffer target,int targetOffset,int count){ + if(stream==null)throw new ObjectDisposedException("AssetStream"); + target.EnsureWritable();Reads++;RequestedBytes+=count;ReadSizes.Add(count); + if(FailNextRead){FailNextRead=false;return Task.FromException(new IOException("Injected storage failure."));} + if(ShortReadNext>=0){count=Math.Min(count,ShortReadNext);ShortReadNext=-1;} + stream.Seek(offset,SeekOrigin.Begin);int read=stream.Read(target.Data,targetOffset,count);return Task.FromResult(read); + } public void Dispose(){if(stream==null)return;stream.Dispose();stream=null;Open--;} } } namespace Dolphin.Timing { - public static class Clock {public static long Timestamp=>System.Diagnostics.Stopwatch.GetTimestamp();} + public static class Clock {public static long Timestamp=>(long)(System.Diagnostics.Stopwatch.GetTimestamp()*(1000000.0/System.Diagnostics.Stopwatch.Frequency));} } diff --git a/tests/Hypercube.GameCube.Tests/StreamingChecks.cs b/tests/Hypercube.GameCube.Tests/StreamingChecks.cs new file mode 100644 index 0000000..2169c11 --- /dev/null +++ b/tests/Hypercube.GameCube.Tests/StreamingChecks.cs @@ -0,0 +1,206 @@ +using System; +using System.IO; +using System.Threading; +using Dolphin.Graphics; +using Dolphin.Memory; +using Hypercube; +using Hypercube.GameCube; + +internal static class StreamingChecks +{ + private static readonly int[] none=Array.Empty(); + private static void Check(bool value,string message) + {if(!value)throw new Exception(message);} + private static int[] Triple(AssetCatalog catalog) + { + for(int id=1;idreads&&streamer.ColdWriteSkips>0, + "A pending cold write prevented the next storage read/source reuse."); + AramTransferQueue.Complete();AramTransferQueue.Delay=false; + Tick(streamer,new[]{pair[1]}); + var record=world.Catalog.Get(pair[0]); + using(var restored=NativeBuffer.Allocate((record.Length+31)&~31)) + { + streamer.Cold.Fetch(pair[0],restored,0,record.Length).GetAwaiter().GetResult(); + Check(restored.ComputeCrc32(0,record.Length)==record.Checksum, + "Reusing the foreground source overwrote the pending cold snapshot."); + } + int collision=world.Catalog.Collision(0);AramTransferQueue.Delay=true; + Ready(streamer,new[]{collision}); + Check(streamer.Cold.PendingStores==1&&!streamer.Stop(),"Stop did not retain the optional DMA source."); + try{streamer.Dispose();throw new Exception("Undrained optional source disposed.");} + catch(InvalidOperationException){} + AramTransferQueue.Complete(new IOException("Injected optional DMA failure."));AramTransferQueue.Delay=false; + while(!streamer.Stop()){} + Check(streamer.ColdWriteFailures==1&&streamer.Cold.State(collision)==AramCacheState.Failed, + "An asynchronous optional failure escaped or retained its partial entry."); + } + Check(NativeBuffer.LiveBytes==native,"Streaming shutdown leaked the detached cold source."); + } + private static void PartialHits(PackedWorld world,int[] pair,byte[] file) + { + using var streamer=new WorldStreamer(world,"unused");streamer.UseAram=true; + Seed(streamer,world.Catalog,pair[0],file); + int reads=world.Assets.Reads,requested=world.Assets.RequestedBytes; + Ready(streamer,pair); + Check(streamer.PartialCacheBatches==1&&world.Assets.Reads==reads+1, + "One cold miss discarded a ready neighboring cache entry."); + int expected=(world.Catalog.Get(pair[1]).Length+31)&~31; + Check(world.Assets.RequestedBytes-requested==expected&&streamer.Cold.Hits==1, + "Mixed-source streaming reread cached storage bytes."); + while(!streamer.Stop()){} + } + private static void CorruptCold(PackedWorld world,int id,byte[] file) + { + using var streamer=new WorldStreamer(world,"unused");streamer.UseAram=true; + Seed(streamer,world.Catalog,id,file,true);int reads=world.Assets.Reads; + Tick(streamer,new[]{id});Tick(streamer,new[]{id}); + Check(streamer.ChecksumFailures==1&&!streamer.Ready(id)&&!streamer.Cold.Has(id), + "Corrupt cold data was published or kept as a retry source."); + Ready(streamer,new[]{id}); + Check(world.Assets.Reads>reads,"Corrupt cache retry did not return to verified storage."); + while(!streamer.Stop()){} + } + private static void MissRuns(PackedWorld world,int[] ids,byte[] file,int cached) + { + using var streamer=new WorldStreamer(world,"unused");streamer.UseAram=true; + Seed(streamer,world.Catalog,ids[cached],file); + int reads=world.Assets.Reads,requested=world.Assets.RequestedBytes; + Ready(streamer,ids); + var a=world.Catalog.Get(ids[0]);var b=world.Catalog.Get(ids[1]);var c=world.Catalog.Get(ids[2]); + int expected=cached==0?(c.Offset+c.Length-b.Offset+31)&~31: + ((a.Length+31)&~31)+((c.Length+31)&~31); + Check(world.Assets.Reads-reads==(cached==0?1:2)&&world.Assets.RequestedBytes-requested==expected, + "Mixed cache hits did not coalesce consecutive storage misses or split at a cached separator."); + Check(streamer.Cold.Hits==1&&streamer.PartialCacheBatches==1,"Mixed coalescing lost its ARAM source."); + while(!streamer.Stop()){} + } + private static void ShortMissRun(PackedWorld world,int[] ids,byte[] file) + { + using var streamer=new WorldStreamer(world,"unused");streamer.UseAram=true; + Seed(streamer,world.Catalog,ids[2],file); + world.Assets.ShortReadNext=world.Catalog.Get(ids[0]).Length-1; + Tick(streamer,ids);Tick(streamer,ids); + Check(!streamer.Ready(ids[0])&&!streamer.Ready(ids[1])&&!streamer.Ready(ids[2])&&streamer.Cold.Hits==0, + "A short storage prefix incorrectly validated a later cached record or stale source bytes."); + Ready(streamer,ids); + while(!streamer.Stop()){} + } + private static void FailedFetch(PackedWorld world,int id,byte[] file) + { + using var streamer=new WorldStreamer(world,"unused");streamer.UseAram=true; + Seed(streamer,world.Catalog,id,file);int reads=world.Assets.Reads; + AramTransferQueue.Delay=true;Tick(streamer,new[]{id}); + Check(AramTransferQueue.HasPending,"Cache fetch did not retain its source."); + AramTransferQueue.Complete(new IOException("Injected cache read failure."));AramTransferQueue.Delay=false; + Ready(streamer,new[]{id}); + Check(streamer.ColdReadFailures==1&&world.Assets.Reads>reads,"Cache DMA failure did not fall back to storage."); + while(!streamer.Stop()){} + } + private static void IdleResidency(PackedWorld world,int mesh) + { + using var streamer=new WorldStreamer(world,"unused"); + streamer.IdleResourceFrames=3;streamer.IdleTextureFrames=2;streamer.MaximumIdleReleases=1; + streamer.WarmTextureHighBytes=streamer.WarmTextureLowBytes=0; + int texture=world.Catalog.Texture(14,1,0,0),collision=world.Catalog.Collision(0); + int[] demand={mesh,texture,collision};Ready(streamer,demand); + var originalMesh=streamer.Geometry(mesh);var originalTexture=streamer.Texture(texture); + int patches=world.ParentMeshCount; + Tick(streamer,none);Tick(streamer,none);Ready(streamer,demand); + Check(streamer.Geometry(mesh)==originalMesh&&streamer.Texture(texture)==originalTexture, + "Demand reversal inside the dwell recreated native detail."); + streamer.Pin(mesh);streamer.Pin(texture);int pinned=streamer.Frame; + for(int i=0;i<6;i++)Tick(streamer,none,pinned-1); + Check(streamer.Ready(mesh)&&streamer.Ready(texture),"Idle reclamation freed an unfinished GPU reader."); + for(int i=0;i<8;i++)Tick(streamer,none,pinned); + Check(!streamer.Ready(mesh)&&!streamer.Ready(texture)&&streamer.PhysicalBytes==44, + "Cold detail did not release physical mesh/texture allocations."); + Check(streamer.Ready(collision)&&streamer.Cells.HasCollision(0)&&world.ParentMeshCount==patches, + "Idle detail retirement removed movement data or permanent fallback."); + while(!streamer.Stop()){} + } + private static void CancelledTexture(PackedWorld world,int mesh) + { + using var streamer=new WorldStreamer(world,"unused");streamer.RetireIdleResources=false; + int texture=world.Catalog.Texture(14,1,0,0);int[] demand={texture}; + StreamingTexture.Delay=true; + for(int i=0;i<12&&StreamingTexture.PendingCount==0;i++)Tick(streamer,demand); + Check(StreamingTexture.PendingCount==1&&streamer.Active!=0,"Texture transfer did not retain its source."); + int reads=world.Assets.Reads; + Check(streamer.Policy.Cancel(texture),"Pending texture could not be cancelled."); + Tick(streamer,new[]{mesh}); + Check(world.Assets.Reads==reads&&streamer.Active!=0,"Cancelled upload released its source before completion."); + StreamingTexture.CompletePending();StreamingTexture.Delay=false; + Ready(streamer,new[]{mesh}); + Check(!streamer.Ready(texture)&&streamer.CancelledUploads==1, + "Cancelled completed texture became visible or its pair stayed transfer-owned."); + while(!streamer.Stop()){} + } +} diff --git a/tests/Hypercube.GameCube.Tests/StreamingTextureMock.cs b/tests/Hypercube.GameCube.Tests/StreamingTextureMock.cs new file mode 100644 index 0000000..066c174 --- /dev/null +++ b/tests/Hypercube.GameCube.Tests/StreamingTextureMock.cs @@ -0,0 +1,43 @@ +using System; +using System.Collections.Generic; +using System.Threading.Tasks; + +namespace Dolphin.Graphics; + +public sealed class StreamingTexture : IDisposable +{ + public static bool Delay; + private static readonly List pending=new List(); + public static int PendingCount=>pending.Count; + private Texture2D front,back; + private NativeBuffer? source; + private int offset; + private TaskCompletionSource? completion; + private Task? upload; + public Texture2D Texture=>front; + public bool HasPendingUpload=>upload!=null; + public StreamingTexture(int width,int height,NativeTextureFormat format,bool linear) + {front=Texture2D.CreateNative(width,height,format,linear);back=Texture2D.CreateNative(width,height,format,linear);} + public Task StageUploadAsync(NativeBuffer buffer,int sourceOffset) + { + if(upload!=null)throw new Exception("An upload is already pending."); + buffer.Hold();source=buffer;offset=sourceOffset; + if(Delay){completion=new TaskCompletionSource();upload=completion.Task;pending.Add(this);} + else{Complete();upload=Task.CompletedTask;} + return upload; + } + private void Complete() + { + Array.Copy(source!.Data,offset,back.Data,0,back.NativeBytes); + source.Release();source=null;completion?.SetResult(back.NativeBytes);completion=null; + } + public static void CompletePending() + {while(pending.Count!=0){var texture=pending[0];pending.RemoveAt(0);texture.Complete();}} + public bool TryPublish() + { + if(upload==null||!upload.IsCompleted)return false; + upload.GetAwaiter().GetResult();upload=null;var old=front;front=back;back=old;return true; + } + public void Dispose() + {if(upload!=null)throw new Exception("Disposing an unfinished streaming texture.");front.Dispose();back.Dispose();} +} diff --git a/tests/Hypercube.GameCube.Tests/TexturePoolChecks.cs b/tests/Hypercube.GameCube.Tests/TexturePoolChecks.cs new file mode 100644 index 0000000..86b46a8 --- /dev/null +++ b/tests/Hypercube.GameCube.Tests/TexturePoolChecks.cs @@ -0,0 +1,45 @@ +using System; +using Hypercube.GameCube; + +internal static class TexturePoolChecks +{ + private static void Check(bool value,string message) + {if(!value)throw new Exception(message);} + internal static void Run() + { + using var world=new PackedWorld("out/assets/world.hcp"); + var record=world.Catalog.Get(world.Catalog.Texture(14,1,0,0)); + int pair=record.Length*2; + using(var fenced=new TexturePool()) + { + int old=fenced.Acquire(record,0);fenced.Pin(old,10);fenced.Unbind(old,10); + Check(fenced.ExtraBytes(record,9)==pair,"A GPU reader was treated as reusable storage."); + Check(fenced.TrimFree(9)==0,"Pressure trimming freed a GPU reader."); + int next=fenced.Acquire(record,9); + Check(next!=old&&fenced.PhysicalBytes==2*pair,"Acquisition reused an unfinished GPU allocation."); + Check(fenced.Acquire(record,10)==old&&fenced.Reuses==1,"Completed storage was not reused."); + fenced.Unbind(old,11);fenced.Unbind(next,11); + Check(fenced.TrimCold(12,10,10,0,0,2)==0,"Cold trimming skipped its idle dwell."); + Check(fenced.TrimCold(21,9,10,0,0,2)==1&&fenced.PhysicalBytes==pair, + "Cold trimming must retain incomplete readers and reclaim completed idle storage."); + Check(fenced.TrimCold(21,10,10,0,0,2)==1&&fenced.PhysicalBytes==0,"Completed cold storage was not physically freed."); + } + using(var warm=new TexturePool()) + { + int first=warm.Acquire(record,0),second=warm.Acquire(record,0),third=warm.Acquire(record,0); + warm.Unbind(first,10);warm.Unbind(second,10);warm.Unbind(third,10); + int allocations=warm.Allocations; + Check(warm.Acquire(record,0)==first&&warm.Allocations==allocations&&warm.Reuses==1, + "Demand reversal inside the warm window allocated instead of reusing."); + warm.Unbind(first,12); + Check(warm.TrimCold(14,0,5,2*pair,pair,1)==0,"Warm dwell was not preserved."); + Check(warm.TrimCold(15,0,5,2*pair,pair,1)==1&&warm.IdleBytes==2*pair, + "Cold trim did not obey its per-pump release limit."); + Check(warm.TrimCold(16,0,5,2*pair,pair,1)==1&&warm.IdleBytes==pair, + "Byte hysteresis stopped at its high watermark instead of continuing to low."); + Check(warm.TrimCold(100,0,5,2*pair,pair,1)==0&&warm.PhysicalBytes==pair, + "A bounded warm reuse reserve was discarded below its low watermark."); + } + Console.WriteLine("Texture pool: GPU fences, warm reversal reuse, dwell, byte hysteresis, bounded trim and physical reclamation passed."); + } +} diff --git a/tests/test_dolphin_memory_validation.py b/tests/test_dolphin_memory_validation.py new file mode 100644 index 0000000..1f002d4 --- /dev/null +++ b/tests/test_dolphin_memory_validation.py @@ -0,0 +1,37 @@ +from pathlib import Path +import sys +import unittest + +sys.path.insert(0,str(Path(__file__).resolve().parents[1]/'tools')) +from dolphin_validation import native_residency_baseline + + +class NativeResidencyValidation(unittest.TestCase): + @staticmethod + def state(case,extra=0): + return dict(scenario=case,nativeKiB=544+200+extra,dynamicKiB=200) + + def test_lazy_bounded_cold_source_and_transition_release(self): + baseline=native_residency_baseline(self.state(0),None) + self.assertEqual(baseline,544) + for case in (6,7): + for extra in (0,16): + self.assertEqual(native_residency_baseline(self.state(case,extra),baseline),baseline) + self.assertEqual(native_residency_baseline(self.state(8),baseline),baseline) + + def test_native_leaks_cannot_hide_in_cold_source_allowance(self): + for case in (6,7): + for extra in (8,24,32,-16): + with self.subTest(case=case,extra=extra),self.assertRaises(AssertionError): + native_residency_baseline(self.state(case,extra),544) + for case in (0,1,2,3,4,5,8,9,10): + with self.subTest(case=case),self.assertRaises(AssertionError): + native_residency_baseline(self.state(case,16),544) + + def test_independent_kib_rounding_does_not_reject_valid_states(self): + for extra in (-1,0,1): + self.assertEqual(native_residency_baseline(self.state(0,extra),544),544) + self.assertEqual(native_residency_baseline(self.state(6,16+extra),544),544) + + +if __name__=='__main__':unittest.main() diff --git a/tests/test_memory_audit.py b/tests/test_memory_audit.py index ee46cca..676b01e 100644 --- a/tests/test_memory_audit.py +++ b/tests/test_memory_audit.py @@ -20,7 +20,15 @@ def test_fixture_counts_and_reported_payload_savings(self): self.assertEqual(result['retainedManagedPayload']['saved'],4*count+1566) self.assertEqual(result['transientCatalogTailPayload']['saved'],192) self.assertEqual(result['idleAramMetadata']['disabled']['saved'],8*(count+1)) - self.assertEqual(result['idleAramMetadata']['enabledAfterFirstStore']['saved'],0) + self.assertEqual(result['idleAramMetadata']['enabledAfterFirstStore']['saved'],-4*(count+1)) + self.assertEqual(result['idleAramMetadata']['enabledAfterFirstStore']['after'],12*(count+1)) + self.assertEqual(result['optionalColdWriteStaging']['bufferBytes'],16384) + self.assertTrue(result['optionalColdWriteStaging']['allocatedLazily']) + self.assertEqual(result['optionalColdWriteStaging']['sourceAndColdBuffers'], + dict(before=131072,after=90368,saved=40704)) + self.assertEqual(result['idleLifecycleArrayPayload']['change'],dict(before=32,after=904,saved=-872)) + self.assertEqual(result['selectedManagedArraySavings']['coldCacheUnused'],12*count+702) + self.assertEqual(result['selectedManagedArraySavings']['coldCacheActive'],690) self.assertEqual(audit(root/'world.hcp',131040)['nativeStagingBytes']['after'],131040) self.assertEqual(audit(root/'world.hcp',32)['nativeStagingBytes']['after'],73984) self.assertEqual(result,audit(root/'world.hcp')) diff --git a/tools/dolphin_validation.py b/tools/dolphin_validation.py index d7a11ab..7eff5c1 100644 --- a/tools/dolphin_validation.py +++ b/tools/dolphin_validation.py @@ -62,6 +62,21 @@ def ground_coverage(rgb,state): if tested<2 or missing>1:raise AssertionError(f'Ground coverage holes: {missing}/{tested} at {fx},{fz}') return tested +def native_residency_baseline(state,baseline): + """V2 scene contract: only ARAM/fault cases can own the lazy 16 KiB source. + + Its allocation is independent of dynamic residents. Require either the + unallocated or full allocation state, and require its release on transition. + One KiB tolerates independent integer rounding of the native/dynamic fields. + """ + current=state['nativeKiB']-state['dynamicKiB'] + if baseline is None:baseline=current + allowed=(0,16) if state['scenario'] in (6,7) else (0,) + if min(abs(current-baseline-extra) for extra in allowed)>1: + raise AssertionError('Resources leaked between cases or cold staging exceeded its bound') + return baseline + + def validate(capture,root,smoke): # A streaming decoder bounds memory independently of suite duration. command=['ffmpeg','-threads','1','-v','error','-i',str(capture),'-vf','fps=2,scale=640:480:flags=neighbor','-f','rawvideo','-pix_fmt','rgb24','pipe:1'] @@ -86,9 +101,7 @@ def validate(capture,root,smoke): states.append(s);case=s['scenario'] if not 0<=case<11:raise AssertionError('Unknown scenario') if s['dynamicKiB']>(48 if case==8 else 384) or s['residentKiB']>s['dynamicKiB']+1:raise AssertionError('Dynamic budget exceeded') - current=s['nativeKiB']-s['dynamicKiB'] - if baseline is None:baseline=current - if abs(current-baseline)>1:raise AssertionError('Resources leaked between cases') + baseline=native_residency_baseline(s,baseline) if s['audioActive']!=1:raise AssertionError('Audio voice stopped') if s['completedMask']|last_mask!=s['completedMask']:raise AssertionError('Completion mask regressed') last_mask=s['completedMask'] diff --git a/tools/memory_audit.py b/tools/memory_audit.py index 547eaab..3aacd4e 100644 --- a/tools/memory_audit.py +++ b/tools/memory_audit.py @@ -27,22 +27,35 @@ def change(before, after): catalog = change(4*(count+782), 2*(count+782)) scheduler = change(4*(count+1), 2*(count+1)) native = change(131072, staging) - return dict(schema=1,scope='validated-v1-world-payload-accounting',hardwareMeasurement=False, + # Bounded idle/fence arrays and cached-read flags replace the previous + # per-batch store-task references. Scalar object fields are excluded. + lifecycle = change(8*4,128*4+48*4*2+8) + aram_active = change(8*(count+1),12*(count+1)) + return dict(schema=2,scope='validated-v1-world-payload-accounting',hardwareMeasurement=False, sourceSha256=hashlib.sha256(raw).hexdigest(),records=count, maximumReadBatchBytes=maximum_read_batch_bytes, largestSupportedStreamRecord=max(supported, default=0), unsupportedStreamRecords=sum(size>131040 for size in lengths), nativeStagingBytes=native, + optionalColdWriteStaging=dict(allocatedLazily=True,bufferBytes=16384, + sourceAndColdBuffers=change(131072,staging+16384)), retainedManagedPayload=dict(catalogIds=catalog,schedulerLookup=scheduler, saved=catalog['saved']+scheduler['saved']), idleAramMetadata=dict(targetPointerBytes=4,disabled=change(8*(count+1),0), - enabledAfterFirstStore=change(8*(count+1),8*(count+1))), + enabledAfterFirstStore=aram_active), + idleLifecycleArrayPayload=dict(targetPointerBytes=4,change=lifecycle, + idleResourceFramesBytes=128*4,poolIdleAndFenceBytes=48*4*2, + cachedReadFlagsBytes=8,removedStoreTaskReferencesBytes=8*4), + selectedManagedArraySavings=dict( + coldCacheUnused=catalog['saved']+scheduler['saved']+8*(count+1)+lifecycle['saved'], + coldCacheActive=catalog['saved']+scheduler['saved']+aram_active['saved']+lifecycle['saved']), transientCatalogTailPayload=change(96*4,96*2), unchanged=dict(parsedRecordPayloadBytes=count*56,metadataInputBytes=count*64, textureCopiesPerPoolSlot=2), caveats=['Selected array element payload only; object field changes, headers and allocator rounding excluded.', 'Managed heap reservation is unchanged; these are occupancy reductions.', 'Cold ARAM, permanent geometry, active/idle texture pairs, framebuffers and SDK heaps are separate.', + 'The optional cold-write ring is extra MEM1; only physically retired residents create further savings.', 'Unsupported large records retain their existing demand-time rejection.']) From 6e3f4169b980d2e5240074ec87067481d8da3b68 Mon Sep 17 00:00:00 2001 From: leroy ketelaars Date: Thu, 12 Nov 2026 15:53:51 +0000 Subject: [PATCH 2/2] Pin the verified ARAM SDK release and source revision --- .sdk-revision | 2 +- Directory.Build.props | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.sdk-revision b/.sdk-revision index b371dcf..2f5376a 100644 --- a/.sdk-revision +++ b/.sdk-revision @@ -1 +1 @@ -4c8cd26a1b5f8003598463116960367ffa17418f +d53a65890222868d2329792569770b2294cd828e diff --git a/Directory.Build.props b/Directory.Build.props index af7440c..7644228 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -2,7 +2,7 @@ false false - 0.1.0-preview.318.1 + 0.1.0-preview.328.1 true net8.0 enable