diff --git a/docs/aram-residency-investigation.md b/docs/aram-residency-investigation.md new file mode 100644 index 0000000..6561685 --- /dev/null +++ b/docs/aram-residency-investigation.md @@ -0,0 +1,299 @@ +# Dynamic ARAM residency across DolphinDotNet, Hypercube and AnimalTown + +Investigation of the current main branches on 2026-11-12. This is a design and +source/asset audit; it enables no new runtime paging policy. Moving a copy to +ARAM saves MEM1 only after its original allocation is actually released. +Asynchronous DMA alone does not establish unchanged frame time. + +| Repository | Audited revision | Consumer versions | +| --- | --- | --- | +| DolphinDotNet | `bac008e509c44cd454eeeec0befad50adf096324` | SDK main includes the memory reductions from PR 171 | +| Hypercube | `a5d2eea566c0521aa5a91a8b177ebdd11df49518` | Source pin and published SDK dependency are SDK 318 | +| AnimalTown | `31d531feebd3a3dc6567627c60ad8abaa34dac3d` | SDK/Assets 315; Hypercube `0.1.0-preview.28.1` | + +AnimalTown's dependency versions and local native patches matter. SDK/engine +main improvements must not be assumed present in its shipped packages. Older +AnimalTown streaming documentation also predates its current polled model +startup. The game uses its own terrain archive and resident texture cache, +rather than Hypercube's V1 `WorldStreamer`. + +## Best opportunities + +| Priority | Resource and trigger | Potential MEM1 release | Conditions and cost | +| --- | --- | ---: | --- | +| 1 | AnimalTown outdoor terrain working cache while indoors | **1,048,576 B** fixed buffer payload | Terrain is already backed by ARAM. Unbind all mesh views after GPU completion, retain archive/metadata/view identities, and release only the working cache. Reserve and prefetch it before returning outdoors. No extra snapshot upload is needed. | +| 2 | AnimalTown species models whose instances are all in other spaces for a predictable interval | Historical fox-player example: **5,527,232 B** of selected package/texture payload for the other five species, plus eligible instance skin caches | This is a sizing example from older converted assets, not a current-build saving. Store 3,233,472 B of packages in ARAM, retain the active player's model, and restore before any instance needs drawing/animation. Fix shared DMA arbitration and bounded restoration first. | +| 3 | Hypercube idle texture pairs and detailed meshes after demand/fences expire | A physically trimmed texture pair releases `2 * record.Length`; detailed meshes release their native geometry | Existing ARAM source copies can avoid later disc reads, but CRC/decode/create/upload costs remain. Use idle dwell and high/low watermarks; retain rapid-turn working sets. | +| 4 | AnimalTown cold UI atlases | Historical heading font + item icons: **786,432 B** pixel payload | Current fonts/batches retain concrete texture aliases, and menus can open immediately. Keep these hot initially; page only after an explicit readiness/prefetch contract exists. | +| 5 | Larger future building/interior catalogs | Historical interior geometry under the current retention policy: only **33,504 B** | Current retained building models reject SDK copy/unload. Cottage parts share a 20,480 B texture that exterior users keep alive. A compact static-geometry pager would be needed; this is low value for today's shared kit. | + +These opportunities are conditional and must not be summed as a demonstrated +concurrent saving. Object fields, allocator overhead, shared ownership, retained +metadata, staging, destination/retirement overlap and fragmentation affect the +net result. No texture-resolution reduction or visible-object omission is +needed for the proposed policy. + +## Global ARAM budget and ownership + +The [SDK allocator][sdk-aram] manages internal 16 MiB ARAM, excluding the lower +16 KiB system area and the application's initialization reservation. AnimalTown +reserves 2 MiB for audio/platform ownership, then reserves 8 MiB for terrain: + +| Item | Bytes | +| --- | ---: | +| Physical ARAM | 16,777,216 | +| System base | −16,384 | +| Audio/application reservation | −2,097,152 | +| Capacity available to SDK allocations | 14,663,680 | +| Existing terrain allocation | −8,388,608 | +| Remaining before other SDK owners | **6,275,072** (5.984375 MiB) | + +The allocator has 256 allocation slots, 32-byte-rounded first-fit blocks and no +compaction. A large model can fail admission despite sufficient aggregate free +bytes; check the largest free block and slot count. Disposed but held allocations +still occupy space until DMA drains. Use a shared budget and bounded arenas for +numerous small records; separate per-cache budgets are insufficient. + +The [historical terrain measurement][town-terrain-evidence] used 3,840,416 B of +its 8 MiB reservation. That leaves 4,548,192 B reserved but unused in that town. +Shrinking a sealed allocation or allocating bounded terrain segments could +recover ARAM headroom, but saves no MEM1 by itself. The SDK has no in-place +shrink API today. Do not free/reallocate the archive underneath its live offset +descriptors, or reduce the audio reservation based on guessed usage. + +## AnimalTown: use space transitions before camera-only eviction + +### Suspend the outdoor working set + +[Indoor rendering skips outdoor terrain preparation][town-scene], but the +[archive's mesh views and cache][town-archive] retain their last outdoor +bindings. The native adapter owns an 8 MiB ARAM archive and a separate 1 MiB +MEM1 cache. Its existing `Reset` releases both; calling it on entry would destroy +the backing archive and force a rebuild. + +A dedicated suspend/resume lifecycle should: + +1. After the final outdoor GPU work completes, unbind every view and release its + parent holds. Preserve managed/native view identities and archive metadata. +2. Release the MEM1 cache, invalidate selection/bound-state caches, and leave + immutable ARAM contents intact. Optionally retain it during short doorway + reversals before demoting it. +3. Before exit commits, reserve a contiguous destination, refill the required + outdoor sections and rebind views. Retain the interior until this succeeds. + +Admission must include the simultaneous interior and returning outdoor working +sets. Avoid repeated 1 MiB allocation churn and fragmentation. Use existing door +transition signals for lookahead; debug teleports, room changes and immediate +reversals need an explicit readiness gate. Current terrain does synchronous DMA +on cache misses, so suspension alone does not make restoration frame-bounded. + +### Cold species groups + +The game [loads six shared species models and seven instances][town-models]. +The player can share a model with an NPC. Native unloading operates on the +**shared model**, releasing its package, last-owned cached textures, and all +matching instances' skinned outputs/workspaces. Wrappers, transforms, metadata, +pose/global matrices, gameplay and animation playback state remain in MEM1. +During the transition, SDK instance drawing/update calls reject that model. +An invisible instance alone is therefore insufficient evidence for eviction. + +The [asset inventory](measurements/aram/animaltown-assets.json) contains six +SHA-verified packages from historical game `fca068009bed`, converted with SDK +266. Their combined package length is 3,812,128 B, with 2,621,440 B of unique +runtime texture-copy payload. These textures have distinct hashes across the +species. A fox-player-only room leaves five candidate packages totaling +3,233,472 B, plus 2,293,760 B of separate texture copies: 5,527,232 B of selected +MEM1 payload, before allocator/instance-cache effects. The package already +contains texture bytes; ARAM stores the package once, not both representations. + +Current actor art is unchanged, but the pinned converter is now 315. Regenerate +and measure current packages before assigning runtime budgets. Native +`Model.NativeBytes` is a per-model budget charge: shared texture bytes can be +charged to multiple models while physically allocated once. Reclaim estimates +must count unique last owners and instance bytes separately. + +Pin the player, visible actors, actors approaching doors/camera bounds and every +model with imminent users. Keep small simulation/collision state hot. Start with +other-space idle windows; camera-only cold decisions need conservative lookahead +for sprinting, cylinder wrapping, NPC movement and sudden camera/teleport changes. + +### Assets with poor economics today + +- [Building retention][town-retained] has already discarded redundant package + tables and points meshes at compact geometry. AnimalTown explicitly rejects + package copy/unload on these models. Original file lengths overstate their + current MEM1 footprint; do not call `UnloadToAramAsync` on retained buildings. +- Shared floor textures, generated tree meshes, active fonts/icons, player + resources and logical terrain/collision are small, immediately needed or + heavily shared. Keep them resident for the initial policy. +- Title/splash textures are already trimmed at the mode boundary. Disposing + one-shot assets avoids retaining an unnecessary ARAM backup. +- Active audio sources feed native decoder callbacks directly. Future long + inactive clips could have explicit residency, but continuous audio requires + a prefetched playback ring; DMA must never run inside an audio callback. +- C# objects cannot become ARAM pointers. Offloading whole objects requires + versioned serialization, stable IDs and reconstruction; GC roots and native + handles cannot be copied as a valid object snapshot. + +## SDK work needed to preserve frame time + +### One DMA broker must include the game-native terrain path + +[Generic and native SDK transfers][sdk-native-queue] have separate FIFO queues +but share one native transfer slot. Both retry `-EBUSY`; neither provides +promotion deadlines or promotion-over-demotion priority. Low ARQ priority does +not create priority between these SDK callers. + +AnimalTown's [custom terrain DMA][town-dma] attempts `dnd_aram_begin_native` +once, treats every nonzero result as failure, then busy-polls completion. +`TerrainArchive.Prepare` throws on the resulting bind error. Adding model or +texture background transfers can therefore break movement when that channel is +busy, including a completed request whose owning caller has not polled it yet. +Do not enable concurrent paging before replacing/coordinating this path. + +Use one native-aware broker with reserved foreground/terrain service, +deadline-aware promotions, speculative prefetch and last-priority demotions. +Arbitrate between bounded chunks, limit queue depth/bytes in flight, and drain +submitted work before releasing its owners. A foreground path must not poll a +different owner's transfer or convert contention into corruption/failure. + +### Bulk copies and bounded model publication + +[Model residency][sdk-model] copies through a managed 4 KiB buffer. Generic ARAM +uploads always perform read-modify-write, including aligned writes. For an +aligned 1 MiB package, first offload currently entails 256 logical requests, +512 DMA operations moving 2 MiB, approximately 3 MiB of CPU memcpy, and at least +768 transient managed transfer/TCS/task objects, plus repost delegates. + +The existing aligned native path can transfer 64 KiB chunks without that bounce +copy/RMW. Model packages need a safe native source lease and rounded tail +ownership before it can be used. Copying into another full-size native buffer +would increase peak MEM1; prefer a direct retained lease or an explicitly +budgeted reusable small workspace. + +[Restore finalization][sdk-restore] synchronously hashes and validates the whole +package, recreates texture allocations, flushes data and evaluates every matching +instance. Unloading also synchronously retires instance buffers and textures. +Other native resource releases, such as `NativeBuffer` disposal, can wait for GX. +`Task.Run` does not bound these operations or +provide another GameCube core; managed executors share an execution gate. + +Add separately bounded copy, validation, texture creation/publication, +instance-reconstruction and retirement steps. Keep required live resources +until atomic publication succeeds. Reserve restore peaks first. Existing cold +model snapshots stay pinned in ARAM after restoration until `Model.Dispose`; +a global cold-budget policy also needs explicit evictable backing ownership. +`PrepareAnimationAsync(name)` restores the whole model, not just one clip. + +## Hypercube: turn a storage cache into an explicit residency policy + +`UseAram=true` alone releases **zero MEM1 bytes**: [the streamer][engine-stream] +caches verified source records while keeping native residents until ordinary +eviction. Mesh eviction disposes storage; texture eviction only unbinds a reusable +double-buffered pair. [Physical trimming][engine-pool] is required to reclaim it. +Keep the existing reference, priority, generation and GPU-fence protections. + +The deterministic 48-resolution fixture has 649 records and SHA256 +`0a782f8137b426528a185cb8bbb5a67ae50d8fc5448ef6a88d56016daec49024`: + +| Candidate set | Records | Packed bytes | ARAM bytes after per-record alignment | Native payload | +| --- | ---: | ---: | ---: | ---: | +| Group-2 CMPR fine textures, three LODs | 18 | 22,080 | 22,080 | 44,160 in pairs | +| Clustered fine meshes, three LODs | 136 | 296,598 | 298,624 | 324,354 | +| Collision | 24 | 1,056 | 1,536 | 1,056 duplicate bytes; decoded hot arrays remain | +| Permanent coarse patches | 89 | 304,260 | 305,632 | 334,620 | + +The first three sets require 178 entries and 322,240 ARAM bytes, exceeding the +current 256 KiB cold budget by 60,096 B. The MEM1 scheduler independently has +128 slots. Increasing budgets cannot bypass the SDK's global 256 ARAM-allocation +limit; arenas would be needed for large per-record catalogs. + +Current cold hits require every record in a batch to be cached; one miss sends +the whole batch to storage. Fetches are serial. Optional stores start before +MEM1 admission, and the next batch waits for every store because they borrow the +same staging buffer. Decouple only with explicit source holds and bounded extra +storage. A second full source buffer costs another 73,984 MEM1 bytes here. +Skipping speculative demotion when demand work is pending may be cheaper. + +Before decoupling, add `Filling/Ready/Failed` cache states and asynchronous failure +rollback: [current Store][engine-cold] exposes an entry before DMA completes. +The existing one-batch drain prevents its normal reader from racing that write; +removing the drain without a replacement would break that protection. + +Prefer revisit-aware admission, partial-hit batches, idle-pair trimming and +prefetch before detail demand. Keep collision and coarse fallback resident: +44-byte collision records offer little gain, while a coarse fallback protects +movement/rendering deadlines. Main contains texture-family/LOD demand metadata, +but no generic family GPU pager; unmerged progressive branches are not assumed. + +## Acceptance and implementation order + +1. **Measure and coordinate first.** Add the shared broker, global memory and + ownership accounting, and bounded prepare/retire steps. Do not change default + residency until baseline traces and these contracts exist. +2. **Suspend outdoor cache indoors.** Exercise entry/exit/reversal, retained + aliases, allocation failure, save/load and debug teleports. Keep interior + ownership until outdoor prefetch is ready; never silently omit geometry. +3. **Page other-space model groups.** Prove all-user pinning, animation/state + preservation, cancellation, shared-texture accounting and retry/failure paths. +4. **Extend engine policies/catalogs as demand grows.** Add partial-hit source + caching and GPU retirement, then mip-aware family/asset adapters. Defer tiny + collision/UI/building candidates until measured pressure justifies them. + +Measure separate MEM1 resident/idle/staging/destination/retired bytes, ARAM +allocated/ready/pending bytes, largest block/slot counts, actual DMA read/write +bytes, queue wait, copy/CRC/decode/create/GX-wait time, managed allocations/GC, +detail-ready deadlines, churn, missed presentations, input latency and audio. +`AramBytes` currently counts cold-read batch spans only; `MaxUploadUs` starts +after cold-store admission and omits that overhead. + +Compare matched replays at equal asset quality and identical initial saves, +camera, movement and audio. Include cold/warm travel, fast reversals, doors, +indoor/outdoor transitions, teleports and low-memory/fragmented conditions. +Restore lead time must exceed measured queue wait + DMA + CPU reconstruction + +publication time, with margin. If the deadline/headroom is unavailable, retain +the asset or postpone demotion; never wait for a cold read in Draw/Step. + +The existing fixture's comparable-layout no-ARAM/ARAM cases showed fewer storage +reads (129 to 87), but rounded p99 frame time was 17 to 18 ms and publication +counts differed. This is illustrative, not a matched performance proof. Keep +the same presentation cadence and visible readiness, and require no regression +in repeated hardware p95/p99/missed-deadline/input/audio measurements. Dolphin +can check correctness and compare traces; it cannot establish stock-console DMA +bandwidth, audio coexistence or a zero-impact guarantee. + +## Evidence and focused verification + +[Cross-repository budget data](measurements/aram/cross-repo-budget.json) and the +[historical asset inventory](measurements/aram/animaltown-assets.json) distinguish +source observations, derived payload figures and older release measurements. +The latter records release/manifest/package hashes; current SDK 315 asset tools +were not cached, so this audit did not regenerate today's converted game assets. + +The existing SDK host ARAM test passed at the audited source revision: + +```sh +cc -std=c11 -O2 -Wall -Wextra -Werror -Iinclude -DDND_ARAM_TEST \ + tests/aram_test.c source/aram.c -o /tmp/dnd-aram-offload-audit-test +/tmp/dnd-aram-offload-audit-test +``` + +It exercises alignment, capacity, fragmentation/coalescing, 256 handles, busy +transfers, adjacent-byte preservation, pending disposal and injected faults. +This verifies simulated ownership/allocator behavior, not hardware throughput. +No console build or new runtime benchmark is needed to validate this docs-only +investigation; performance acceptance remains future implementation work. + +[sdk-aram]: https://github.com/capz/DolphinDotNet/blob/bac008e509c44cd454eeeec0befad50adf096324/source/aram.c#L39 +[sdk-native-queue]: https://github.com/capz/DolphinDotNet/blob/bac008e509c44cd454eeeec0befad50adf096324/src/DolphinDotNet.GameCube/Dolphin/Graphics/AramTransferQueue.cs#L15 +[sdk-model]: https://github.com/capz/DolphinDotNet/blob/bac008e509c44cd454eeeec0befad50adf096324/src/DolphinDotNet.GameCube/Dolphin/Graphics/Model.cs#L217 +[sdk-restore]: https://github.com/capz/DolphinDotNet/blob/bac008e509c44cd454eeeec0befad50adf096324/source/model.c#L611 +[town-scene]: https://github.com/capz/AnimalTown/blob/31d531feebd3a3dc6567627c60ad8abaa34dac3d/game/AnimalTown.GameCube/Program.cs#L638 +[town-archive]: https://github.com/capz/AnimalTown/blob/31d531feebd3a3dc6567627c60ad8abaa34dac3d/game/AnimalTown.GameCube/TerrainArchive.cs#L72 +[town-dma]: https://github.com/capz/AnimalTown/blob/31d531feebd3a3dc6567627c60ad8abaa34dac3d/tools/native-terrain-archive.inc#L29 +[town-models]: https://github.com/capz/AnimalTown/blob/31d531feebd3a3dc6567627c60ad8abaa34dac3d/game/AnimalTown.GameCube/Program.cs#L112 +[town-retained]: https://github.com/capz/AnimalTown/blob/31d531feebd3a3dc6567627c60ad8abaa34dac3d/tools/patch-managed-allocator.py#L23 +[town-terrain-evidence]: https://github.com/capz/AnimalTown/blob/31d531feebd3a3dc6567627c60ad8abaa34dac3d/docs/performance/2026-11-09-immutable-terrain.json +[engine-stream]: https://github.com/capz/hypercube-engine/blob/a5d2eea566c0521aa5a91a8b177ebdd11df49518/src/Hypercube.GameCube/WorldStreamer.cs#L185 +[engine-pool]: https://github.com/capz/hypercube-engine/blob/a5d2eea566c0521aa5a91a8b177ebdd11df49518/src/Hypercube.GameCube/TexturePool.cs#L21 +[engine-cold]: https://github.com/capz/hypercube-engine/blob/a5d2eea566c0521aa5a91a8b177ebdd11df49518/src/Hypercube.GameCube/AramCache.cs#L58 diff --git a/docs/measurements/aram/animaltown-assets.json b/docs/measurements/aram/animaltown-assets.json new file mode 100644 index 0000000..d8c6fc7 --- /dev/null +++ b/docs/measurements/aram/animaltown-assets.json @@ -0,0 +1,548 @@ +{ + "schema": 1, + "currentSourceRevision": "31d531feebd3a3dc6567627c60ad8abaa34dac3d", + "currentPinnedSdk": "0.1.0-preview.315.1", + "currentPinnedHypercube": "0.1.0-preview.28.1", + "scope": "Read-only ARAM opportunity inventory, historical asset sizing", + "historicalProvenance": { + "gameRevision": "fca068009bed8025d71e3f95cfa3972db92fbf40", + "sdkVersion": "0.1.0-preview.266.1", + "sdkRevision": "858577c63aaf191fce7c83fd4308075d3775f43a", + "hypercubeVersion": "0.1.0-preview.9.1", + "compactFile": "AnimalTown-0.11.16+fca068009bed.nkit.iso", + "compactSha256": "ca7e16eaa26ed43ff4f4c491d9d170be07235f3d7b24f95771befd1b3ec413e1", + "manifestSha256": "dff7bab71f9f63eff01556a85adad8992048f1898cdecab36cb6853a53439899", + "verification": "Every extracted package SHA256 equals release manifest file SHA256; headers and texture section ranges parsed.", + "currentSourceActorArtUnchanged": true, + "currentConverterChanged": true + }, + "models": [ + { + "species": "fox", + "file": "fox.dndmodel", + "packageBytes": 578656, + "sha256": "308d93ca96e53765f06387828254fc6011395bb4d8afdccb174fbde7b9d77065", + "sections": [ + { + "kind": 1, + "offset": 160, + "length": 2920, + "records": 27 + }, + { + "kind": 2, + "offset": 3104, + "length": 199456, + "records": 1 + }, + { + "kind": 3, + "offset": 202560, + "length": 84, + "records": 2 + }, + { + "kind": 4, + "offset": 202656, + "length": 327712, + "records": 1 + }, + { + "kind": 5, + "offset": 530368, + "length": 1640, + "records": 1 + }, + { + "kind": 6, + "offset": 532032, + "length": 46620, + "records": 2 + } + ], + "decodedTexturePayloadBytes": 327680, + "textures": [ + { + "index": 0, + "width": 256, + "height": 256, + "mipLevels": 2, + "decodedRgbaPayloadBytes": 327680, + "sha256": "158914ef785af94eb51f70d374df0ef486da1cffc25266f59f10c49af0866418" + } + ] + }, + { + "species": "bunny", + "file": "bunny.dndmodel", + "packageBytes": 867744, + "sha256": "6a4d6e89cf2c879cfddb00ada6789edb243dfbb17d43d5b15cb0d5696eab7671", + "sections": [ + { + "kind": 1, + "offset": 160, + "length": 220, + "records": 2 + }, + { + "kind": 2, + "offset": 384, + "length": 211748, + "records": 1 + }, + { + "kind": 3, + "offset": 212160, + "length": 84, + "records": 2 + }, + { + "kind": 4, + "offset": 212256, + "length": 655420, + "records": 2 + }, + { + "kind": 5, + "offset": 867680, + "length": 4, + "records": 0 + }, + { + "kind": 6, + "offset": 867712, + "length": 4, + "records": 0 + } + ], + "decodedTexturePayloadBytes": 655360, + "textures": [ + { + "index": 0, + "width": 256, + "height": 256, + "mipLevels": 2, + "decodedRgbaPayloadBytes": 327680, + "sha256": "7fcffabd46fde642f14cfc73cd90877668a325e2eeb738bfacee782691e56132" + }, + { + "index": 1, + "width": 256, + "height": 256, + "mipLevels": 2, + "decodedRgbaPayloadBytes": 327680, + "sha256": "ca1ebcf1ec06af2b4b41d2214eb2a7796a09f9c09e5840110ee7fb72d4086610" + } + ] + }, + { + "species": "giraffe", + "file": "giraffe.dndmodel", + "packageBytes": 491488, + "sha256": "796cda8486aba87d31da585bb8a12c93ecd9f6a52d2e8a14b4ac38ef2dfffe65", + "sections": [ + { + "kind": 1, + "offset": 160, + "length": 3352, + "records": 31 + }, + { + "kind": 2, + "offset": 3520, + "length": 158192, + "records": 1 + }, + { + "kind": 3, + "offset": 161728, + "length": 84, + "records": 2 + }, + { + "kind": 4, + "offset": 161824, + "length": 327712, + "records": 1 + }, + { + "kind": 5, + "offset": 489536, + "length": 1912, + "records": 1 + }, + { + "kind": 6, + "offset": 491456, + "length": 4, + "records": 0 + } + ], + "decodedTexturePayloadBytes": 327680, + "textures": [ + { + "index": 0, + "width": 256, + "height": 256, + "mipLevels": 2, + "decodedRgbaPayloadBytes": 327680, + "sha256": "cd563201d5fb4a6b2617189d5139d1f58a8e7929e68198a9efb533d66aaf1a27" + } + ] + }, + { + "species": "cat", + "file": "cat.dndmodel", + "packageBytes": 902432, + "sha256": "3850975810e19234fd69a7c6ab0dc514fe1b4d04ea52e51f293417c76e4bdd1c", + "sections": [ + { + "kind": 1, + "offset": 160, + "length": 4000, + "records": 37 + }, + { + "kind": 2, + "offset": 4160, + "length": 240384, + "records": 1 + }, + { + "kind": 3, + "offset": 244544, + "length": 84, + "records": 2 + }, + { + "kind": 4, + "offset": 244640, + "length": 655420, + "records": 2 + }, + { + "kind": 5, + "offset": 900064, + "length": 2320, + "records": 1 + }, + { + "kind": 6, + "offset": 902400, + "length": 4, + "records": 0 + } + ], + "decodedTexturePayloadBytes": 655360, + "textures": [ + { + "index": 0, + "width": 256, + "height": 256, + "mipLevels": 2, + "decodedRgbaPayloadBytes": 327680, + "sha256": "ceb702f3d33715244abd67facd4ea62c5880a50e96b22cbe3b14e17741f74dbd" + }, + { + "index": 1, + "width": 256, + "height": 256, + "mipLevels": 2, + "decodedRgbaPayloadBytes": 327680, + "sha256": "ad0d3eb83f39dfc044d40902a21dda9f01b8fac6b9357cb8f997552ad2788474" + } + ] + }, + { + "species": "hamster", + "file": "hamster.dndmodel", + "packageBytes": 481504, + "sha256": "2c693e25ba76ebd701cd620b55409ce0713fd01daa2c29ecb733c424a74bbaec", + "sections": [ + { + "kind": 1, + "offset": 160, + "length": 3028, + "records": 28 + }, + { + "kind": 2, + "offset": 3200, + "length": 148712, + "records": 1 + }, + { + "kind": 3, + "offset": 151936, + "length": 84, + "records": 2 + }, + { + "kind": 4, + "offset": 152032, + "length": 327712, + "records": 1 + }, + { + "kind": 5, + "offset": 479744, + "length": 1708, + "records": 1 + }, + { + "kind": 6, + "offset": 481472, + "length": 4, + "records": 0 + } + ], + "decodedTexturePayloadBytes": 327680, + "textures": [ + { + "index": 0, + "width": 256, + "height": 256, + "mipLevels": 2, + "decodedRgbaPayloadBytes": 327680, + "sha256": "c099f9bf44525cf3582ceb89f9bc31c92760c4d3e25ab67cd85c324eb47c463b" + } + ] + }, + { + "species": "spaniel", + "file": "spaniel.dndmodel", + "packageBytes": 490304, + "sha256": "f3c9c0505f8ecb7a0811289a8a43226524851520136b6de2a7fe4ff285febf8c", + "sections": [ + { + "kind": 1, + "offset": 160, + "length": 4864, + "records": 45 + }, + { + "kind": 2, + "offset": 5024, + "length": 154536, + "records": 1 + }, + { + "kind": 3, + "offset": 159584, + "length": 84, + "records": 2 + }, + { + "kind": 4, + "offset": 159680, + "length": 327712, + "records": 1 + }, + { + "kind": 5, + "offset": 487392, + "length": 2864, + "records": 1 + }, + { + "kind": 6, + "offset": 490272, + "length": 4, + "records": 0 + } + ], + "decodedTexturePayloadBytes": 327680, + "textures": [ + { + "index": 0, + "width": 256, + "height": 256, + "mipLevels": 2, + "decodedRgbaPayloadBytes": 327680, + "sha256": "ce2d227caaf5eff861c6e7a866f9277abbb45e5a7e97f06e5b830e8e18cc997b" + } + ] + } + ], + "uiTextures": [ + { + "file": "gorditas-bold.dndtex", + "packageBytes": 524320, + "format": 3, + "width": 512, + "height": 512, + "pixelPayloadBytes": 524288, + "mipLevels": 1, + "sha256": "0578ec4a8fe0c634119c76678d1762be6dd9222136574d3bc1ad6bd9c78e2e9f" + }, + { + "file": "item-icons.dndtex", + "packageBytes": 262176, + "format": 5, + "width": 512, + "height": 256, + "pixelPayloadBytes": 262144, + "mipLevels": 1, + "sha256": "f32e24032453b08f31c98f1c0f65e47fb5006865949d5f4bdcdb0ca1824af87d" + }, + { + "file": "floor-outdoor-neutral.dndtex", + "packageBytes": 43744, + "format": 14, + "width": 256, + "height": 256, + "pixelPayloadBytes": 43712, + "mipLevels": 7, + "sha256": "3bc0f5bc9bc6e2bf18ac28e1d1d6775e8cb6239b2dd913eccaafc39911164b95" + } + ], + "totals": { + "packageBytes": 3812128, + "decodedRgbaTexturePayloadBytes": 2621440, + "uniqueDecodedRgbaTexturePayloadBytes": 2621440 + }, + "conditionalFoxIndoorExample": { + "conditions": [ + "Fox player remains active", + "All five other species are outside current room", + "No other active instance shares these five model resources", + "Package and texture payload figures only; metadata, native allocator charges and instance caches excluded" + ], + "coldPackageBytes": 3233472, + "potentialDecodedTexturePayloadBytes": 2293760, + "potentialSelectedMem1PayloadBytes": 5527232 + }, + "terrain": { + "existingAramReservationBytes": 8388608, + "fixedMem1CachePayloadBytes": 1048576, + "historicalUsedAramPayloadBytes": 3840416, + "historicalChargedMem1BufferBytes": 1168384, + "historicalEvidenceRevision": "fbba8e2e52e43c63b52704c1b7880226017f52ee", + "source": "docs/performance/2026-11-09-immutable-terrain.json", + "potentialInteriorMem1CachePayloadBytes": 1048576 + }, + "caveats": [ + "This is not a current-source runtime or hardware trace.", + "Historical converter266 outputs are examples; regenerate with pinned315 tool before budgeting current main.", + "Model package bytes already embed the listed texture payload, so sum package plus decoded texture only to estimate existing MEM1 duplication; ARAM stores package once.", + "Do not sum UI/terrain/model examples as a proven concurrent working set.", + "The currently retained building representation explicitly rejects SDK package copy/unload.", + "Existing shared native ARAM single-flight arbitration must be fixed before simultaneous model paging and terrain binds." + ], + "historicalBuildingParts": [ + { + "file": "cottage-door-tex128.dndmodel", + "packageBytes": 30080, + "retainedGeometrySectionBytes": 9120, + "textures": [ + { + "width": 64, + "height": 64, + "levels": 2, + "pixelBytes": 20480, + "sha256": "1849915b91d48d91d558106da39a89f53df241489e7b6702ef0a9c5c1615ff1e" + } + ] + }, + { + "file": "cottage-east-tex128.dndmodel", + "packageBytes": 24032, + "retainedGeometrySectionBytes": 3072, + "textures": [ + { + "width": 64, + "height": 64, + "levels": 2, + "pixelBytes": 20480, + "sha256": "1849915b91d48d91d558106da39a89f53df241489e7b6702ef0a9c5c1615ff1e" + } + ] + }, + { + "file": "cottage-exterior-closed-tex128.dndmodel", + "packageBytes": 76960, + "retainedGeometrySectionBytes": 55992, + "textures": [ + { + "width": 64, + "height": 64, + "levels": 2, + "pixelBytes": 20480, + "sha256": "1849915b91d48d91d558106da39a89f53df241489e7b6702ef0a9c5c1615ff1e" + } + ] + }, + { + "file": "cottage-exterior-tex128.dndmodel", + "packageBytes": 67904, + "retainedGeometrySectionBytes": 46920, + "textures": [ + { + "width": 64, + "height": 64, + "levels": 2, + "pixelBytes": 20480, + "sha256": "1849915b91d48d91d558106da39a89f53df241489e7b6702ef0a9c5c1615ff1e" + } + ] + }, + { + "file": "cottage-floor-tex128.dndmodel", + "packageBytes": 27072, + "retainedGeometrySectionBytes": 6096, + "textures": [ + { + "width": 64, + "height": 64, + "levels": 2, + "pixelBytes": 20480, + "sha256": "1849915b91d48d91d558106da39a89f53df241489e7b6702ef0a9c5c1615ff1e" + } + ] + }, + { + "file": "cottage-north-tex128.dndmodel", + "packageBytes": 33120, + "retainedGeometrySectionBytes": 12144, + "textures": [ + { + "width": 64, + "height": 64, + "levels": 2, + "pixelBytes": 20480, + "sha256": "1849915b91d48d91d558106da39a89f53df241489e7b6702ef0a9c5c1615ff1e" + } + ] + }, + { + "file": "cottage-south-tex128.dndmodel", + "packageBytes": 30080, + "retainedGeometrySectionBytes": 9120, + "textures": [ + { + "width": 64, + "height": 64, + "levels": 2, + "pixelBytes": 20480, + "sha256": "1849915b91d48d91d558106da39a89f53df241489e7b6702ef0a9c5c1615ff1e" + } + ] + }, + { + "file": "cottage-west-tex128.dndmodel", + "packageBytes": 24032, + "retainedGeometrySectionBytes": 3072, + "textures": [ + { + "width": 64, + "height": 64, + "levels": 2, + "pixelBytes": 20480, + "sha256": "1849915b91d48d91d558106da39a89f53df241489e7b6702ef0a9c5c1615ff1e" + } + ] + } + ], + "historicalInteriorGeometrySectionBytes": 33504, + "historicalKitUniqueDecodedTexturePayloadBytes": 20480 +} diff --git a/docs/measurements/aram/cross-repo-budget.json b/docs/measurements/aram/cross-repo-budget.json new file mode 100644 index 0000000..fcecb54 --- /dev/null +++ b/docs/measurements/aram/cross-repo-budget.json @@ -0,0 +1,129 @@ +{ + "schema": 1, + "scope": "Source and asset arithmetic; no new runtime policy or hardware benchmark", + "hardwareMeasurement": false, + "sourceRevisions": { + "sdk": "bac008e509c44cd454eeeec0befad50adf096324", + "hypercube": "a5d2eea566c0521aa5a91a8b177ebdd11df49518", + "animaltown": "31d531feebd3a3dc6567627c60ad8abaa34dac3d" + }, + "aramBudget": { + "physicalBytes": 16777216, + "systemBaseBytes": 16384, + "audioReservationBytes": 2097152, + "sdkUsableBytes": 14663680, + "terrainReservationBytes": 8388608, + "remainingBeforeOtherOwnersBytes": 6275072, + "maximumAllocations": 256, + "alignmentBytes": 32, + "compaction": false + }, + "terrain": { + "proposedSuspendMem1BufferPayloadBytes": 1048576, + "additionalAramSnapshotBytes": 0, + "historicalUnusedReservationBytes": 4548192, + "historicalEvidenceRevision": "fbba8e2e52e43c63b52704c1b7880226017f52ee" + }, + "engineFixture": { + "sourceSha256": "0a782f8137b426528a185cb8bbb5a67ae50d8fc5448ef6a88d56016daec49024", + "resolution": 48, + "records": 649, + "candidates": [ + { + "name": "group-2-cmpr-fine-textures", + "records": 18, + "packedBytes": 22080, + "aramAlignedBytes": 22080, + "nativePayloadBytes": 44160 + }, + { + "name": "clustered-fine-meshes", + "records": 136, + "packedBytes": 296598, + "aramAlignedBytes": 298624, + "nativePayloadBytes": 324354 + }, + { + "name": "collision", + "records": 24, + "packedBytes": 1056, + "aramAlignedBytes": 1536, + "nativePayloadBytes": 1056 + }, + { + "name": "permanent-coarse-patches", + "records": 89, + "packedBytes": 304260, + "aramAlignedBytes": 305632, + "nativePayloadBytes": 334620 + } + ], + "coldBudgetBytes": 262144, + "selectedCandidateRecords": 178, + "selectedAramAlignedBytes": 322240, + "coldBudgetShortfallBytes": 60096, + "schedulerSlots": 128, + "extraFullStagingBufferBytes": 73984 + }, + "sdkOneMiBFirstModelUpload": { + "packageBytes": 1048576, + "managedChunkBytes": 4096, + "logicalRequests": 256, + "dmaOperations": 512, + "dmaBytes": 2097152, + "approximateCpuMemcpyBytes": 3145728, + "minimumTransferObjects": 768, + "directNativeChunkBytes": 65536, + "directNativePotentialDmaOperations": 16, + "directNativePotentialDmaBytes": 1048576, + "requiresSafeNativePackageLease": true + }, + "caveats": [ + "Opportunity sizes are not realized savings; no runtime pager was enabled.", + "Check unique last owners, allocator overhead, pending/retired allocations, peak restore memory and largest free block.", + "Historical AnimalTown converter266 assets must be regenerated with pinned315 tooling before current runtime budgeting.", + "Selected candidates are not a proven concurrent working set.", + "An ARAM copy frees no MEM1 until original allocations are actually released." + ], + "illustrativeDolphinComparison": { + "scope": "Prior combined memory-reduction validation capture; not a matched replay or new benchmark", + "hardwareMeasurement": false, + "matchedReplay": false, + "sourceFile": "out/dolphin-memory-sdk-release-extended/results.json", + "sourceSha256": "50e2662f40ac1a9f864d8d0fdbac327855233cafe6e54ae5be319931641db398", + "configuration": { + "group": 2, + "format": 14, + "readBatchBytes": 65536, + "maxBatchRecords": 8, + "injectFaults": false + }, + "cases": [ + { + "scenario": 4, + "caseFrames": 663, + "frame99ms": 17, + "reads": 129, + "storageKiB": 456, + "aramKiB": 0, + "aramHits": 0, + "publications": 225, + "cancelled": 331, + "useAram": false + }, + { + "scenario": 6, + "caseFrames": 690, + "frame99ms": 18, + "reads": 87, + "storageKiB": 327, + "aramKiB": 142, + "aramHits": 69, + "publications": 232, + "cancelled": 348, + "useAram": true + } + ], + "interpretation": "Less storage traffic; different publications/frame counts and rounded frame p99. Does not establish no performance regression." + } +} diff --git a/docs/memory-and-validation.md b/docs/memory-and-validation.md index 4954beb..e5ee452 100644 --- a/docs/memory-and-validation.md +++ b/docs/memory-and-validation.md @@ -52,3 +52,7 @@ Texture page splitting can cause excessive draws; fix via hierarchical merging. See [the memory reduction audit](memory-reduction-audit.md) for measured host allocation changes, reproducible world payload accounting, implemented staging and metadata reductions, and larger opportunities requiring API/hardware work. + +See the [cross-repository ARAM residency investigation](aram-residency-investigation.md) +for cold-resource opportunities, actual allocator/transfer constraints and the +performance gates needed before automatic paging in AnimalTown.