discussion framework migration
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
# Time Model and Cycles
|
||||
|
||||
Domain: machine timing and cycles
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../runtime/learn/mental-model-time-and-cycles.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the temporal contract of the PROMETEU machine.
|
||||
|
||||
It covers:
|
||||
|
||||
- machine base clock;
|
||||
- logical frame structure;
|
||||
- cycle accounting;
|
||||
- per-frame budget;
|
||||
- CAP interaction with time measurement.
|
||||
|
||||
## 2 System Base Clock
|
||||
|
||||
PROMETEU operates with a fixed **60 Hz** logical clock.
|
||||
|
||||
This means:
|
||||
|
||||
- 60 iterations of the machine loop per second;
|
||||
- each iteration corresponds to one logical frame;
|
||||
- the logical clock is stable regardless of host platform.
|
||||
|
||||
## 3 Logical Frame
|
||||
|
||||
A PROMETEU frame represents a complete unit of machine execution.
|
||||
|
||||
Conceptual stage order:
|
||||
|
||||
```text
|
||||
FRAME N
|
||||
INPUT
|
||||
UPDATE
|
||||
DRAW
|
||||
AUDIO
|
||||
SYNC
|
||||
```
|
||||
|
||||
The machine guarantees:
|
||||
|
||||
- fixed stage order;
|
||||
- deterministic repetition;
|
||||
- no implicit extra frames between logical frame boundaries.
|
||||
|
||||
## 4 PROMETEU Cycles
|
||||
|
||||
### 4.1 Definition
|
||||
|
||||
A **PROMETEU cycle** is the abstract unit used to measure execution cost inside the machine.
|
||||
|
||||
- VM instructions consume documented cycle cost;
|
||||
- peripheral operations also consume cycle cost;
|
||||
- cycle cost is independent of host wall-clock timing.
|
||||
|
||||
### 4.2 Properties
|
||||
|
||||
Cycles are:
|
||||
|
||||
- countable;
|
||||
- comparable;
|
||||
- stable across supported hosts;
|
||||
- suitable for certification and profiling.
|
||||
|
||||
## 5 Per-Frame Budget
|
||||
|
||||
Each frame has a maximum cycle budget.
|
||||
|
||||
This budget:
|
||||
|
||||
- is reset every frame;
|
||||
- does not accumulate unused cycles;
|
||||
- represents the capacity of the virtual execution envelope for that frame.
|
||||
|
||||
### 5.1 Conceptual Example
|
||||
|
||||
```text
|
||||
Frame Budget: 10,000 cycles
|
||||
|
||||
Used:
|
||||
- Update logic: 4,200
|
||||
- Draw calls: 3,100
|
||||
- Audio: 900
|
||||
|
||||
Remaining:
|
||||
1,800 cycles
|
||||
```
|
||||
|
||||
## 6 Work Distribution Over Time
|
||||
|
||||
PROMETEU does not require all logic to run every frame.
|
||||
|
||||
Machine-visible work may be distributed over time, for example:
|
||||
|
||||
- enemy logic every 2 frames;
|
||||
- pathfinding every 4 frames;
|
||||
- timers based on frame count;
|
||||
- subsystem-specific update cadence.
|
||||
|
||||
Such distribution changes cycle pressure and is part of the observable execution model.
|
||||
|
||||
## 7 CAP Interaction
|
||||
|
||||
The **CAP** defines contextual technical limits such as:
|
||||
|
||||
- maximum cycle budget per frame;
|
||||
- memory limits;
|
||||
- peripheral call limits.
|
||||
|
||||
### 7.1 CAP Does Not Block Execution
|
||||
|
||||
Fundamental rules:
|
||||
|
||||
- the game always runs;
|
||||
- the game can always be packaged;
|
||||
- the game can always be played.
|
||||
|
||||
CAP does not prevent execution.
|
||||
|
||||
### 7.2 CAP Generates Evidence
|
||||
|
||||
When CAP is active, PROMETEU measures and records:
|
||||
|
||||
- average cycle usage per frame;
|
||||
- cycle peaks;
|
||||
- problematic frames;
|
||||
- cost distribution.
|
||||
|
||||
These data feed certification artifacts without changing cartridge semantics.
|
||||
|
||||
## 8 Time-Based Certification
|
||||
|
||||
PROMETEU certification may analyze:
|
||||
|
||||
- average cycle usage per frame;
|
||||
- maximum peaks;
|
||||
- problematic frames;
|
||||
- dominant cost sources.
|
||||
|
||||
### 8.1 Conceptual Example
|
||||
|
||||
```text
|
||||
Target CAP: PROMETEU-LITE
|
||||
Frame Budget: 5,000 cycles
|
||||
|
||||
Frame 18231:
|
||||
Used: 5,612 cycles
|
||||
|
||||
Primary cause:
|
||||
enemy.updateAI(): 1,012 cycles
|
||||
```
|
||||
@@ -0,0 +1,129 @@
|
||||
# Prometeu Virtual Machine (PVM)
|
||||
|
||||
Domain: VM subsystem overview
|
||||
Function: normative
|
||||
|
||||
This chapter defines the VM as an execution subsystem inside the PROMETEU machine.
|
||||
|
||||
It is intentionally narrower than the broader machine specs:
|
||||
|
||||
- execution model;
|
||||
- opcode families;
|
||||
- verifier boundary;
|
||||
- relationship between the VM and adjacent specs.
|
||||
|
||||
For the bytecode-level instruction contract, see [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md).
|
||||
|
||||
## 1 Scope
|
||||
|
||||
The PVM is a **deterministic, stack-based VM** designed for a fantasy console environment with fixed frame timing and explicit hardware-facing services.
|
||||
|
||||
This chapter does not fully restate:
|
||||
|
||||
- detailed value and calling semantics;
|
||||
- heap/gate/GC internals;
|
||||
- coroutine scheduling internals;
|
||||
- host ABI policy.
|
||||
|
||||
Those now live in focused companion specs:
|
||||
|
||||
- [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md)
|
||||
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md)
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md)
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md)
|
||||
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md)
|
||||
- [`16a-syscall-policies.md`](16a-syscall-policies.md)
|
||||
|
||||
## 2 Core Design Principles
|
||||
|
||||
The PVM is designed around the following constraints:
|
||||
|
||||
1. **Deterministic execution**: no hidden threads or asynchronous callbacks.
|
||||
2. **Frame-based timing**: execution is bounded by frame time and explicit safepoints.
|
||||
3. **Safe memory model**: heap access is mediated by validated handles.
|
||||
4. **Simple compilation target**: stack-based bytecode with verified control flow.
|
||||
5. **Stable ABI**: calls and syscalls follow fixed slot-based contracts.
|
||||
6. **First-class functions**: user function values are represented through closures.
|
||||
|
||||
## 3 Execution Model
|
||||
|
||||
The PVM executes bytecode inside the PROMETEU frame loop.
|
||||
|
||||
Each frame:
|
||||
|
||||
1. firmware enters the VM;
|
||||
2. the VM runs until:
|
||||
- the frame budget is consumed; or
|
||||
- a `FRAME_SYNC` instruction is reached;
|
||||
3. at `FRAME_SYNC`, the VM reaches the primary safepoint for GC and cooperative scheduling;
|
||||
4. control returns to firmware/runtime orchestration.
|
||||
|
||||
`FRAME_SYNC` is the primary VM synchronization point. It is the boundary where the machine can safely account for:
|
||||
|
||||
- GC opportunity;
|
||||
- coroutine handoff;
|
||||
- frame-completion semantics;
|
||||
- deterministic return to firmware.
|
||||
|
||||
## 4 Instruction Families
|
||||
|
||||
The public VM instruction surface is documented at the bytecode level in [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md). At the machine/spec level, the instruction families are:
|
||||
|
||||
- execution control:
|
||||
- `NOP`, `HALT`, `JMP`, `JMP_IF_FALSE`, `JMP_IF_TRUE`, `TRAP`, `FRAME_SYNC`
|
||||
- stack manipulation:
|
||||
- `PUSH_CONST`, literal pushes, `POP`, `POP_N`, `DUP`, `SWAP`
|
||||
- arithmetic and logic:
|
||||
- numeric, comparison, boolean, and bitwise operations
|
||||
- variable access:
|
||||
- globals and locals
|
||||
- function calls:
|
||||
- `CALL`, `RET`
|
||||
- function values:
|
||||
- `MAKE_CLOSURE`, `CALL_CLOSURE`
|
||||
- cooperative concurrency:
|
||||
- `SPAWN`, `YIELD`, `SLEEP`
|
||||
- VM/host boundary:
|
||||
- `HOSTCALL`, `SYSCALL`, `INTRINSIC`
|
||||
|
||||
The machine-level rule is simple:
|
||||
|
||||
- opcodes define explicit behavior;
|
||||
- there are no hidden execution paths;
|
||||
- timing-sensitive behavior is exposed through frame and safepoint semantics.
|
||||
|
||||
## 5 Verifier Boundary
|
||||
|
||||
Before execution, bytecode must pass the verifier.
|
||||
|
||||
The verifier ensures, at minimum:
|
||||
|
||||
1. valid instruction decoding;
|
||||
2. valid jump targets;
|
||||
3. consistent stack depth across control-flow joins;
|
||||
4. valid call/return shape;
|
||||
5. closure call safety rules;
|
||||
6. patched syscall and intrinsic validity.
|
||||
|
||||
The verifier is structural. It does not replace runtime validation of dynamic values.
|
||||
|
||||
## 6 Relationship to Adjacent Specs
|
||||
|
||||
- [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) defines slot values, tuples, frames, and return-slot semantics.
|
||||
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines closure representation and function-value behavior.
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines stack/heap, handles, object layout, and GC.
|
||||
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines events, timers, and the frame boundary model.
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling.
|
||||
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the syscall ABI boundary.
|
||||
|
||||
## 7 Summary
|
||||
|
||||
The PVM is:
|
||||
|
||||
- stack-based;
|
||||
- deterministic;
|
||||
- frame-synchronized;
|
||||
- verifier-gated;
|
||||
- closure-capable;
|
||||
- coroutine-capable;
|
||||
- embedded inside the larger PROMETEU console model, not equal to it.
|
||||
@@ -0,0 +1,102 @@
|
||||
# VM Values and Calling Convention
|
||||
|
||||
Domain: VM values and calling convention
|
||||
Function: normative
|
||||
|
||||
This chapter isolates the slot/value model and the rules for calls, returns, tuples, and frames.
|
||||
|
||||
## 1 Value Types
|
||||
|
||||
All runtime values are stored in VM slots as `Value`.
|
||||
|
||||
### Primitive value types
|
||||
|
||||
| Type | Description |
|
||||
| ------- | --------------------- |
|
||||
| `int` | 64-bit signed integer |
|
||||
| `bool` | Boolean value |
|
||||
| `float` | 64-bit floating point |
|
||||
|
||||
### Built-in vector and graphics types
|
||||
|
||||
These are treated as VM values with stable layout semantics.
|
||||
|
||||
| Type | Description |
|
||||
| ------- | --------------------------------- |
|
||||
| `vec2` | 2D vector (x, y) |
|
||||
| `color` | Packed color value |
|
||||
| `pixel` | Combination of position and color |
|
||||
|
||||
These values:
|
||||
|
||||
- live on the stack;
|
||||
- are copied by value;
|
||||
- do not require heap allocation by themselves.
|
||||
|
||||
### Heap values
|
||||
|
||||
Heap-resident entities are referenced indirectly through handles.
|
||||
|
||||
| Type | Description |
|
||||
| -------- | -------------------------- |
|
||||
| `handle` | Reference to a heap object |
|
||||
| `null` | Null handle |
|
||||
|
||||
Handle semantics are defined in [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md).
|
||||
|
||||
## 2 Tuples and Multi-Return ABI
|
||||
|
||||
The PVM supports multi-value returns.
|
||||
|
||||
Tuple rules:
|
||||
|
||||
- tuples are stack-only;
|
||||
- tuples are not heap objects by default;
|
||||
- tuple persistence requires explicit boxing into a heap representation when such a representation exists in the language/toolchain;
|
||||
- return shape is part of the function contract.
|
||||
|
||||
## 3 Call Convention
|
||||
|
||||
Each function declares a fixed return-slot shape.
|
||||
|
||||
At call time:
|
||||
|
||||
1. the caller prepares arguments;
|
||||
2. `CALL` transfers control;
|
||||
3. the callee executes under its frame contract;
|
||||
4. `RET` leaves exactly the declared return-slot shape on the stack.
|
||||
|
||||
The verifier ensures:
|
||||
|
||||
- all reachable return paths agree on return-slot count;
|
||||
- stack depth remains coherent across the function body.
|
||||
|
||||
## 4 Call Stack and Frames
|
||||
|
||||
The VM uses a call stack.
|
||||
|
||||
Conceptual frame shape:
|
||||
|
||||
```
|
||||
Frame {
|
||||
return_pc
|
||||
base_pointer
|
||||
ret_slots
|
||||
}
|
||||
```
|
||||
|
||||
Execution uses the public call instructions:
|
||||
|
||||
| Opcode | Description |
|
||||
| ------ | ---------------------- |
|
||||
| `CALL` | Calls a function by id |
|
||||
| `RET` | Returns from function |
|
||||
|
||||
There is no separate public ISA for manual frame stack manipulation.
|
||||
|
||||
## 5 Relationship to Other Specs
|
||||
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM execution subsystem at a higher level.
|
||||
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines first-class function values.
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines stack/heap and handle-backed objects.
|
||||
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) reuses the same slot-oriented argument/return philosophy for syscalls.
|
||||
@@ -0,0 +1,70 @@
|
||||
# VM Function Values and Closures
|
||||
|
||||
Domain: VM closures and function values
|
||||
Function: normative
|
||||
|
||||
This chapter defines how the PVM models first-class function values.
|
||||
|
||||
## 1 First-Class Function Model
|
||||
|
||||
The PVM treats user function values as closures.
|
||||
|
||||
This means:
|
||||
|
||||
- functions can be stored in variables;
|
||||
- functions can be passed as arguments;
|
||||
- functions can be returned from other functions;
|
||||
- function values carry explicit runtime representation.
|
||||
|
||||
Even functions without captures may be represented as closures with an empty capture set.
|
||||
|
||||
## 2 Closure Layout
|
||||
|
||||
Closures are heap objects.
|
||||
|
||||
Conceptual layout:
|
||||
|
||||
```
|
||||
Closure {
|
||||
func_id
|
||||
captures[]
|
||||
}
|
||||
```
|
||||
|
||||
Captures may be:
|
||||
|
||||
- copied values;
|
||||
- handles to heap objects.
|
||||
|
||||
Closure environments are part of the GC root graph as long as the closure remains reachable.
|
||||
|
||||
## 3 Direct and Indirect Calls
|
||||
|
||||
The PVM supports two forms of invocation:
|
||||
|
||||
| Opcode | Description |
|
||||
| -------------- | -------------------------------------- |
|
||||
| `CALL` | Direct call by function id |
|
||||
| `CALL_CLOSURE` | Indirect call through a closure handle |
|
||||
|
||||
For `CALL_CLOSURE`:
|
||||
|
||||
1. the closure handle is read from the stack;
|
||||
2. the VM resolves the target function;
|
||||
3. captured environment state becomes available to the callee according to the closure calling convention.
|
||||
|
||||
## 4 Verification and Safety
|
||||
|
||||
The verifier ensures, at minimum:
|
||||
|
||||
- closure call sites have coherent arity;
|
||||
- invalid closure call shapes are rejected or trapped according to the verifier/runtime boundary;
|
||||
- return-slot contracts remain valid.
|
||||
|
||||
Handle validity, heap reachability, and dynamic misuse remain subject to runtime checks where static proof is not possible.
|
||||
|
||||
## 5 Relationship to Memory and GC
|
||||
|
||||
- Closure objects live in heap memory, so their object model is constrained by [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md).
|
||||
- Captured heap references participate in the GC root graph.
|
||||
- Closures are function values, not syscalls; syscall calls remain a separate non-first-class boundary defined in [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md).
|
||||
@@ -0,0 +1,192 @@
|
||||
# Memory Model
|
||||
|
||||
Domain: VM memory model
|
||||
Function: normative
|
||||
|
||||
This chapter defines the VM memory architecture: stack, heap, handles, object layout, allocation, and garbage collection.
|
||||
|
||||
It intentionally focuses on VM-managed memory.
|
||||
|
||||
Host-owned memory surfaces such as asset banks and persistent save storage are covered by their own domain specs and by the host ABI docs.
|
||||
|
||||
## 1 Overview
|
||||
|
||||
The PVM memory model is based on:
|
||||
|
||||
- stack-resident execution values;
|
||||
- heap-resident objects;
|
||||
- validated handles for indirect heap access;
|
||||
- GC-managed object lifetime.
|
||||
|
||||
## 2 Stack Memory
|
||||
|
||||
The stack stores transient execution values and frame-scoped data.
|
||||
|
||||
### Stack value types
|
||||
|
||||
The stack may contain:
|
||||
|
||||
- primitive values;
|
||||
- built-in fixed-layout values;
|
||||
- heap handles;
|
||||
- tuple-shaped multi-return values.
|
||||
|
||||
See [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) for the slot/value model.
|
||||
|
||||
### Stack properties
|
||||
|
||||
- stack values are local to execution state;
|
||||
- stack discipline is verifier-sensitive;
|
||||
- stack underflow and invalid access are traps.
|
||||
|
||||
## 3 Heap Memory
|
||||
|
||||
The heap stores runtime objects that require identity and reachability tracking.
|
||||
|
||||
### Heap characteristics
|
||||
|
||||
- user objects live in the heap;
|
||||
- arrays and closures live in the heap;
|
||||
- heap access is indirect through handles;
|
||||
- the collector is non-moving in the baseline model.
|
||||
|
||||
## 4 Handles and Gate Table
|
||||
|
||||
All heap objects are accessed via handles.
|
||||
|
||||
A conceptual handle:
|
||||
|
||||
```
|
||||
handle = { index, generation }
|
||||
```
|
||||
|
||||
Conceptual gate entry:
|
||||
|
||||
```
|
||||
GateEntry {
|
||||
alive: bool
|
||||
generation: u32
|
||||
base: usize
|
||||
slots: u32
|
||||
type_id: u32
|
||||
}
|
||||
```
|
||||
|
||||
### Handle safety
|
||||
|
||||
When an object is freed:
|
||||
|
||||
- `alive` becomes false;
|
||||
- `generation` is incremented.
|
||||
|
||||
When a handle is used:
|
||||
|
||||
- the index must exist;
|
||||
- the generation must match;
|
||||
- invalid or stale handles trap.
|
||||
|
||||
This prevents:
|
||||
|
||||
- use-after-free;
|
||||
- stale references;
|
||||
- hidden raw memory access.
|
||||
|
||||
## 5 Object Layout
|
||||
|
||||
Heap objects use explicit, implementation-visible layout rules.
|
||||
|
||||
Conceptual form:
|
||||
|
||||
```
|
||||
Object {
|
||||
type_id
|
||||
field_0
|
||||
field_1
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Properties:
|
||||
|
||||
- fields are stored in slot order;
|
||||
- there is no raw pointer arithmetic in the VM model;
|
||||
- layout rules are explicit and verifier/runtime-friendly.
|
||||
|
||||
Closures and coroutine-owned state may build on top of this memory model, but their behavioral rules are documented separately:
|
||||
|
||||
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md)
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md)
|
||||
|
||||
## 6 Garbage Collection
|
||||
|
||||
The PVM uses a **mark-sweep collector**.
|
||||
|
||||
### GC properties
|
||||
|
||||
- non-moving in the baseline model;
|
||||
- runs only at safepoints;
|
||||
- primary safepoint: `FRAME_SYNC`.
|
||||
|
||||
### GC triggers
|
||||
|
||||
GC may run when:
|
||||
|
||||
- heap usage exceeds threshold;
|
||||
- allocation pressure is high.
|
||||
|
||||
### Root set
|
||||
|
||||
The collector marks from:
|
||||
|
||||
- operand stack;
|
||||
- call stack frames;
|
||||
- global variables;
|
||||
- coroutine-owned execution state;
|
||||
- closure environments;
|
||||
- host-held roots where the host legally retains VM heap references.
|
||||
|
||||
## 7 Allocation and Deallocation
|
||||
|
||||
### Allocation
|
||||
|
||||
Heap allocation conceptually performs:
|
||||
|
||||
1. reserve object storage;
|
||||
2. create or reuse gate entry;
|
||||
3. return validated handle.
|
||||
|
||||
If allocation fails:
|
||||
|
||||
- the VM may trigger GC;
|
||||
- if pressure remains unresolved, allocation may trap or fail according to the runtime contract.
|
||||
|
||||
### Deallocation
|
||||
|
||||
Objects are reclaimed by GC.
|
||||
|
||||
When reclaimed:
|
||||
|
||||
- the gate is marked dead;
|
||||
- the generation is incremented;
|
||||
- storage becomes reusable.
|
||||
|
||||
## 8 Memory Safety Rules
|
||||
|
||||
The VM enforces:
|
||||
|
||||
1. all heap access goes through handles;
|
||||
2. generation checks validate handle freshness;
|
||||
3. object and field access is bounds-checked;
|
||||
4. there is no guest-visible raw pointer arithmetic;
|
||||
5. stack discipline remains verifier-constrained.
|
||||
|
||||
Any violation results in a trap or rejected program image.
|
||||
|
||||
## 9 Relationship to Other Specs
|
||||
|
||||
- [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) defines stack values and tuple/call-slot semantics.
|
||||
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines closure function values.
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine state and scheduling behavior.
|
||||
- [`15-asset-management.md`](15-asset-management.md) defines asset-bank surfaces outside VM heap ownership.
|
||||
- [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) defines save storage outside VM heap ownership.
|
||||
- [`16a-syscall-policies.md`](16a-syscall-policies.md) defines host-root rules and host/heap interaction policy.
|
||||
@@ -0,0 +1,593 @@
|
||||
# GFX Peripheral (Graphics System)
|
||||
|
||||
Domain: virtual hardware: graphics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-gfx.md`](../runtime/learn/mental-model-gfx.md)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The **GFX** peripheral is responsible for generating images in PROMETEU.
|
||||
|
||||
It is an explicit 2D graphics device based on:
|
||||
|
||||
- framebuffer
|
||||
- tilemaps
|
||||
- tile banks
|
||||
- priority-based sprites
|
||||
- composition by drawing order
|
||||
|
||||
---
|
||||
|
||||
## 2. Resolution and Framebuffer
|
||||
|
||||
### Base resolution
|
||||
|
||||
- **320 × 180 pixels**
|
||||
- aspect ratio close to 16:9
|
||||
- scalable by the host (nearest-neighbor)
|
||||
|
||||
### Pixel format
|
||||
|
||||
- **RGB565**
|
||||
- 5 bits Red
|
||||
- 6 bits Green
|
||||
- 5 bits Blue
|
||||
- no alpha channel
|
||||
|
||||
Transparency is handled via **color key**.
|
||||
|
||||
---
|
||||
|
||||
## 3. Double Buffering
|
||||
|
||||
The GFX maintains two buffers:
|
||||
|
||||
- **Back Buffer** — where the frame is built
|
||||
- **Front Buffer** — where the frame is displayed
|
||||
|
||||
Per-frame flow:
|
||||
|
||||
1. The system draws to the back buffer
|
||||
2. Calls `present()`
|
||||
3. Buffers are swapped
|
||||
4. The host displays the front buffer
|
||||
|
||||
This guarantees:
|
||||
|
||||
- no tearing
|
||||
- clear per-frame synchronization
|
||||
- deterministic behavior
|
||||
|
||||
---
|
||||
|
||||
## 4. PROMETEU Graphical Structure
|
||||
|
||||
The graphical world is composed of:
|
||||
|
||||
- Up to **16 Tile Banks**
|
||||
- **4 Tile Layers** (scrollable)
|
||||
- **1 HUD Layer** (fixed, always on top)
|
||||
- Sprites with priority between layers
|
||||
|
||||
### 4.1 Tile Banks
|
||||
|
||||
- There are up to **16 banks**
|
||||
- Each bank has a fixed tile size:
|
||||
- 8×8, 16×16, or 32×32
|
||||
- A bank is a graphics library:
|
||||
- environment
|
||||
- characters
|
||||
- UI
|
||||
- effects
|
||||
- `assets.pa` tile-bank payloads use a serialized representation distinct from runtime memory:
|
||||
- serialized pixels are `4bpp` packed in payload order
|
||||
- runtime memory may expand pixels to one `u8` palette index per pixel after decode
|
||||
|
||||
### 4.2 Layers
|
||||
|
||||
- There are:
|
||||
- 4 Tile Layers
|
||||
- 1 HUD Layer
|
||||
- Each layer points to **a single bank**
|
||||
- Sprites can use **any bank**
|
||||
- HUD:
|
||||
- does not scroll
|
||||
- maximum priority
|
||||
- generally uses 8×8 tiles
|
||||
|
||||
---
|
||||
|
||||
## 5. Internal Model of a Tile Layer
|
||||
|
||||
A Tile Layer **is not a bitmap of pixels**.
|
||||
It is composed of:
|
||||
|
||||
- A **logical Tilemap** (tile indices)
|
||||
- A **Border Cache** (window of visible tiles)
|
||||
- A **Scroll Offset**
|
||||
|
||||
### Structure:
|
||||
|
||||
- `bank_id`
|
||||
- `tile_size`
|
||||
- `tilemap` (large matrix)
|
||||
- `scroll_x`, `scroll_y`
|
||||
- `cache_origin_x`, `cache_origin_y`
|
||||
- `cache_tiles[w][h]`
|
||||
|
||||
---
|
||||
|
||||
## 6. Logical Tilemap
|
||||
|
||||
The tilemap represents the world:
|
||||
|
||||
Each cell contains:
|
||||
|
||||
- `tile_id`
|
||||
- `flip_x`
|
||||
- `flip_y`
|
||||
- `priority` (optional)
|
||||
- `palette_id` (optional)
|
||||
|
||||
The tilemap can be much larger than the screen.
|
||||
|
||||
---
|
||||
|
||||
## 7. Border Cache (Tile Cache)
|
||||
|
||||
The cache is a window of tiles around the camera.
|
||||
|
||||
Example:
|
||||
|
||||
- Screen: 320×180
|
||||
- 16×16 tiles → 20×12 visible
|
||||
- Cache: 22×14 (1-tile margin)
|
||||
|
||||
It stores tiles already resolved from the tilemap.
|
||||
|
||||
---
|
||||
|
||||
## 8. Cache Update
|
||||
|
||||
Every frame:
|
||||
|
||||
1. Calculate:
|
||||
- `tile_x = scroll_x / tile_size`
|
||||
- `tile_y = scroll_y / tile_size`
|
||||
- `offset_x = scroll_x % tile_size`
|
||||
- `offset_y = scroll_y % tile_size`
|
||||
|
||||
2. If `tile_x` changed:
|
||||
- Advance `cache_origin_x`
|
||||
- Reload only the new column
|
||||
|
||||
3. If `tile_y` changed:
|
||||
- Advance `cache_origin_y`
|
||||
- Reload only the new line
|
||||
|
||||
Only **one row and/or column** is updated per frame.
|
||||
|
||||
---
|
||||
|
||||
## 9. Cache as Ring Buffer
|
||||
|
||||
The cache is circular:
|
||||
|
||||
- Does not physically move data
|
||||
- Only moves logical indices
|
||||
|
||||
Access:
|
||||
- `real_x = (cache_origin_x + logical_x) % cache_width`
|
||||
- `real_y = (cache_origin_y + logical_y) % cache_height`
|
||||
|
||||
---
|
||||
|
||||
## 10. Projection to the Back Buffer
|
||||
|
||||
For each frame:
|
||||
|
||||
1. For each Tile Layer, in order:
|
||||
- Rasterize visible tiles from the cache
|
||||
- Apply scroll, flip, and transparency
|
||||
- Write to the back buffer
|
||||
|
||||
2. Draw sprites:
|
||||
- With priority between layers
|
||||
- Drawing order defines depth
|
||||
|
||||
3. Draw HUD layer last
|
||||
|
||||
---
|
||||
|
||||
## 11. Drawing Order and Priority
|
||||
|
||||
- There is no Z-buffer
|
||||
- There is no automatic sorting
|
||||
- Whoever draws later is in front
|
||||
|
||||
Base order:
|
||||
|
||||
1. Tile Layer 0
|
||||
2. Tile Layer 1
|
||||
3. Tile Layer 2
|
||||
4. Tile Layer 3
|
||||
5. Sprites (by priority between layers)
|
||||
6. HUD Layer
|
||||
|
||||
---
|
||||
|
||||
## 12. Transparency (Color Key)
|
||||
|
||||
- One RGB565 value is reserved as TRANSPARENT_KEY
|
||||
- Pixels with this color are not drawn
|
||||
|
||||
```
|
||||
if src == TRANSPARENT_KEY:
|
||||
skip
|
||||
else:
|
||||
draw
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 13. Color Math (Discrete Blending)
|
||||
|
||||
Inspired by the SNES.
|
||||
|
||||
Official modes:
|
||||
|
||||
- `BLEND_NONE`
|
||||
- `BLEND_HALF`
|
||||
- `BLEND_HALF_PLUS`
|
||||
- `BLEND_HALF_MINUS`
|
||||
- `BLEND_FULL`
|
||||
|
||||
No continuous alpha.
|
||||
No arbitrary blending.
|
||||
|
||||
Everything is:
|
||||
|
||||
- integer
|
||||
- cheap
|
||||
- deterministic
|
||||
|
||||
---
|
||||
|
||||
## 14. Where Blend is Applied
|
||||
|
||||
- Blending occurs during drawing
|
||||
- The result goes directly to the back buffer
|
||||
- There is no automatic post-composition
|
||||
|
||||
---
|
||||
|
||||
## 15. What the GFX DOES NOT support
|
||||
|
||||
By design:
|
||||
|
||||
- Continuous alpha
|
||||
- RGBA framebuffer
|
||||
- Shaders
|
||||
- Modern GPU pipeline
|
||||
- HDR
|
||||
- Gamma correction
|
||||
|
||||
---
|
||||
|
||||
## 16. Performance Rule
|
||||
|
||||
- Layers:
|
||||
- only update the border when crossing a tile
|
||||
- never redraw the entire world
|
||||
- Rasterization:
|
||||
- always per frame, only the visible area
|
||||
- Sprites:
|
||||
- always redrawn per frame
|
||||
|
||||
---
|
||||
|
||||
## 17. Special PostFX — Fade (Scene and HUD)
|
||||
|
||||
PROMETEU supports **gradual fade** as a special PostFX, with two independent
|
||||
controls:
|
||||
|
||||
- **Scene Fade**: affects the entire scene (Tile Layers 0–3 + Sprites)
|
||||
- **HUD Fade**: affects only the HUD Layer (always composed last)
|
||||
|
||||
The fade is implemented without continuous per-pixel alpha and without floats.
|
||||
It uses a **discrete integer level** (0..31), which in practice produces an
|
||||
"almost continuous" visual result in 320×180 pixel art.
|
||||
|
||||
---
|
||||
|
||||
### 17.1 Fade Representation
|
||||
|
||||
Each fade is represented by:
|
||||
|
||||
- `fade_level: u8` in the range **[0..31]**
|
||||
- `0` → fully replaced by the fade color
|
||||
- `31` → fully visible (no fade)
|
||||
- `fade_color: RGB565`
|
||||
- color the image will be blended into
|
||||
|
||||
Registers:
|
||||
|
||||
- `SCENE_FADE_LEVEL` (0..31)
|
||||
- `SCENE_FADE_COLOR` (RGB565)
|
||||
- `HUD_FADE_LEVEL` (0..31)
|
||||
- `HUD_FADE_COLOR` (RGB565)
|
||||
|
||||
Common cases:
|
||||
|
||||
- Fade-out: `fade_color = BLACK`
|
||||
- Flash/teleport: `fade_color = WHITE`
|
||||
- Special effects: any RGB565 color
|
||||
|
||||
---
|
||||
|
||||
### 17.2 Fade Operation (Blending with Arbitrary Color)
|
||||
|
||||
For each RGB565 pixel `src` and fade color `fc`, the final pixel `dst` is calculated per channel.
|
||||
|
||||
1) Extract components:
|
||||
|
||||
- `src_r5`, `src_g6`, `src_b5`
|
||||
- `fc_r5`, `fc_g6`, `fc_b5`
|
||||
|
||||
2) Apply integer blending:
|
||||
|
||||
```
|
||||
src_weight = fade_level // 0..31
|
||||
fc_weight = 31 - fade_level
|
||||
|
||||
r5 = (src_r5 * src_weight + fc_r5 * fc_weight) / 31
|
||||
g6 = (src_g6 * src_weight + fc_g6 * fc_weight) / 31
|
||||
b5 = (src_b5 * src_weight + fc_b5 * fc_weight) / 31
|
||||
```
|
||||
- `src_r5`, `src_g6`, `src_b5`
|
||||
- `fc_r5`, `fc_g6`, `fc_b5`
|
||||
|
||||
3) Repack:
|
||||
|
||||
```
|
||||
dst = pack_rgb565(r5, g6, b5)
|
||||
```
|
||||
|
||||
|
||||
Notes:
|
||||
|
||||
- Deterministic operation
|
||||
- Integers only
|
||||
- Can be optimized via LUT
|
||||
|
||||
---
|
||||
|
||||
### 17.3 Order of Application in the Frame
|
||||
|
||||
The frame composition follows this order:
|
||||
|
||||
1. Rasterize **Tile Layers 0–3** → Back Buffer
|
||||
2. Rasterize **Sprites** according to priority
|
||||
3. (Optional) Extra pipeline (Emission/Light/Glow etc.)
|
||||
4. Apply **Scene Fade** using:
|
||||
- `SCENE_FADE_LEVEL`
|
||||
- `SCENE_FADE_COLOR`
|
||||
5. Rasterize **HUD Layer**
|
||||
6. Apply **HUD Fade** using:
|
||||
- `HUD_FADE_LEVEL`
|
||||
- `HUD_FADE_COLOR`
|
||||
7. `present()`
|
||||
|
||||
Rules:
|
||||
|
||||
- Scene Fade never affects the HUD
|
||||
- HUD Fade never affects the scene
|
||||
|
||||
---
|
||||
|
||||
## 18. Palette System
|
||||
|
||||
### 18.1. Overview
|
||||
|
||||
PROMETEU uses **exclusively** palette-indexed graphics.
|
||||
|
||||
There is no direct RGB-per-pixel mode.
|
||||
Every graphical pixel is an **index** pointing to a real color in a palette.
|
||||
|
||||
---
|
||||
|
||||
### 18.2. Pixel Format
|
||||
|
||||
Each pixel of a tile or sprite is:
|
||||
|
||||
- **4 bits per pixel (4bpp)**
|
||||
- values: `0..15`
|
||||
|
||||
Fixed rule:
|
||||
|
||||
- Index `0` = TRANSPARENT
|
||||
- Indices `1..15` = valid palette colors
|
||||
|
||||
---
|
||||
|
||||
### 18.3. Palette Structure
|
||||
|
||||
Each **Tile Bank** contains:
|
||||
|
||||
- **64 palettes** in runtime-facing v1
|
||||
- Each palette has:
|
||||
- **16 colors**
|
||||
- each color in **RGB565 (`u16`, little-endian in serialized assets)**
|
||||
|
||||
Size:
|
||||
|
||||
- 1 palette = 16 × 2 bytes = **32 bytes**
|
||||
- 64 palettes = **2 KB per bank**
|
||||
- 16 banks = **32 KB maximum palettes**
|
||||
|
||||
---
|
||||
|
||||
### 18.4. Palette Association
|
||||
|
||||
#### Fundamental Rule
|
||||
|
||||
- Each **tile** uses **a single palette**
|
||||
- Each **sprite** uses **a single palette**
|
||||
- The palette must be provided **explicitly** in every draw
|
||||
|
||||
There is no palette swap within the same tile or sprite.
|
||||
|
||||
---
|
||||
|
||||
### 18.5. Where the Palette is Defined
|
||||
|
||||
#### Tilemap
|
||||
|
||||
Each tilemap cell contains:
|
||||
|
||||
- `tile_id`
|
||||
- `palette_id (u8)`
|
||||
- `flip_x`
|
||||
- `flip_y`
|
||||
|
||||
Runtime-facing validity rule for v1:
|
||||
|
||||
- `palette_id` values are valid only in the range `0..63`
|
||||
|
||||
#### Sprite
|
||||
|
||||
Each sprite draw contains:
|
||||
|
||||
- `bank_id`
|
||||
- `tile_id`
|
||||
- `palette_id (u8)`
|
||||
- `x`, `y`
|
||||
- `flip_x`, `flip_y`
|
||||
- `priority`
|
||||
|
||||
Runtime-facing validity rule for v1:
|
||||
|
||||
- `palette_id` values are valid only in the range `0..63`
|
||||
|
||||
---
|
||||
|
||||
### 18.6. Color Resolution
|
||||
|
||||
The pipeline works like this:
|
||||
|
||||
1. Read indexed pixel from tile (value 0..15)
|
||||
2. If index == 0 → transparent pixel
|
||||
3. Otherwise:
|
||||
- real_color = palette[palette_id][index]
|
||||
4. Apply:
|
||||
- flip
|
||||
- discrete blend
|
||||
- writing to back buffer
|
||||
|
||||
In other words:
|
||||
```
|
||||
pixel_index = tile_pixel(x,y)
|
||||
if pixel_index == 0:
|
||||
skip
|
||||
else:
|
||||
color = bank.palettes[palette_id][pixel_index]
|
||||
draw(color)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 18.7. Organization of Tile Banks
|
||||
|
||||
Tile Banks are "strong assets":
|
||||
|
||||
- Tiles and palettes live together
|
||||
- Export/import always carries:
|
||||
- tiles + palettes
|
||||
- In `assets.pa` v1, the serialized payload is:
|
||||
- packed indexed pixels for the whole sheet
|
||||
- followed by the palette table for the same bank
|
||||
- The hardware does not impose semantic organization:
|
||||
- grouping is the creator's decision
|
||||
- Tooling and scripts can create conventions:
|
||||
- e.g.: palettes 0..15 = enemies
|
||||
- 16..31 = scenery
|
||||
- etc.
|
||||
|
||||
Runtime-facing v1 baseline:
|
||||
|
||||
- sheet pixels are authored and resolved as indexed values `0..15`
|
||||
- serialized tile-bank payload uses packed `u4` pixel indices
|
||||
- runtime may materialize the decoded bank as expanded `u8` pixel indices plus palette table
|
||||
|
||||
---
|
||||
|
||||
### 18.8. Metrics for Certification (CAP)
|
||||
|
||||
The system can measure:
|
||||
|
||||
- `palettes_loaded_total`
|
||||
- `palettes_referenced_this_frame`
|
||||
- `tiles_drawn_by_palette_id`
|
||||
- `sprites_drawn_by_palette_id`
|
||||
|
||||
---
|
||||
|
||||
## 19. Syscall Return and Fault Policy
|
||||
|
||||
`gfx` follows status-first policy for operations with operational failure modes.
|
||||
|
||||
Fault boundary:
|
||||
|
||||
- `Trap`: structural ABI misuse (type/arity/capability/shape mismatch);
|
||||
- `status`: operational failure;
|
||||
- `Panic`: internal runtime invariant break only.
|
||||
|
||||
### 19.1 `gfx.set_sprite`
|
||||
|
||||
Return-shape matrix in v1:
|
||||
|
||||
| Syscall | Return | Policy basis |
|
||||
| ------------------ | ------------- | ---------------------------------------------------- |
|
||||
| `gfx.clear` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.fill_rect` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_line` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_circle` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_disc` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_square` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.set_sprite` | `status:int` | operational rejection must be explicit |
|
||||
| `gfx.draw_text` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.clear_565` | `void` | no real operational failure path in v1 |
|
||||
|
||||
Only `gfx.set_sprite` is status-returning in v1.
|
||||
All other `gfx` syscalls remain `void` unless a future domain revision introduces a real operational failure path.
|
||||
|
||||
### 19.2 `gfx.set_sprite`
|
||||
|
||||
`gfx.set_sprite` returns `status:int`.
|
||||
|
||||
ABI:
|
||||
1. `bank_id: int` — index of the tile bank
|
||||
2. `index: int` — sprite index (0..511)
|
||||
3. `x: int` — x coordinate
|
||||
4. `y: int` — y coordinate
|
||||
5. `tile_id: int` — tile index within the bank
|
||||
6. `palette_id: int` — palette index (0..63)
|
||||
7. `active: bool` — visibility toggle
|
||||
8. `flip_x: bool` — horizontal flip
|
||||
9. `flip_y: bool` — vertical flip
|
||||
10. `priority: int` — layer priority (0..4)
|
||||
|
||||
Minimum status table:
|
||||
|
||||
- `0` = `OK`
|
||||
- `2` = `INVALID_SPRITE_INDEX`
|
||||
- `3` = `INVALID_ARG_RANGE`
|
||||
- `4` = `BANK_INVALID`
|
||||
|
||||
Operational notes:
|
||||
|
||||
- no fallback to default bank when the sprite bank id cannot be resolved;
|
||||
- no silent no-op for invalid index/range;
|
||||
- `palette_id` and `priority` must be validated against runtime-supported ranges.
|
||||
@@ -0,0 +1,225 @@
|
||||
# Audio Peripheral (Audio System)
|
||||
|
||||
Domain: virtual hardware: audio
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-audio.md`](../runtime/learn/mental-model-audio.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the runtime-facing audio contract of PROMETEU.
|
||||
|
||||
The AUDIO peripheral is responsible for sound generation and mixing under explicit machine limits.
|
||||
|
||||
Core contract:
|
||||
|
||||
- command-driven control from the game loop;
|
||||
- fixed output format;
|
||||
- finite voice count;
|
||||
- deterministic voice conflict policy;
|
||||
- explicit cost in cycles and certification surface.
|
||||
|
||||
## 2 General Architecture
|
||||
|
||||
The audio system is composed of:
|
||||
|
||||
- **Voices (channels)** — independent players
|
||||
- **Samples** — PCM data
|
||||
- **Mixer** — summation of voices
|
||||
- **Output** — PCM stereo buffer
|
||||
|
||||
Timing boundary:
|
||||
|
||||
- game sends commands at **60 Hz**;
|
||||
- audio generates PCM at **48 kHz**.
|
||||
|
||||
## 3 Output Format
|
||||
|
||||
- Sample rate: **48,000 Hz**
|
||||
- Format: **PCM16 stereo (signed i16)**
|
||||
- Clipping: saturation/clamp
|
||||
|
||||
## 4 Voices
|
||||
|
||||
### 4.1 Quantity
|
||||
|
||||
```
|
||||
MAX_VOICES = 16
|
||||
```
|
||||
|
||||
Each voice:
|
||||
|
||||
- plays **1 sample at a time**
|
||||
- is independent
|
||||
- is mixed into the final output
|
||||
|
||||
### 4.2 Voice State
|
||||
|
||||
Each voice maintains:
|
||||
|
||||
- `sample_id`
|
||||
- `pos` (fractional position in the sample)
|
||||
- `rate` (pitch)
|
||||
- `volume` (0..255)
|
||||
- `pan` (0..255, left→right)
|
||||
- `loop_mode` (off / on)
|
||||
- `loop_start`, `loop_end`
|
||||
- `priority` (optional)
|
||||
|
||||
### 4.3 Voice Conflict
|
||||
|
||||
If all voices are occupied:
|
||||
|
||||
- an explicit policy is applied:
|
||||
- `STEAL_OLDEST`
|
||||
- `STEAL_QUIETEST`
|
||||
- `STEAL_LOWEST_PRIORITY`
|
||||
|
||||
## 5 Samples
|
||||
|
||||
### 5.1 Format
|
||||
|
||||
PROMETEU samples:
|
||||
|
||||
- **PCM16 mono**
|
||||
- own sample_rate (e.g., 22050, 44100, 48000)
|
||||
- immutable data at runtime
|
||||
|
||||
Fields:
|
||||
|
||||
- `sample_rate`
|
||||
- `frames_len`
|
||||
- `loop_start`, `loop_end` (optional)
|
||||
|
||||
### 5.2 Command Surface
|
||||
|
||||
Representative command surface:
|
||||
|
||||
```text
|
||||
audio.play(sample, voice, volume, pan, pitch, priority)
|
||||
audio.stop(voice)
|
||||
audio.setVolume(voice, value)
|
||||
audio.setPan(voice, value)
|
||||
audio.setPitch(voice, value)
|
||||
audio.isPlaying(voice)
|
||||
```
|
||||
|
||||
## 6 Pitch and Interpolation
|
||||
|
||||
- `rate = 1.0` → normal speed
|
||||
- `rate > 1.0` → higher pitch
|
||||
- `rate < 1.0` → lower pitch
|
||||
|
||||
As position becomes fractional:
|
||||
|
||||
- **linear interpolation** is used between two neighboring samples
|
||||
|
||||
## 7 Mixer
|
||||
|
||||
For each output frame (48kHz):
|
||||
|
||||
1. For each active voice:
|
||||
- read sample at current position
|
||||
- apply pitch
|
||||
- apply volume
|
||||
- apply pan → generates L/R
|
||||
2. Sum all voices
|
||||
3. Apply clamp
|
||||
4. Write to the stereo buffer
|
||||
|
||||
Cost depends on:
|
||||
|
||||
- number of active voices
|
||||
- use of interpolation
|
||||
|
||||
## 8 Synchronization with the Game
|
||||
|
||||
- Game runs at **60Hz**
|
||||
- Audio generates data at **48kHz**
|
||||
|
||||
Every frame (60Hz):
|
||||
|
||||
- game sends commands:
|
||||
- play
|
||||
- stop
|
||||
- set_volume
|
||||
- set_pan
|
||||
- set_pitch
|
||||
|
||||
The audio applies these commands and continues playing.
|
||||
|
||||
## 9 Host Responsibilities
|
||||
|
||||
The PROMETEU machine defines the audio model, commands, and limits.
|
||||
|
||||
The host is responsible for:
|
||||
|
||||
- choosing the concrete audio backend;
|
||||
- scheduling buffer delivery;
|
||||
- keeping PCM output continuous without changing logical behavior.
|
||||
|
||||
## 10 Audio and CAP
|
||||
|
||||
Audio participates in the Execution CAP:
|
||||
|
||||
- mixing cost per frame
|
||||
- cost per active voice
|
||||
- command cost
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Frame 1024:
|
||||
voices_active: 9
|
||||
mix_cycles: 410
|
||||
audio_commands: 6
|
||||
```
|
||||
|
||||
## 11 Syscall Return and Fault Policy
|
||||
|
||||
`audio` follows status-first policy for operations with operational failure modes.
|
||||
|
||||
Fault boundary:
|
||||
|
||||
- `Trap`: structural ABI misuse (type/arity/capability/shape mismatch);
|
||||
- `status`: operational failure;
|
||||
- `Panic`: internal invariant break only.
|
||||
|
||||
### 11.1 MVP return shape
|
||||
|
||||
In the current MVP:
|
||||
|
||||
- `audio.play` returns `status:int`;
|
||||
- `audio.play_sample` returns `status:int`.
|
||||
|
||||
ABI `audio.play`:
|
||||
1. `bank_id: int` — index of the sound bank
|
||||
2. `sample_id: int` — index of the sample within the bank
|
||||
3. `voice_id: int` — index of the voice to use (0..15)
|
||||
4. `volume: int` — volume level (0..255)
|
||||
5. `pan: int` — panning (0..255)
|
||||
6. `pitch: float` — playback rate
|
||||
7. `loop_mode: int` — `0` for Off, `1` for On
|
||||
|
||||
Return-shape matrix in v1 syscall surface:
|
||||
|
||||
| Syscall | Return | Policy basis |
|
||||
| --------------------- | ------------ | -------------------------------------- |
|
||||
| `audio.play` | `status:int` | operational rejection is observable |
|
||||
| `audio.play_sample` | `status:int` | operational rejection is observable |
|
||||
|
||||
### 11.2 Minimum status table for `play`/`play_sample`
|
||||
|
||||
- `0` = `OK`
|
||||
- `1` = `VOICE_INVALID`
|
||||
- `2` = `SAMPLE_NOT_FOUND`
|
||||
- `3` = `ARG_RANGE_INVALID`
|
||||
- `5` = `NO_EFFECT`
|
||||
- `6` = `BANK_INVALID`
|
||||
|
||||
Operational rules:
|
||||
|
||||
- no fallback to default bank when a bank id cannot be resolved;
|
||||
- no silent no-op for invalid `voice_id`;
|
||||
- invalid `voice_id` must return `VOICE_INVALID`, not `ARG_RANGE_INVALID`;
|
||||
- invalid numeric ranges (e.g. `volume`, `pan`, `pitch`) must return explicit status.
|
||||
@@ -0,0 +1,109 @@
|
||||
# Input Peripheral (VM-Owned Snapshot Input)
|
||||
|
||||
Domain: virtual hardware: input
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-input.md`](../runtime/learn/mental-model-input.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the runtime-facing input contract of PROMETEU.
|
||||
|
||||
Core contract:
|
||||
|
||||
- input is exposed as VM-owned snapshot state;
|
||||
- sampling happens at a deterministic point of each logical frame;
|
||||
- queries are deterministic inside the same frame;
|
||||
- input access uses VM-owned intrinsics (not host syscalls in v1).
|
||||
|
||||
## 2 Devices and Surface
|
||||
|
||||
For v1, the input domain includes:
|
||||
|
||||
- `pad`
|
||||
- `touch`
|
||||
- `button` (as a nested state surface used by `pad` and `touch`)
|
||||
|
||||
No analog axis is part of the v1 input contract.
|
||||
|
||||
## 3 Frame Sampling Model
|
||||
|
||||
Input state is captured at the beginning of each logical frame, before update logic runs.
|
||||
|
||||
Conceptual flow:
|
||||
|
||||
```text
|
||||
FRAME N:
|
||||
SAMPLE_INPUT
|
||||
UPDATE
|
||||
DRAW
|
||||
AUDIO
|
||||
SYNC
|
||||
```
|
||||
|
||||
Within the same frame:
|
||||
|
||||
- input state is immutable;
|
||||
- repeated reads return the same values.
|
||||
|
||||
## 4 State Semantics
|
||||
|
||||
`button` exposes:
|
||||
|
||||
- `pressed: bool` (true only on transition up -> down in this frame)
|
||||
- `released: bool` (true only on transition down -> up in this frame)
|
||||
- `down: bool` (true while physically pressed in this frame snapshot)
|
||||
- `hold: int` (count of consecutive pressed frames)
|
||||
|
||||
`pad` is a fixed set of buttons:
|
||||
|
||||
- `up`, `down`, `left`, `right`
|
||||
- `a`, `b`, `x`, `y`
|
||||
- `l`, `r`, `start`, `select`
|
||||
|
||||
`touch` exposes:
|
||||
|
||||
- `x: int`
|
||||
- `y: int`
|
||||
- `button` with the same `pressed/released/down/hold` semantics
|
||||
|
||||
PROMETEU handheld v1 uses single-touch active pointer semantics.
|
||||
|
||||
## 5 Access Model
|
||||
|
||||
Input is VM-owned in v1:
|
||||
|
||||
- frontend surfaces may be ergonomic and language-specific;
|
||||
- lowering maps to VM-owned `INTRINSIC <id_final>`;
|
||||
- no input syscall is required in the host ABI path.
|
||||
|
||||
Illustrative (language-level) shape:
|
||||
|
||||
```text
|
||||
Input.pad().up().hold()
|
||||
Input.touch().x()
|
||||
```
|
||||
|
||||
The normative contract is intrinsic identity/version and semantics, not source syntax.
|
||||
|
||||
## 6 Determinism and Replay
|
||||
|
||||
Given the same per-frame input snapshots, execution must produce the same observable results.
|
||||
|
||||
This enables:
|
||||
|
||||
- deterministic replay;
|
||||
- deterministic certification analysis;
|
||||
- controlled input injection in tests/tooling.
|
||||
|
||||
## 7 Capability and Certification
|
||||
|
||||
Input reads are not capability-gated by syscall capability policy in v1.
|
||||
|
||||
Input access is VM-owned and should not be reported as host syscall consumption.
|
||||
|
||||
## 8 Portability
|
||||
|
||||
All platforms must provide the mandatory input elements (`pad`, `touch`, `button`) to the runtime.
|
||||
|
||||
Platform differences in physical device mapping are resolved outside VM semantics.
|
||||
@@ -0,0 +1,171 @@
|
||||
# Touch Peripheral (Absolute Pointer Input System)
|
||||
|
||||
Domain: virtual hardware: touch
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-touch.md`](../runtime/learn/mental-model-touch.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the runtime-facing TOUCH contract of PROMETEU.
|
||||
|
||||
Core contract:
|
||||
|
||||
- one absolute pointer at a time;
|
||||
- framebuffer-aligned coordinates;
|
||||
- per-frame state exposure;
|
||||
- no gesture semantics;
|
||||
- no acceleration or smoothing semantics.
|
||||
|
||||
## 2 Coordinate Space
|
||||
|
||||
- TOUCH coordinates use **the same space as the framebuffer**
|
||||
- Resolution: **320×180**
|
||||
- Origin: top-left corner `(0,0)`
|
||||
- Ranges:
|
||||
- `x ∈ [0, 319]`
|
||||
- `y ∈ [0, 179]`
|
||||
|
||||
TOUCH is **absolute**:
|
||||
|
||||
- `(x, y)` represents the current contact position after normalization;
|
||||
- the runtime does not apply dynamic transformation to that coordinate pair.
|
||||
|
||||
## 3 TOUCH Peripheral API
|
||||
|
||||
### 3.1 Exposed Structure
|
||||
|
||||
```
|
||||
TOUCH:
|
||||
present : bool
|
||||
down : bool
|
||||
pressed : bool
|
||||
released : bool
|
||||
x : int
|
||||
y : int
|
||||
|
||||
```
|
||||
### 3.2 Field Semantics
|
||||
|
||||
- **present**
|
||||
- `true` if the TOUCH peripheral is available
|
||||
- `false` if there is no physical touch (desktop, hardware without touch)
|
||||
- **down**
|
||||
- `true` while the active pointer is pressed
|
||||
- **pressed**
|
||||
- `true` only in the frame where the active pointer was captured
|
||||
- **released**
|
||||
- `true` only in the frame where the active pointer was released
|
||||
- **x, y**
|
||||
- current position of the active pointer
|
||||
- valid only when `down == true`
|
||||
|
||||
## 4 Pointer Selection Policy
|
||||
|
||||
### *Single Pointer Capture Policy*
|
||||
|
||||
When multiple physical touches occur, PROMETEU applies the following policy:
|
||||
|
||||
### 4.1 Initial Capture
|
||||
|
||||
1. If **no pointer is active**
|
||||
2. And a **new physical touch** occurs
|
||||
3. The **first detected touch** is captured
|
||||
4. This touch becomes the **active pointer**
|
||||
|
||||
This frame generates:
|
||||
|
||||
- `pressed = true`
|
||||
- `down = true`
|
||||
|
||||
### 4.2 Capture Maintenance
|
||||
|
||||
While the active pointer is pressed:
|
||||
|
||||
- Only it is tracked
|
||||
- All other physical touches are ignored
|
||||
- `x, y` follow only the active pointer
|
||||
|
||||
### 4.3 Release
|
||||
|
||||
When the active pointer is released:
|
||||
|
||||
- `released = true`
|
||||
- `down = false`
|
||||
- The system enters a **no active pointer** state
|
||||
|
||||
### 4.4 Recapture
|
||||
|
||||
After release:
|
||||
|
||||
- Touches that **were already present** are ignored
|
||||
- A new pointer is only captured with a **new touch event**
|
||||
|
||||
## 5 Deliberately Unsupported Behaviors
|
||||
|
||||
The TOUCH peripheral **does not implement**:
|
||||
|
||||
❌ Multitouch
|
||||
|
||||
❌ Gestures (swipe, pinch, rotate, long-press)
|
||||
|
||||
❌ Acceleration or smoothing
|
||||
|
||||
❌ Dynamic sensitivity
|
||||
|
||||
❌ Implicit history
|
||||
|
||||
❌ Intent interpretation
|
||||
|
||||
If a game wants any of these behaviors, it must:
|
||||
|
||||
- implement them explicitly
|
||||
- using only per-frame state
|
||||
- without implicit hardware support
|
||||
|
||||
## 6 “No Gesture” — Formal Definition
|
||||
|
||||
PROMETEU **does not interpret temporal patterns**.
|
||||
|
||||
The TOUCH peripheral **does not classify actions** as:
|
||||
|
||||
- swipe
|
||||
- drag
|
||||
- long press
|
||||
- double tap
|
||||
|
||||
It only reports:
|
||||
|
||||
- current position
|
||||
- contact state
|
||||
|
||||
All semantics are the game's responsibility.
|
||||
|
||||
## 7 “No Acceleration” — Formal Definition
|
||||
|
||||
PROMETEU **does not modify** the TOUCH input.
|
||||
|
||||
- No sensitivity curves
|
||||
- No speed-based amplification
|
||||
- No smoothing
|
||||
|
||||
The relationship between the physical touch and `(x, y)` is **1:1** after normalization.
|
||||
|
||||
## 8 Integration with Other Input Forms
|
||||
|
||||
- Desktop:
|
||||
- mouse can emulate TOUCH
|
||||
- Mobile:
|
||||
- direct physical touch
|
||||
- Steam Deck:
|
||||
- physical touchscreen
|
||||
- PROMETEU Hardware:
|
||||
- optional touch, but supported
|
||||
|
||||
## 9 Portability Guarantees
|
||||
|
||||
Every PROMETEU game that uses TOUCH:
|
||||
|
||||
- behaves identically on all platforms
|
||||
- does not depend on host-specific capabilities
|
||||
- does not suffer semantic variation between desktop, mobile, and dedicated hardware
|
||||
@@ -0,0 +1,140 @@
|
||||
# Save Memory and MEMCARD
|
||||
|
||||
Domain: virtual hardware: save memory
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-save-memory-and-memcard.md`](../runtime/learn/mental-model-save-memory-and-memcard.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the `game` persistence surface in PROMETEU.
|
||||
|
||||
MEMCARD is a runtime-owned service layered on top of the runtime filesystem.
|
||||
|
||||
Games do not get broad path-based filesystem access for saves. They use slot operations only.
|
||||
|
||||
## 2 Profile Contract (`game`)
|
||||
|
||||
The v1 contract is fixed:
|
||||
|
||||
- `32` slots per game (`slot_index: 0..31`);
|
||||
- each slot has up to `32KB` payload;
|
||||
- ownership is isolated by `app_id`;
|
||||
- persistence is explicit through `slot_commit`;
|
||||
- copy/export/import is a Hub/OS responsibility (outside game userland).
|
||||
|
||||
## 3 Slot Identity and Metadata
|
||||
|
||||
Each slot has runtime-owned metadata:
|
||||
|
||||
- `app_id` owner;
|
||||
- `slot_index`;
|
||||
- `save_uuid`;
|
||||
- `generation`;
|
||||
- `checksum`;
|
||||
- `payload_size`;
|
||||
- `state`.
|
||||
|
||||
State values:
|
||||
|
||||
- `0 = EMPTY`
|
||||
- `1 = STAGED`
|
||||
- `2 = COMMITTED`
|
||||
- `3 = CORRUPT`
|
||||
|
||||
`generation` and `checksum` are not manually controlled by game code:
|
||||
|
||||
- `generation` increments on successful `slot_commit`;
|
||||
- `checksum` is recalculated by runtime for committed payload integrity.
|
||||
|
||||
## 4 Host ABI Surface (v1)
|
||||
|
||||
Canonical module: `mem` (version `1`).
|
||||
|
||||
| Operation | Signature |
|
||||
| --- | --- |
|
||||
| `slot_count` | `mem.slot_count() -> (status:int, count:int)` |
|
||||
| `slot_stat` | `mem.slot_stat(slot:int) -> (status:int, state:int, used_bytes:int, generation:int, checksum:int)` |
|
||||
| `slot_read` | `mem.slot_read(slot:int, offset:int, max_bytes:int) -> (status:int, payload_hex:string, bytes_read:int)` |
|
||||
| `slot_write` | `mem.slot_write(slot:int, offset:int, payload_hex:string) -> (status:int, bytes_written:int)` |
|
||||
| `slot_commit` | `mem.slot_commit(slot:int) -> status:int` |
|
||||
| `slot_clear` | `mem.slot_clear(slot:int) -> status:int` |
|
||||
|
||||
`status` is always the first return slot.
|
||||
|
||||
### 4.1 Byte transport note (v1)
|
||||
|
||||
Current ABI transport for memcard payload is `payload_hex:string`.
|
||||
|
||||
This is a temporary transport form until VM-owned bytes (`HeapRef<Bytes>`) is exposed in the host ABI path.
|
||||
|
||||
## 5 Operation Semantics
|
||||
|
||||
### `slot_count`
|
||||
|
||||
- returns slot capacity visible to game profile (`32`);
|
||||
- does not depend on slot content.
|
||||
|
||||
### `slot_stat`
|
||||
|
||||
- returns current state and integrity/version metadata for one slot.
|
||||
|
||||
### `slot_read`
|
||||
|
||||
- reads from staged content when present, otherwise committed content;
|
||||
- returns empty payload with success when offset is beyond current payload end.
|
||||
|
||||
### `slot_write`
|
||||
|
||||
- writes into slot staging buffer (does not persist directly);
|
||||
- supports offset writes;
|
||||
- does not allow resulting payload above `32KB`.
|
||||
|
||||
### `slot_commit`
|
||||
|
||||
- persists staged payload for one slot;
|
||||
- commit is atomic at slot operation level (all-or-error, no silent partial success).
|
||||
|
||||
### `slot_clear`
|
||||
|
||||
- clears staged content and removes committed slot payload.
|
||||
|
||||
## 6 Status Codes (Domain-Owned)
|
||||
|
||||
Minimum status catalog:
|
||||
|
||||
- `0 = OK`
|
||||
- `1 = EMPTY`
|
||||
- `2 = NOT_FOUND`
|
||||
- `3 = NO_SPACE`
|
||||
- `4 = ACCESS_DENIED`
|
||||
- `5 = CORRUPT`
|
||||
- `6 = CONFLICT`
|
||||
- `7 = UNAVAILABLE`
|
||||
- `8 = INVALID_STATE`
|
||||
|
||||
## 7 Fault Classification
|
||||
|
||||
MEMCARD follows `16a`:
|
||||
|
||||
- `Trap`: structural violations (invalid slot index, invalid call shape, invalid window value type/range);
|
||||
- `status`: operational domain conditions;
|
||||
- `Panic`: runtime invariant break only.
|
||||
|
||||
Silent no-op is forbidden for operations with operational failure paths.
|
||||
|
||||
## 8 Runtime Layering and Storage Mapping
|
||||
|
||||
MEMCARD is a domain layer over runtime FS.
|
||||
|
||||
Runtime host mapping for v1 is namespace-isolated by `app_id`, for example:
|
||||
|
||||
`/user/games/<app_id>/memcard/slot_<NN>.pmem`
|
||||
|
||||
The exact host-side file naming is internal to runtime/host as long as ownership and isolation guarantees are preserved.
|
||||
|
||||
## 9 Explicit Persistence Rule
|
||||
|
||||
PROMETEU does not auto-save slot staging data.
|
||||
|
||||
Without `slot_commit`, writes remain staged and are not guaranteed as persisted committed state.]
|
||||
@@ -0,0 +1,123 @@
|
||||
# Events and Scheduling
|
||||
|
||||
Domain: machine events and frame scheduling
|
||||
Function: normative
|
||||
|
||||
This chapter defines events, timers, faults, and the frame-boundary model of the PROMETEU machine.
|
||||
|
||||
Coroutine lifecycle and cooperative scheduling details now live in a dedicated companion chapter.
|
||||
|
||||
## 1 Core Philosophy
|
||||
|
||||
PROMETEU does not model hidden asynchronous execution.
|
||||
|
||||
Machine-visible event behavior is based on:
|
||||
|
||||
- explicit frame steps;
|
||||
- deterministic delivery points;
|
||||
- observable costs;
|
||||
- no surprise callbacks.
|
||||
|
||||
## 2 Events
|
||||
|
||||
### 2.1 Definition
|
||||
|
||||
Events are machine-level facts made visible to the system in controlled phases.
|
||||
|
||||
Examples include:
|
||||
|
||||
- input state changes;
|
||||
- timer expiry;
|
||||
- host-signaled machine events;
|
||||
- fault publication at the machine boundary.
|
||||
|
||||
### 2.2 Event Queue
|
||||
|
||||
Events are conceptually queued and processed at known synchronization points.
|
||||
|
||||
The machine model forbids arbitrary guest code execution at event arrival time.
|
||||
|
||||
## 3 Frame Boundary (Sync Phase)
|
||||
|
||||
The frame boundary is the primary global synchronization point of the machine.
|
||||
|
||||
At this phase, the system may:
|
||||
|
||||
- sample input;
|
||||
- deliver pending events;
|
||||
- account for frame-level work;
|
||||
- coordinate VM/runtime/firmware transitions around `FRAME_SYNC`.
|
||||
|
||||
This preserves determinism and keeps machine behavior legible.
|
||||
|
||||
## 4 System Events vs System Faults
|
||||
|
||||
### 4.1 Normal events
|
||||
|
||||
Normal events report machine state changes without implying system failure.
|
||||
|
||||
### 4.2 System faults
|
||||
|
||||
System faults are not ordinary events.
|
||||
|
||||
When a terminal fault occurs:
|
||||
|
||||
- execution stops or transitions to fault-handling flow;
|
||||
- diagnostics are produced;
|
||||
- the fault is not treated like a recoverable guest event queue item.
|
||||
|
||||
## 5 Timers
|
||||
|
||||
Timers are modeled as frame-based counters.
|
||||
|
||||
Properties:
|
||||
|
||||
- measured in frames, not wall-clock time;
|
||||
- deterministic across runs;
|
||||
- integrated with the frame model rather than hidden interrupts.
|
||||
|
||||
Timers do not execute code by themselves; they make state or events available to be observed at deterministic boundaries.
|
||||
|
||||
## 6 Relationship Between Events and the Frame Loop
|
||||
|
||||
High-level structure:
|
||||
|
||||
```
|
||||
FRAME N
|
||||
------------------------
|
||||
Sample Input
|
||||
Deliver Events
|
||||
Run VM until:
|
||||
- budget exhausted, or
|
||||
- FRAME_SYNC reached
|
||||
Sync Phase
|
||||
------------------------
|
||||
```
|
||||
|
||||
Important properties:
|
||||
|
||||
- events are processed at known points;
|
||||
- no execution occurs outside the frame loop;
|
||||
- frame structure remains observable for tooling and certification.
|
||||
|
||||
## 7 Determinism and Best Practices
|
||||
|
||||
PROMETEU encourages:
|
||||
|
||||
- treating events as data;
|
||||
- querying state explicitly;
|
||||
- structuring logic around frame boundaries;
|
||||
- avoiding implicit control flow hidden behind event delivery.
|
||||
|
||||
PROMETEU discourages:
|
||||
|
||||
- asynchronous callback simulation;
|
||||
- hidden timing channels;
|
||||
- ambiguous out-of-band execution.
|
||||
|
||||
## 8 Relationship to Other Specs
|
||||
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
|
||||
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.
|
||||
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines firmware orchestration at machine level.
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines VM execution inside this frame model.
|
||||
@@ -0,0 +1,107 @@
|
||||
# Coroutines and Cooperative Scheduling
|
||||
|
||||
Domain: VM coroutine model
|
||||
Function: normative
|
||||
|
||||
This chapter isolates PROMETEU coroutine semantics from the broader event/frame model.
|
||||
|
||||
## 1 Coroutine Model
|
||||
|
||||
PROMETEU provides coroutines as the only guest-visible concurrency model.
|
||||
|
||||
Coroutines are:
|
||||
|
||||
- cooperative;
|
||||
- deterministic;
|
||||
- scheduled only at safepoints;
|
||||
- never preemptive.
|
||||
|
||||
There is:
|
||||
|
||||
- no parallel execution;
|
||||
- no hidden threads;
|
||||
- no scheduler behavior outside explicit machine rules.
|
||||
|
||||
## 2 Coroutine Lifecycle
|
||||
|
||||
Each coroutine can be in one of the following states:
|
||||
|
||||
- `Ready`
|
||||
- `Running`
|
||||
- `Sleeping`
|
||||
- `Finished`
|
||||
|
||||
Coroutine-local execution state includes, conceptually:
|
||||
|
||||
```
|
||||
Coroutine {
|
||||
call_stack
|
||||
operand_stack
|
||||
state
|
||||
}
|
||||
```
|
||||
|
||||
## 3 Scheduling
|
||||
|
||||
At each eligible scheduling boundary:
|
||||
|
||||
1. the scheduler selects the next coroutine;
|
||||
2. ordering remains deterministic;
|
||||
3. execution continues within the frame-budget model.
|
||||
|
||||
Baseline policy:
|
||||
|
||||
- round-robin or equivalent deterministic ordering;
|
||||
- no surprise priority inversion hidden from the model;
|
||||
- no preemption between safepoints.
|
||||
|
||||
## 4 Coroutine Operations
|
||||
|
||||
Typical operations:
|
||||
|
||||
| Operation | Description |
|
||||
| --------- | ----------------------------- |
|
||||
| `spawn` | Create a coroutine |
|
||||
| `yield` | Voluntarily suspend execution |
|
||||
| `sleep` | Suspend for N frames |
|
||||
|
||||
`yield` and `sleep` only take effect at safepoints.
|
||||
|
||||
## 5 Interaction with the Frame Loop
|
||||
|
||||
Coroutine scheduling happens inside the frame model, not beside it.
|
||||
|
||||
Conceptually:
|
||||
|
||||
```
|
||||
FRAME N
|
||||
------------------------
|
||||
Sample Input
|
||||
Deliver Events
|
||||
Schedule Coroutine
|
||||
Run VM
|
||||
FRAME_SYNC
|
||||
------------------------
|
||||
```
|
||||
|
||||
This preserves:
|
||||
|
||||
- deterministic replay;
|
||||
- explicit cost accounting;
|
||||
- consistent host/runtime handoff.
|
||||
|
||||
## 6 Costs and Determinism
|
||||
|
||||
Coroutine management:
|
||||
|
||||
- consumes cycles;
|
||||
- contributes to certification/cost reporting;
|
||||
- remains part of the deterministic execution trace.
|
||||
|
||||
Nothing about scheduling is "free" or hidden.
|
||||
|
||||
## 7 Relationship to Other Specs
|
||||
|
||||
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the broader frame/event model.
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines coroutine-related instruction families.
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines coroutine-owned execution state in the memory model.
|
||||
@@ -0,0 +1,239 @@
|
||||
# Debug, Inspection, and Profiling
|
||||
|
||||
Domain: machine diagnostics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../runtime/learn/mental-model-observability-and-debugging.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the machine-visible debugging, inspection, and profiling surface of PROMETEU.
|
||||
|
||||
It covers:
|
||||
|
||||
- execution modes;
|
||||
- pause and stepping;
|
||||
- state inspection;
|
||||
- graphics inspection;
|
||||
- profiling;
|
||||
- breakpoints and watchpoints;
|
||||
- event and fault visibility;
|
||||
- certification-facing diagnostics.
|
||||
|
||||
## 2 Execution Modes
|
||||
|
||||
PROMETEU operates in three main modes:
|
||||
|
||||
### 2.1 Normal Mode
|
||||
|
||||
- continuous execution
|
||||
- no detailed inspection
|
||||
- focus on game and experience
|
||||
|
||||
### 2.2 Debug Mode
|
||||
|
||||
- controlled execution
|
||||
- access to internal state
|
||||
- pauses and stepping
|
||||
|
||||
### 2.3 Certification Mode
|
||||
|
||||
- deterministic execution
|
||||
- collected metrics
|
||||
- report generation
|
||||
|
||||
No mode alters the logical result of the program.
|
||||
|
||||
## 3 Execution Debug
|
||||
|
||||
### 3.1 Pause and Resume
|
||||
|
||||
The system can be paused at safepoints:
|
||||
|
||||
- frame start
|
||||
- before UPDATE
|
||||
- after DRAW
|
||||
- before SYNC
|
||||
|
||||
During pause:
|
||||
|
||||
- state is frozen
|
||||
- buffers are not swapped
|
||||
- logical time does not advance
|
||||
|
||||
### 3.2 Step-by-Step
|
||||
|
||||
PROMETEU allows stepping at different levels:
|
||||
|
||||
- **by frame**
|
||||
- **by function**
|
||||
- **by VM instruction**
|
||||
|
||||
Stepping by instruction reveals:
|
||||
|
||||
- Program Counter (PC)
|
||||
- current instruction
|
||||
- operand stack
|
||||
- call stack
|
||||
|
||||
## 4 State Inspection
|
||||
|
||||
### 4.1 Stacks
|
||||
|
||||
PROMETEU allows inspecting:
|
||||
|
||||
- **Operand Stack**
|
||||
- **Call Stack**
|
||||
|
||||
For each frame:
|
||||
|
||||
- content
|
||||
- depth
|
||||
- growth and cleanup
|
||||
|
||||
### 4.2 Heap
|
||||
|
||||
The heap can be inspected in real time:
|
||||
|
||||
- total size
|
||||
- current usage
|
||||
- peak usage
|
||||
- live objects
|
||||
|
||||
The programmer can observe:
|
||||
|
||||
- allocation patterns
|
||||
- fragmentation
|
||||
- GC pressure
|
||||
|
||||
### 4.3 Global Space
|
||||
|
||||
Global variables:
|
||||
|
||||
- current values
|
||||
- references
|
||||
- initialization
|
||||
|
||||
## 5 Graphics Debug
|
||||
|
||||
PROMETEU allows inspecting the graphics system:
|
||||
|
||||
- front buffer
|
||||
- back buffer
|
||||
- palette state
|
||||
- active sprites
|
||||
|
||||
It is possible to:
|
||||
|
||||
- freeze the image
|
||||
- observe buffers separately
|
||||
- identify excessive redraw
|
||||
|
||||
## 6 Time Profiling (Cycles)
|
||||
|
||||
### 6.1 Per-Frame Measurement
|
||||
|
||||
For each frame, PROMETEU records:
|
||||
|
||||
- total cycles used
|
||||
- cycles per subsystem
|
||||
- execution peaks
|
||||
|
||||
Conceptual example:
|
||||
|
||||
```
|
||||
Frame 18231:
|
||||
Total:9,842/10,000cycles
|
||||
UPDATE:4,210
|
||||
DRAW:3,180
|
||||
AUDIO:920
|
||||
SYSTEM:612
|
||||
```
|
||||
|
||||
### 6.2 Per-Function Profiling
|
||||
|
||||
PROMETEU can associate cycles with:
|
||||
|
||||
- functions
|
||||
- methods
|
||||
- logical blocks
|
||||
|
||||
### 6.3 Per-Instruction Profiling
|
||||
|
||||
At the lowest level, the system can display:
|
||||
|
||||
- executed instructions
|
||||
- individual cost
|
||||
- frequency
|
||||
|
||||
## 7 Memory Profiling
|
||||
|
||||
PROMETEU records:
|
||||
|
||||
- average heap usage
|
||||
- heap peak
|
||||
- allocations per frame
|
||||
- GC frequency
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Heap:
|
||||
Avg:24KB
|
||||
Peak:34KB❌
|
||||
Limit:32KB
|
||||
```
|
||||
|
||||
These data directly feed the certification.
|
||||
|
||||
## 8 Breakpoints and Watchpoints
|
||||
|
||||
### 8.1 Breakpoints
|
||||
|
||||
PROMETEU supports breakpoints in:
|
||||
|
||||
- specific frames
|
||||
- functions
|
||||
- VM instructions
|
||||
|
||||
Breakpoints:
|
||||
|
||||
- pause execution
|
||||
- preserve state
|
||||
- do not change behavior
|
||||
|
||||
### 8.2 Watchpoints
|
||||
|
||||
Watchpoints monitor:
|
||||
|
||||
- variables
|
||||
- heap addresses
|
||||
- specific values
|
||||
|
||||
Execution can pause when:
|
||||
|
||||
- a value changes
|
||||
- a limit is exceeded
|
||||
|
||||
## 9 Event and Fault Debugging
|
||||
|
||||
PROMETEU allows observing:
|
||||
|
||||
- event queue
|
||||
- active timers
|
||||
- published system faults
|
||||
|
||||
Each event has:
|
||||
|
||||
- origin
|
||||
- frame
|
||||
- cost
|
||||
- consequence
|
||||
|
||||
## 10 Integration with CAP and Certification
|
||||
|
||||
All debug and profiling data:
|
||||
|
||||
- feed the certification report
|
||||
- are collected deterministically
|
||||
- do not depend on external tools
|
||||
@@ -0,0 +1,168 @@
|
||||
# Portability Guarantees and Cross-Platform Execution
|
||||
|
||||
Domain: portability contract
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-portability-and-cross-platform.md`](../runtime/learn/mental-model-portability-and-cross-platform.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
This chapter defines the portability contract of the PROMETEU machine across supported hosts.
|
||||
|
||||
Portability means:
|
||||
|
||||
- same cartridge;
|
||||
- same machine rules;
|
||||
- same logical inputs;
|
||||
- same logical results.
|
||||
|
||||
The contract is about logical behavior, not identical physical latency or throughput.
|
||||
|
||||
## 2 Separation of Responsibilities
|
||||
|
||||
```
|
||||
+----------------------------+
|
||||
| CARTRIDGE |
|
||||
| (bytecode + assets) |
|
||||
+-------------+--------------+
|
||||
|
|
||||
+-------------v--------------+
|
||||
| PROMETEU VM |
|
||||
| (logic, time, memory) |
|
||||
+-------------+--------------+
|
||||
|
|
||||
+-------------v--------------+
|
||||
| PLATFORM LAYER |
|
||||
| window, audio, input, FS |
|
||||
+----------------------------+
|
||||
```
|
||||
|
||||
### 2.1 What the machine controls
|
||||
|
||||
- bytecode execution
|
||||
- logical time (frames, cycles)
|
||||
- memory (stack, heap)
|
||||
- determinism
|
||||
- costs and metrics
|
||||
|
||||
### 2.2 What the host provides
|
||||
|
||||
- pixel display
|
||||
- audio output
|
||||
- physical input collection
|
||||
- access to the sandbox file system
|
||||
|
||||
The host provides realization of machine surfaces. It does not redefine cartridge semantics.
|
||||
|
||||
## 3 Determinism as the Basis of Portability
|
||||
|
||||
PROMETEU guarantees determinism through:
|
||||
|
||||
- fixed logical clock (60 Hz)
|
||||
- abstract cycles, not real time
|
||||
- input sampled per frame
|
||||
- absence of implicit concurrency
|
||||
- absence of system-dependent operations
|
||||
|
||||
## 4 Independence from Real Hardware
|
||||
|
||||
PROMETEU **does not use**:
|
||||
|
||||
- operating system timers
|
||||
- high-resolution clocks
|
||||
- CPU-specific instructions
|
||||
- uncontrolled graphics acceleration
|
||||
|
||||
All performance is measured in **PROMETEU cycles**, not in milliseconds.
|
||||
|
||||
## 5 Floating Point Precision
|
||||
|
||||
To guarantee numerical consistency:
|
||||
|
||||
- PROMETEU defines explicit mathematical operations
|
||||
- avoids dependence on specific FPUs
|
||||
- standardizes `number` behavior
|
||||
|
||||
This avoids:
|
||||
|
||||
- divergences between architectures
|
||||
- unpredictable cumulative errors
|
||||
- subtle differences between platforms
|
||||
|
||||
## 6 Cross-Platform Input
|
||||
|
||||
PROMETEU abstracts physical input into **logical state**.
|
||||
|
||||
- keyboard, gamepad, and touch are mapped externally
|
||||
- the cartridge only sees logical buttons and axes
|
||||
- the reading moment is fixed per frame
|
||||
|
||||
## 7 Cross-Platform Audio
|
||||
|
||||
The audio system:
|
||||
|
||||
- defines channels and mixing logically
|
||||
- uses native APIs only as output
|
||||
- maintains per-frame synchronization
|
||||
|
||||
Hardware differences:
|
||||
|
||||
- do not change logical timing
|
||||
- do not change sound sequence
|
||||
- do not affect certification
|
||||
|
||||
## 8 Cross-Platform Graphics
|
||||
|
||||
The graphics system:
|
||||
|
||||
- operates on a logical framebuffer
|
||||
- uses an indexed palette
|
||||
- does not depend on a specific GPU
|
||||
|
||||
The platform layer:
|
||||
|
||||
- only displays the framebuffer
|
||||
- does not reinterpret graphics commands
|
||||
|
||||
## 9 File System and Persistence
|
||||
|
||||
PROMETEU defines a **sandbox logical filesystem**:
|
||||
|
||||
- virtual paths
|
||||
- size limits
|
||||
- deterministic behavior
|
||||
|
||||
The platform maps this filesystem to:
|
||||
|
||||
- disk
|
||||
- mobile storage
|
||||
- persistent memory
|
||||
|
||||
Without changing semantics.
|
||||
|
||||
## 10 Certification and Portability
|
||||
|
||||
The **PROMETEU Certification** is valid for all platforms.
|
||||
|
||||
If a cartridge:
|
||||
|
||||
- passes on one platform
|
||||
- with the same inputs
|
||||
|
||||
It:
|
||||
|
||||
- will pass on all
|
||||
- will produce the same reports
|
||||
|
||||
## 11 What PROMETEU Does Not Guarantee
|
||||
|
||||
PROMETEU **does not promise**:
|
||||
|
||||
- identical absolute performance (real FPS)
|
||||
- identical physical latency
|
||||
- equivalent energy consumption
|
||||
|
||||
PROMETEU promises:
|
||||
|
||||
- **identical logical behavior**
|
||||
- **reproducible technical decisions**
|
||||
@@ -0,0 +1,138 @@
|
||||
# Firmware - POS and PrometeuHub
|
||||
|
||||
Domain: firmware and system orchestration
|
||||
Function: normative
|
||||
|
||||
This chapter defines the firmware layer of the PROMETEU machine.
|
||||
|
||||
It covers:
|
||||
|
||||
- machine authority above the VM;
|
||||
- POS responsibilities;
|
||||
- Hub responsibilities;
|
||||
- firmware states and cartridge launch flow.
|
||||
|
||||
## 1 Firmware Scope
|
||||
|
||||
The PROMETEU firmware is composed of two cooperating layers:
|
||||
|
||||
- **PrometeuOS (POS)**: the machine authority responsible for boot, VM/runtime orchestration, peripherals, crash handling, and system-level policy;
|
||||
- **PrometeuHub**: the launcher/UI layer that runs over POS and uses the system window model.
|
||||
|
||||
The VM does not own the machine lifecycle. Firmware does.
|
||||
|
||||
## 2 Terms
|
||||
|
||||
- **Host**: the real platform that drives the core loop and presents output.
|
||||
- **POS**: system firmware/core authority.
|
||||
- **PrometeuHub**: launcher and system UI running over POS.
|
||||
- **PVM**: the VM subsystem that executes cartridge bytecode.
|
||||
- **Cartridge**: the executable package loaded by firmware.
|
||||
- **AppMode**: cartridge mode, currently `Game` or `System`.
|
||||
- **Logical frame**: execution unit completed when the app reaches `FRAME_SYNC`.
|
||||
- **Host tick**: the host-driven outer update tick.
|
||||
|
||||
## 3 POS Responsibilities
|
||||
|
||||
POS is responsible for:
|
||||
|
||||
- deterministic reset into known machine state;
|
||||
- VM initialization and teardown for cartridge execution;
|
||||
- input latching and logical-frame budgeting;
|
||||
- peripheral reset/orchestration;
|
||||
- fault capture and crash-flow transition;
|
||||
- return to Hub after app exit or crash.
|
||||
|
||||
At the VM boundary, POS must preserve:
|
||||
|
||||
- logical-frame semantics;
|
||||
- `FRAME_SYNC` as the canonical frame boundary;
|
||||
- deterministic transition from host tick to VM slice execution.
|
||||
|
||||
## 4 PrometeuHub Responsibilities
|
||||
|
||||
PrometeuHub is responsible for:
|
||||
|
||||
- presenting available apps;
|
||||
- reading cartridge metadata needed for launch decisions;
|
||||
- deciding launch behavior based on `AppMode`;
|
||||
- managing the system window surface for system-mode apps.
|
||||
|
||||
The Hub does not execute bytecode directly. It always delegates execution setup to POS.
|
||||
|
||||
## 5 App Modes
|
||||
|
||||
### Game
|
||||
|
||||
Game-mode cartridges:
|
||||
|
||||
- transition firmware into the game-running state;
|
||||
- run as the active app flow;
|
||||
- present through the main frame path.
|
||||
|
||||
### System
|
||||
|
||||
System-mode cartridges:
|
||||
|
||||
- are initialized by POS;
|
||||
- are integrated into the Hub/window environment;
|
||||
- do not replace the firmware state with the game-running path.
|
||||
|
||||
## 6 Cartridge Load Flow
|
||||
|
||||
Current high-level flow:
|
||||
|
||||
1. POS receives a cartridge to load;
|
||||
2. asset manager is initialized from the cartridge asset table, preload list, and packed asset bytes;
|
||||
3. POS initializes the VM/runtime for the cartridge;
|
||||
4. launch behavior branches by `AppMode`:
|
||||
- `Game` -> transition to the game-running firmware state;
|
||||
- `System` -> create/focus a Hub window and return to the Hub state.
|
||||
|
||||
If VM initialization fails, firmware transitions to the crash path.
|
||||
|
||||
POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
|
||||
|
||||
## 7 Firmware States
|
||||
|
||||
The current firmware state model includes:
|
||||
|
||||
- `Reset`
|
||||
- `SplashScreen`
|
||||
- `LaunchHub`
|
||||
- `HubHome`
|
||||
- `LoadCartridge`
|
||||
- `GameRunning`
|
||||
- `AppCrashes`
|
||||
|
||||
These states express machine orchestration above the VM. They are not guest-visible bytecode states.
|
||||
|
||||
## 8 Execution Contract
|
||||
|
||||
For game-mode execution, firmware/runtime coordination preserves:
|
||||
|
||||
- input latched per logical frame;
|
||||
- execution in host-driven slices until `FRAME_SYNC`;
|
||||
- present only when a logical frame completes;
|
||||
- no frame present when budget ends before `FRAME_SYNC`.
|
||||
|
||||
This keeps the machine model deterministic and observable.
|
||||
|
||||
## 9 Crash Handling
|
||||
|
||||
Firmware owns terminal fault presentation.
|
||||
|
||||
When a terminal app fault occurs:
|
||||
|
||||
- POS captures the crash report;
|
||||
- firmware leaves normal app execution flow;
|
||||
- the machine transitions to `AppCrashes`.
|
||||
|
||||
Crash handling is outside the guest VM execution model.
|
||||
|
||||
## 10 Relationship to Other Specs
|
||||
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM subsystem run by firmware.
|
||||
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the frame-boundary model used by firmware.
|
||||
- [`13-cartridge.md`](13-cartridge.md) defines cartridge structure and metadata consumed by firmware.
|
||||
- [`14-boot-profiles.md`](14-boot-profiles.md) defines startup target selection.
|
||||
@@ -0,0 +1,157 @@
|
||||
# Cartridges
|
||||
|
||||
Domain: cartridge package
|
||||
Function: normative
|
||||
|
||||
This chapter defines the cartridge contract consumed by the current runtime.
|
||||
|
||||
## 1 Scope
|
||||
|
||||
A cartridge is the distributable unit loaded by firmware/runtime.
|
||||
|
||||
In the current implementation, the supported dev/runtime form is a directory containing:
|
||||
|
||||
- `manifest.json`
|
||||
- `program.pbx`
|
||||
- optional `assets.pa`
|
||||
|
||||
The loader also recognizes `.pmc` as a future packaged form, but packaged cartridge loading is not implemented yet.
|
||||
|
||||
## 2 Cartridge Metadata
|
||||
|
||||
The runtime currently expects the following manifest fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"magic": "PMTU",
|
||||
"cartridge_version": 1,
|
||||
"app_id": 1234,
|
||||
"title": "My Game",
|
||||
"app_version": "1.0.0",
|
||||
"app_mode": "Game"
|
||||
}
|
||||
```
|
||||
|
||||
Additional manifest-supported fields include:
|
||||
|
||||
- `capabilities`
|
||||
|
||||
## 3 Required Fields
|
||||
|
||||
Current required manifest fields:
|
||||
|
||||
- `magic`
|
||||
- `cartridge_version`
|
||||
- `app_id`
|
||||
- `title`
|
||||
- `app_version`
|
||||
- `app_mode`
|
||||
|
||||
Current required file payloads:
|
||||
|
||||
- `program.pbx`
|
||||
|
||||
Optional file payloads:
|
||||
|
||||
- `assets.pa`
|
||||
|
||||
## 4 Runtime Validation Rules
|
||||
|
||||
The current loader validates:
|
||||
|
||||
- `magic == "PMTU"`
|
||||
- `cartridge_version == 1`
|
||||
- manifest parse validity
|
||||
- capability normalization
|
||||
- presence of `program.pbx`
|
||||
- when `Asset` capability is declared, presence of valid `assets.pa` before asset bootstrap
|
||||
|
||||
If validation fails, cartridge loading is rejected before execution.
|
||||
|
||||
## 5 App Mode and Boot Protocol
|
||||
|
||||
`app_mode` controls firmware launch behavior:
|
||||
|
||||
- `Game`
|
||||
- `System`
|
||||
|
||||
Cartridge boot is protocol-driven, not manifest-driven.
|
||||
|
||||
The executable entrypoint of a valid cartridge is always `func_id = 0`.
|
||||
|
||||
This means:
|
||||
|
||||
- `manifest.json` does not select the callable to execute;
|
||||
- firmware/runtime loads the cartridge and starts execution from `func_id = 0`;
|
||||
- nominal exports may exist for linking or introspection, but they do not hold boot authority.
|
||||
|
||||
## 6 Assets and Preload
|
||||
|
||||
`assets.pa` is the runtime-facing asset artifact consumed by the current runtime.
|
||||
|
||||
`assets.pa` v1 is an autocontained binary with:
|
||||
|
||||
- fixed binary prelude;
|
||||
- JSON header;
|
||||
- binary payload region.
|
||||
|
||||
The fixed prelude includes, at minimum:
|
||||
|
||||
- `magic`
|
||||
- `schema_version`
|
||||
- `header_len`
|
||||
- `payload_offset`
|
||||
|
||||
It may additionally include:
|
||||
|
||||
- `flags`
|
||||
- `reserved`
|
||||
- `header_checksum`
|
||||
|
||||
The JSON header carries:
|
||||
|
||||
- `asset_table`
|
||||
- `preload`
|
||||
|
||||
`asset_table` and `preload` are therefore no longer the primary runtime contract of `manifest.json`.
|
||||
|
||||
`preload` is structurally validated as part of `assets.pa` bootstrap:
|
||||
|
||||
- each preload entry is `{ asset_id, slot }`;
|
||||
- `asset_id` uses 32-bit signed integer semantics;
|
||||
- each `preload.asset_id` must resolve to an entry in the same `asset_table`;
|
||||
- no two preload entries may claim the same `(bank_type, slot)` pair once `bank_type` is resolved from `asset_table`.
|
||||
|
||||
Runtime lifecycle:
|
||||
|
||||
- `asset_table` is loaded from `assets.pa` and remains live while the cartridge is running;
|
||||
- `preload` is loaded from `assets.pa`, consumed during cartridge initialization, and may be discarded after boot;
|
||||
- payload bytes are resolved from the payload region using offsets relative to `payload_offset`.
|
||||
|
||||
Runtime loading policy:
|
||||
|
||||
- cartridges without `assets.pa` remain valid when `Asset` capability is not declared;
|
||||
- cartridges that declare `Asset` capability must provide valid `assets.pa`;
|
||||
- `assets.pa` with invalid preload references or preload slot clashes is structurally invalid;
|
||||
- failure must occur as early as cartridge bootstrap, before preload execution.
|
||||
|
||||
## 7 Runtime Forms
|
||||
|
||||
### Directory form
|
||||
|
||||
This is the working runtime/dev form used by the current loader.
|
||||
|
||||
### Packaged `.pmc` form
|
||||
|
||||
This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
|
||||
|
||||
The cartridge spec therefore distinguishes:
|
||||
|
||||
- supported current load form;
|
||||
- reserved future distribution form.
|
||||
|
||||
## 8 Relationship to Other Specs
|
||||
|
||||
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines how firmware consumes cartridge metadata.
|
||||
- [`14-boot-profiles.md`](14-boot-profiles.md) defines cartridge selection at boot.
|
||||
- [`15-asset-management.md`](15-asset-management.md) defines the `assets.pa` envelope, asset table semantics, preload lifecycle, and residency semantics.
|
||||
@@ -0,0 +1,86 @@
|
||||
# Boot Profiles
|
||||
|
||||
Domain: firmware boot flow
|
||||
Function: normative
|
||||
|
||||
This chapter defines how PROMETEU chooses what to execute at startup.
|
||||
|
||||
## 1 Boot Target
|
||||
|
||||
The current firmware-side boot target concept is:
|
||||
|
||||
```rust
|
||||
enum BootTarget {
|
||||
Hub,
|
||||
Cartridge { path: String, debug: bool, debug_port: u16 },
|
||||
}
|
||||
```
|
||||
|
||||
This is a firmware/host orchestration contract, not a guest-visible ABI.
|
||||
|
||||
## 2 Boot Modes
|
||||
|
||||
### Hub
|
||||
|
||||
When the boot target is `Hub`:
|
||||
|
||||
- firmware boots into the Hub flow;
|
||||
- no cartridge is auto-launched.
|
||||
|
||||
### Cartridge
|
||||
|
||||
When the boot target is `Cartridge`:
|
||||
|
||||
1. firmware loads the requested cartridge;
|
||||
2. cartridge metadata is read;
|
||||
3. launch behavior follows cartridge `app_mode`;
|
||||
4. bytecode execution starts through the cartridge boot protocol defined by the cartridge contract, not by textual entry metadata.
|
||||
|
||||
## 3 Launch Resolution by App Mode
|
||||
|
||||
For a cartridge boot target:
|
||||
|
||||
- `Game` cartridges transition into game-running flow;
|
||||
- `System` cartridges are initialized and integrated into the Hub/window path.
|
||||
|
||||
This preserves the distinction between machine firmware state and app execution mode.
|
||||
|
||||
## 4 Host CLI Relationship
|
||||
|
||||
Typical host-facing boot intents are:
|
||||
|
||||
- default start -> enter Hub;
|
||||
- run cartridge -> boot with cartridge target;
|
||||
- debug cartridge -> boot with cartridge target plus debug mode parameters.
|
||||
|
||||
The CLI is an entry surface for boot target selection; the firmware contract remains the same underneath.
|
||||
|
||||
## 5 Firmware State Relationship
|
||||
|
||||
Boot target selection feeds into firmware states such as:
|
||||
|
||||
- `Reset`
|
||||
- `SplashScreen`
|
||||
- `LaunchHub`
|
||||
- `HubHome`
|
||||
- `LoadCartridge`
|
||||
- `GameRunning`
|
||||
- `AppCrashes`
|
||||
|
||||
Boot target is not itself a firmware state. It is an input to the firmware state machine.
|
||||
|
||||
## 6 Debug Boot
|
||||
|
||||
When booting a cartridge in debug mode:
|
||||
|
||||
- firmware/runtime uses the cartridge target path;
|
||||
- debugger-related startup behavior is enabled;
|
||||
- execution still follows the same cartridge/app-mode resolution path.
|
||||
|
||||
Debug mode changes orchestration, not the cartridge contract.
|
||||
|
||||
## 7 Relationship to Other Specs
|
||||
|
||||
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines the firmware state machine that consumes boot targets.
|
||||
- [`13-cartridge.md`](13-cartridge.md) defines cartridge structure.
|
||||
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines the observability/debugging layer.
|
||||
@@ -0,0 +1,324 @@
|
||||
# Asset Management
|
||||
|
||||
Domain: asset runtime surface
|
||||
Function: normative
|
||||
|
||||
This chapter defines the runtime-facing asset model of PROMETEU.
|
||||
|
||||
## 1 Scope
|
||||
|
||||
PROMETEU asset management is bank-centric.
|
||||
|
||||
Assets are:
|
||||
|
||||
- cold bytes stored in the cartridge;
|
||||
- described by cartridge metadata;
|
||||
- materialized into host-managed banks;
|
||||
- separate from VM heap ownership.
|
||||
|
||||
This chapter describes the runtime contract currently visible in the codebase. It is not a full tooling pipeline specification.
|
||||
|
||||
## 2 Core Principles
|
||||
|
||||
1. asset residency is explicit;
|
||||
2. asset memory belongs to the machine, not to the VM heap;
|
||||
3. banks and slots are hardware/runtime concepts;
|
||||
4. loading and activation are explicit operations;
|
||||
5. asset memory does not participate in GC.
|
||||
|
||||
## 3 Cartridge Asset Artifact
|
||||
|
||||
The runtime currently consumes one primary cartridge asset artifact:
|
||||
|
||||
- `assets.pa`: autocontained asset artifact.
|
||||
|
||||
`assets.pa` carries, inside the same binary:
|
||||
|
||||
- fixed binary prelude;
|
||||
- JSON header;
|
||||
- payload bytes.
|
||||
|
||||
The JSON header carries:
|
||||
|
||||
- `asset_table`: metadata entries describing asset content;
|
||||
- `preload`: optional initial residency requests consumed during cartridge initialization.
|
||||
|
||||
This chapter describes the runtime-facing asset contract. It does not define the Studio packer workflow or the shipper pipeline that publishes the cartridge.
|
||||
|
||||
### 3.1 `assets.pa` v1 envelope
|
||||
|
||||
`assets.pa` v1 is structured as:
|
||||
|
||||
```text
|
||||
[fixed binary prelude]
|
||||
[json header]
|
||||
[binary payload region]
|
||||
```
|
||||
|
||||
The fixed binary prelude contains, at minimum:
|
||||
|
||||
- `magic`
|
||||
- `schema_version`
|
||||
- `header_len`
|
||||
- `payload_offset`
|
||||
|
||||
It may additionally include:
|
||||
|
||||
- `flags`
|
||||
- `reserved`
|
||||
- `header_checksum`
|
||||
|
||||
### 3.2 Header and payload contract
|
||||
|
||||
The runtime loads:
|
||||
|
||||
- `asset_table` from the JSON header and keeps it live during cartridge execution;
|
||||
- `preload` from the JSON header and consumes it only during boot.
|
||||
|
||||
Payload bytes are addressed from the payload region using offsets relative to `payload_offset`, not relative to the start of the whole file.
|
||||
|
||||
## 4 Asset Table
|
||||
|
||||
Current runtime-facing asset metadata includes:
|
||||
|
||||
```text
|
||||
AssetEntry {
|
||||
asset_id
|
||||
asset_name
|
||||
bank_type
|
||||
offset
|
||||
size
|
||||
decoded_size
|
||||
codec
|
||||
metadata
|
||||
}
|
||||
```
|
||||
|
||||
This table describes content identity and storage layout, not live residency.
|
||||
|
||||
`asset_id` is the stable runtime-facing asset identity and uses 32-bit signed integer semantics compatible with Java `int`.
|
||||
|
||||
`offset` is relative to the start of the payload region inside `assets.pa`.
|
||||
|
||||
`size` is the serialized byte count stored in the payload region.
|
||||
|
||||
`decoded_size` is the byte count of the materialized runtime bank after decode, not necessarily the same as the serialized payload size.
|
||||
|
||||
`codec` identifies the generic transformation pipeline applied to the serialized payload slice before the asset becomes a resident bank.
|
||||
|
||||
`codec` does not define the bank-specific serialized layout itself. Specialized banks may still have normative decode rules even when `codec = NONE`.
|
||||
|
||||
### 4.1 `TILES` asset contract in v1
|
||||
|
||||
For `BankType::TILES`, the runtime-facing v1 contract is:
|
||||
|
||||
- `codec = NONE`
|
||||
- serialized pixels use packed `u4` palette indices
|
||||
- serialized palettes use `RGB565` (`u16`, little-endian)
|
||||
- `palette_count = 64`
|
||||
- runtime materialization may expand pixel indices to one `u8` per pixel
|
||||
|
||||
`NONE` for `TILES` means there is no additional generic codec layer beyond the bank contract itself.
|
||||
|
||||
For the current transition window:
|
||||
|
||||
- `RAW` is a deprecated legacy alias of `NONE`
|
||||
- new published material must use `NONE` as the canonical value
|
||||
|
||||
Even with `codec = NONE`, `TILES` still requires deterministic bank-specific decode from its serialized payload. The serialized byte layout is therefore not required to be identical to the in-memory layout.
|
||||
|
||||
Required `AssetEntry.metadata` fields for `TILES`:
|
||||
|
||||
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
|
||||
- `width`: full bank sheet width in pixels
|
||||
- `height`: full bank sheet height in pixels
|
||||
- `palette_count`: number of palettes serialized for the bank
|
||||
|
||||
Validation rules for `TILES` v1:
|
||||
|
||||
- `palette_count` must be `64`
|
||||
- `width * height` defines the number of logical indexed pixels in the decoded sheet
|
||||
- additional metadata may exist, but the runtime contract must not depend on it to reconstruct the bank in memory
|
||||
|
||||
Serialized payload layout for `TILES` v1:
|
||||
|
||||
1. packed indexed pixels for the full sheet, using `ceil(width * height / 2)` bytes;
|
||||
2. palette table, using `palette_count * 16 * 2` bytes.
|
||||
|
||||
The tile-bank payload therefore separates serialized storage form from runtime memory form:
|
||||
|
||||
- serialized pixel plane: packed `4bpp`
|
||||
- decoded pixel plane: expanded `u8` indices, one entry per pixel
|
||||
- palette table: `64 * 16` colors in `RGB565`
|
||||
|
||||
For `TILES` v1:
|
||||
|
||||
- `size` must match `ceil(width * height / 2) + (palette_count * 16 * 2)`
|
||||
- `decoded_size` must match `(width * height) + (palette_count * 16 * 2)`
|
||||
|
||||
## 5 Banks and Slots
|
||||
|
||||
The current runtime exposes bank types:
|
||||
|
||||
- `TILES`
|
||||
- `SOUNDS`
|
||||
|
||||
Assets are loaded into explicit slots identified by bank context plus index.
|
||||
|
||||
Conceptual slot reference:
|
||||
|
||||
```text
|
||||
SlotRef { bank_type, index }
|
||||
```
|
||||
|
||||
This prevents ambiguity between graphics and audio residency.
|
||||
|
||||
## 6 Load Lifecycle
|
||||
|
||||
The runtime asset manager exposes a staged lifecycle:
|
||||
|
||||
- `PENDING`
|
||||
- `LOADING`
|
||||
- `READY`
|
||||
- `COMMITTED`
|
||||
- `CANCELED`
|
||||
- `ERROR`
|
||||
|
||||
High-level flow:
|
||||
|
||||
1. request load of an asset into a slot;
|
||||
2. resolve the asset entry from live `asset_table`;
|
||||
3. open the payload slice in `assets.pa`;
|
||||
4. perform read/decode/materialization work;
|
||||
5. mark the load `READY`;
|
||||
6. explicitly `commit`;
|
||||
7. activate the resident asset in the slot.
|
||||
|
||||
The canonical payload paths are:
|
||||
|
||||
- `ROM -> open_slice -> CODEX/decode -> Bank`
|
||||
- `ROM -> open_slice -> temporary in-memory blob -> CODEX/decode -> Bank`
|
||||
|
||||
`open_slice` is the runtime-facing concept for opening a limited view over a payload slice. The runtime must not require the whole `assets.pa` payload to remain resident in RAM as its baseline operating mode.
|
||||
|
||||
`OP_MODE` selects between direct slice consumption and temporary materialization in memory.
|
||||
|
||||
For v1:
|
||||
|
||||
- `OP_MODE` is derived from `codec`/CODEX;
|
||||
- explicit per-asset hinting is not part of the baseline contract.
|
||||
- `TILES` with `codec = NONE` may still stage in memory before bank installation because bank-specific decode expands packed pixel indices into the resident representation.
|
||||
- during the migration window, runtime may accept legacy `RAW` as an alias of `NONE`.
|
||||
|
||||
The runtime does not treat asset installation as implicit side effect.
|
||||
|
||||
## 7 Residency and Ownership
|
||||
|
||||
Asset banks are host/runtime-owned memory.
|
||||
|
||||
Therefore:
|
||||
|
||||
- VM heap does not own asset residency;
|
||||
- GC does not scan asset bank memory;
|
||||
- shutting down a cartridge can release bank residency independently of VM heap behavior.
|
||||
- the runtime must not keep the full `assets.pa` payload resident in RAM as a baseline requirement.
|
||||
|
||||
## 8 Bank Telemetry
|
||||
|
||||
The runtime surfaces bank and slot statistics such as:
|
||||
|
||||
- total bytes;
|
||||
- used bytes;
|
||||
- free bytes;
|
||||
- inflight bytes;
|
||||
- slot occupancy;
|
||||
- resident asset identity per slot.
|
||||
|
||||
These metrics support debugging, telemetry, and certification-oriented inspection.
|
||||
|
||||
## 9 Preload
|
||||
|
||||
`preload` is stored in the JSON header of `assets.pa`.
|
||||
|
||||
The normative preload shape is:
|
||||
|
||||
```text
|
||||
PreloadEntry {
|
||||
asset_id
|
||||
slot
|
||||
}
|
||||
```
|
||||
|
||||
These preload entries are consumed during cartridge initialization so the asset manager can establish initial residency before normal execution flow.
|
||||
|
||||
Validation rules:
|
||||
|
||||
- `preload` is resolved by `asset_id`, not by `asset_name`;
|
||||
- every `preload.asset_id` must exist in the same `asset_table`;
|
||||
- no two preload entries may resolve to the same `(bank_type, slot)` pair;
|
||||
- legacy preload keyed by `asset_name` is invalid for the current contract.
|
||||
|
||||
Lifecycle rule:
|
||||
|
||||
- `preload` is boot-time input only;
|
||||
- it does not need to remain live after initialization completes.
|
||||
|
||||
Bootstrap rule:
|
||||
|
||||
- invalid preload is a structural cartridge error and must fail cartridge bootstrap before normal execution begins.
|
||||
|
||||
## 10 Relationship to Other Specs
|
||||
|
||||
- [`13-cartridge.md`](13-cartridge.md) defines the cartridge package and the requirement that `assets.pa` carries its own asset header.
|
||||
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the syscall boundary used to manipulate assets.
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines the distinction between VM heap memory and host-owned memory.
|
||||
|
||||
## 11 Syscall Surface and Status Policy
|
||||
|
||||
`asset` follows status-first policy.
|
||||
|
||||
Fault boundary:
|
||||
|
||||
- `Trap`: structural ABI misuse (type/arity/capability/shape mismatch);
|
||||
- `status`: operational failure;
|
||||
- `Panic`: internal invariant break only.
|
||||
|
||||
### 11.1 MVP syscall shape
|
||||
|
||||
- `asset.load(name, kind, slot) -> (status:int, handle:int)`
|
||||
- `asset.status(handle) -> status:int`
|
||||
- `asset.commit(handle) -> status:int`
|
||||
- `asset.cancel(handle) -> status:int`
|
||||
|
||||
Rules:
|
||||
|
||||
- `handle` is valid only when `load` status is `OK`;
|
||||
- failed `load` returns `handle = 0`;
|
||||
- `commit` and `cancel` must not be silent no-op for unknown/invalid handle state.
|
||||
- slot validation, kind mismatch, and residency/lifecycle rejection remain in `asset` status space and are not delegated to `bank`.
|
||||
|
||||
### 11.2 Minimum status tables
|
||||
|
||||
`asset.load` request statuses:
|
||||
|
||||
- `0` = `OK`
|
||||
- `3` = `ASSET_NOT_FOUND`
|
||||
- `4` = `SLOT_KIND_MISMATCH`
|
||||
- `5` = `SLOT_INDEX_INVALID`
|
||||
- `6` = `BACKEND_ERROR`
|
||||
|
||||
`asset.status` lifecycle statuses:
|
||||
|
||||
- `0` = `PENDING`
|
||||
- `1` = `LOADING`
|
||||
- `2` = `READY`
|
||||
- `3` = `COMMITTED`
|
||||
- `4` = `CANCELED`
|
||||
- `5` = `ERROR`
|
||||
- `6` = `UNKNOWN_HANDLE`
|
||||
|
||||
`asset.commit` and `asset.cancel` operation statuses:
|
||||
|
||||
- `0` = `OK`
|
||||
- `1` = `UNKNOWN_HANDLE`
|
||||
- `2` = `INVALID_STATE`
|
||||
@@ -0,0 +1,202 @@
|
||||
# Host ABI and Syscalls
|
||||
|
||||
Domain: host ABI structure
|
||||
Function: normative
|
||||
|
||||
This chapter defines the structural ABI between the PVM and the host environment.
|
||||
|
||||
It focuses on:
|
||||
|
||||
- syscall identity;
|
||||
- load-time resolution;
|
||||
- instruction-level call semantics;
|
||||
- metadata shape;
|
||||
- argument and return-slot contract.
|
||||
|
||||
Operational policies such as capabilities, fault classes, determinism, GC interaction, budgeting, and blocking are split into a companion chapter.
|
||||
|
||||
## 1 Design Principles
|
||||
|
||||
The syscall ABI follows these rules:
|
||||
|
||||
1. **Stack-based ABI**: arguments and return values are passed through VM slots.
|
||||
2. **Canonical identity**: host services are named by stable `(module, name, version)`.
|
||||
3. **Load-time resolution**: symbolic host bindings are resolved before execution.
|
||||
4. **Metadata-driven execution**: arity and result shape come from syscall metadata.
|
||||
5. **Not first-class**: syscalls are callable but not ordinary function values.
|
||||
6. **Status-first operational policy**: across syscall domains, operationally observable failure must surface through explicit `status` values, while only structural violations fault as `Trap` and only internal invariant breaks escalate as `Panic`.
|
||||
|
||||
## 2 Canonical Syscall Identity
|
||||
|
||||
Syscalls are identified by a canonical triple:
|
||||
|
||||
```
|
||||
(module, name, version)
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
("gfx", "present", 1)
|
||||
("audio", "play", 2)
|
||||
```
|
||||
|
||||
This identity is:
|
||||
|
||||
- language-independent;
|
||||
- toolchain-stable;
|
||||
- used for linking and capability gating.
|
||||
|
||||
Input queries are VM-owned intrinsic calls in v1 and are outside the syscall identity space.
|
||||
|
||||
## 3 Syscall Resolution
|
||||
|
||||
The host maintains a registry:
|
||||
|
||||
```
|
||||
(module, name, version) -> syscall_id
|
||||
```
|
||||
|
||||
At load time:
|
||||
|
||||
1. the cartridge declares required syscalls by canonical identity;
|
||||
2. bytecode encodes host-backed call sites as `HOSTCALL <sysc_index>`;
|
||||
3. the loader validates and resolves those identities;
|
||||
4. the loader rewrites `HOSTCALL <sysc_index>` into `SYSCALL <id>`;
|
||||
5. the executable image uses only numeric syscall ids at runtime.
|
||||
|
||||
Raw `SYSCALL <id>` is not valid in a PBX pre-load artifact and must be rejected there.
|
||||
|
||||
## 4 Syscall Instruction Semantics
|
||||
|
||||
Pre-load artifact form:
|
||||
|
||||
```
|
||||
HOSTCALL <sysc_index>
|
||||
```
|
||||
|
||||
Final executable form:
|
||||
|
||||
```
|
||||
SYSCALL <id>
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `<sysc_index>` indexes the program-declared syscall table;
|
||||
- `<id>` is the final numeric host syscall id.
|
||||
|
||||
Execution steps:
|
||||
|
||||
1. the VM looks up syscall metadata by `<id>`;
|
||||
2. the VM ensures the argument contract is satisfiable;
|
||||
3. the syscall executes in the host environment;
|
||||
4. the syscall produces exactly the declared `ret_slots`.
|
||||
|
||||
The execution result must respect the canonical runtime boundary defined with [`16a-syscall-policies.md`](16a-syscall-policies.md):
|
||||
|
||||
- successful or operationally rejected execution returns values in the declared stack shape;
|
||||
- `Trap` is reserved for structural ABI misuse or invalid call shape;
|
||||
- `Panic` is reserved for runtime/host invariant failure.
|
||||
|
||||
## 5 Syscall Metadata Table
|
||||
|
||||
Each syscall is defined by metadata.
|
||||
|
||||
Conceptual structure:
|
||||
|
||||
```
|
||||
SyscallMeta {
|
||||
id: u32
|
||||
module: string
|
||||
name: string
|
||||
version: u16
|
||||
arg_slots: u8
|
||||
ret_slots: u8
|
||||
capability: CapabilityId
|
||||
may_allocate: bool
|
||||
cost_hint: u32
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
| Field | Description |
|
||||
| -------------- | ------------------------------------------------ |
|
||||
| `id` | Unique numeric syscall identifier |
|
||||
| `module` | Canonical module name |
|
||||
| `name` | Canonical syscall name |
|
||||
| `version` | ABI version of the syscall |
|
||||
| `arg_slots` | Number of input stack slots |
|
||||
| `ret_slots` | Number of return stack slots |
|
||||
| `capability` | Required capability |
|
||||
| `may_allocate` | Whether the syscall may allocate VM heap objects |
|
||||
| `cost_hint` | Expected cycle cost |
|
||||
|
||||
The loader uses this table to resolve identities and validate declared ABI shape.
|
||||
|
||||
## 6 Arguments and Return Values
|
||||
|
||||
Syscalls use the same slot-oriented argument/return philosophy as ordinary calls.
|
||||
|
||||
### Argument passing
|
||||
|
||||
Arguments are pushed before the syscall.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
push a
|
||||
push b
|
||||
SYSCALL X
|
||||
```
|
||||
|
||||
### Return values
|
||||
|
||||
After execution, the syscall leaves exactly `ret_slots` values on the stack.
|
||||
|
||||
Composite results use multiple stack slots rather than implicit hidden structures.
|
||||
|
||||
Return shape must also follow the transversal status-first policy in [`16a-syscall-policies.md`](16a-syscall-policies.md):
|
||||
|
||||
- when a syscall exposes operational failure, `status:int` is the canonical first return slot;
|
||||
- operations with observable operational failure paths must expose that explicit `status:int` return;
|
||||
- operations with no real operational error path may remain `void` (`ret_slots = 0`);
|
||||
- if extra payload is returned together with `status`, the payload must follow the leading status slot in the declared stack shape;
|
||||
- stack shape remains strict in both cases and must match syscall metadata exactly.
|
||||
|
||||
### MEMCARD game surface (`mem`, v1)
|
||||
|
||||
The game memcard profile uses module `mem` with status-first return shapes.
|
||||
`mem` is a domain layer backed by runtime `fs` (it is not a separate storage backend).
|
||||
|
||||
Canonical operations in v1 are:
|
||||
|
||||
- `mem.slot_count() -> (status, count)`
|
||||
- `mem.slot_stat(slot) -> (status, state, used_bytes, generation, checksum)`
|
||||
- `mem.slot_read(slot, offset, max_bytes) -> (status, payload_hex, bytes_read)`
|
||||
- `mem.slot_write(slot, offset, payload_hex) -> (status, bytes_written)`
|
||||
- `mem.slot_commit(slot) -> status`
|
||||
- `mem.slot_clear(slot) -> status`
|
||||
|
||||
Semantics and domain status catalog are defined by [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
|
||||
|
||||
## 7 Syscalls as Callable Entities (Not First-Class)
|
||||
|
||||
Syscalls behave like call sites, not like first-class guest values.
|
||||
|
||||
This means:
|
||||
|
||||
- syscalls can be invoked;
|
||||
- syscalls cannot be stored in variables;
|
||||
- syscalls cannot be passed as function values;
|
||||
- syscalls cannot be returned as closures.
|
||||
|
||||
Only user-defined functions and closures are first-class.
|
||||
|
||||
## 8 Relationship to Other Specs
|
||||
|
||||
- [`16a-syscall-policies.md`](16a-syscall-policies.md) defines operational policies layered on top of this ABI.
|
||||
- [`15-asset-management.md`](15-asset-management.md) defines asset-domain semantics behind some syscall families.
|
||||
- [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) defines persistent save-domain semantics.
|
||||
- [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) defines the slot/call philosophy reused by the syscall ABI.
|
||||
@@ -0,0 +1,162 @@
|
||||
# Syscall Policies
|
||||
|
||||
Domain: host ABI operational policy
|
||||
Function: normative
|
||||
|
||||
This chapter defines the operational policies that sit on top of the host ABI.
|
||||
|
||||
It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), which defines the structural ABI itself.
|
||||
|
||||
Unless a domain chapter explicitly narrows behavior further, this chapter is the transversal policy for all syscalls in v1.
|
||||
|
||||
## 1 Error Model: Faults vs Status Returns
|
||||
|
||||
Syscalls use a status-first hybrid model.
|
||||
|
||||
### Fault conditions
|
||||
|
||||
The VM faults when contract rules are violated, for example:
|
||||
|
||||
- invalid syscall id;
|
||||
- unresolved canonical identity;
|
||||
- missing required capability;
|
||||
- insufficient argument slots;
|
||||
- invalid or dead heap handle.
|
||||
|
||||
These are not ordinary domain statuses.
|
||||
|
||||
Faults are split into two runtime classes:
|
||||
|
||||
- `Trap`: guest-visible structural violation (ABI misuse / invalid call shape).
|
||||
- `Panic`: runtime invariant break (internal inconsistency).
|
||||
|
||||
`Unavailable` is not a canonical fault class in this policy model.
|
||||
|
||||
- operational unavailability should be represented as `status`;
|
||||
- structural host/runtime collapse should be treated as `Panic`.
|
||||
|
||||
### Status returns
|
||||
|
||||
Normal operational success and operational failure conditions should be represented as values in return slots.
|
||||
|
||||
Examples:
|
||||
|
||||
- asset not yet loaded;
|
||||
- audio voice unavailable;
|
||||
- persistent storage full.
|
||||
|
||||
When a syscall returns `status`, that `status:int` occupies the first return slot.
|
||||
Any additional payload is domain-defined and follows that leading status slot.
|
||||
|
||||
### Return shape policy (`void` vs `status`)
|
||||
|
||||
This policy is normative:
|
||||
|
||||
- if an operation has observable operational failure modes, it must return `status:int` explicitly;
|
||||
- if an operation can be operationally rejected, ignored, deferred with failure, or conclude with guest-observable `no_effect`, it is not eligible to remain `void`;
|
||||
- if an operation has no real operational error path, it may remain `void` (`ret_slots = 0`);
|
||||
- `status` coding is domain-owned and may differ by operation, but must be deterministic and documented.
|
||||
|
||||
Practical rule:
|
||||
|
||||
- `void` is allowed only for operations whose non-fault path is effectively unconditional success;
|
||||
- any operation with a meaningful operational non-success outcome must surface that outcome through `status`, not through absence of return values.
|
||||
|
||||
### No-op policy
|
||||
|
||||
Silent no-op is not allowed when an operation can fail operationally in a guest-observable way.
|
||||
|
||||
In those cases, the runtime must return explicit `status` instead of masking failure as implicit success.
|
||||
|
||||
Implicit fallback is also forbidden when it hides an operational error or state rejection that the guest could observe or reason about.
|
||||
|
||||
This means operational problems must not be reclassified as:
|
||||
|
||||
- silent success;
|
||||
- silent ignore;
|
||||
- `Trap`, when the failure is not structural;
|
||||
- `Panic`, when the failure is not an internal invariant break.
|
||||
|
||||
## 2 Capability System
|
||||
|
||||
Each syscall requires a declared capability.
|
||||
|
||||
Example groups:
|
||||
|
||||
- `gfx`
|
||||
- `audio`
|
||||
- `asset`
|
||||
- `fs` (includes game memcard module `mem` in v1)
|
||||
|
||||
Capability checks exist to constrain which host-managed surfaces a cartridge may use.
|
||||
|
||||
Input in v1 is VM-owned intrinsic surface and is not capability-gated through syscall policy.
|
||||
|
||||
Game memcard operations (`mem.*`) are status-first and use `fs` capability in v1.
|
||||
`mem` remains layered on runtime `fs`; no parallel persistence channel is introduced.
|
||||
Domain surface, status catalog and slot semantics are defined in [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
|
||||
|
||||
## 3 Interaction with the Garbage Collector
|
||||
|
||||
The VM heap and host-managed memory are separate.
|
||||
|
||||
### Heap vs host memory
|
||||
|
||||
| Memory | Managed by | GC scanned |
|
||||
| --------------- | ---------- | ---------- |
|
||||
| VM heap objects | VM GC | Yes |
|
||||
| Asset banks | Host | No |
|
||||
| Audio buffers | Host | No |
|
||||
| Framebuffers | Host | No |
|
||||
|
||||
### Host root rule
|
||||
|
||||
If the host stores a VM heap handle beyond the duration of the syscall, that handle must be treated as a host root according to the runtime contract.
|
||||
|
||||
This rule applies to VM heap objects, not to host-owned asset identifiers or primitive values.
|
||||
|
||||
## 4 Determinism Rules
|
||||
|
||||
Syscalls must obey machine-level determinism.
|
||||
|
||||
Forbidden patterns:
|
||||
|
||||
- reading wall-clock time as gameplay state;
|
||||
- non-deterministic OS access in the gameplay contract;
|
||||
- blocking I/O in the execution slice.
|
||||
|
||||
Allowed patterns:
|
||||
|
||||
- frame-based timing;
|
||||
- request + poll status models;
|
||||
- deterministic event publication at frame boundaries.
|
||||
|
||||
## 5 Cost Model and Budgeting
|
||||
|
||||
Each syscall contributes to frame cost.
|
||||
|
||||
The system may account for:
|
||||
|
||||
- syscall count;
|
||||
- cycles spent in syscalls;
|
||||
- allocations triggered by syscalls.
|
||||
|
||||
This keeps host interaction visible in certification, telemetry, and profiling.
|
||||
|
||||
## 6 Blocking and Long Operations
|
||||
|
||||
Syscalls must not block the execution model.
|
||||
|
||||
Long operations should follow explicit staged patterns such as:
|
||||
|
||||
1. request;
|
||||
2. status polling or completion observation.
|
||||
|
||||
This keeps the host ABI compatible with a deterministic frame machine.
|
||||
|
||||
## 7 Relationship to Other Specs
|
||||
|
||||
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the structural ABI.
|
||||
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines VM heap ownership and handles.
|
||||
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines visibility of cost and diagnostics.
|
||||
- domain chapters (e.g. `04`, `05`, `15`) define per-operation status tables.
|
||||
@@ -0,0 +1,116 @@
|
||||
# PROMETEU Machine Specs
|
||||
|
||||
This directory contains the technical specs for the PROMETEU machine.
|
||||
|
||||
PROMETEU is a fantasy handheld / fantasy console. The VM is only one subsystem of that machine. Because of that, this documentation surface covers more than bytecode and runtime: it covers timing, virtual hardware, firmware, cartridge packaging, assets, and the host ABI.
|
||||
|
||||
The organization here is intentionally flat. The taxonomy is conceptual, not structural.
|
||||
|
||||
## Scope Boundary
|
||||
|
||||
Belongs in `docs/runtime/specs/`:
|
||||
|
||||
- the technical contract of the PROMETEU machine;
|
||||
- virtual hardware and its peripherals;
|
||||
- the firmware and boot envelope;
|
||||
- cartridge, asset, and load surfaces;
|
||||
- the VM-to-host ABI.
|
||||
|
||||
Does not belong in `docs/runtime/specs/` as the primary canonical source:
|
||||
|
||||
- internal architectural invariants of the VM/runtime:
|
||||
[`../virtual-machine/ARCHITECTURE.md`](../vm-arch/ARCHITECTURE.md);
|
||||
- bytecode-level ISA:
|
||||
[`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md);
|
||||
- pedagogical guides and learning material:
|
||||
[`../learn/README.md`](../runtime/learn/README.md);
|
||||
- agendas, proposals, and plans:
|
||||
`docs/runtime/agendas/` and `docs/runtime/pull-requests/`.
|
||||
|
||||
## Organization Rules
|
||||
|
||||
- flat structure;
|
||||
- no `topics/` folder;
|
||||
- no embedded `Back` / `Next` / `Summary` navigation;
|
||||
- semantic filenames;
|
||||
- each chapter must stand on its own;
|
||||
- each chapter must declare its domain and documentary function at the top of the file;
|
||||
- taxonomy should live in the `README`, not in an artificial directory tree.
|
||||
|
||||
## Taxonomy
|
||||
|
||||
| Range | Domain |
|
||||
| --- | --- |
|
||||
| `01` | machine timing and cycle budget |
|
||||
| `02` to `03`, `09a`, `16` to `16a` | VM subsystem and host ABI |
|
||||
| `04` to `08` | virtual hardware peripherals |
|
||||
| `09` to `11` | machine execution envelope, diagnostics, and portability |
|
||||
| `12` and `14` | firmware and boot orchestration |
|
||||
| `13` and `15` | cartridge package and asset surface |
|
||||
|
||||
Here, hardware is not a generic bucket for everything. In the current package, "hardware" means the machine's virtual peripherals: GFX, AUDIO, INPUT, TOUCH, and MEMCARD/save memory. VM, firmware, cartridge, and ABI sit in sibling categories rather than inside hardware.
|
||||
|
||||
## Document Functions
|
||||
|
||||
- `normative`: defines the technical contract, expected behavior, or implementation-facing surface.
|
||||
- `mixed (normative + explanatory)`: contains technical contract material but preserves explanatory framing to clarify the machine model.
|
||||
- `historical`: archived material; not the authority for new implementation work.
|
||||
- `pedagogical`: teaching material; does not define the technical contract on its own.
|
||||
|
||||
In the current state, no chapter under the active `docs/runtime/specs/` root is purely `historical`. If historical material appears, it must not compete with the primary normative surface.
|
||||
|
||||
## Current Chapter Map
|
||||
|
||||
| File | Domain | Function |
|
||||
| --- | --- | --- |
|
||||
| [`01-time-model-and-cycles.md`](01-time-model-and-cycles.md) | machine timing and cycles | normative |
|
||||
| [`02-vm-instruction-set.md`](02-vm-instruction-set.md) | VM subsystem overview | normative |
|
||||
| [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) | VM values and calling convention | normative |
|
||||
| [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) | VM closures and function values | normative |
|
||||
| [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) | VM memory model | normative |
|
||||
| [`04-gfx-peripheral.md`](04-gfx-peripheral.md) | virtual hardware: graphics | normative |
|
||||
| [`05-audio-peripheral.md`](05-audio-peripheral.md) | virtual hardware: audio | normative |
|
||||
| [`06-input-peripheral.md`](06-input-peripheral.md) | virtual hardware: input | normative |
|
||||
| [`07-touch-peripheral.md`](07-touch-peripheral.md) | virtual hardware: touch | normative |
|
||||
| [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) | virtual hardware: save memory | normative |
|
||||
| [`09-events-and-concurrency.md`](09-events-and-concurrency.md) | machine events and frame scheduling | normative |
|
||||
| [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) | VM coroutine model | normative |
|
||||
| [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) | machine diagnostics | normative |
|
||||
| [`11-portability-and-cross-platform-execution.md`](11-portability-and-cross-platform-execution.md) | portability contract | normative |
|
||||
| [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) | firmware and system orchestration | normative |
|
||||
| [`13-cartridge.md`](13-cartridge.md) | cartridge package | normative |
|
||||
| [`14-boot-profiles.md`](14-boot-profiles.md) | firmware boot flow | normative |
|
||||
| [`15-asset-management.md`](15-asset-management.md) | asset runtime surface | normative |
|
||||
| [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) | host ABI structure | normative |
|
||||
| [`16a-syscall-policies.md`](16a-syscall-policies.md) | host ABI operational policy | normative |
|
||||
|
||||
## Authority Model
|
||||
|
||||
- `docs/runtime/specs/` defines the PROMETEU machine and its external execution surfaces.
|
||||
- [`../virtual-machine/ARCHITECTURE.md`](../vm-arch/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants.
|
||||
- [`../virtual-machine/ISA_CORE.md`](../vm-arch/ISA_CORE.md) remains the authority for the bytecode ISA.
|
||||
- When a chapter here touches the VM, it may complement but must not contradict the canonical VM/runtime architecture.
|
||||
|
||||
## Rules for Future Chapters
|
||||
|
||||
- the filename should communicate the domain;
|
||||
- the chapter should declare `Domain` and `Function` at the top;
|
||||
- hardware chapters should cover peripherals or observable machine surfaces, not arbitrary technical topics;
|
||||
- historical or purely pedagogical chapters must not compete with normative chapters for authority;
|
||||
- internal links should add real context rather than act as mandatory navigation.
|
||||
|
||||
## Pairing Rule
|
||||
|
||||
A topic should be created as a `spec` + `learn` pair when:
|
||||
|
||||
- the normative contract matters, but the mental model matters too;
|
||||
- the text needs historical context, comparison with classic hardware, or extensive design rationale;
|
||||
- the pedagogical material risks bloating or confusing the normative chapter;
|
||||
- the subject serves both as a technical surface and as a teaching tool.
|
||||
|
||||
In those cases:
|
||||
|
||||
- `docs/runtime/specs/` defines the contract;
|
||||
- `docs/runtime/learn/` explains the why, the intuition, and the examples;
|
||||
- the spec should point to the pedagogical companion near the top;
|
||||
- the pedagogical guide should point back to the canonical spec.
|
||||
Reference in New Issue
Block a user