discussion framework migration
This commit is contained in:
@@ -7,8 +7,8 @@ It exists to explain the fantasy handheld's mental model, influences, tradeoffs,
|
||||
## Authority
|
||||
|
||||
- `docs/runtime/learn/` is not a canonical source of technical contract.
|
||||
- The machine's normative surfaces live in [`../specs/`](../specs/README.md).
|
||||
- The VM/runtime's internal invariants live in [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md).
|
||||
- The machine's normative surfaces live in [`../specs/`](../../specs/README.md).
|
||||
- The VM/runtime's internal invariants live in [`../virtual-machine/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md).
|
||||
|
||||
## Reading Order
|
||||
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
Status: historical snapshot in `learn`, not normative.
|
||||
Current normative anchors:
|
||||
|
||||
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
## Status
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
Status: historical snapshot in `learn`, not normative.
|
||||
Current normative anchors:
|
||||
|
||||
- [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
## Status
|
||||
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
Status: pedagogical / historical
|
||||
Normative anchors:
|
||||
- [`../specs/13-cartridge.md`](../specs/13-cartridge.md)
|
||||
- [`../specs/12-firmware-pos-and-prometeuhub.md`](../specs/12-firmware-pos-and-prometeuhub.md)
|
||||
- [`../specs/14-boot-profiles.md`](../specs/14-boot-profiles.md)
|
||||
- [`../specs/13-cartridge.md`](../../specs/13-cartridge.md)
|
||||
- [`../specs/12-firmware-pos-and-prometeuhub.md`](../../specs/12-firmware-pos-and-prometeuhub.md)
|
||||
- [`../specs/14-boot-profiles.md`](../../specs/14-boot-profiles.md)
|
||||
|
||||
This document records the historical rationale behind removing `entrypoint` from the cartridge manifest and moving cartridge boot authority into the executable artifact itself.
|
||||
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
Status: historical snapshot in `learn`, not normative.
|
||||
Current normative anchors:
|
||||
|
||||
- [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
|
||||
- [`../specs/16-host-abi-and-syscalls.md`](../specs/16-host-abi-and-syscalls.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
|
||||
- [`../specs/16-host-abi-and-syscalls.md`](../../specs/16-host-abi-and-syscalls.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
|
||||
- [`mental-model-save-memory-and-memcard.md`](mental-model-save-memory-and-memcard.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
|
||||
@@ -3,8 +3,8 @@
|
||||
Status: historical snapshot in `learn`, not normative.
|
||||
Current normative anchors:
|
||||
|
||||
- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
## Status
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
Status: pedagogical
|
||||
Companion specs:
|
||||
|
||||
- [`../specs/13-cartridge.md`](../specs/13-cartridge.md)
|
||||
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
|
||||
- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
|
||||
- [`../specs/13-cartridge.md`](../../specs/13-cartridge.md)
|
||||
- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
|
||||
- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
|
||||
|
||||
Origin decisions:
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Audio Mental Model
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
|
||||
Companion spec: [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
|
||||
|
||||
The right mental model for audio in PROMETEU is an active peripheral with a budget, not "automatic sound".
|
||||
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
# GFX Mental Model
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
|
||||
Companion spec: [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
|
||||
|
||||
Related asset spec: [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
|
||||
Related asset spec: [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
|
||||
|
||||
PROMETEU treats graphics as an explicit peripheral, not as a modern GPU.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Input Mental Model
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/06-input-peripheral.md`](../specs/06-input-peripheral.md)
|
||||
Companion spec: [`../specs/06-input-peripheral.md`](../../specs/06-input-peripheral.md)
|
||||
|
||||
PROMETEU treats input as sampled state, not as an asynchronous event.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Observability and Debugging
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/10-debug-inspection-and-profiling.md`](../specs/10-debug-inspection-and-profiling.md)
|
||||
Companion spec: [`../specs/10-debug-inspection-and-profiling.md`](../../specs/10-debug-inspection-and-profiling.md)
|
||||
|
||||
PROMETEU was designed to be observable.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Portability and Cross-Platform Execution
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/11-portability-and-cross-platform-execution.md`](../specs/11-portability-and-cross-platform-execution.md)
|
||||
Companion spec: [`../specs/11-portability-and-cross-platform-execution.md`](../../specs/11-portability-and-cross-platform-execution.md)
|
||||
|
||||
PROMETEU treats portability as an architectural property of the machine, not as an after-the-fact adaptation.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Save Memory and MEMCARD
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
|
||||
Companion spec: [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
|
||||
Historical snapshot: [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md)
|
||||
|
||||
PROMETEU treats persistence as explicit hardware, not as invisible save behavior.
|
||||
|
||||
@@ -3,11 +3,11 @@
|
||||
Status: pedagogical
|
||||
Companion specs:
|
||||
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
|
||||
- [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
|
||||
- [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
|
||||
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../../specs/16a-syscall-policies.md)
|
||||
- [`../specs/04-gfx-peripheral.md`](../../specs/04-gfx-peripheral.md)
|
||||
- [`../specs/05-audio-peripheral.md`](../../specs/05-audio-peripheral.md)
|
||||
- [`../specs/08-save-memory-and-memcard.md`](../../specs/08-save-memory-and-memcard.md)
|
||||
- [`../specs/15-asset-management.md`](../../specs/15-asset-management.md)
|
||||
|
||||
PROMETEU uses a status-first model so the host/runtime boundary does not hide operational errors as silence, improper `Trap`, or accidental `Panic`.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Time Model and Cycles
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/01-time-model-and-cycles.md`](../specs/01-time-model-and-cycles.md)
|
||||
Companion spec: [`../specs/01-time-model-and-cycles.md`](../../specs/01-time-model-and-cycles.md)
|
||||
|
||||
PROMETEU treats time as an explicit part of the machine.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Touch Mental Model
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/07-touch-peripheral.md`](../specs/07-touch-peripheral.md)
|
||||
Companion spec: [`../specs/07-touch-peripheral.md`](../../specs/07-touch-peripheral.md)
|
||||
|
||||
PROMETEU uses TOUCH as an absolute, deterministic pointer, not as a gesture-rich surface.
|
||||
|
||||
|
||||
@@ -1,156 +0,0 @@
|
||||
# Time Model and Cycles
|
||||
|
||||
Domain: machine timing and cycles
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../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
|
||||
```
|
||||
@@ -1,129 +0,0 @@
|
||||
# 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`](../virtual-machine/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`](../virtual-machine/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.
|
||||
@@ -1,102 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,70 +0,0 @@
|
||||
# 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).
|
||||
@@ -1,192 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,593 +0,0 @@
|
||||
# GFX Peripheral (Graphics System)
|
||||
|
||||
Domain: virtual hardware: graphics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-gfx.md`](../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.
|
||||
@@ -1,225 +0,0 @@
|
||||
# Audio Peripheral (Audio System)
|
||||
|
||||
Domain: virtual hardware: audio
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-audio.md`](../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.
|
||||
@@ -1,109 +0,0 @@
|
||||
# Input Peripheral (VM-Owned Snapshot Input)
|
||||
|
||||
Domain: virtual hardware: input
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-input.md`](../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.
|
||||
@@ -1,171 +0,0 @@
|
||||
# Touch Peripheral (Absolute Pointer Input System)
|
||||
|
||||
Domain: virtual hardware: touch
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-touch.md`](../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
|
||||
@@ -1,140 +0,0 @@
|
||||
# Save Memory and MEMCARD
|
||||
|
||||
Domain: virtual hardware: save memory
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-save-memory-and-memcard.md`](../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.]
|
||||
@@ -1,123 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,107 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,239 +0,0 @@
|
||||
# Debug, Inspection, and Profiling
|
||||
|
||||
Domain: machine diagnostics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../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
|
||||
@@ -1,168 +0,0 @@
|
||||
# Portability Guarantees and Cross-Platform Execution
|
||||
|
||||
Domain: portability contract
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/mental-model-portability-and-cross-platform.md`](../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**
|
||||
@@ -1,138 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,157 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,86 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,324 +0,0 @@
|
||||
# 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`
|
||||
@@ -1,202 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,162 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,116 +0,0 @@
|
||||
# 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`](../virtual-machine/ARCHITECTURE.md);
|
||||
- bytecode-level ISA:
|
||||
[`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md);
|
||||
- pedagogical guides and learning material:
|
||||
[`../learn/README.md`](../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`](../virtual-machine/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants.
|
||||
- [`../virtual-machine/ISA_CORE.md`](../virtual-machine/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.
|
||||
@@ -1,184 +0,0 @@
|
||||
Prometeu VM Runtime — Canonical Architecture
|
||||
|
||||
Status: canonical
|
||||
|
||||
This document is the authoritative architectural reference for the Prometeu VM runtime. It reflects the implementation as it exists today and defines the invariants that govern architectural changes in the VM layer.
|
||||
|
||||
Scope boundary:
|
||||
|
||||
- PROMETEU itself is a fantasy handheld / fantasy console with a broader machine model, firmware model, cartridge model, and virtual hardware surface.
|
||||
- This document does not define the whole PROMETEU machine.
|
||||
- This document defines the VM/runtime subsystem that executes bytecode inside that machine.
|
||||
- For broader machine-level framing, see [`../specs/README.md`](../specs/README.md).
|
||||
|
||||
Document roles:
|
||||
|
||||
- This file is normative for VM/runtime architecture.
|
||||
- Detailed domain specifications may live under `docs/runtime/specs/`, but they must not contradict this document where VM/runtime invariants are concerned.
|
||||
- Roadmaps, agendas, and PR proposals may discuss future changes, but they are not authoritative until this document is updated.
|
||||
- The machine-wide fantasy console framing lives in the runtime specs manual and related domain specs; those documents are complementary, not competing VM architecture sources.
|
||||
|
||||
Maintenance rule:
|
||||
|
||||
- Any PR that changes VM/runtime architectural invariants must update this document in the same change.
|
||||
|
||||
|
||||
1. Overview
|
||||
-----------
|
||||
|
||||
- Stack‑based virtual machine
|
||||
- Operand stack + call frames; bytecode is fetched from a ROM/program image with a separate constant pool.
|
||||
- GC‑managed heap
|
||||
- Non‑compacting mark–sweep collector; stable object handles (`HeapRef`) while live. Sweep invalidates unreachable handles; objects are never moved.
|
||||
- Closures (Model B)
|
||||
- First‑class closures with a heap‑allocated environment. The closure object is passed to the callee as a hidden `arg0` when invoking a closure.
|
||||
- Cooperative coroutines
|
||||
- Deterministic, cooperative scheduling. Switching and GC occur only at explicit safepoints (`FRAME_SYNC`).
|
||||
- Unified syscall ABI
|
||||
- PBX pre-load artifacts declare canonical host bindings in `SYSC` and encode call sites as `HOSTCALL <sysc_index>`. The loader resolves and patches them to numeric `SYSCALL <id>` before verification/execution. Capability gating is enforced at load and checked again defensively at runtime. Syscalls are not first‑class values.
|
||||
|
||||
|
||||
2. Memory Model
|
||||
----------------
|
||||
|
||||
2.1 Stack vs Heap
|
||||
|
||||
- Stack
|
||||
- Each running context has an operand stack plus call frames (locals, return bookkeeping). Primitive values (integers, floats, booleans) reside on the stack. Heap objects are referenced by opaque `HeapRef` values on the stack.
|
||||
- The VM’s current operand stack and frames are GC roots.
|
||||
|
||||
- Heap
|
||||
- The heap stores runtime objects that require identity and reachability tracking. Handles are `HeapRef` indices into an internal object store.
|
||||
- The collector is mark–sweep, non‑moving: it marks from roots, then reclaims unreachable objects without relocating survivors. Indices for live objects remain stable across collections.
|
||||
|
||||
2.2 Heap Object Kinds (as used today)
|
||||
|
||||
- Arrays of `Value`
|
||||
- Variable‑length arrays whose elements may contain further `HeapRef`s.
|
||||
- Closures
|
||||
- Carry a function identifier and a captured environment (a slice/vector of `Value`s stored with the closure). Captured `HeapRef`s are traversed by the GC.
|
||||
- Coroutines
|
||||
- Heap‑resident coroutine records (state + wake time + suspended operand stack and call frames). These act as GC roots when suspended.
|
||||
|
||||
Notes:
|
||||
- Literals like strings and numbers are sourced from the constant pool in the program image; heap allocation is only used for runtime objects (closures, arrays, coroutine records, and any future heap kinds). The constant pool never embeds raw `HeapRef`s.
|
||||
|
||||
2.3 GC Roots
|
||||
|
||||
- VM roots
|
||||
- Current operand stack and call frames of the running coroutine (or main context).
|
||||
- Suspended coroutines
|
||||
- All heap‑resident, suspended coroutine objects are treated as roots. Their saved stacks/frames are scanned during marking.
|
||||
- Root traversal
|
||||
- The VM exposes a root‑visitor that walks the operand stack, frames, and coroutine records to feed the collector. The collector then follows children from each object kind (e.g., array elements, closure environments, coroutine stacks).
|
||||
|
||||
|
||||
3. Execution Model
|
||||
-------------------
|
||||
|
||||
3.1 Interpreter Loop
|
||||
|
||||
- The VM runs a classic fetch–decode–execute loop over the ROM’s bytecode. The current program counter (PC), operand stack, and call frames define execution state.
|
||||
- Function calls establish new frames; returns restore the caller’s frame and adjust the operand stack to the callee’s declared return slot count (the verifier enforces this shape statically).
|
||||
- Errors
|
||||
- Traps (well‑defined fault conditions) surface as trap reasons; panics indicate internal consistency failures. The VM can report logical frame endings such as `FrameSync`, `BudgetExhausted`, `Halted`, end‑of‑ROM, `Breakpoint`, `Trap(code, …)`, and `Panic(msg)`.
|
||||
|
||||
3.2 Safepoints
|
||||
|
||||
- `FRAME_SYNC` is the only safepoint.
|
||||
- At `FRAME_SYNC`, the VM performs two actions in a well‑defined order:
|
||||
1) Garbage‑collection opportunity: root enumeration + mark–sweep.
|
||||
2) Scheduler handoff: the currently running coroutine may yield/sleep, and a next ready coroutine is selected deterministically.
|
||||
- No other opcode constitutes a GC or scheduling safepoint. Syscalls do not implicitly trigger GC or rescheduling.
|
||||
|
||||
3.3 Scheduler Behavior (Cooperative Coroutines)
|
||||
|
||||
- Coroutines are cooperative and scheduled deterministically (FIFO among ready coroutines).
|
||||
- `YIELD` and `SLEEP` take effect at `FRAME_SYNC`:
|
||||
- `YIELD` places the current coroutine at the end of the ready queue.
|
||||
- `SLEEP` parks the current coroutine until its exact `wake_tick`, after which it re‑enters the ready queue at the correct point.
|
||||
- `SPAWN` creates a new coroutine with its own stack/frames recorded in the heap and enqueues it deterministically.
|
||||
- No preemption: the VM never interrupts a coroutine between safepoints.
|
||||
|
||||
|
||||
4. Verification Model
|
||||
----------------------
|
||||
|
||||
4.1 Verifier Responsibilities
|
||||
|
||||
The verifier statically checks bytecode for structural safety and stack‑shape correctness. Representative checks include:
|
||||
|
||||
- Instruction well‑formedness
|
||||
- Unknown opcode, truncated immediates/opcodes, malformed function boundaries, trailing bytes.
|
||||
- Control‑flow integrity
|
||||
- Jump targets within bounds and to instruction boundaries; functions must have proper terminators; path coverage ensures a valid exit.
|
||||
- Stack discipline
|
||||
- No underflow/overflow relative to declared max stack; consistent stack height at control‑flow joins; `RET` occurs at the expected height.
|
||||
- Call/return shape
|
||||
- Direct calls and returns must match the declared argument counts and return slot counts. Mismatches are rejected.
|
||||
- Syscalls
|
||||
- The verifier runs only on the patched executable image. `HOSTCALL` is invalid at verification time. Final `SYSCALL` IDs must exist per `SyscallMeta`, and arity/declared return slot counts must match metadata.
|
||||
- Closures
|
||||
- `CALL_CLOSURE` is only allowed on closure values; the callee function must be known; argument counts for closure calls must match.
|
||||
- Coroutines
|
||||
- `YIELD` context must be valid; `SPAWN` argument counts are validated.
|
||||
|
||||
4.2 Runtime vs Verifier Guarantees
|
||||
|
||||
- The verifier guarantees structural correctness and stack‑shape invariants. It does not perform full type checking of value contents; dynamic checks (e.g., numeric domain checks, polymorphic comparisons, concrete syscall argument validation) occur at runtime and may trap.
|
||||
- Capability gating for syscalls is enforced at load from cartridge capability flags and checked again at runtime by the VM/native interface.
|
||||
|
||||
|
||||
5. Closures (Model B) — Calling Convention
|
||||
-------------------------------------------
|
||||
|
||||
- Creation
|
||||
- `MAKE_CLOSURE` captures N values from the operand stack into a heap‑allocated environment alongside a function identifier. The opcode _pushes a `HeapRef` to the new closure.
|
||||
- Call
|
||||
- `CALL_CLOSURE` invokes a closure. The closure object itself is supplied to the callee as a hidden `arg0`. User‑visible arguments follow the function’s declared arity.
|
||||
- Access to captures
|
||||
- The callee can access captured values via the closure’s environment. Captured `HeapRef`s are traced by the GC.
|
||||
|
||||
|
||||
6. Unified Syscall ABI
|
||||
-----------------------
|
||||
|
||||
- Identification
|
||||
- Host bindings are declared canonically as `(module, name, version)` in PBX `SYSC`, then executed as numeric IDs after loader patching. Syscalls are not first‑class values.
|
||||
- Metadata‑driven
|
||||
- `SyscallMeta` defines expected arity and return slot counts. The loader resolves `HOSTCALL` against this metadata and rejects raw `SYSCALL` in PBX pre-load artifacts; the verifier checks final IDs/arity/return‑slot counts against the same metadata.
|
||||
- Arguments and returns
|
||||
- Arguments are taken from the operand stack in the order defined by the ABI. Returns use multi‑slot results via a host‑side return buffer (`HostReturn`) which the VM copies back onto the stack, or zero slots for “void”. A mismatch in result counts is a fault/panic per current hardening logic.
|
||||
- Capabilities
|
||||
- Cartridge capability flags are applied before load-time host resolution. Missing required capability aborts load; invoking a syscall without the required capability also traps defensively at runtime.
|
||||
|
||||
|
||||
7. Garbage Collection
|
||||
----------------------
|
||||
|
||||
- Collector
|
||||
- Non‑moving mark–sweep.
|
||||
- Triggers
|
||||
- GC runs only at `FRAME_SYNC` safepoints.
|
||||
- Liveness
|
||||
- Roots comprise: the live VM stack/frames and all suspended coroutines. The collector traverses object‑specific children (array elements, closure environments, coroutine stacks).
|
||||
- Determinism
|
||||
- GC opportunities and scheduling order are tied to `FRAME_SYNC`, ensuring repeatable execution traces across runs with the same inputs.
|
||||
|
||||
|
||||
8. Non‑Goals
|
||||
-------------
|
||||
|
||||
- No RC
|
||||
- No HIP
|
||||
- No preemption
|
||||
- No mailbox
|
||||
|
||||
|
||||
9. Notes for Contributors
|
||||
--------------------------
|
||||
|
||||
- Keep the public surface minimal and metadata‑driven (e.g., syscalls via `SyscallMeta`).
|
||||
- Do not assume implicit safepoints; schedule and GC only at `FRAME_SYNC`.
|
||||
- When adding new opcodes or object kinds, extend the verifier and GC traversal accordingly (children enumeration, environment scanning, root sets).
|
||||
- Update this document alongside any architectural change that affects runtime invariants.
|
||||
@@ -1,24 +0,0 @@
|
||||
final_id_hex,final_id_dec,canonical_name,canonical_version,owner,name,arg_slots,ret_slots,arg_layout,ret_layout,deterministic,may_allocate
|
||||
0x1000,4096,vec2.dot,1,vec2,dot,4,1,float|float|float|float,float,true,false
|
||||
0x1001,4097,vec2.length,1,vec2,length,2,1,float|float,float,true,false
|
||||
0x2000,8192,input.pad,1,input,pad,0,1,,builtin:input.pad,true,false
|
||||
0x2001,8193,input.touch,1,input,touch,0,1,,builtin:input.touch,true,false
|
||||
0x2010,8208,input.pad.up,1,input.pad,up,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2011,8209,input.pad.down,1,input.pad,down,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2012,8210,input.pad.left,1,input.pad,left,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2013,8211,input.pad.right,1,input.pad,right,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2014,8212,input.pad.a,1,input.pad,a,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2015,8213,input.pad.b,1,input.pad,b,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2016,8214,input.pad.x,1,input.pad,x,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2017,8215,input.pad.y,1,input.pad,y,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2018,8216,input.pad.l,1,input.pad,l,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2019,8217,input.pad.r,1,input.pad,r,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x201A,8218,input.pad.start,1,input.pad,start,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x201B,8219,input.pad.select,1,input.pad,select,1,1,builtin:input.pad,builtin:input.button,true,false
|
||||
0x2020,8224,input.touch.button,1,input.touch,button,1,1,builtin:input.touch,builtin:input.button,true,false
|
||||
0x2021,8225,input.touch.x,1,input.touch,x,1,1,builtin:input.touch,int,true,false
|
||||
0x2022,8226,input.touch.y,1,input.touch,y,1,1,builtin:input.touch,int,true,false
|
||||
0x2030,8240,input.button.pressed,1,input.button,pressed,1,1,builtin:input.button,bool,true,false
|
||||
0x2031,8241,input.button.released,1,input.button,released,1,1,builtin:input.button,bool,true,false
|
||||
0x2032,8242,input.button.down,1,input.button,down,1,1,builtin:input.button,bool,true,false
|
||||
0x2033,8243,input.button.hold,1,input.button,hold,1,1,builtin:input.button,int,true,false
|
||||
|
@@ -1,134 +0,0 @@
|
||||
### Prometeu Bytecode — Core ISA
|
||||
|
||||
Status: bytecode-level normative
|
||||
|
||||
This document defines the stable Core ISA surface for the Prometeu Virtual Machine at the bytecode level. It specifies instruction encoding, the stack evaluation model, and the instruction set currently available in the canonical opcode surface used by encoder, decoder, disassembler, assembler, verifier, and VM execution.
|
||||
|
||||
Machine boundary:
|
||||
|
||||
- PROMETEU is not "just the VM". It is the broader fantasy console/handheld machine.
|
||||
- This document covers only the bytecode ISA of the VM subsystem embedded in that machine.
|
||||
|
||||
Authority rule:
|
||||
|
||||
- This document is normative for bytecode-level encoding and opcode surface.
|
||||
- Runtime-wide invariants still live in [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md).
|
||||
- If a bytecode-level rule here conflicts with runtime architecture, the conflict must be resolved explicitly in both documents; neither should drift silently.
|
||||
|
||||
#### Encoding Rules
|
||||
|
||||
- Endianness: Little‑endian.
|
||||
- Instruction layout: `[opcode: u16][immediate: spec.imm_bytes]`.
|
||||
- Opcodes are defined in `prometeu_bytecode::isa::core::CoreOpCode`.
|
||||
- Immediate sizes and stack effects are defined by `CoreOpCode::spec()` returning `CoreOpcodeSpec`.
|
||||
- All jump immediates are absolute u32 byte offsets from the start of the current function.
|
||||
|
||||
#### Stack Machine Model
|
||||
|
||||
- The VM is stack‑based. Unless noted, operands are taken from the top of the operand stack and results are pushed back.
|
||||
- Types at the bytecode level are represented by the `Value` enum; the VM may perform numeric promotion where appropriate (e.g., `Int32 + Float -> Float`).
|
||||
- Stack underflow is a trap (TRAP_STACK_UNDERFLOW).
|
||||
- Some operations may trap for other reasons (e.g., division by zero, invalid indices, type mismatches).
|
||||
|
||||
#### Instruction Set (Core)
|
||||
|
||||
- Execution control:
|
||||
- `NOP` — no effect.
|
||||
- `HALT` — terminates execution (block terminator).
|
||||
- `JMP u32` — unconditional absolute jump (block terminator).
|
||||
- `JMP_IF_FALSE u32` — pops `[bool]`, jumps if false.
|
||||
- `JMP_IF_TRUE u32` — pops `[bool]`, jumps if true.
|
||||
- `TRAP` — software trap/breakpoint (block terminator).
|
||||
|
||||
- Stack manipulation:
|
||||
- `PUSH_CONST u32` — load constant by index → _pushes `[value]`.
|
||||
- `PUSH_I64 i64`, `PUSH_F64 f64`, `PUSH_BOOL u8`, `PUSH_I32 i32` — push literals.
|
||||
- `POP` — pops 1.
|
||||
- `POP_N u32` — pops N.
|
||||
- `DUP` — `[x] -> [x, x]`.
|
||||
- `SWAP` — `[a, b] -> [b, a]`.
|
||||
|
||||
- Arithmetic:
|
||||
- `ADD`, `SUB`, `MUL`, `DIV`, `MOD` — binary numeric ops.
|
||||
- `NEG` — unary numeric negation.
|
||||
|
||||
- Comparison and logic:
|
||||
- `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE` — comparisons → `[bool]`.
|
||||
- `AND`, `OR`, `NOT` — boolean logic.
|
||||
- `BIT_AND`, `BIT_OR`, `BIT_XOR`, `SHL`, `SHR` — integer bit operations.
|
||||
|
||||
- Variables:
|
||||
- `GET_GLOBAL u32`, `SET_GLOBAL u32` — access global slots.
|
||||
- `GET_LOCAL u32`, `SET_LOCAL u32` — access local slots (current frame).
|
||||
|
||||
- Functions and scopes:
|
||||
- `CALL u32` — call by function index; argument/result arity per function metadata.
|
||||
- `RET` — return from current function (block terminator).
|
||||
- `MAKE_CLOSURE u32,u32` — create closure from `(fn_id, capture_count)`.
|
||||
- `CALL_CLOSURE u32` — invoke closure with `arg_count` user arguments.
|
||||
|
||||
- Concurrency:
|
||||
- `SPAWN u32,u32` — create coroutine for `(fn_id, arg_count)`.
|
||||
- `YIELD` — request cooperative yield at the next safepoint.
|
||||
- `SLEEP u32` — request suspension for a logical tick duration.
|
||||
|
||||
- System/Timing:
|
||||
- `HOSTCALL u32` — PBX pre-load host binding call by `SYSC` table index; the loader must resolve and rewrite it before verification or execution.
|
||||
- `SYSCALL u32` — final numeric platform call in the executable image; raw `SYSCALL` in PBX pre-load artifacts is rejected by the loader.
|
||||
- `INTRINSIC u32` — final numeric VM-owned intrinsic call.
|
||||
- `FRAME_SYNC` — yield until the next frame boundary (e.g., vblank); explicit safepoint.
|
||||
|
||||
#### Canonical Intrinsic Registry Artifact
|
||||
|
||||
- Final intrinsic IDs and intrinsic stack metadata are published in [`INTRINSICS.csv`](INTRINSICS.csv).
|
||||
- This CSV is the ISA-scoped artifact intended to be consumed by compiler/tooling consumers such as `../studio`.
|
||||
- Each row defines one canonical intrinsic identity and its final numeric ID.
|
||||
- `canonical_name` is the fully qualified intrinsic identity seen by compiler-side intrinsic pools.
|
||||
- `arg_slots` and `ret_slots` are the real stack effect contract for verifier/lowering consumers.
|
||||
- `arg_layout` and `ret_layout` use `|`-separated ABI atoms:
|
||||
- `int`
|
||||
- `float`
|
||||
- `bool`
|
||||
- `builtin:<builtin_name>`
|
||||
- Rows must remain unique by both `(canonical_name, canonical_version)` and `final_id_hex` / `final_id_dec`.
|
||||
- Rows must remain deterministically ordered by final ID.
|
||||
|
||||
For exact immediates and stack effects, see `CoreOpCode::spec()` which is the single source of truth used by the decoder, disassembler, and verifier.
|
||||
|
||||
#### Canonical Decoder Contract
|
||||
|
||||
- The canonical decoder is `prometeu_bytecode::decode_next(pc, bytes)`.
|
||||
- It uses the Core ISA spec to determine immediate size and the canonical `next_pc`.
|
||||
- Unknown or legacy opcodes must produce a deterministic `UnknownOpcode` error.
|
||||
|
||||
#### Module Boundary
|
||||
|
||||
- Core ISA lives under `prometeu_bytecode::isa::core` and re‑exports:
|
||||
- `CoreOpCode` — the opcode enum of the core profile.
|
||||
- `CoreOpcodeSpec` and `CoreOpCodeSpecExt` — spec with `imm_bytes`, stack effects, and flags.
|
||||
- Consumers (encoder/decoder/disasm/verifier) should import from this module to avoid depending on internal layout.
|
||||
|
||||
#### Scope Notes
|
||||
|
||||
- "Core ISA" in the current repository means the canonical opcode surface implemented by the runtime today.
|
||||
- It includes closures, coroutines, `HOSTCALL` patching semantics, `INTRINSIC`, and `FRAME_SYNC`.
|
||||
- It does not, by itself, define higher-level runtime policy such as crash taxonomy, firmware behavior, cartridge lifecycle, or host service organization. Those belong to the canonical runtime architecture and related specs.
|
||||
|
||||
#### FRAME_SYNC — Semantics and Placement (Bytecode Level)
|
||||
|
||||
- Semantics:
|
||||
- `FRAME_SYNC` is a zero-operand instruction and does not modify the operand stack.
|
||||
- It marks a VM safepoint for GC and the cooperative scheduler. In `CoreOpcodeSpec` this is exposed as `spec.is_safepoint == true`.
|
||||
- On execution, the VM may suspend the current coroutine until the next frame boundary and/or perform GC. After resuming, execution continues at the next instruction.
|
||||
|
||||
- Placement rules (representable and checkable):
|
||||
- `FRAME_SYNC` may appear anywhere inside a function body where normal instructions can appear. It is NOT a block terminator (`spec.is_terminator == false`).
|
||||
- Instruction boundaries are canonical: encoders/emitters must only place `FRAME_SYNC` at valid instruction PCs. The verifier already enforces “jump-to-boundary” and end-exclusive `[start, end)` function ranges using the canonical layout routine.
|
||||
- Entrypoints that represent a render/update loop SHOULD ensure at least one reachable `FRAME_SYNC` along every long-running path to provide deterministic safepoints for GC/scheduling. This policy is semantic and may be enforced by higher-level tooling; at the bytecode level it is representable via `spec.is_safepoint` and can be counted by static analyzers.
|
||||
|
||||
- Disassembly:
|
||||
- Disassemblers must print the mnemonic `FRAME_SYNC` verbatim for this opcode.
|
||||
- Tools MAY optionally annotate it as a safepoint in comments, e.g., `FRAME_SYNC ; safepoint`.
|
||||
|
||||
- Verification notes:
|
||||
- The bytecode verifier treats `FRAME_SYNC` as a normal instruction with no stack effect and no control-flow targets. It is permitted before `RET`, between basic blocks, and as the last instruction of a function. Jumps targeting the function end (`pc == end`) remain valid under the end-exclusive rule.
|
||||
Reference in New Issue
Block a user