dev/asset-management (#6)
Co-authored-by: Nilton Constantino <nilton.constantino@visma.com> Reviewed-on: #6
This commit was merged in pull request #6.
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
< [Back](chapter-13.md) | [Summary](table-of-contents.md) >
|
||||
< [Back](chapter-13.md) | [Summary](table-of-contents.md) | [Next](chapter-15.md) >
|
||||
|
||||
# Boot Profiles
|
||||
|
||||
@@ -132,4 +132,4 @@ When `debug == true`:
|
||||
* New boot modes must be compatible extensions
|
||||
|
||||
|
||||
< [Back](chapter-13.md) | [Summary](table-of-contents.md) >
|
||||
< [Back](chapter-13.md) | [Summary](table-of-contents.md) | [Next](chapter-15.md) >
|
||||
|
||||
@@ -0,0 +1,331 @@
|
||||
< [Back](chapter-14.md) | [Summary](table-of-contents.md) >
|
||||
|
||||
# Asset Management
|
||||
|
||||
## Bank-Centric Hardware Asset Model
|
||||
|
||||
**Scope:** Runtime / Hardware Asset Management (SDK-agnostic)
|
||||
|
||||
---
|
||||
|
||||
## 1. Fundamental Principles
|
||||
|
||||
1. **Every asset in Prometeu resides in a Bank**
|
||||
2. **A Bank is a hardware memory management system**
|
||||
3. **Assets are cold binaries stored in the cartridge**
|
||||
4. **Asset memory belongs to the console, not to the VM**
|
||||
5. **Loading, residency, and eviction are explicit**
|
||||
6. **Hardware does not interpret gameplay semantics**
|
||||
7. **The SDK orchestrates policies; hardware executes contracts**
|
||||
|
||||
> In Prometeu, you do not load “data”. You load **residency**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Asset Origin (Cold Storage)
|
||||
|
||||
* All assets initially reside in **cold storage** inside the cartridge.
|
||||
* Typically, each asset corresponds to a binary file.
|
||||
* The runtime **never scans the cartridge directly**.
|
||||
* All access goes through the **Asset Table**.
|
||||
|
||||
---
|
||||
|
||||
## 3. Asset Table
|
||||
|
||||
The Asset Table is an index loaded at cartridge boot.
|
||||
|
||||
It describes **content**, not residency.
|
||||
|
||||
### Location
|
||||
|
||||
* The Asset Table **must be embedded as JSON inside `manifest.json`**.
|
||||
* Tooling may compile this JSON into a binary table for runtime use, but the source of truth is the manifest.
|
||||
|
||||
### Required Fields (conceptual)
|
||||
|
||||
* `asset_id` (integer, internal identifier)
|
||||
* `asset_name` (string, user-facing identifier)
|
||||
* `asset_type` (TILEBANK, SOUNDBANK, BLOB, TILEMAP, ...)
|
||||
* `bank_kind` (mandatory, single)
|
||||
* `offset` (byte offset in cartridge)
|
||||
* `size` (cold size)
|
||||
* `decoded_size` (resident size)
|
||||
* `codec` (RAW, LZ4, ZSTD, ...)
|
||||
* `asset_metadata` (type-specific)
|
||||
|
||||
> `bank_kind` defines **where** an asset may reside in hardware.
|
||||
|
||||
---
|
||||
|
||||
## 4. Bank — Definition
|
||||
|
||||
> **A Bank is the residency and swapping mechanism of the Prometeu hardware.**
|
||||
|
||||
A Bank:
|
||||
|
||||
* owns **numbered slots**
|
||||
* enforces **resident memory budgets**
|
||||
* enforces **staging / inflight budgets**
|
||||
* accepts only compatible assets
|
||||
* supports **atomic swap via commit**
|
||||
* exposes memory and residency metrics
|
||||
|
||||
Banks are hardware infrastructure, not assets.
|
||||
|
||||
---
|
||||
|
||||
## 5. BankKind
|
||||
|
||||
Each Bank belongs to a **BankKind**, defining its pipeline and constraints.
|
||||
|
||||
### Example BankKinds
|
||||
|
||||
* `GFX_TILEBANK`
|
||||
* `AUDIO_SOUNDBANK`
|
||||
* `DATA_BLOBBANK`
|
||||
* `MAP_TILEMAPBANK`
|
||||
|
||||
Each BankKind defines:
|
||||
|
||||
* slot count
|
||||
* maximum resident memory
|
||||
* inflight / staging memory budget
|
||||
* decode and validation pipeline
|
||||
* hardware consumer subsystem (renderer, audio mixer, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 6. Slots and Slot References
|
||||
|
||||
* Each BankKind owns a fixed set of **slots**.
|
||||
* A slot:
|
||||
|
||||
* references a resident asset (or is empty)
|
||||
* never stores data directly
|
||||
* may expose a **generation counter** (debug)
|
||||
|
||||
### Slot Reference
|
||||
|
||||
Slots are always referenced with explicit BankKind context:
|
||||
|
||||
* `gfxSlot(3)`
|
||||
* `audioSlot(1)`
|
||||
* `blobSlot(7)`
|
||||
|
||||
This prevents cross-bank ambiguity.
|
||||
|
||||
---
|
||||
|
||||
## 7. Bank Memory Model
|
||||
|
||||
* Bank memory is **console-owned memory**.
|
||||
* It does not belong to the VM heap.
|
||||
* It does not participate in GC.
|
||||
* It can be fully released when the cartridge shuts down.
|
||||
|
||||
Each Bank manages:
|
||||
|
||||
* total memory
|
||||
* used memory
|
||||
* free memory
|
||||
* inflight (staging) memory
|
||||
|
||||
Conceptually, each Bank is a **specialized allocator**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Unified Loader
|
||||
|
||||
### Conceptual API
|
||||
|
||||
```text
|
||||
handle = asset.load(asset_name, slotRef, flags)
|
||||
```
|
||||
|
||||
Load flow:
|
||||
|
||||
1. Resolve `asset_name` via Asset Table to get its `asset_id`
|
||||
2. Read `bank_kind` from asset entry
|
||||
3. Validate compatibility with `slotRef`
|
||||
4. Enqueue load request
|
||||
5. Perform IO + decode on worker
|
||||
6. Produce materialized asset in staging
|
||||
|
||||
### Handle States
|
||||
|
||||
* `PENDING` — enqueued
|
||||
* `LOADING` — IO/decode in progress
|
||||
* `READY` — staging completed
|
||||
* `COMMITTED` — installed into slot
|
||||
* `CANCELED`
|
||||
* `ERROR`
|
||||
|
||||
---
|
||||
|
||||
## 9. Commit
|
||||
|
||||
```text
|
||||
asset.commit(handle)
|
||||
```
|
||||
|
||||
* Commit is **explicit** and **atomic**
|
||||
* Executed at a safe frame boundary
|
||||
* Performs **pointer swap** in the target slot
|
||||
* Previous asset is released if no longer referenced
|
||||
|
||||
The hardware **never swaps slots automatically**.
|
||||
|
||||
---
|
||||
|
||||
## 10. Asset Deduplication
|
||||
|
||||
* A decoded asset exists **at most once per BankKind**.
|
||||
* Multiple slots may reference the same resident asset.
|
||||
* Redundant loads become **install-only** operations.
|
||||
|
||||
Memory duplication is forbidden by contract.
|
||||
|
||||
---
|
||||
|
||||
## 11. Bank Specializations
|
||||
|
||||
### 11.1 GFX_TILEBANK
|
||||
|
||||
* AssetType: TILEBANK
|
||||
* Immutable graphical tile + palette structure
|
||||
* Consumed by the graphics subsystem
|
||||
|
||||
### 11.2 AUDIO_SOUNDBANK
|
||||
|
||||
* AssetType: SOUNDBANK
|
||||
* Resident audio samples or streams
|
||||
* Consumed by the audio mixer
|
||||
|
||||
### 11.3 DATA_BLOBBANK
|
||||
|
||||
* AssetType: BLOB
|
||||
* Read-only byte buffers
|
||||
* Hardware does not interpret contents
|
||||
|
||||
Used by the SDK via:
|
||||
|
||||
* **Views** (zero-copy, read-only)
|
||||
* **Decode** (materialization into VM heap)
|
||||
|
||||
---
|
||||
|
||||
## 12. Views and Decode (SDK Contract)
|
||||
|
||||
* **View**
|
||||
|
||||
* read-only
|
||||
* zero-copy
|
||||
* valid only while the blob remains resident
|
||||
|
||||
* **Decode**
|
||||
|
||||
* allocates VM-owned entities
|
||||
* independent from the Bank after creation
|
||||
|
||||
Hardware is unaware of Views and Decode semantics.
|
||||
|
||||
---
|
||||
|
||||
## 13. Manifest and Initial Load
|
||||
|
||||
* The cartridge may include a `manifest.json`.
|
||||
* The manifest may declare:
|
||||
|
||||
* assets to preload
|
||||
* target slot references
|
||||
|
||||
These loads occur **before the first frame**.
|
||||
|
||||
---
|
||||
|
||||
## 14. Shutdown and Eviction
|
||||
|
||||
* On cartridge shutdown:
|
||||
|
||||
* all Banks are cleared
|
||||
* all resident memory is released
|
||||
|
||||
No implicit persistence exists.
|
||||
|
||||
---
|
||||
|
||||
## 15. Debugger and Telemetry
|
||||
|
||||
Each Bank must expose:
|
||||
|
||||
* total memory
|
||||
* used memory
|
||||
* free memory
|
||||
* inflight memory
|
||||
* occupied slots
|
||||
* `asset_id` per slot
|
||||
* `asset_name` per slot
|
||||
* generation per slot
|
||||
|
||||
This enables debuggers to visualize:
|
||||
|
||||
* memory stacks per Bank
|
||||
* memory pressure
|
||||
* streaming strategies
|
||||
|
||||
---
|
||||
|
||||
## 16. Minimal Syscall API (Derived)
|
||||
|
||||
The following syscalls form the minimal hardware contract for asset management:
|
||||
|
||||
```text
|
||||
asset.load(asset_name, slotRef, flags) -> handle
|
||||
asset.status(handle) -> LoadStatus
|
||||
asset.commit(handle)
|
||||
asset.cancel(handle)
|
||||
|
||||
bank.info(bank_kind) -> BankStats
|
||||
bank.slot_info(slotRef) -> SlotStats
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
* `LoadStatus` ∈ { PENDING, LOADING, READY, COMMITTED, CANCELED, ERROR }
|
||||
* `BankStats` exposes memory usage and limits
|
||||
* `SlotStats` exposes current asset_id, asset_name and generation
|
||||
|
||||
---
|
||||
|
||||
## 17. Separation of Responsibilities
|
||||
|
||||
### Hardware (Prometeu)
|
||||
|
||||
* manages memory
|
||||
* loads bytes
|
||||
* decodes assets
|
||||
* swaps pointers
|
||||
* reports usage
|
||||
|
||||
### SDK
|
||||
|
||||
* defines packs, scenes, and policies
|
||||
* interprets blobs
|
||||
* creates VM entities
|
||||
|
||||
### VM
|
||||
|
||||
* executes logic
|
||||
* manages its own heap
|
||||
* never owns hardware assets
|
||||
|
||||
---
|
||||
|
||||
## 18. Golden Rule
|
||||
|
||||
> **Banks are the foundation of the hardware.**
|
||||
> **Asset Types describe content.**
|
||||
> **The SDK orchestrates; the hardware executes.**
|
||||
|
||||
< [Back](chapter-14.md) | [Summary](table-of-contents.md) >
|
||||
@@ -14,6 +14,7 @@
|
||||
- [Chapter 12: Firmware — PrometeuOS (POS) + PrometeuHub](chapter-12.md)
|
||||
- [Chapter 13: Cartridge](chapter-13.md)
|
||||
- [Chapter 14: Boot Profiles](chapter-14.md)
|
||||
- [Chapter 15: Asset Management](chapter-15.md)
|
||||
|
||||
---
|
||||
[Back to README](../README.md)
|
||||
Reference in New Issue
Block a user