adjustments on docs
This commit is contained in:
@@ -0,0 +1,254 @@
|
||||
< [Summary](table-of-contents.md) | [Next](chapter-2.md) >
|
||||
|
||||
# ⏱️ **Time Model and Cycles**
|
||||
|
||||
# 1. Overview
|
||||
|
||||
PROMETEU is a **time-oriented** system.
|
||||
|
||||
Nothing happens "instantly".
|
||||
|
||||
Every action consumes **measurable time**, expressed in **execution cycles**.
|
||||
|
||||
This chapter defines:
|
||||
|
||||
- the system's **base clock**
|
||||
- the concept of a **PROMETEU cycle**
|
||||
- how time is distributed across frames
|
||||
- how the **CAP (Execution Cap)** relates to this model
|
||||
|
||||
---
|
||||
|
||||
## 2. System Base Clock
|
||||
|
||||
PROMETEU operates with a **fixed clock of 60 Hz**.
|
||||
|
||||
This means:
|
||||
|
||||
- 60 iterations of the main loop per second
|
||||
- each iteration corresponds to **one frame**
|
||||
- the clock is **deterministic and stable**, regardless of the platform
|
||||
|
||||
> The clock defines the machine's rhythm,
|
||||
not the amount of mandatory work per frame.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 3. The PROMETEU Frame
|
||||
|
||||
A **PROMETEU frame** represents a complete unit of execution.
|
||||
|
||||
Each frame conceptually executes the following stages:
|
||||
|
||||
```
|
||||
FRAME N
|
||||
──────────────
|
||||
INPUT
|
||||
UPDATE
|
||||
DRAW
|
||||
AUDIO
|
||||
SYNC
|
||||
──────────────
|
||||
|
||||
```
|
||||
|
||||
The system guarantees:
|
||||
|
||||
- fixed order
|
||||
- predictable repetition
|
||||
- absence of "ghost" frames
|
||||
|
||||
---
|
||||
|
||||
## 4. PROMETEU Cycles
|
||||
|
||||
### 4.1 Definition
|
||||
|
||||
A **PROMETEU cycle** is the smallest abstract unit of time in the system.
|
||||
|
||||
- each VM instruction consumes a fixed number of cycles
|
||||
- peripheral calls also have a cost
|
||||
- the cost is **documented and stable**
|
||||
|
||||
Cycles are:
|
||||
|
||||
- **countable**
|
||||
- **comparable**
|
||||
- **independent of real hardware**
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Why cycles, and not milliseconds?
|
||||
|
||||
PROMETEU does not measure time in milliseconds because:
|
||||
|
||||
- milliseconds vary between platforms
|
||||
- real clocks differ
|
||||
- jitter and latency hide the real cost
|
||||
|
||||
Cycles allow stating:
|
||||
|
||||
> "This program is more expensive than that one,
|
||||
>
|
||||
>
|
||||
> regardless of where it runs."
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 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 CPU"
|
||||
|
||||
### Conceptual example
|
||||
|
||||
```
|
||||
Frame Budget:10,000cycles
|
||||
|
||||
Used:
|
||||
-Update logic:4,200
|
||||
-Draw calls:3,100
|
||||
-Audio:900
|
||||
|
||||
Remaining:
|
||||
1,800cycles
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Separation between Clock and Work
|
||||
|
||||
PROMETEU **does not require** all logic to run every frame.
|
||||
|
||||
The programmer is **explicitly encouraged** to distribute work over time.
|
||||
|
||||
### Common examples
|
||||
|
||||
- enemy logic every 2 frames (30 Hz)
|
||||
- pathfinding every 4 frames (15 Hz)
|
||||
- animations independent of AI
|
||||
- timers based on frame count
|
||||
|
||||
This reflects real-world practices from:
|
||||
|
||||
- classic consoles
|
||||
- embedded systems
|
||||
- microcontroller firmware
|
||||
|
||||
> Not everything needs to happen now.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 7. Temporal Distribution as Architecture
|
||||
|
||||
PROMETEU treats **work distribution over time** as an architectural decision.
|
||||
|
||||
This means that:
|
||||
|
||||
- code that runs every frame is more expensive
|
||||
- distributed code is more efficient
|
||||
- optimization is, first and foremost, **temporal organization**
|
||||
|
||||
PROMETEU teaches:
|
||||
|
||||
> performance doesn't just come from "less code",
|
||||
>
|
||||
>
|
||||
> but from **when** the code runs.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 8. Execution CAP (Contextual Budget)
|
||||
|
||||
### 8.1 What is the CAP
|
||||
|
||||
The **CAP** defines a set of technical limits associated with a **specific context**, such as:
|
||||
|
||||
- Game Jams
|
||||
- academic evaluations
|
||||
- technical challenges
|
||||
|
||||
The CAP can define:
|
||||
|
||||
- maximum cycle budget per frame
|
||||
- memory limit
|
||||
- peripheral call limits
|
||||
|
||||
---
|
||||
|
||||
### 8.2 CAP does not block execution
|
||||
|
||||
Fundamental rules:
|
||||
|
||||
- the game **always runs**
|
||||
- the game **can always be packaged**
|
||||
- the game **can always be played**
|
||||
|
||||
The CAP **never prevents** execution.
|
||||
|
||||
---
|
||||
|
||||
### 8.3 CAP generates evidence, not punishment
|
||||
|
||||
When a CAP is active, PROMETEU:
|
||||
|
||||
- measures execution
|
||||
- records peaks
|
||||
- identifies bottlenecks
|
||||
- generates a **certification report**
|
||||
|
||||
This report:
|
||||
|
||||
- does not block the game
|
||||
- does not invalidate the delivery
|
||||
- **documents compliance or non-compliance**
|
||||
|
||||
---
|
||||
|
||||
## 9. Time-Based Certification
|
||||
|
||||
PROMETEU certification analyzes:
|
||||
|
||||
- average cycle usage per frame
|
||||
- maximum peaks
|
||||
- problematic frames
|
||||
- cost distribution
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Target CAP:PROMETEU-LITE
|
||||
Frame Budget:5,000cycles
|
||||
|
||||
Frame 18231:
|
||||
Used:5,612cycles❌
|
||||
|
||||
Primary cause:
|
||||
enemy.updateAI():1,012cycles
|
||||
|
||||
```
|
||||
|
||||
This certification accompanies the game as a **technical artifact**.
|
||||
|
||||
---
|
||||
|
||||
## 10. Pedagogical Implications
|
||||
|
||||
The time and cycles model allows teaching:
|
||||
|
||||
- execution planning
|
||||
- time-oriented architecture
|
||||
- technical trade-offs
|
||||
- reading real profiles
|
||||
|
||||
< [Summary](table-of-contents.md) | [Next](chapter-2.md) >
|
||||
@@ -0,0 +1,350 @@
|
||||
< [Back](chapter-9.md) | [Summary](table-of-contents.md) | [Next](chapter-11.md) >
|
||||
|
||||
# 🛠️ **Debug, Inspection, and Profiling**
|
||||
|
||||
## 1. Overview
|
||||
|
||||
PROMETEU was designed to **be observed**.
|
||||
|
||||
Debug, inspection, and profiling **are not optional external tools** —
|
||||
|
||||
they are **integral parts of the machine**.
|
||||
|
||||
Nothing happens without leaving traces.
|
||||
|
||||
Nothing consumes resources without being measured.
|
||||
|
||||
Nothing fails without explanation.
|
||||
|
||||
> PROMETEU does not hide state.
|
||||
> PROMETEU exposes behavior.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 2. Debug Philosophy in PROMETEU
|
||||
|
||||
PROMETEU follows three fundamental debug principles:
|
||||
|
||||
1. **State before abstraction**
|
||||
|
||||
The programmer sees the machine before seeing “features”.
|
||||
|
||||
2. **Time as first class**
|
||||
|
||||
Every action is analyzed in the context of the frame and cycles.
|
||||
|
||||
3. **Observation does not alter execution**
|
||||
|
||||
Debug never changes the behavior of the system.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 3. Execution Modes
|
||||
|
||||
PROMETEU operates in three main modes:
|
||||
|
||||
### 3.1 Normal Mode
|
||||
|
||||
- continuous execution
|
||||
- no detailed inspection
|
||||
- focus on game and experience
|
||||
|
||||
---
|
||||
|
||||
### 3.2 Debug Mode
|
||||
|
||||
- controlled execution
|
||||
- access to internal state
|
||||
- pauses and stepping
|
||||
|
||||
This mode is used for:
|
||||
|
||||
- learning
|
||||
- investigation
|
||||
- error correction
|
||||
|
||||
---
|
||||
|
||||
### 3.3 Certification Mode
|
||||
|
||||
- deterministic execution
|
||||
- collected metrics
|
||||
- report generation
|
||||
|
||||
No mode alters the logical result of the program.
|
||||
|
||||
---
|
||||
|
||||
## 4. Execution Debug
|
||||
|
||||
### 4.1 Pause and Resume
|
||||
|
||||
The system can be paused at safe points:
|
||||
|
||||
- frame start
|
||||
- before UPDATE
|
||||
- after DRAW
|
||||
- before SYNC
|
||||
|
||||
During pause:
|
||||
|
||||
- state is frozen
|
||||
- buffers are not swapped
|
||||
- logical time does not advance
|
||||
|
||||
---
|
||||
|
||||
### 4.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
|
||||
|
||||
---
|
||||
|
||||
## 5. State Inspection
|
||||
|
||||
### 5.1 Stacks
|
||||
|
||||
PROMETEU allows inspecting:
|
||||
|
||||
- **Operand Stack**
|
||||
- **Call Stack**
|
||||
|
||||
For each frame:
|
||||
|
||||
- content
|
||||
- depth
|
||||
- growth and cleanup
|
||||
|
||||
Stack overflow and underflow are immediately visible.
|
||||
|
||||
---
|
||||
|
||||
### 5.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
|
||||
|
||||
---
|
||||
|
||||
### 5.3 Global Space
|
||||
|
||||
Global variables:
|
||||
|
||||
- current values
|
||||
- references
|
||||
- initialization
|
||||
|
||||
Globals are visible as **static RAM**.
|
||||
|
||||
---
|
||||
|
||||
## 6. 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
|
||||
|
||||
---
|
||||
|
||||
## 7. Time Profiling (Cycles)
|
||||
|
||||
### 7.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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7.2 Per-Function Profiling
|
||||
|
||||
PROMETEU can associate cycles with:
|
||||
|
||||
- functions
|
||||
- methods
|
||||
- logical blocks
|
||||
|
||||
This allows answering:
|
||||
|
||||
> “where is the time being spent?”
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
### 7.3 Per-Instruction Profiling
|
||||
|
||||
At the lowest level, the system can display:
|
||||
|
||||
- executed instructions
|
||||
- individual cost
|
||||
- frequency
|
||||
|
||||
This level is especially useful for:
|
||||
|
||||
- VM teaching
|
||||
- deep optimization
|
||||
- bytecode analysis
|
||||
|
||||
---
|
||||
|
||||
## 8. 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.
|
||||
|
||||
---
|
||||
|
||||
## 9. Breakpoints and Watchpoints
|
||||
|
||||
### 9.1 Breakpoints
|
||||
|
||||
PROMETEU supports breakpoints in:
|
||||
|
||||
- specific frames
|
||||
- functions
|
||||
- VM instructions
|
||||
|
||||
Breakpoints:
|
||||
|
||||
- pause execution
|
||||
- preserve state
|
||||
- do not change behavior
|
||||
|
||||
---
|
||||
|
||||
### 9.2 Watchpoints
|
||||
|
||||
Watchpoints monitor:
|
||||
|
||||
- variables
|
||||
- heap addresses
|
||||
- specific values
|
||||
|
||||
Execution can pause when:
|
||||
|
||||
- a value changes
|
||||
- a limit is exceeded
|
||||
|
||||
---
|
||||
|
||||
## 10. Event and Interrupt Debugging
|
||||
|
||||
PROMETEU allows observing:
|
||||
|
||||
- event queue
|
||||
- active timers
|
||||
- occurred interrupts
|
||||
|
||||
Each event has:
|
||||
|
||||
- origin
|
||||
- frame
|
||||
- cost
|
||||
- consequence
|
||||
|
||||
Nothing happens “silently”.
|
||||
|
||||
---
|
||||
|
||||
## 11. Integration with CAP and Certification
|
||||
|
||||
All debug and profiling data:
|
||||
|
||||
- feed the certification report
|
||||
- are collected deterministically
|
||||
- do not depend on external tools
|
||||
|
||||
The final report is:
|
||||
|
||||
- reproducible
|
||||
- auditable
|
||||
- explainable
|
||||
|
||||
---
|
||||
|
||||
## 12. Pedagogical Use
|
||||
|
||||
This system allows teaching:
|
||||
|
||||
- how to debug real systems
|
||||
- how to read metrics
|
||||
- how to correlate time and memory
|
||||
- how to justify technical decisions
|
||||
|
||||
The student learns:
|
||||
|
||||
> debug is not trial and error,
|
||||
> it is informed observation.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 13. Summary
|
||||
|
||||
- debug is part of the system
|
||||
- inspection is complete
|
||||
- profiling is deterministic
|
||||
- time and memory are visible
|
||||
- certification is evidence-based
|
||||
|
||||
< [Back](chapter-9.md) | [Summary](table-of-contents.md) | [Next](chapter-11.md) >
|
||||
@@ -0,0 +1,258 @@
|
||||
< [Back](chapter-10.md) | [Summary](table-of-contents.md) | [Next](chapter-12.md) >
|
||||
|
||||
# 🌍 **Portability Guarantees and Cross-Platform Execution**
|
||||
|
||||
## 1. Overview
|
||||
|
||||
PROMETEU was designed from the beginning to be **portable by construction**, not by later adaptation.
|
||||
|
||||
A PROMETEU cartridge:
|
||||
|
||||
- executes the same way on any supported platform
|
||||
- produces the same results for the same inputs
|
||||
- maintains predictable technical behavior
|
||||
|
||||
> PROMETEU does not depend on the platform.
|
||||
> The platform depends on PROMETEU.
|
||||
>
|
||||
|
||||
This chapter defines the system's **portability contract**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Fundamental Principle of Portability
|
||||
|
||||
Portability in PROMETEU is based on a simple rule:
|
||||
|
||||
> Only the PROMETEU VM defines the program's behavior.
|
||||
>
|
||||
|
||||
This means:
|
||||
|
||||
- source languages do not matter after compilation
|
||||
- real hardware does not influence logic
|
||||
- the operating system does not change semantics
|
||||
|
||||
Everything that does not belong to the VM is **adaptation**, not execution.
|
||||
|
||||
---
|
||||
|
||||
## 3. Separation of Responsibilities
|
||||
|
||||
PROMETEU strictly separates three layers:
|
||||
|
||||
```
|
||||
+----------------------------+
|
||||
| CARTRIDGE |
|
||||
| (bytecode + assets) |
|
||||
+-------------+--------------+
|
||||
|
|
||||
+-------------v--------------+
|
||||
| PROMETEU VM |
|
||||
| (logic, time, memory) |
|
||||
+-------------+--------------+
|
||||
|
|
||||
+-------------v--------------+
|
||||
| PLATFORM LAYER |
|
||||
| window, audio, input, FS |
|
||||
+----------------------------+
|
||||
```
|
||||
|
||||
### What the VM controls
|
||||
|
||||
- bytecode execution
|
||||
- logical time (frames, cycles)
|
||||
- memory (stack, heap)
|
||||
- determinism
|
||||
- costs and metrics
|
||||
|
||||
### What the platform provides
|
||||
|
||||
- pixel display
|
||||
- audio output
|
||||
- physical input collection
|
||||
- access to the sandbox file system
|
||||
|
||||
The platform **never decides behavior**.
|
||||
|
||||
---
|
||||
|
||||
## 4. 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
|
||||
|
||||
This allows stating:
|
||||
|
||||
> “If the cartridge is the same, the game is the same.”
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 5. 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.
|
||||
|
||||
The real hardware:
|
||||
|
||||
- only executes the VM
|
||||
- never interferes with semantics
|
||||
|
||||
---
|
||||
|
||||
## 6. 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
|
||||
|
||||
---
|
||||
|
||||
## 7. 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
|
||||
|
||||
The same cartridge:
|
||||
|
||||
- reacts the same way on PC, mobile, or console
|
||||
- does not contain device-dependent logic
|
||||
|
||||
---
|
||||
|
||||
## 8. 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
|
||||
|
||||
---
|
||||
|
||||
## 9. 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
|
||||
|
||||
PROMETEU **does not delegate graphics decisions to the hardware**.
|
||||
|
||||
---
|
||||
|
||||
## 10. 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.
|
||||
|
||||
---
|
||||
|
||||
## 11. 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
|
||||
|
||||
This is possible because:
|
||||
|
||||
> the certification validates the VM, not the environment.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 12. 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**
|
||||
|
||||
---
|
||||
|
||||
## 13. Pedagogical Implications
|
||||
|
||||
This model allows teaching:
|
||||
|
||||
- the difference between logic and presentation
|
||||
- why modern engines break determinism
|
||||
- how to isolate systems
|
||||
- how to design portable software
|
||||
|
||||
The student learns:
|
||||
|
||||
> portability is not luck — it is architecture.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 14. Summary
|
||||
|
||||
- PROMETEU defines behavior in the VM
|
||||
- platforms only execute
|
||||
- time is logical, not physical
|
||||
- input, audio, and graphics are abstracted
|
||||
- certification is universal
|
||||
- portability is guaranteed by design
|
||||
|
||||
< [Back](chapter-10.md) | [Summary](table-of-contents.md) | [Next](chapter-12.md) >
|
||||
@@ -0,0 +1,236 @@
|
||||
< [Back](chapter-11.md) | [Summary](table-of-contents.md) | [Next](chapter-13.md) >
|
||||
|
||||
# 🧠 Firmware — PrometeuOS (POS) + PrometeuHub
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The **PROMETEU Firmware** is composed of two layers:
|
||||
|
||||
- **PrometeuOS (POS)**: the system firmware/base. It is the maximum authority for boot, peripherals, PVM execution, and fault handling.
|
||||
- **PrometeuHub**: the system launcher and UI environment, embedded in the firmware, executed **over** the POS and using the **PROMETEU Window System**.
|
||||
|
||||
> **Every cartridge is an App**.
|
||||
> The difference is the **App mode** (Game or System), specified in the cartridge header.
|
||||
|
||||
---
|
||||
|
||||
## 2. Terms and Definitions
|
||||
|
||||
- **Host**: real platform (desktop, mobile, DIY console, etc.) that calls the core at 60Hz and displays the framebuffer.
|
||||
- **POS (PrometeuOS)**: firmware (system core). Controls boot, PVM, budget, input latch, peripherals, and crash.
|
||||
- **PrometeuHub**: system UI / launcher running over POS.
|
||||
- **PVM (PROMETEU Virtual Machine)**: VM that executes the App's bytecode.
|
||||
- **App / Cartridge**: PROMETEU executable package (e.g., `.pbc`).
|
||||
- **AppMode**: App mode in the cartridge header:
|
||||
- `GAME`: assumes full screen, own UI
|
||||
- `SYSTEM`: app integrated into the system, should run "in a window" in the Hub
|
||||
- **Logical frame**: App update unit, terminated by `FRAME_SYNC`.
|
||||
- **Host tick**: call from the host (real 60Hz).
|
||||
|
||||
---
|
||||
|
||||
## 3. Responsibilities of the POS (PrometeuOS)
|
||||
|
||||
The POS must guarantee:
|
||||
|
||||
### 3.1 Boot and System States
|
||||
- Deterministic RESET (known state)
|
||||
- Optional SPLASH (short)
|
||||
- initialization of the PrometeuHub and the Window System
|
||||
- return to the Hub after app exit/crash
|
||||
|
||||
### 3.2 PVM Control
|
||||
- load cartridge into the PVM
|
||||
- reset PC/stack/heap upon app start
|
||||
- execute budget per logical frame
|
||||
- respect `FRAME_SYNC` as logical frame boundary
|
||||
- maintain input latched per logical frame
|
||||
|
||||
### 3.3 Peripheral Control
|
||||
- initialization and reset of:
|
||||
- GFX / buffers
|
||||
- AUDIO (channels, command queue)
|
||||
- INPUT / TOUCH
|
||||
- "safe mode" policy (ignore Hub/config if requested)
|
||||
|
||||
### 3.4 Failures and Recovery
|
||||
- capture fatal PVM faults
|
||||
- present **POS_CRASH_SCREEN** (outside the PVM)
|
||||
- allow:
|
||||
- app restart
|
||||
- return to Hub
|
||||
- system reset
|
||||
|
||||
---
|
||||
|
||||
## 4. Responsibilities of the PrometeuHub
|
||||
|
||||
The PrometeuHub must:
|
||||
|
||||
- list available Apps in storage
|
||||
- read metadata from the cartridge header (including `AppMode`)
|
||||
- allow selection and launch
|
||||
- apply system theme/UI via Window System
|
||||
- decide the "execution behavior" based on the `AppMode`
|
||||
|
||||
### 4.1 Decision by `AppMode`
|
||||
When selecting an App:
|
||||
|
||||
- If `AppMode = GAME`:
|
||||
- the Hub delegates to the POS: **execute as a game** (full screen)
|
||||
- If `AppMode = SYSTEM`:
|
||||
- the Hub delegates to the POS: **load the App**
|
||||
- and the Hub **opens a window** and runs the App "integrated into the system"
|
||||
|
||||
> Note: the Hub does not execute bytecode directly; it always delegates to the POS.
|
||||
|
||||
---
|
||||
|
||||
## 5. PROMETEU Window System (System UI)
|
||||
|
||||
The Window System is part of the firmware (POS + Hub) and offers:
|
||||
|
||||
- global theme (palette, fonts, UI sounds)
|
||||
- window system (at least: one active window + dialog stack)
|
||||
- input routing:
|
||||
- focus, navigation, confirmation/cancellation
|
||||
- touch as "tap" (single pointer)
|
||||
|
||||
### 5.1 System App Integration
|
||||
System Apps are executed in "window" mode and must:
|
||||
|
||||
- respect the viewport area provided by the window
|
||||
- cooperate with the Window System's focus/inputs
|
||||
- accept being suspended/closed by the Hub
|
||||
|
||||
The Hub can offer window "chrome":
|
||||
- title
|
||||
- back/close button
|
||||
- overlays (toast, dialogs)
|
||||
|
||||
---
|
||||
|
||||
## 6. Cartridge Header (minimum requirement for the firmware)
|
||||
|
||||
The firmware requires every cartridge to provide at least the following in the header:
|
||||
|
||||
- `magic` / `version`
|
||||
- `app_id` (short string or hash)
|
||||
- `title` (string)
|
||||
- `entrypoint` (PC address)
|
||||
- `app_mode`: `GAME` or `SYSTEM`
|
||||
- (optional) `icon_id` / `cover_id`
|
||||
- (optional) `requested_cap` / VM version
|
||||
|
||||
The POS/HUB must use `app_mode` to decide on execution.
|
||||
|
||||
---
|
||||
|
||||
## 7. Official Boot States (Firmware)
|
||||
|
||||
### 7.1 POS_RESET
|
||||
- initializes peripherals
|
||||
- prepares PVM
|
||||
- loads config
|
||||
- detects safe mode
|
||||
|
||||
Transition: `POS_SPLASH` or `POS_LAUNCH_HUB`
|
||||
|
||||
### 7.2 POS_SPLASH (optional)
|
||||
- displays logo/version
|
||||
- fixed time or "skip"
|
||||
|
||||
Transition: `POS_LAUNCH_HUB`
|
||||
|
||||
### 7.3 POS_LAUNCH_HUB
|
||||
- starts Window System
|
||||
- enters the Hub loop
|
||||
|
||||
Transition: `HUB_HOME`
|
||||
|
||||
### 7.4 HUB_HOME
|
||||
- lists Apps
|
||||
- allows selection:
|
||||
- `GAME` → `POS_RUN_GAME(app)`
|
||||
- `SYSTEM` → `HUB_OPEN_WINDOW(app)` (which delegates `POS_RUN_SYSTEM(app)`)
|
||||
|
||||
### 7.5 POS_RUN_GAME(app)
|
||||
- loads cartridge into the PVM
|
||||
- executes logical frame (budget + `FRAME_SYNC`)
|
||||
- presents frames
|
||||
- maintains latch per logical frame
|
||||
|
||||
Exits:
|
||||
- `APP_EXIT` → `POS_LAUNCH_HUB`
|
||||
- `APP_FAULT` → `POS_CRASH_SCREEN`
|
||||
|
||||
### 7.6 POS_RUN_SYSTEM(app)
|
||||
- loads cartridge into the PVM (or separate instance, if supported in the future)
|
||||
- executes under the Hub/Window System cycle
|
||||
- presents in the window area (viewport)
|
||||
|
||||
Exits:
|
||||
- `APP_EXIT` → returns to the Hub
|
||||
- `APP_FAULT` → `POS_CRASH_SCREEN` (or crash window + fallback)
|
||||
|
||||
### 7.7 POS_CRASH_SCREEN
|
||||
- displays error (type, PC, stack trace)
|
||||
- actions: restart app / hub / reset
|
||||
|
||||
Transition: as chosen.
|
||||
|
||||
---
|
||||
|
||||
## 8. Execution Model (Budget, Latch, and `FRAME_SYNC`)
|
||||
|
||||
The POS is responsible for guaranteeing:
|
||||
|
||||
- **Input latched per logical frame**
|
||||
- execution in slices (host ticks) until the app reaches `FRAME_SYNC`
|
||||
- only at `FRAME_SYNC`:
|
||||
- `present()` (or compose+present)
|
||||
- advances `logical_frame_index`
|
||||
- releases input latch
|
||||
- resets the budget for the next logical frame
|
||||
|
||||
If the budget runs out before `FRAME_SYNC`:
|
||||
- does not present
|
||||
- maintains latch
|
||||
- execution continues in the next host tick within the same logical frame
|
||||
|
||||
---
|
||||
|
||||
## 9. Rules for Returning to the Hub
|
||||
|
||||
The firmware must offer a "return to system" mechanism:
|
||||
|
||||
- button shortcut (e.g., START+SELECT for X ticks)
|
||||
- or controlled syscall (System Apps only)
|
||||
|
||||
Upon returning to the Hub:
|
||||
- the POS terminates or suspends the current App
|
||||
- returns to the Window System with a consistent state
|
||||
|
||||
---
|
||||
|
||||
## 10. Pedagogical Objectives
|
||||
|
||||
This firmware allows teaching:
|
||||
|
||||
- boot stages and firmware as an authority
|
||||
- separation between system and application
|
||||
- deterministic execution with budget and logical frame
|
||||
- difference between apps (Game vs System)
|
||||
- fault tolerance and realistic crash handling
|
||||
|
||||
---
|
||||
|
||||
## 11. Summary
|
||||
|
||||
- POS is the base layer and controls the PVM, budget, latch, peripherals, and crash.
|
||||
- PrometeuHub is the embedded firmware launcher/UI over the POS.
|
||||
- Every cartridge is an App; the header defines the `app_mode` (GAME/SYSTEM).
|
||||
- `GAME` runs in full screen; `SYSTEM` runs integrated into the Hub in a window.
|
||||
- `FRAME_SYNC` is the logical frame boundary.
|
||||
|
||||
< [Back](chapter-11.md) | [Summary](table-of-contents.md) | [Next](chapter-13.md) >
|
||||
@@ -0,0 +1,110 @@
|
||||
< [Back](chapter-12.md) | [Summary](table-of-contents.md) | [Next](chapter-14.md) >
|
||||
|
||||
# Cartridges
|
||||
|
||||
**Version:** 1.0 (stable baseline)
|
||||
**Status:** Proposal
|
||||
|
||||
---
|
||||
|
||||
## 1. Objective
|
||||
|
||||
Define a minimum and stable contract for Prometeu cartridges, allowing:
|
||||
|
||||
* App identification
|
||||
* Mode selection (Game/System)
|
||||
* Entrypoint resolution
|
||||
* Predictable loading by the runtime
|
||||
|
||||
---
|
||||
|
||||
## 2. Concept
|
||||
|
||||
A cartridge is the distributable unit of Prometeu. It can exist as:
|
||||
|
||||
* **Directory (dev)** — ideal for development and hot-reload
|
||||
* **Packaged file (.pmc)** — ideal for distribution
|
||||
|
||||
Both share the same logical layout.
|
||||
|
||||
---
|
||||
|
||||
## 3. Logical Layout
|
||||
|
||||
```
|
||||
<cartridge>/
|
||||
├── manifest.json
|
||||
├── program.pbc
|
||||
└── assets/
|
||||
└── ...
|
||||
```
|
||||
|
||||
Required fields:
|
||||
|
||||
* `manifest.json`
|
||||
* `program.pbc` (Prometeu bytecode)
|
||||
|
||||
---
|
||||
|
||||
## 4. manifest.json (Contract v1)
|
||||
|
||||
```json
|
||||
{
|
||||
"magic": "PMTU",
|
||||
"cartridge_version": 1,
|
||||
"app_id": 1234,
|
||||
"title": "My Game",
|
||||
"app_version": "1.0.0",
|
||||
"app_mode": "Game",
|
||||
"entrypoint": "main"
|
||||
}
|
||||
```
|
||||
|
||||
### Fields
|
||||
|
||||
* `magic`: fixed string `PMTU`
|
||||
* `cartridge_version`: format version
|
||||
* `app_id`: unique numerical identifier
|
||||
* `title`: name of the app
|
||||
* `app_version`: app version
|
||||
* `app_mode`: `Game` or `System`
|
||||
* `entrypoint`: symbol or index recognized by the VM
|
||||
|
||||
---
|
||||
|
||||
## 5. Runtime Rules
|
||||
|
||||
* Validate `magic` and `cartridge_version`
|
||||
* Read `app_mode` to decide execution flow
|
||||
* Resolve `entrypoint` in `program.pbc`
|
||||
* Ignore `assets/` if not supported yet
|
||||
|
||||
---
|
||||
|
||||
## 6. Usage Modes
|
||||
|
||||
### Directory (development)
|
||||
|
||||
```
|
||||
prometeu --run ./mycart/
|
||||
```
|
||||
|
||||
### Packaged file
|
||||
|
||||
```
|
||||
prometeu --run mygame.pmc
|
||||
```
|
||||
|
||||
Both must behave identically in the runtime.
|
||||
|
||||
---
|
||||
|
||||
## 7. Contract Stability
|
||||
|
||||
From v1 onwards:
|
||||
|
||||
* `manifest.json` is the source of truth
|
||||
* Fields can only be added in a backward-compatible manner
|
||||
* Incompatible changes require a new `cartridge_version`
|
||||
|
||||
< [Back](chapter-12.md) | [Summary](table-of-contents.md) | [Next](chapter-14.md) >
|
||||
@@ -0,0 +1,135 @@
|
||||
< [Back](chapter-13.md) | [Summary](table-of-contents.md) | [Next](chapter-15.md) >
|
||||
|
||||
# Boot Profiles
|
||||
|
||||
**Version:** 1.0
|
||||
**Status:** Proposal
|
||||
|
||||
---
|
||||
|
||||
## 1. Objective
|
||||
|
||||
Define how Prometeu decides what to execute at startup:
|
||||
|
||||
* Hub
|
||||
* Automatic cartridge
|
||||
* Debug mode
|
||||
|
||||
---
|
||||
|
||||
## 2. BootTarget Concept
|
||||
|
||||
At the beginning of boot, the POS resolves a target:
|
||||
|
||||
```rust
|
||||
enum BootTarget {
|
||||
Hub,
|
||||
Cartridge { path: String, debug: bool },
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. General Rules
|
||||
|
||||
### If BootTarget == Hub
|
||||
|
||||
* Firmware enters `HubHome`
|
||||
* No cartridge is automatically loaded
|
||||
|
||||
### If BootTarget == Cartridge
|
||||
|
||||
1. Load cartridge
|
||||
2. Read `app_mode` in the manifest
|
||||
3. Apply rules:
|
||||
|
||||
* `Game`:
|
||||
|
||||
* Enter `RunningGame`
|
||||
* `System`:
|
||||
|
||||
* Stay in `HubHome`
|
||||
* Open the app as a window/system tool
|
||||
|
||||
---
|
||||
|
||||
## 4. Host CLI
|
||||
|
||||
### Default boot
|
||||
|
||||
```
|
||||
prometeu
|
||||
```
|
||||
|
||||
Result: enters the Hub
|
||||
|
||||
### Run cartridge
|
||||
|
||||
```
|
||||
prometeu run <cartridge>
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
* Game → enters directly into the game
|
||||
* System → opens as a tool in the Hub
|
||||
|
||||
### Run with debugger
|
||||
|
||||
```
|
||||
prometeu debug <cartridge>
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
* Same flow as `run`
|
||||
* Runtime starts in debug mode
|
||||
* Waits for connection from the Java Debugger
|
||||
|
||||
---
|
||||
|
||||
## 5. Firmware States
|
||||
|
||||
Firmware maintains only:
|
||||
|
||||
* `Boot`
|
||||
* `HubHome`
|
||||
* `RunningGame`
|
||||
* `AppCrashed`
|
||||
|
||||
System apps never change the firmware state.
|
||||
|
||||
---
|
||||
|
||||
## 6. Behavior on Real Hardware (future)
|
||||
|
||||
* If miniSD/physical cartridge is present at boot:
|
||||
|
||||
* POS can:
|
||||
|
||||
* always go to the Hub, or
|
||||
* auto-execute according to user configuration
|
||||
|
||||
---
|
||||
|
||||
## 7. Integration with Debugger
|
||||
|
||||
When `debug == true`:
|
||||
|
||||
* Runtime:
|
||||
|
||||
* Initializes
|
||||
* Opens DevTools socket
|
||||
* Waits for `start` command
|
||||
* Only after that does it start cartridge execution
|
||||
|
||||
---
|
||||
|
||||
## 8. Stability
|
||||
|
||||
* BootTarget is an internal POS contract
|
||||
* Host CLI must respect these rules
|
||||
* New boot modes must be compatible extensions
|
||||
|
||||
|
||||
< [Back](chapter-13.md) | [Summary](table-of-contents.md) | [Next](chapter-15.md) >
|
||||
@@ -0,0 +1,331 @@
|
||||
< [Back](chapter-14.md) | [Summary](table-of-contents.md) | [Next](chapter-16.md) >
|
||||
|
||||
# Asset Management
|
||||
|
||||
## Bank-Centric Hardware Asset Model
|
||||
|
||||
**Scope:** Runtime / Hardware Asset Management (SDK-agnostic)
|
||||
|
||||
---
|
||||
|
||||
## 1. Fundamental Principles
|
||||
|
||||
1. **Every asset in Prometeu resides in a Bank**
|
||||
2. **A Bank is a hardware memory management system**
|
||||
3. **Assets are cold binaries stored in the cartridge**
|
||||
4. **Asset memory belongs to the console, not to the VM**
|
||||
5. **Loading, residency, and eviction are explicit**
|
||||
6. **Hardware does not interpret gameplay semantics**
|
||||
7. **The SDK orchestrates policies; hardware executes contracts**
|
||||
|
||||
> In Prometeu, you do not load “data”. You load **residency**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Asset Origin (Cold Storage)
|
||||
|
||||
* All assets initially reside in **cold storage** inside the cartridge.
|
||||
* Typically, each asset corresponds to a binary file.
|
||||
* The runtime **never scans the cartridge directly**.
|
||||
* All access goes through the **Asset Table**.
|
||||
|
||||
---
|
||||
|
||||
## 3. Asset Table
|
||||
|
||||
The Asset Table is an index loaded at cartridge boot.
|
||||
|
||||
It describes **content**, not residency.
|
||||
|
||||
### Location
|
||||
|
||||
* The Asset Table **must be embedded as JSON inside `manifest.json`**.
|
||||
* Tooling may compile this JSON into a binary table for runtime use, but the source of truth is the manifest.
|
||||
|
||||
### Required Fields (conceptual)
|
||||
|
||||
* `asset_id` (integer, internal identifier)
|
||||
* `asset_name` (string, user-facing identifier)
|
||||
* `asset_type` (TILEBANK, SOUNDBANK, BLOB, TILEMAP, ...)
|
||||
* `bank_kind` (mandatory, single)
|
||||
* `offset` (byte offset in cartridge)
|
||||
* `size` (cold size)
|
||||
* `decoded_size` (resident size)
|
||||
* `codec` (RAW, LZ4, ZSTD, ...)
|
||||
* `asset_metadata` (type-specific)
|
||||
|
||||
> `bank_kind` defines **where** an asset may reside in hardware.
|
||||
|
||||
---
|
||||
|
||||
## 4. Bank — Definition
|
||||
|
||||
> **A Bank is the residency and swapping mechanism of the Prometeu hardware.**
|
||||
|
||||
A Bank:
|
||||
|
||||
* owns **numbered slots**
|
||||
* enforces **resident memory budgets**
|
||||
* enforces **staging / inflight budgets**
|
||||
* accepts only compatible assets
|
||||
* supports **atomic swap via commit**
|
||||
* exposes memory and residency metrics
|
||||
|
||||
Banks are hardware infrastructure, not assets.
|
||||
|
||||
---
|
||||
|
||||
## 5. BankKind
|
||||
|
||||
Each Bank belongs to a **BankKind**, defining its pipeline and constraints.
|
||||
|
||||
### Example BankKinds
|
||||
|
||||
* `GFX_TILEBANK`
|
||||
* `AUDIO_SOUNDBANK`
|
||||
* `DATA_BLOBBANK`
|
||||
* `MAP_TILEMAPBANK`
|
||||
|
||||
Each BankKind defines:
|
||||
|
||||
* slot count
|
||||
* maximum resident memory
|
||||
* inflight / staging memory budget
|
||||
* decode and validation pipeline
|
||||
* hardware consumer subsystem (renderer, audio mixer, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 6. Slots and Slot References
|
||||
|
||||
* Each BankKind owns a fixed set of **slots**.
|
||||
* A slot:
|
||||
|
||||
* references a resident asset (or is empty)
|
||||
* never stores data directly
|
||||
* may expose a **generation counter** (debug)
|
||||
|
||||
### Slot Reference
|
||||
|
||||
Slots are always referenced with explicit BankKind context:
|
||||
|
||||
* `gfxSlot(3)`
|
||||
* `audioSlot(1)`
|
||||
* `blobSlot(7)`
|
||||
|
||||
This prevents cross-bank ambiguity.
|
||||
|
||||
---
|
||||
|
||||
## 7. Bank Memory Model
|
||||
|
||||
* Bank memory is **console-owned memory**.
|
||||
* It does not belong to the VM heap.
|
||||
* It does not participate in GC.
|
||||
* It can be fully released when the cartridge shuts down.
|
||||
|
||||
Each Bank manages:
|
||||
|
||||
* total memory
|
||||
* used memory
|
||||
* free memory
|
||||
* inflight (staging) memory
|
||||
|
||||
Conceptually, each Bank is a **specialized allocator**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Unified Loader
|
||||
|
||||
### Conceptual API
|
||||
|
||||
```text
|
||||
handle = asset.load(asset_name, slotRef, flags)
|
||||
```
|
||||
|
||||
Load flow:
|
||||
|
||||
1. Resolve `asset_name` via Asset Table to get its `asset_id`
|
||||
2. Read `bank_kind` from asset entry
|
||||
3. Validate compatibility with `slotRef`
|
||||
4. Enqueue load request
|
||||
5. Perform IO + decode on worker
|
||||
6. Produce materialized asset in staging
|
||||
|
||||
### Handle States
|
||||
|
||||
* `PENDING` — enqueued
|
||||
* `LOADING` — IO/decode in progress
|
||||
* `READY` — staging completed
|
||||
* `COMMITTED` — installed into slot
|
||||
* `CANCELED`
|
||||
* `ERROR`
|
||||
|
||||
---
|
||||
|
||||
## 9. Commit
|
||||
|
||||
```text
|
||||
asset.commit(handle)
|
||||
```
|
||||
|
||||
* Commit is **explicit** and **atomic**
|
||||
* Executed at a safe frame boundary
|
||||
* Performs **pointer swap** in the target slot
|
||||
* Previous asset is released if no longer referenced
|
||||
|
||||
The hardware **never swaps slots automatically**.
|
||||
|
||||
---
|
||||
|
||||
## 10. Asset Deduplication
|
||||
|
||||
* A decoded asset exists **at most once per BankKind**.
|
||||
* Multiple slots may reference the same resident asset.
|
||||
* Redundant loads become **install-only** operations.
|
||||
|
||||
Memory duplication is forbidden by contract.
|
||||
|
||||
---
|
||||
|
||||
## 11. Bank Specializations
|
||||
|
||||
### 11.1 GFX_TILEBANK
|
||||
|
||||
* AssetType: TILEBANK
|
||||
* Immutable graphical tile + palette structure
|
||||
* Consumed by the graphics subsystem
|
||||
|
||||
### 11.2 AUDIO_SOUNDBANK
|
||||
|
||||
* AssetType: SOUNDBANK
|
||||
* Resident audio samples or streams
|
||||
* Consumed by the audio mixer
|
||||
|
||||
### 11.3 DATA_BLOBBANK
|
||||
|
||||
* AssetType: BLOB
|
||||
* Read-only byte buffers
|
||||
* Hardware does not interpret contents
|
||||
|
||||
Used by the SDK via:
|
||||
|
||||
* **Views** (zero-copy, read-only)
|
||||
* **Decode** (materialization into VM heap)
|
||||
|
||||
---
|
||||
|
||||
## 12. Views and Decode (SDK Contract)
|
||||
|
||||
* **View**
|
||||
|
||||
* read-only
|
||||
* zero-copy
|
||||
* valid only while the blob remains resident
|
||||
|
||||
* **Decode**
|
||||
|
||||
* allocates VM-owned entities
|
||||
* independent from the Bank after creation
|
||||
|
||||
Hardware is unaware of Views and Decode semantics.
|
||||
|
||||
---
|
||||
|
||||
## 13. Manifest and Initial Load
|
||||
|
||||
* The cartridge may include a `manifest.json`.
|
||||
* The manifest may declare:
|
||||
|
||||
* assets to preload
|
||||
* target slot references
|
||||
|
||||
These loads occur **before the first frame**.
|
||||
|
||||
---
|
||||
|
||||
## 14. Shutdown and Eviction
|
||||
|
||||
* On cartridge shutdown:
|
||||
|
||||
* all Banks are cleared
|
||||
* all resident memory is released
|
||||
|
||||
No implicit persistence exists.
|
||||
|
||||
---
|
||||
|
||||
## 15. Debugger and Telemetry
|
||||
|
||||
Each Bank must expose:
|
||||
|
||||
* total memory
|
||||
* used memory
|
||||
* free memory
|
||||
* inflight memory
|
||||
* occupied slots
|
||||
* `asset_id` per slot
|
||||
* `asset_name` per slot
|
||||
* generation per slot
|
||||
|
||||
This enables debuggers to visualize:
|
||||
|
||||
* memory stacks per Bank
|
||||
* memory pressure
|
||||
* streaming strategies
|
||||
|
||||
---
|
||||
|
||||
## 16. Minimal Syscall API (Derived)
|
||||
|
||||
The following syscalls form the minimal hardware contract for asset management:
|
||||
|
||||
```text
|
||||
asset.load(asset_name, slotRef, flags) -> handle
|
||||
asset.status(handle) -> LoadStatus
|
||||
asset.commit(handle)
|
||||
asset.cancel(handle)
|
||||
|
||||
bank.info(bank_kind) -> BankStats
|
||||
bank.slot_info(slotRef) -> SlotStats
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
* `LoadStatus` ∈ { PENDING, LOADING, READY, COMMITTED, CANCELED, ERROR }
|
||||
* `BankStats` exposes memory usage and limits
|
||||
* `SlotStats` exposes current asset_id, asset_name and generation
|
||||
|
||||
---
|
||||
|
||||
## 17. Separation of Responsibilities
|
||||
|
||||
### Hardware (Prometeu)
|
||||
|
||||
* manages memory
|
||||
* loads bytes
|
||||
* decodes assets
|
||||
* swaps pointers
|
||||
* reports usage
|
||||
|
||||
### SDK
|
||||
|
||||
* defines packs, scenes, and policies
|
||||
* interprets blobs
|
||||
* creates VM entities
|
||||
|
||||
### VM
|
||||
|
||||
* executes logic
|
||||
* manages its own heap
|
||||
* never owns hardware assets
|
||||
|
||||
---
|
||||
|
||||
## 18. Golden Rule
|
||||
|
||||
> **Banks are the foundation of the hardware.**
|
||||
> **Asset Types describe content.**
|
||||
> **The SDK orchestrates; the hardware executes.**
|
||||
|
||||
< [Back](chapter-14.md) | [Summary](table-of-contents.md) | [Next](chapter-16.md) >
|
||||
@@ -0,0 +1,384 @@
|
||||
< [Back](chapter-15.md) | [Summary](table-of-contents.md) >
|
||||
|
||||
# **Host ABI and Syscalls**
|
||||
|
||||
This chapter defines the Application Binary Interface (ABI) between the Prometeu Virtual Machine (PVM) and the host environment. It specifies how syscalls are identified, resolved, invoked, verified, and accounted for.
|
||||
|
||||
Syscalls provide controlled access to host-managed subsystems such as graphics, audio, input, asset banks, and persistent storage.
|
||||
|
||||
This chapter defines the **contract**. Individual subsystems (GFX, AUDIO, MEMCARD, ASSETS, etc.) define their own syscall tables that conform to this ABI.
|
||||
|
||||
---
|
||||
|
||||
## 1 Design Principles
|
||||
|
||||
The syscall system follows these rules:
|
||||
|
||||
1. **Deterministic**: Syscalls must behave deterministically for the same inputs and frame state.
|
||||
2. **Synchronous**: Syscalls execute to completion within the current VM slice.
|
||||
3. **Non-blocking**: Long operations must be modeled as request + status polling.
|
||||
4. **Capability-gated**: Each syscall requires a declared capability.
|
||||
5. **Stack-based ABI**: Arguments and return values are passed via VM slots.
|
||||
6. **Not first-class**: Syscalls are callable but cannot be stored as values.
|
||||
7. **Language-agnostic identity**: Syscalls are identified by canonical names, not language syntax.
|
||||
|
||||
---
|
||||
|
||||
## 2 Canonical Syscall Identity
|
||||
|
||||
Syscalls are identified by a **canonical triple**:
|
||||
|
||||
```
|
||||
(module, name, version)
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
("gfx", "present", 1)
|
||||
("input", "state", 1)
|
||||
("audio", "play", 2)
|
||||
```
|
||||
|
||||
This identity is:
|
||||
|
||||
* Independent of language syntax.
|
||||
* Stable across languages and toolchains.
|
||||
* Used for capability checks and linking.
|
||||
|
||||
### Language independence
|
||||
|
||||
Different languages may reference the same syscall using different syntax:
|
||||
|
||||
| Language style | Reference form |
|
||||
| -------------- | --------------- |
|
||||
| Dot-based | `gfx.present` |
|
||||
| Namespace | `gfx::present` |
|
||||
| Object-style | `Gfx.present()` |
|
||||
| Functional | `present(gfx)` |
|
||||
|
||||
All of these map to the same canonical identity:
|
||||
|
||||
```
|
||||
("gfx", "present", 1)
|
||||
```
|
||||
|
||||
The compiler is responsible for this mapping.
|
||||
|
||||
---
|
||||
|
||||
## 3 Syscall Resolution
|
||||
|
||||
The host maintains a **Syscall Registry**:
|
||||
|
||||
```
|
||||
(module, name, version) -> syscall_id
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
("gfx", "present", 1) -> 0x0101
|
||||
("gfx", "submit", 1) -> 0x0102
|
||||
("audio", "play", 1) -> 0x0201
|
||||
```
|
||||
|
||||
### Resolution process
|
||||
|
||||
At cartridge load time:
|
||||
|
||||
1. The cartridge declares required syscalls using canonical identities.
|
||||
2. The cartridge bytecode encodes host-backed call sites as `HOSTCALL <sysc_index>` into that declaration table.
|
||||
3. The host verifies capabilities from the cartridge manifest before execution begins.
|
||||
4. The host resolves each canonical identity to a numeric `syscall_id`.
|
||||
5. The loader rewrites every `HOSTCALL <sysc_index>` into `SYSCALL <id>`.
|
||||
6. The VM stores the patched executable image for fast execution.
|
||||
|
||||
At runtime, the VM executes:
|
||||
|
||||
```
|
||||
SYSCALL <id>
|
||||
```
|
||||
|
||||
Only numeric IDs are used during execution.
|
||||
Raw `SYSCALL <id>` is not valid in a PBX pre-load artifact and must be rejected by the loader.
|
||||
|
||||
---
|
||||
|
||||
## 4 Syscall Instruction Semantics
|
||||
|
||||
The VM provides two relevant instruction forms across the load pipeline:
|
||||
|
||||
Pre-load PBX artifact:
|
||||
|
||||
```
|
||||
HOSTCALL <sysc_index>
|
||||
```
|
||||
|
||||
Final executable image:
|
||||
|
||||
```
|
||||
SYSCALL <id>
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
* `<sysc_index>` is an index into the program-declared syscall table.
|
||||
* `<id>` is a 32-bit integer identifying the syscall.
|
||||
|
||||
Execution steps:
|
||||
|
||||
1. The VM looks up syscall metadata using `<id>`.
|
||||
2. The VM verifies that enough arguments exist on the stack.
|
||||
3. The VM checks capability requirements defensively.
|
||||
4. The syscall executes in the host environment.
|
||||
5. The syscall leaves exactly `ret_slots` values on the stack.
|
||||
|
||||
If any contract rule is violated, the VM traps.
|
||||
|
||||
---
|
||||
|
||||
## 5 Syscall Metadata Table
|
||||
|
||||
Each syscall is defined by a metadata entry.
|
||||
|
||||
### SyscallMeta 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 canonical identities, validate declared ABI shape, and enforce capability gating. The verifier uses the final numeric metadata to validate stack effects after patching.
|
||||
|
||||
---
|
||||
|
||||
## 6 Arguments and Return Values
|
||||
|
||||
Syscalls use the same slot-based ABI as functions.
|
||||
|
||||
### Argument passing
|
||||
|
||||
Arguments are pushed onto the stack before the syscall.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
push a
|
||||
push b
|
||||
SYSCALL X // expects 2 arguments
|
||||
```
|
||||
|
||||
### Return values
|
||||
|
||||
After execution, the syscall leaves exactly `ret_slots` values on the stack.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
// before: []
|
||||
SYSCALL input_state
|
||||
// after: [held, pressed, released]
|
||||
```
|
||||
|
||||
Composite return values are represented as multiple slots (stack tuples).
|
||||
|
||||
---
|
||||
|
||||
## 7 Syscalls as Callable Entities (Not First-Class)
|
||||
|
||||
Syscalls behave like functions in terms of arguments and return values, but they are **not first-class values**.
|
||||
|
||||
This means:
|
||||
|
||||
* Syscalls can be invoked.
|
||||
* Syscalls cannot be stored in variables.
|
||||
* Syscalls cannot be passed as arguments.
|
||||
* Syscalls cannot be returned from functions.
|
||||
|
||||
Only user-defined functions and closures are first-class.
|
||||
|
||||
### Conceptual declaration
|
||||
|
||||
```
|
||||
host fn input_state() -> (int, int, int)
|
||||
```
|
||||
|
||||
This represents a syscall with three return values, but it cannot be treated as a function value.
|
||||
|
||||
---
|
||||
|
||||
## 8 Error Model: Traps vs Status Codes
|
||||
|
||||
Syscalls use a hybrid error model.
|
||||
|
||||
### Trap conditions (contract violations)
|
||||
|
||||
The VM traps when:
|
||||
|
||||
* The syscall id is invalid.
|
||||
* The canonical identity cannot be resolved.
|
||||
* The required capability is missing.
|
||||
* The stack does not contain enough arguments.
|
||||
* A handle is invalid or dead.
|
||||
|
||||
These are fatal contract violations.
|
||||
|
||||
### Status returns (domain conditions)
|
||||
|
||||
Normal operational states are returned as values.
|
||||
|
||||
Examples:
|
||||
|
||||
* asset not yet loaded
|
||||
* audio voice unavailable
|
||||
* memcard full
|
||||
|
||||
These are represented by status codes in return slots.
|
||||
|
||||
---
|
||||
|
||||
## 9 Capability System
|
||||
|
||||
Each syscall requires a capability.
|
||||
|
||||
Capabilities are declared by the cartridge manifest.
|
||||
|
||||
Example capability groups:
|
||||
|
||||
* `gfx`
|
||||
* `audio`
|
||||
* `input`
|
||||
* `asset`
|
||||
* `memcard`
|
||||
|
||||
If a syscall is invoked without the required capability:
|
||||
|
||||
* The VM traps.
|
||||
|
||||
---
|
||||
|
||||
## 10 Interaction with the Garbage Collector
|
||||
|
||||
The VM heap is managed by the GC. Host-managed memory is 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 |
|
||||
|
||||
Assets are addressed by identifiers, not VM heap handles.
|
||||
|
||||
### Host root rule
|
||||
|
||||
If a syscall stores a handle to a VM heap object beyond the duration of the call, it must register that handle as a **host root**.
|
||||
|
||||
This prevents the GC from collecting objects still in use by the host.
|
||||
|
||||
This rule applies only to VM heap objects (such as closures or user objects), not to asset identifiers or primitive values.
|
||||
|
||||
---
|
||||
|
||||
## 11 Determinism Rules
|
||||
|
||||
Syscalls must obey deterministic execution rules.
|
||||
|
||||
Forbidden behaviors:
|
||||
|
||||
* reading real-time clocks
|
||||
* accessing non-deterministic OS APIs
|
||||
* performing blocking I/O
|
||||
|
||||
Allowed patterns:
|
||||
|
||||
* frame-based timers
|
||||
* request + poll status models
|
||||
* event delivery at frame boundaries
|
||||
|
||||
---
|
||||
|
||||
## 12 Cost Model and Budgeting
|
||||
|
||||
Each syscall contributes to frame cost.
|
||||
|
||||
The VM tracks:
|
||||
|
||||
* cycles spent in syscalls
|
||||
* syscall counts
|
||||
* allocation cost (if any)
|
||||
|
||||
Example telemetry:
|
||||
|
||||
```
|
||||
Frame 10231:
|
||||
Syscalls: 12
|
||||
Cycles (syscalls): 380
|
||||
Allocations via syscalls: 2
|
||||
```
|
||||
|
||||
Nothing is free.
|
||||
|
||||
---
|
||||
|
||||
## 13 Blocking and Long Operations
|
||||
|
||||
Syscalls must not block.
|
||||
|
||||
Long operations must use a two-phase model:
|
||||
|
||||
1. Request
|
||||
2. Status polling or event notification
|
||||
|
||||
Example pattern:
|
||||
|
||||
```
|
||||
asset.load(id)
|
||||
...
|
||||
status, progress = asset.status(id)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14 Summary
|
||||
|
||||
* Syscalls are deterministic, synchronous, and non-blocking.
|
||||
* They use the same slot-based ABI as functions.
|
||||
* They are callable but not first-class.
|
||||
* They are identified canonically by `(module, name, version)`.
|
||||
* Language syntax does not affect the ABI.
|
||||
* The host resolves canonical identities to numeric syscall IDs.
|
||||
* Capabilities control access to host subsystems.
|
||||
* GC only manages VM heap objects.
|
||||
* Host-held heap objects must be registered as roots.
|
||||
* All syscall costs are tracked per frame.
|
||||
|
||||
|
||||
|
||||
< [Back](chapter-15.md) | [Summary](table-of-contents.md) >
|
||||
@@ -0,0 +1,427 @@
|
||||
< [Back](chapter-1.md) | [Summary](table-of-contents.md) | [Next](chapter-3.md) >
|
||||
|
||||
# **Prometeu Virtual Machine (PVM)**
|
||||
|
||||
This chapter defines the execution model, value system, calling convention, memory model, and host interface of the Prometeu Virtual Machine.
|
||||
|
||||
The PVM is a **deterministic, stack-based VM** designed for a 2D fantasy console environment. Its primary goal is to provide predictable performance, safe memory access, and a stable execution contract suitable for real-time games running at a fixed frame rate. fileciteturn2file0
|
||||
|
||||
---
|
||||
|
||||
## 1 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.
|
||||
3. **Safe memory model**: all heap objects are accessed through handles.
|
||||
4. **Simple compilation target**: stack-based bytecode with verified control flow.
|
||||
5. **Stable ABI**: multi-value returns with fixed slot semantics.
|
||||
6. **First-class functions**: functions can be passed, stored, and returned.
|
||||
|
||||
---
|
||||
|
||||
## 2 Execution Model
|
||||
|
||||
The PVM executes bytecode in a **frame loop**. Each frame:
|
||||
|
||||
1. The 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`:
|
||||
|
||||
* events are delivered
|
||||
* input is sampled
|
||||
* optional GC may run
|
||||
4. Control returns to the firmware.
|
||||
|
||||
`FRAME_SYNC` is the **primary safepoint** in the system.
|
||||
|
||||
---
|
||||
|
||||
## 3 Value Types
|
||||
|
||||
All runtime values are stored in VM slots as a `Value`.
|
||||
|
||||
### Primitive value types (stack values)
|
||||
|
||||
| Type | Description |
|
||||
| ------- | --------------------- |
|
||||
| `int` | 64-bit signed integer |
|
||||
| `bool` | Boolean value |
|
||||
| `float` | 64-bit floating point |
|
||||
|
||||
### Built-in vector and graphics types (stack values)
|
||||
|
||||
These are treated as VM primitives with dedicated opcodes:
|
||||
|
||||
| Type | Description |
|
||||
| ------- | --------------------------------- |
|
||||
| `vec2` | 2D vector (x, y) |
|
||||
| `color` | Packed color value |
|
||||
| `pixel` | Combination of position and color |
|
||||
|
||||
These types:
|
||||
|
||||
* live entirely on the stack
|
||||
* are copied by value
|
||||
* never allocate on the heap
|
||||
|
||||
### Heap values
|
||||
|
||||
All user-defined objects live on the heap and are accessed via **handles**.
|
||||
|
||||
| Type | Description |
|
||||
| -------- | -------------------------- |
|
||||
| `handle` | Reference to a heap object |
|
||||
| `null` | Null handle |
|
||||
|
||||
Handles may refer to:
|
||||
|
||||
* user objects
|
||||
* arrays
|
||||
* strings
|
||||
* closures
|
||||
|
||||
---
|
||||
|
||||
## 4 Handles and Gate Table
|
||||
|
||||
Heap objects are accessed through **handles**. A handle is a pair:
|
||||
|
||||
```
|
||||
handle = { index, generation }
|
||||
```
|
||||
|
||||
The VM maintains a **gate table**:
|
||||
|
||||
```
|
||||
GateEntry {
|
||||
alive: bool
|
||||
generation: u32
|
||||
base: usize
|
||||
slots: u32
|
||||
type_id: u32
|
||||
}
|
||||
```
|
||||
|
||||
When an object is freed:
|
||||
|
||||
* its gate entry is marked dead
|
||||
* its generation is incremented
|
||||
|
||||
If a handle’s generation does not match the gate entry, the VM traps.
|
||||
|
||||
This prevents use-after-free bugs.
|
||||
|
||||
---
|
||||
|
||||
## 5 Heap Model
|
||||
|
||||
* All user objects live in the heap.
|
||||
* Objects are fixed-layout blocks of slots.
|
||||
* No inheritance at the memory level.
|
||||
* Traits/interfaces are resolved by the compiler or via vtables.
|
||||
|
||||
Built-in types remain stack-only.
|
||||
|
||||
Heap objects include:
|
||||
|
||||
* user structs/classes
|
||||
* strings
|
||||
* arrays
|
||||
* closures
|
||||
|
||||
---
|
||||
|
||||
## 6 Tuples and Multi-Return ABI
|
||||
|
||||
The PVM supports **multi-value returns**.
|
||||
|
||||
### Tuple rules
|
||||
|
||||
* Tuples are **stack-only**.
|
||||
* Maximum tuple arity is **N = 6**.
|
||||
* Tuples are not heap objects by default.
|
||||
* To persist a tuple, it must be explicitly boxed.
|
||||
|
||||
### Call convention
|
||||
|
||||
Each function declares a fixed `ret_slots` value.
|
||||
|
||||
At call time:
|
||||
|
||||
1. Caller prepares arguments.
|
||||
2. `CALL` transfers control.
|
||||
3. Callee executes.
|
||||
4. `RET` leaves exactly `ret_slots` values on the stack.
|
||||
|
||||
The verifier ensures that:
|
||||
|
||||
* all control paths produce the same `ret_slots`
|
||||
* stack depth is consistent.
|
||||
|
||||
---
|
||||
|
||||
## 7 Call Stack and Frames
|
||||
|
||||
The VM uses a **call stack**.
|
||||
|
||||
Each frame contains:
|
||||
|
||||
```
|
||||
Frame {
|
||||
return_pc
|
||||
base_pointer
|
||||
ret_slots
|
||||
}
|
||||
```
|
||||
|
||||
Execution uses only the following call instructions:
|
||||
|
||||
| Opcode | Description |
|
||||
| ------ | ---------------------- |
|
||||
| `CALL` | Calls a function by id |
|
||||
| `RET` | Returns from function |
|
||||
|
||||
There is no separate `PUSH_FRAME` or `POP_FRAME` instruction in the public ISA.
|
||||
|
||||
---
|
||||
|
||||
## 8 Closures and First-Class Functions
|
||||
|
||||
Closures are heap objects and represent **function values**.
|
||||
|
||||
The PVM treats functions as **first-class values**. This means:
|
||||
|
||||
* Functions can be stored in variables.
|
||||
* Functions can be passed as arguments.
|
||||
* Functions can be returned from other functions.
|
||||
* All function values are represented as closures.
|
||||
|
||||
Even functions without captures are represented as closures with an empty capture set.
|
||||
|
||||
### Closure layout
|
||||
|
||||
```
|
||||
Closure {
|
||||
func_id
|
||||
captures[]
|
||||
}
|
||||
```
|
||||
|
||||
Captures are stored as handles or value copies.
|
||||
|
||||
All closure environments are part of the GC root set.
|
||||
|
||||
### Direct and indirect calls
|
||||
|
||||
The PVM supports two forms of function 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 extracts the `func_id` from the closure.
|
||||
3. The function is invoked using the closure’s captures as its environment.
|
||||
|
||||
The verifier ensures that:
|
||||
|
||||
* The closure handle is valid.
|
||||
* The target function’s arity matches the call site.
|
||||
* The `ret_slots` contract is respected.
|
||||
|
||||
---
|
||||
|
||||
## 9 Coroutines (Deterministic)
|
||||
|
||||
The PVM supports **cooperative coroutines**.
|
||||
|
||||
Characteristics:
|
||||
|
||||
* Coroutines are scheduled deterministically.
|
||||
* No preemption.
|
||||
* No parallel execution.
|
||||
* All scheduling happens at safepoints.
|
||||
|
||||
Each coroutine contains:
|
||||
|
||||
```
|
||||
Coroutine {
|
||||
call_stack
|
||||
operand_stack
|
||||
state
|
||||
}
|
||||
```
|
||||
|
||||
### Coroutine instructions
|
||||
|
||||
| Opcode | Description |
|
||||
| ------- | -------------------------- |
|
||||
| `SPAWN` | Creates a coroutine |
|
||||
| `YIELD` | Suspends current coroutine |
|
||||
| `SLEEP` | Suspends for N frames |
|
||||
|
||||
Scheduling is:
|
||||
|
||||
* round-robin
|
||||
* deterministic
|
||||
* bounded by frame budget
|
||||
|
||||
Coroutine stacks are part of the GC root set.
|
||||
|
||||
---
|
||||
|
||||
## 10 Garbage Collection
|
||||
|
||||
The PVM uses a **mark-sweep collector**.
|
||||
|
||||
### GC rules
|
||||
|
||||
* GC runs only at **safepoints**.
|
||||
* The primary safepoint is `FRAME_SYNC`.
|
||||
* GC is triggered by:
|
||||
|
||||
* heap thresholds, or
|
||||
* allocation pressure.
|
||||
|
||||
### Root set
|
||||
|
||||
The GC marks from:
|
||||
|
||||
* operand stack
|
||||
* call stack frames
|
||||
* global variables
|
||||
* coroutine stacks
|
||||
* closure environments
|
||||
* host-held handles
|
||||
|
||||
The collector:
|
||||
|
||||
* does not compact memory (v1)
|
||||
* uses free lists for reuse
|
||||
|
||||
---
|
||||
|
||||
## 11 Event and Interrupt Model
|
||||
|
||||
The PVM does not allow asynchronous callbacks.
|
||||
|
||||
All events are:
|
||||
|
||||
* queued by the firmware
|
||||
* delivered at `FRAME_SYNC`
|
||||
|
||||
This ensures:
|
||||
|
||||
* deterministic execution
|
||||
* predictable frame timing
|
||||
|
||||
Coroutines are the only supported concurrency mechanism.
|
||||
|
||||
---
|
||||
|
||||
## 12 Host Interface (Syscalls)
|
||||
|
||||
All hardware access occurs through syscalls.
|
||||
|
||||
Syscalls are:
|
||||
|
||||
* synchronous
|
||||
* deterministic
|
||||
* capability-checked
|
||||
|
||||
They operate on the following subsystems:
|
||||
|
||||
### Graphics
|
||||
|
||||
* tilebanks
|
||||
* layers
|
||||
* sprites
|
||||
* palette control
|
||||
* fade registers
|
||||
* frame present
|
||||
|
||||
### Audio
|
||||
|
||||
* voice allocation
|
||||
* play/stop
|
||||
* volume/pan/pitch
|
||||
* steal policy
|
||||
|
||||
### Input
|
||||
|
||||
* sampled once per frame
|
||||
* exposed as frame state
|
||||
|
||||
### Assets
|
||||
|
||||
Asset banks are **host-owned memory**.
|
||||
|
||||
The VM interacts through handles:
|
||||
|
||||
| Syscall | Description |
|
||||
| -------------- | ---------------------------- |
|
||||
| `asset.load` | Request asset load into slot |
|
||||
| `asset.status` | Query load state |
|
||||
| `asset.commit` | Activate loaded asset |
|
||||
|
||||
Asset memory:
|
||||
|
||||
* is not part of the VM heap
|
||||
* is not scanned by GC
|
||||
|
||||
### Save Memory (MEMCARD)
|
||||
|
||||
| Syscall | Description |
|
||||
| --------------- | --------------- |
|
||||
| `mem.read_all` | Read save data |
|
||||
| `mem.write_all` | Write save data |
|
||||
| `mem.commit` | Persist save |
|
||||
| `mem.size` | Query capacity |
|
||||
|
||||
---
|
||||
|
||||
## 13 Verifier Requirements
|
||||
|
||||
Before execution, bytecode must pass the verifier.
|
||||
|
||||
The verifier ensures:
|
||||
|
||||
1. Valid jump targets
|
||||
2. Stack depth consistency
|
||||
3. Correct `ret_slots` across all paths
|
||||
4. Handle safety rules
|
||||
5. Closure call safety
|
||||
6. No invalid opcode sequences
|
||||
|
||||
Invalid bytecode is rejected.
|
||||
|
||||
---
|
||||
|
||||
## 14 Summary
|
||||
|
||||
The Prometeu VM is:
|
||||
|
||||
* stack-based
|
||||
* deterministic
|
||||
* frame-synchronized
|
||||
* handle-based for heap access
|
||||
* multi-return capable
|
||||
* first-class function capable
|
||||
* coroutine-driven for concurrency
|
||||
|
||||
This design balances:
|
||||
|
||||
* ease of compilation
|
||||
* predictable performance
|
||||
* safety and debuggability
|
||||
* suitability for real-time 2D games.
|
||||
|
||||
< [Back](chapter-1.md) | [Summary](table-of-contents.md) | [Next](chapter-3.md) >
|
||||
@@ -0,0 +1,353 @@
|
||||
< [Back](chapter-2.md) | [Summary](table-of-contents.md) | [Next](chapter-4.md) >
|
||||
|
||||
# 🧠 **Memory Model**
|
||||
|
||||
This chapter defines the memory architecture of the Prometeu Virtual Machine (PVM). It describes the stack, heap, handles, object layout, garbage collection, and interaction with host-owned memory such as asset banks.
|
||||
|
||||
The memory model is designed to be:
|
||||
|
||||
* deterministic
|
||||
* safe
|
||||
* simple to verify
|
||||
* suitable for real-time 2D games
|
||||
|
||||
---
|
||||
|
||||
## 1 Overview
|
||||
|
||||
The PVM uses a **split memory model**:
|
||||
|
||||
1. **Stack memory**
|
||||
|
||||
* used for temporary values
|
||||
* function arguments
|
||||
* multi-return tuples
|
||||
2. **Heap memory**
|
||||
|
||||
* used for all user-defined objects
|
||||
* accessed only through handles
|
||||
3. **Host-owned memory**
|
||||
|
||||
* asset banks
|
||||
* audio buffers
|
||||
* framebuffers
|
||||
* not part of the VM heap
|
||||
|
||||
---
|
||||
|
||||
## 2 Stack Memory
|
||||
|
||||
The stack is used for:
|
||||
|
||||
* primitive values
|
||||
* built-in value types
|
||||
* temporary results
|
||||
* function arguments
|
||||
* tuple returns
|
||||
|
||||
### Stack value types
|
||||
|
||||
| Type | Description |
|
||||
| -------- | ------------------------ |
|
||||
| `int` | 64-bit integer |
|
||||
| `bool` | Boolean |
|
||||
| `float` | 64-bit float |
|
||||
| `vec2` | 2D vector |
|
||||
| `color` | Packed color |
|
||||
| `pixel` | Position + color |
|
||||
| `handle` | Reference to heap object |
|
||||
|
||||
All stack values are:
|
||||
|
||||
* fixed-size
|
||||
* copied by value
|
||||
* never directly reference raw memory
|
||||
|
||||
### Stack properties
|
||||
|
||||
* Stack is bounded and verified.
|
||||
* Stack depth must be consistent across all control paths.
|
||||
* Stack never stores raw pointers.
|
||||
|
||||
---
|
||||
|
||||
## 3 Tuples (Stack-Only Aggregates)
|
||||
|
||||
Tuples are used for multi-value returns.
|
||||
|
||||
### Tuple rules
|
||||
|
||||
* Tuples exist only on the stack.
|
||||
* Maximum tuple arity: **6 slots**.
|
||||
* Tuples are not heap objects by default.
|
||||
* To persist a tuple, it must be explicitly boxed into a heap object.
|
||||
|
||||
### Example
|
||||
|
||||
Function returning two values:
|
||||
|
||||
```
|
||||
fn position(): (int, int)
|
||||
```
|
||||
|
||||
At runtime:
|
||||
|
||||
```
|
||||
stack top → [x, y]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4 Heap Memory
|
||||
|
||||
All user-defined objects live in the heap.
|
||||
|
||||
### Heap characteristics
|
||||
|
||||
* Linear slot-based storage.
|
||||
* Objects are fixed-layout blocks.
|
||||
* No raw pointer access.
|
||||
* No inheritance at memory level.
|
||||
|
||||
Heap objects include:
|
||||
|
||||
* user structs/classes
|
||||
* arrays
|
||||
* strings
|
||||
* closures
|
||||
* boxed tuples (optional)
|
||||
|
||||
---
|
||||
|
||||
## 5 Handles and Gate Table
|
||||
|
||||
All heap objects are accessed via **handles**.
|
||||
|
||||
A handle is defined as:
|
||||
|
||||
```
|
||||
handle = { index, generation }
|
||||
```
|
||||
|
||||
The VM maintains a **gate table**:
|
||||
|
||||
```
|
||||
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:
|
||||
|
||||
* index must exist
|
||||
* generation must match
|
||||
|
||||
Otherwise, the VM traps.
|
||||
|
||||
This prevents:
|
||||
|
||||
* use-after-free
|
||||
* stale references
|
||||
|
||||
---
|
||||
|
||||
## 6 Object Layout
|
||||
|
||||
Heap objects have a simple, fixed layout:
|
||||
|
||||
```
|
||||
Object {
|
||||
type_id
|
||||
field_0
|
||||
field_1
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Properties:
|
||||
|
||||
* Fields are stored in slot order.
|
||||
* No hidden base classes.
|
||||
* No pointer arithmetic.
|
||||
|
||||
Traits and method dispatch are resolved:
|
||||
|
||||
* statically by the compiler, or
|
||||
* via vtable handles (if dynamic dispatch is used).
|
||||
|
||||
---
|
||||
|
||||
## 7 Closures
|
||||
|
||||
Closures are heap objects.
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
Closure {
|
||||
func_id
|
||||
capture_count
|
||||
captures[]
|
||||
}
|
||||
```
|
||||
|
||||
Captures may be:
|
||||
|
||||
* copied values
|
||||
* handles to heap objects
|
||||
|
||||
Closure environments are part of the GC root set.
|
||||
|
||||
---
|
||||
|
||||
## 8 Coroutine Memory
|
||||
|
||||
Each coroutine owns its own stacks:
|
||||
|
||||
```
|
||||
Coroutine {
|
||||
call_stack
|
||||
operand_stack
|
||||
state
|
||||
}
|
||||
```
|
||||
|
||||
All coroutine stacks are included in the GC root set.
|
||||
|
||||
Coroutines do not share stacks or frames.
|
||||
|
||||
---
|
||||
|
||||
## 9 Garbage Collection
|
||||
|
||||
The PVM uses a **mark-sweep collector**.
|
||||
|
||||
### GC properties
|
||||
|
||||
* Non-moving (no compaction in v1).
|
||||
* 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 stacks
|
||||
* closure environments
|
||||
* host-held handles
|
||||
|
||||
---
|
||||
|
||||
## 10 Allocation and Deallocation
|
||||
|
||||
### Allocation
|
||||
|
||||
Heap allocation:
|
||||
|
||||
1. VM reserves a slot block.
|
||||
2. A gate entry is created.
|
||||
3. A handle is returned.
|
||||
|
||||
If allocation fails:
|
||||
|
||||
* VM may trigger GC.
|
||||
* If still failing, a trap occurs.
|
||||
|
||||
### Deallocation
|
||||
|
||||
Objects are freed only by the GC.
|
||||
|
||||
When freed:
|
||||
|
||||
* gate is marked dead
|
||||
* generation is incremented
|
||||
* memory becomes available via free list
|
||||
|
||||
---
|
||||
|
||||
## 11 Host-Owned Memory (Asset Banks)
|
||||
|
||||
Asset memory is **not part of the VM heap**.
|
||||
|
||||
It is managed by the firmware.
|
||||
|
||||
Examples:
|
||||
|
||||
* tilebanks
|
||||
* audio sample banks
|
||||
* sprite sheets
|
||||
|
||||
### Properties
|
||||
|
||||
* VM cannot access asset memory directly.
|
||||
* Access occurs only through syscalls.
|
||||
* Asset memory is not scanned by GC.
|
||||
|
||||
---
|
||||
|
||||
## 12 Save Memory (MEMCARD)
|
||||
|
||||
Save memory is a host-managed persistent storage area.
|
||||
|
||||
Properties:
|
||||
|
||||
* fixed size
|
||||
* accessed only via syscalls
|
||||
* not part of the VM heap
|
||||
* not scanned by GC
|
||||
|
||||
---
|
||||
|
||||
## 13 Memory Safety Rules
|
||||
|
||||
The VM enforces:
|
||||
|
||||
1. All heap access via handles.
|
||||
2. Generation checks on every handle use.
|
||||
3. Bounds checking on object fields.
|
||||
4. No raw pointer arithmetic.
|
||||
5. Verified stack discipline.
|
||||
|
||||
Any violation results in a trap.
|
||||
|
||||
---
|
||||
|
||||
## 14 Summary
|
||||
|
||||
The PVM memory model is based on:
|
||||
|
||||
* stack-only primitive and tuple values
|
||||
* heap-only user objects
|
||||
* generation-based handles
|
||||
* deterministic GC at frame safepoints
|
||||
* strict separation between VM heap and host memory
|
||||
|
||||
This design ensures:
|
||||
|
||||
* predictable performance
|
||||
* memory safety
|
||||
* simple verification
|
||||
* suitability for real-time game workloads.
|
||||
|
||||
< [Back](chapter-2.md) | [Summary](table-of-contents.md) | [Next](chapter-4.md) >
|
||||
@@ -0,0 +1,600 @@
|
||||
< [Back](chapter-3.md) | [Summary](table-of-contents.md) | [Next](chapter-5.md) >
|
||||
|
||||
# 🎨 **GFX Peripheral (Graphics System)**
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The **GFX** peripheral is responsible for generating images in PROMETEU.
|
||||
|
||||
It models **simple graphics hardware**, inspired by classic consoles
|
||||
(SNES, CPS-2, Neo-Geo), prioritizing:
|
||||
|
||||
- determinism
|
||||
- low computational cost
|
||||
- didactics
|
||||
- portability
|
||||
|
||||
The GFX **is not a modern GPU**.
|
||||
It is an explicit 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
|
||||
|
||||
### 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
|
||||
|
||||
---
|
||||
|
||||
### 17.4 Use Cases
|
||||
|
||||
- HUD Switch:
|
||||
- decrease `HUD_FADE_LEVEL` to 0
|
||||
- switch HUD/tilemap
|
||||
- increase `HUD_FADE_LEVEL` to 31
|
||||
|
||||
- Area Switch:
|
||||
- decrease `SCENE_FADE_LEVEL` to 0
|
||||
- switch scenery
|
||||
- increase `SCENE_FADE_LEVEL` to 31
|
||||
|
||||
- Flash / damage / teleport:
|
||||
- use `fade_color = WHITE` or another thematic color
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
Objectives:
|
||||
|
||||
- reduce RAM and storage usage
|
||||
- allow color swapping without shaders
|
||||
- maintain retro identity
|
||||
- facilitate effects like variation, damage, day/night
|
||||
|
||||
---
|
||||
|
||||
### 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:
|
||||
|
||||
- Up to **256 palettes**
|
||||
- Each palette has:
|
||||
- **16 colors**
|
||||
- each color in **RGB565 (u16)**
|
||||
|
||||
Size:
|
||||
|
||||
- 1 palette = 16 × 2 bytes = **32 bytes**
|
||||
- 256 palettes = **8 KB per bank**
|
||||
- 16 banks = **128 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`
|
||||
|
||||
#### Sprite
|
||||
|
||||
Each sprite draw contains:
|
||||
|
||||
- `bank_id`
|
||||
- `tile_id`
|
||||
- `palette_id (u8)`
|
||||
- `x`, `y`
|
||||
- `flip_x`, `flip_y`
|
||||
- `priority`
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
- 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.
|
||||
|
||||
---
|
||||
|
||||
### 18.8. Possible Effects with Palettes
|
||||
|
||||
Without shaders, it is possible to:
|
||||
|
||||
- Palette swap:
|
||||
- enemies with color variation
|
||||
- States:
|
||||
- damage, ice, poison, power-up
|
||||
- Day / night:
|
||||
- swap palettes globally
|
||||
- Biomes:
|
||||
- same art, different climate
|
||||
- UI themes
|
||||
|
||||
All this without changing tiles.
|
||||
|
||||
---
|
||||
|
||||
### 18.9. Artistic Limitations
|
||||
|
||||
- Each tile/sprite:
|
||||
|
||||
- maximum of 16 colors
|
||||
|
||||
- Smooth gradients require:
|
||||
|
||||
- dithering
|
||||
- discrete blend
|
||||
- glow/emission
|
||||
|
||||
This limitation is intentional and part of the PROMETEU identity.
|
||||
|
||||
---
|
||||
|
||||
### 18.10. 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`
|
||||
|
||||
This allows:
|
||||
|
||||
- analyzing artistic cost
|
||||
- teaching the impact of excessive variety
|
||||
- suggesting best practices for visual cohesion
|
||||
|
||||
---
|
||||
|
||||
## 19. Summary
|
||||
|
||||
PROMETEU's GFX is simple **by choice**, not by limitation.
|
||||
|
||||
- RGB565 Framebuffer with double buffer
|
||||
- Color key for transparency
|
||||
- SNES-style discrete blending
|
||||
- Up to 16 tile banks
|
||||
- 4 Tile Layers + 1 HUD
|
||||
- Layer = tilemap + cache + scroll
|
||||
- Rasterized projection per frame
|
||||
- Depth defined by drawing order
|
||||
|
||||
< [Back](chapter-3.md) | [Summary](table-of-contents.md) | [Next](chapter-5.md) >
|
||||
@@ -0,0 +1,331 @@
|
||||
< [Back](chapter-4.md) | [Summary](table-of-contents.md) | [Next](chapter-6.md) >
|
||||
|
||||
# 🔊 AUDIO Peripheral (Audio System)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The **AUDIO Peripheral** is responsible for **sound generation and mixing** in PROMETEU.
|
||||
|
||||
Just like the other subsystems:
|
||||
|
||||
- it is not automatic
|
||||
- it is not free
|
||||
- it is not magic
|
||||
|
||||
Each sound is the result of **explicit commands**, executed under a **time and resource budget**.
|
||||
|
||||
> Sound consumes time.
|
||||
> Sound consumes memory.
|
||||
|
||||
---
|
||||
|
||||
## 2. Philosophy
|
||||
|
||||
PROMETEU treats audio as:
|
||||
|
||||
- an **active peripheral**
|
||||
- with **limited channels**
|
||||
- **deterministic** behavior
|
||||
- **explicit** control
|
||||
|
||||
Objective: architectural and didactic clarity, not absolute realism.
|
||||
|
||||
---
|
||||
|
||||
## 3. General Architecture
|
||||
|
||||
The audio system is composed of:
|
||||
|
||||
- **Voices (channels)** — independent players
|
||||
- **Samples** — PCM data
|
||||
- **Mixer** — summation of voices
|
||||
- **Output** — PCM stereo buffer
|
||||
|
||||
Conceptual separation:
|
||||
|
||||
- Game sends **commands at 60Hz**
|
||||
- Audio is **generated continuously** at 48kHz
|
||||
|
||||
---
|
||||
|
||||
## 4. Output Format
|
||||
|
||||
- Sample rate: **48,000 Hz**
|
||||
- Format: **PCM16 stereo (signed i16)**
|
||||
- Clipping: saturation/clamp
|
||||
|
||||
This format is compatible with:
|
||||
|
||||
- common I2S DACs
|
||||
- HDMI audio
|
||||
- USB audio
|
||||
- DIY SBCs (Raspberry Pi, Orange Pi, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 5. Voices (Channels)
|
||||
|
||||
### 5.1 Quantity
|
||||
|
||||
```
|
||||
MAX_VOICES = 16
|
||||
```
|
||||
|
||||
Each voice:
|
||||
|
||||
- plays **1 sample at a time**
|
||||
- is independent
|
||||
- is mixed into the final output
|
||||
|
||||
---
|
||||
|
||||
### 5.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)
|
||||
|
||||
---
|
||||
|
||||
### 5.3 Voice Conflict
|
||||
|
||||
If all voices are occupied:
|
||||
|
||||
- an explicit policy is applied:
|
||||
- `STEAL_OLDEST`
|
||||
- `STEAL_QUIETEST`
|
||||
- `STEAL_LOWEST_PRIORITY`
|
||||
|
||||
|
||||
PROMETEU does not resolve this automatically without a defined rule.
|
||||
|
||||
---
|
||||
|
||||
## 6. Conceptual Model: “Audio CPU”
|
||||
|
||||
The PROMETEU AUDIO is conceived as an **independent peripheral**, just as classic consoles had:
|
||||
|
||||
- Main game CPU
|
||||
- Dedicated sound CPU
|
||||
|
||||
In PROMETEU:
|
||||
|
||||
- The **logical core** assumes this conceptual separation
|
||||
- The **host decides** how to implement it:
|
||||
- same thread
|
||||
- separate thread
|
||||
- separate core
|
||||
|
||||
### 6.1 Hardware Metaphor
|
||||
|
||||
Conceptually:
|
||||
|
||||
```
|
||||
[Game CPU] → sends 60Hz commands → [AUDIO Peripheral]
|
||||
|
|
||||
v
|
||||
Voices + Mixer
|
||||
|
|
||||
v
|
||||
PCM Output
|
||||
```
|
||||
|
||||
|
||||
### 6.2 Implementation is the Host's Role
|
||||
|
||||
The core:
|
||||
|
||||
- defines the **model**
|
||||
- defines the **commands**
|
||||
- defines the **limits**
|
||||
|
||||
The host:
|
||||
|
||||
- chooses:
|
||||
- threads
|
||||
- CPU affinity
|
||||
- audio backend
|
||||
- guarantees continuous delivery of buffers
|
||||
|
||||
Thus:
|
||||
|
||||
> PROMETEU models the hardware.
|
||||
> The host decides how to physically realize it.
|
||||
|
||||
---
|
||||
|
||||
## 7. Samples
|
||||
|
||||
### 7.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)
|
||||
|
||||
---
|
||||
|
||||
### 7.2 Usage
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
audio.play(sample_id, voice_id, volume, pan, pitch, priority)
|
||||
```
|
||||
|
||||
Or:
|
||||
|
||||
```
|
||||
audio.playAuto(sample_id, volume, pan, pitch, priority)
|
||||
```
|
||||
|
||||
(uses stealing policy)
|
||||
|
||||
---
|
||||
|
||||
## 8. 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
|
||||
|
||||
---
|
||||
|
||||
## 9. 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
|
||||
|
||||
---
|
||||
|
||||
## 10. 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.
|
||||
|
||||
---
|
||||
|
||||
## 11. Basic Commands
|
||||
|
||||
Conceptual examples:
|
||||
|
||||
```
|
||||
audio.play(sample, voice, volume, pan, pitch, priority)
|
||||
audio.stop(voice)
|
||||
audio.setVolume(voice, v)
|
||||
audio.setPan(voice, p)
|
||||
audio.setPitch(voice, p)
|
||||
audio.isPlaying(voice)
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 12. 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
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 13. Best Practices
|
||||
|
||||
Recommended:
|
||||
|
||||
- reuse samples
|
||||
- limit simultaneous voices
|
||||
- treat sound as an event
|
||||
- separate music and effects
|
||||
|
||||
Avoid:
|
||||
|
||||
- playing sound every frame
|
||||
- abusing voices
|
||||
- giant samples for simple effects
|
||||
|
||||
---
|
||||
|
||||
## 14. Historical Inspiration
|
||||
|
||||
The PROMETEU model is inspired by:
|
||||
|
||||
- NES: fixed channels
|
||||
- SNES: sample playback + mixing
|
||||
- CPS2: comfortable polyphony
|
||||
- Neo Geo: heavy samples (not fully copied)
|
||||
|
||||
But abstracted for:
|
||||
|
||||
- clarity
|
||||
- simplicity
|
||||
- teaching
|
||||
|
||||
---
|
||||
|
||||
## 15. Summary
|
||||
|
||||
- Output: stereo PCM16 @ 48kHz
|
||||
- 16 voices
|
||||
- mono PCM16 samples
|
||||
- Volume, pan, pitch
|
||||
- Linear interpolation
|
||||
- Explicit mixer
|
||||
- "Audio CPU" concept
|
||||
- Implementation is the host's role
|
||||
|
||||
< [Back](chapter-4.md) | [Summary](table-of-contents.md) | [Next](chapter-6.md) >
|
||||
@@ -0,0 +1,260 @@
|
||||
< [Back](chapter-5.md) | [Summary](table-of-contents.md) | [Next](chapter-7.md) >
|
||||
|
||||
# 🎮 **INPUT Peripheral (Input System)**
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The **INPUT Peripheral** is responsible for **collecting and providing the state of controls** to the PROMETEU program.
|
||||
|
||||
In PROMETEU:
|
||||
|
||||
- input is **state**, not an implicit event
|
||||
- input is **sampled over time**, not delivered asynchronously
|
||||
- input has a **defined order, cost, and moment**
|
||||
|
||||
> Buttons do not “trigger events”.
|
||||
> They change state.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 2. Philosophy of the Input System
|
||||
|
||||
PROMETEU models input like classic hardware:
|
||||
|
||||
- the state of controls is read **once per frame**
|
||||
- the program queries this state during `UPDATE`
|
||||
- there are no asynchronous input callbacks
|
||||
|
||||
This model:
|
||||
|
||||
- is deterministic
|
||||
- is simple to understand
|
||||
- reflects microcontrollers and classic consoles
|
||||
|
||||
---
|
||||
|
||||
## 3. Input Devices
|
||||
|
||||
PROMETEU abstracts different devices into a common interface.
|
||||
|
||||
Typical devices:
|
||||
|
||||
- digital control (D-Pad + botões)
|
||||
- keyboard (mapped to buttons)
|
||||
- gamepad
|
||||
- touch (mobile, mapped)
|
||||
|
||||
Regardless of the origin, PROMETEU exposes **the same logical model**.
|
||||
|
||||
---
|
||||
|
||||
## 4. State Model
|
||||
|
||||
### 4.1 Per-Frame State
|
||||
|
||||
For each frame, the system maintains:
|
||||
|
||||
- current state of buttons
|
||||
- state from the previous frame
|
||||
|
||||
This allows querying:
|
||||
|
||||
- button pressed
|
||||
- button released
|
||||
- button held down
|
||||
|
||||
---
|
||||
|
||||
### 4.2 Query Types
|
||||
|
||||
Typical operations:
|
||||
|
||||
```
|
||||
input.btn(id)// button is pressed
|
||||
input.btnp(id)// button was pressed this frame
|
||||
input.btnr(id)// button was released this frame
|
||||
```
|
||||
|
||||
These functions:
|
||||
|
||||
- are purely advisory
|
||||
- do not change state
|
||||
- have an explicit cost
|
||||
|
||||
---
|
||||
|
||||
## 5. Sampling Moment
|
||||
|
||||
The input state is captured **at the beginning of each frame**, before the `UPDATE` phase.
|
||||
|
||||
Conceptual flow:
|
||||
|
||||
```
|
||||
FRAME N:
|
||||
SAMPLEINPUT
|
||||
UPDATE
|
||||
DRAW
|
||||
AUDIO
|
||||
SYNC
|
||||
```
|
||||
|
||||
Throughout the entire frame:
|
||||
|
||||
- the input state is immutable
|
||||
- repeated calls return the same value
|
||||
|
||||
> Input does not change in the middle of the frame.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 6. Determinism and Reproducibility
|
||||
|
||||
The PROMETEU input model guarantees:
|
||||
|
||||
- same sequence of inputs
|
||||
- same frames
|
||||
- same results
|
||||
|
||||
This allows:
|
||||
|
||||
- execution playback
|
||||
- deterministic replays
|
||||
- reliable certification
|
||||
|
||||
Input can be:
|
||||
|
||||
- recorded
|
||||
- played back
|
||||
- artificially injected
|
||||
|
||||
---
|
||||
|
||||
## 7. Input and CAP
|
||||
|
||||
Input operations:
|
||||
|
||||
- consume few cycles
|
||||
- participate in the per-frame budget
|
||||
- appear in certification reports
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Frame 18231:
|
||||
input.btn():12cycles
|
||||
```
|
||||
|
||||
Although cheap, input **is not free**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Button Mapping
|
||||
|
||||
### 8.1 Logical Identifiers
|
||||
|
||||
PROMETEU defines logical button identifiers:
|
||||
|
||||
- `UP`, `DOWN`, `LEFT`, `RIGHT`
|
||||
- `A`, `B`, `X`, `Y`
|
||||
- `START`, `SELECT`
|
||||
|
||||
The physical mapping:
|
||||
|
||||
- depends on the platform
|
||||
- is resolved outside the VM
|
||||
- is transparent to the program
|
||||
|
||||
---
|
||||
|
||||
### 8.2 Portability
|
||||
|
||||
The same PROMETEU cartridge:
|
||||
|
||||
- runs on a keyboard
|
||||
- runs on a gamepad
|
||||
- runs on touch
|
||||
|
||||
Without any code changes.
|
||||
|
||||
---
|
||||
|
||||
## 9. Analog Input (Optional)
|
||||
|
||||
PROMETEU can expose analog axes explicitly:
|
||||
|
||||
```
|
||||
input.axis(id)
|
||||
```
|
||||
|
||||
Characteristics:
|
||||
|
||||
- normalized value (e.g.: -1.0 to 1.0)
|
||||
- explicit cost
|
||||
- per-frame update
|
||||
|
||||
Analog input:
|
||||
|
||||
- is not mandatory
|
||||
- does not replace digital input
|
||||
- must be used consciously
|
||||
|
||||
---
|
||||
|
||||
## 10. Input Best Practices
|
||||
|
||||
PROMETEU encourages:
|
||||
|
||||
- treating input as state
|
||||
- querying input only in `UPDATE`
|
||||
- separating input from heavy logic
|
||||
- mapping actions, not keys
|
||||
|
||||
And discourages:
|
||||
|
||||
- logic dependent on excessive polling
|
||||
- reading input in DRAW
|
||||
- direct coupling to physical hardware
|
||||
|
||||
---
|
||||
|
||||
## 11. Relationship with Classic Consoles
|
||||
|
||||
The PROMETEU model reflects:
|
||||
|
||||
- reading input registers
|
||||
- per-frame polling
|
||||
- absence of asynchronous events
|
||||
|
||||
This model:
|
||||
|
||||
- simplifies reasoning
|
||||
- increases predictability
|
||||
- facilitates debugging
|
||||
|
||||
---
|
||||
|
||||
## 12. Pedagogical Implications
|
||||
|
||||
The INPUT Peripheral allows teaching:
|
||||
|
||||
- the difference between event and state
|
||||
- temporal sampling
|
||||
- determinism in interactive systems
|
||||
- synchronization between input and logic
|
||||
|
||||
With clear and reproducible feedback.
|
||||
|
||||
---
|
||||
|
||||
## 13. Summary
|
||||
|
||||
- input is state, not an event
|
||||
- sampled once per frame
|
||||
- immutable during the frame
|
||||
- queries have an explicit cost
|
||||
- input participates in the CAP
|
||||
- model is deterministic
|
||||
|
||||
< [Back](chapter-5.md) | [Summary](table-of-contents.md) | [Next](chapter-7.md) >
|
||||
@@ -0,0 +1,262 @@
|
||||
< [Back](chapter-6.md) | [Summary](table-of-contents.md) | [Next](chapter-8.md) >
|
||||
|
||||
# 🖐️ TOUCH Peripheral (Absolute Pointer Input System)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The **TOUCH** peripheral provides PROMETEU with an **absolute pointer**, based on screen coordinates, intended for:
|
||||
|
||||
- UI interaction
|
||||
- direct element selection
|
||||
- contextual actions in the scenery
|
||||
- drag-based mechanics (drag, slash, trail)
|
||||
|
||||
The TOUCH is a **first-class peripheral**, as valid as D-Pad and buttons.
|
||||
|
||||
---
|
||||
|
||||
## 2. Design Principles
|
||||
|
||||
TOUCH in PROMETEU follows strict principles:
|
||||
|
||||
- ✅ **Universal single-touch**
|
||||
- ✅ **Deterministic**
|
||||
- ✅ **Per-frame state**
|
||||
- ✅ **No gestures**
|
||||
- ✅ **No acceleration**
|
||||
- ✅ **No heuristics**
|
||||
- ✅ **Same behavior on all platforms**
|
||||
|
||||
> If a behavior cannot be guaranteed on all platforms, it does not exist in PROMETEU.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 3. Conceptual Model
|
||||
|
||||
PROMETEU exposes **only one active pointer at a time**, regardless of how many physical touches the hardware recognizes.
|
||||
|
||||
- Hardware may detect multitouch
|
||||
- Runtime selects **only one active touch**
|
||||
- The API **never exposes multitouch**
|
||||
|
||||
This model guarantees:
|
||||
|
||||
- total portability
|
||||
- predictability
|
||||
- absence of ambiguities
|
||||
|
||||
---
|
||||
|
||||
## 4. 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 exact position of contact, without dynamic transformation.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 5. TOUCH Peripheral API
|
||||
|
||||
### 5.1 Exposed Structure
|
||||
|
||||
```
|
||||
TOUCH:
|
||||
present : bool
|
||||
down : bool
|
||||
pressed : bool
|
||||
released : bool
|
||||
x : int
|
||||
y : int
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.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`
|
||||
|
||||
---
|
||||
|
||||
## 6. Pointer Selection Policy
|
||||
|
||||
### *Single Pointer Capture Policy*
|
||||
|
||||
When multiple physical touches occur, PROMETEU applies the following policy:
|
||||
|
||||
---
|
||||
|
||||
### 6.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`
|
||||
|
||||
---
|
||||
|
||||
### 6.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
|
||||
|
||||
---
|
||||
|
||||
### 6.3 Release
|
||||
|
||||
When the active pointer is released:
|
||||
|
||||
- `released = true`
|
||||
- `down = false`
|
||||
- The system enters a **no active pointer** state
|
||||
|
||||
---
|
||||
|
||||
### 6.4 Recapture (Important Rule)
|
||||
|
||||
After release:
|
||||
|
||||
- Touches that **were already present** are ignored
|
||||
- A new pointer is only captured with a **new touch event**
|
||||
|
||||
> This avoids unexpected pointer jumps and accidental actions.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 7. Deliberately NOT Supported 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
|
||||
|
||||
---
|
||||
|
||||
## 8. “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.
|
||||
|
||||
---
|
||||
|
||||
## 9. “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.
|
||||
|
||||
---
|
||||
|
||||
## 10. Integration with Other Input Forms
|
||||
|
||||
- Desktop:
|
||||
- mouse can emulate TOUCH
|
||||
- Mobile:
|
||||
- direct physical touch
|
||||
- Steam Deck:
|
||||
- physical touchscreen
|
||||
- PROMETEU Hardware:
|
||||
- optional touch, but supported
|
||||
|
||||
From PROMETEU's point of view:
|
||||
|
||||
> TOUCH is always TOUCH.
|
||||
>
|
||||
|
||||
---
|
||||
|
||||
## 11. Expected Uses
|
||||
|
||||
The TOUCH peripheral is suitable for:
|
||||
|
||||
- UI (menus, inventory, maps)
|
||||
- drag-and-drop
|
||||
- direct selection
|
||||
- “click to investigate”
|
||||
- pointing-based puzzles
|
||||
- trail mechanics (e.g.: Fruit Ninja-like)
|
||||
|
||||
---
|
||||
|
||||
## 12. 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
|
||||
|
||||
---
|
||||
|
||||
## 13. Summary
|
||||
|
||||
The TOUCH in PROMETEU is:
|
||||
|
||||
- simple
|
||||
- explicit
|
||||
- predictable
|
||||
- universal
|
||||
- deterministic
|
||||
|
||||
< [Back](chapter-6.md) | [Summary](table-of-contents.md) | [Next](chapter-8.md) >
|
||||
@@ -0,0 +1,238 @@
|
||||
< [Back](chapter-7.md) | [Summary](table-of-contents.md) | [Next](chapter-9.md) >
|
||||
|
||||
# 📀 MEMCARD Peripheral (Save/Load System)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The **MEMCARD** is the peripheral responsible for the **explicit persistence of game data** in PROMETEU.
|
||||
|
||||
It simulates the behavior of classic *memory cards* (PS1, GameCube), providing:
|
||||
|
||||
- limited storage
|
||||
- explicit I/O cost
|
||||
- full game control over when to save
|
||||
- portability across platforms
|
||||
|
||||
The MEMCARD **is not a save state**.
|
||||
|
||||
It represents **data that the game itself decides to persist**.
|
||||
|
||||
---
|
||||
|
||||
## 2. Design Principles
|
||||
|
||||
The MEMCARD peripheral follows these principles:
|
||||
|
||||
- ✅ **Explicit persistence** (nothing automatic)
|
||||
- ✅ **Limited and known size**
|
||||
- ✅ **Mandatory commit**
|
||||
- ✅ **Measurable time cost (cycles)**
|
||||
- ✅ **Stable and documented format**
|
||||
- ✅ **Platform independent**
|
||||
- ❌ No complex file system (in v0.1)
|
||||
- ❌ No multiple internal files (in v0.1)
|
||||
|
||||
---
|
||||
|
||||
## 3. Conceptual Model
|
||||
|
||||
Each PROMETEU cartridge can access **one or more MEMCARD slots**, the default model being:
|
||||
|
||||
- **Slot A** — main
|
||||
- **Slot B** — optional (future)
|
||||
|
||||
Each slot corresponds to **a file on the host**:
|
||||
|
||||
```
|
||||
MyGame_A.mem
|
||||
MyGame_B.mem
|
||||
```
|
||||
|
||||
The runtime mounts this file as a **persistent storage device**.
|
||||
|
||||
---
|
||||
|
||||
## 4. Capacity and CAP
|
||||
|
||||
The size of the MEMCARD is **fixed**, defined by the execution profile (CAP).
|
||||
|
||||
### Suggested sizes
|
||||
|
||||
| Profile | Size |
|
||||
| --- | --- |
|
||||
| JAM | 8 KB |
|
||||
| STANDARD | 32 KB |
|
||||
| ADVANCED | 128 KB |
|
||||
|
||||
The game **cannot exceed** this size.
|
||||
|
||||
Attempts to write above the limit result in an error.
|
||||
|
||||
---
|
||||
|
||||
## 5. Peripheral API (v0.1)
|
||||
|
||||
### 5.1 Logical Interface
|
||||
|
||||
The MEMCARD exposes a **simple single-blob API**:
|
||||
|
||||
```
|
||||
mem.read_all() -> byte[]
|
||||
mem.write_all(byte[])
|
||||
mem.commit()
|
||||
mem.clear()
|
||||
mem.size() -> int
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5.2 Operation Semantics
|
||||
|
||||
### `read_all()`
|
||||
|
||||
- Returns all persisted content
|
||||
- If the card is empty, returns a zeroed buffer
|
||||
- Cycle cost proportional to size
|
||||
|
||||
---
|
||||
|
||||
### `write_all(bytes)`
|
||||
|
||||
- Writes the buffer **to temporary memory**
|
||||
- Does not persist immediately
|
||||
- Fails if `bytes.length > mem.size()`
|
||||
|
||||
---
|
||||
|
||||
### `commit()`
|
||||
|
||||
- Persists data to the device
|
||||
- **Mandatory** operation
|
||||
- Simulates hardware flush
|
||||
- May fail (e.g., I/O, simulated corruption)
|
||||
|
||||
---
|
||||
|
||||
### `clear()`
|
||||
|
||||
- Zeroes the card content
|
||||
- Requires `commit()` to persist
|
||||
|
||||
---
|
||||
|
||||
### `size()`
|
||||
|
||||
- Returns total card capacity in bytes
|
||||
|
||||
---
|
||||
|
||||
## 6. Explicit Commit (Fundamental Rule)
|
||||
|
||||
PROMETEU **does not save automatically**.
|
||||
|
||||
Without `commit()`:
|
||||
|
||||
- data remains volatile
|
||||
- can be lost upon exiting the game
|
||||
- simulates abrupt hardware shutdown
|
||||
|
||||
👉 This teaches:
|
||||
|
||||
- data flushing
|
||||
- atomicity
|
||||
- risk of corruption
|
||||
- real cost of persistence
|
||||
|
||||
---
|
||||
|
||||
## 7. Execution Cost (Cycles)
|
||||
|
||||
All MEMCARD operations have an explicit cost.
|
||||
|
||||
### Example (illustrative values)
|
||||
|
||||
| Operation | Cost |
|
||||
| --- | --- |
|
||||
| read_all | 1 cycle / 256 bytes |
|
||||
| write_all | 1 cycle / 256 bytes |
|
||||
| commit | fixed + proportional cost |
|
||||
|
||||
These costs appear:
|
||||
|
||||
- in the profiler
|
||||
- in the frame timeline
|
||||
- in the CAP report
|
||||
|
||||
---
|
||||
|
||||
## 8. `.mem` File Format
|
||||
|
||||
The MEMCARD file has a simple and robust format.
|
||||
|
||||
### 8.1 Header
|
||||
|
||||
| Field | Size |
|
||||
| --- | --- |
|
||||
| Magic (`PMEM`) | 4 bytes |
|
||||
| Version | 1 byte |
|
||||
| Cart ID | 8 bytes |
|
||||
| Payload Size | 4 bytes |
|
||||
| CRC32 | 4 bytes |
|
||||
|
||||
---
|
||||
|
||||
### 8.2 Payload
|
||||
|
||||
- Binary buffer defined by the game
|
||||
- Fixed size
|
||||
- Content interpreted only by the game
|
||||
|
||||
---
|
||||
|
||||
## 9. Integrity and Security
|
||||
|
||||
- CRC validates corruption
|
||||
- Cart ID prevents using wrong save
|
||||
- Version allows future format evolution
|
||||
- Runtime can:
|
||||
- warn of corruption
|
||||
- allow card reset
|
||||
|
||||
---
|
||||
|
||||
## 10. Integration with the Editor / GUI
|
||||
|
||||
The main tool can provide a **Memory Card Manager**:
|
||||
|
||||
- create/reset card
|
||||
- see size and usage
|
||||
- import/export `.mem`
|
||||
- visualize last commits
|
||||
- associate cards with projects
|
||||
|
||||
None of these operations change the runtime.
|
||||
|
||||
---
|
||||
|
||||
## 11. Planned Evolutions (outside v0.1)
|
||||
|
||||
- Block API (`read_block`, `write_block`)
|
||||
- multiple internal slots
|
||||
- wear simulation
|
||||
- save versioning
|
||||
- optional encryption (educational)
|
||||
|
||||
---
|
||||
|
||||
## 12. Summary
|
||||
|
||||
The MEMCARD peripheral in PROMETEU:
|
||||
|
||||
- simulates real hardware
|
||||
- forces design decisions
|
||||
- teaches persistence correctly
|
||||
- is simple to use
|
||||
- is hard to abuse
|
||||
- grows without breaking compatibility
|
||||
|
||||
< [Back](chapter-7.md) | [Summary](table-of-contents.md) | [Next](chapter-9.md) >
|
||||
@@ -0,0 +1,308 @@
|
||||
< [Back](chapter-8.md) | [Summary](table-of-contents.md) | [Next](chapter-10.md) >
|
||||
|
||||
# ⚡ **Events and Scheduling**
|
||||
|
||||
This chapter defines how the Prometeu Virtual Machine (PVM) handles events, frame synchronization, and cooperative concurrency. It replaces the older interrupt-oriented terminology with a simpler and more accurate model based on **frame boundaries**, **event queues**, and **coroutines**.
|
||||
|
||||
The goal is to preserve determinism while still allowing responsive and structured game logic.
|
||||
|
||||
---
|
||||
|
||||
## 1 Core Philosophy
|
||||
|
||||
Prometeu does **not use asynchronous callbacks** or preemptive interrupts for user code.
|
||||
|
||||
All external signals are:
|
||||
|
||||
* queued by the firmware
|
||||
* delivered at deterministic points
|
||||
* processed inside the main execution loop
|
||||
|
||||
Nothing executes “out of time”.
|
||||
Nothing interrupts the program in the middle of an instruction.
|
||||
Nothing occurs without a known cost.
|
||||
|
||||
This guarantees:
|
||||
|
||||
* deterministic behavior
|
||||
* reproducible runs
|
||||
* stable frame timing
|
||||
|
||||
---
|
||||
|
||||
## 2 Events
|
||||
|
||||
### 2.1 Definition
|
||||
|
||||
An **event** is a logical signal generated by the system or by internal runtime mechanisms.
|
||||
|
||||
Events:
|
||||
|
||||
* represent something that has occurred
|
||||
* do not execute code automatically
|
||||
* are processed explicitly during the frame
|
||||
|
||||
Examples:
|
||||
|
||||
* end of frame
|
||||
* timer expiration
|
||||
* asset load completion
|
||||
* system state change
|
||||
* execution error
|
||||
|
||||
---
|
||||
|
||||
### 2.2 Event Queue
|
||||
|
||||
The firmware maintains an **event queue**.
|
||||
|
||||
Properties:
|
||||
|
||||
* events are queued in order
|
||||
* events are processed at frame boundaries
|
||||
* event processing is deterministic
|
||||
|
||||
Events never:
|
||||
|
||||
* execute user code automatically
|
||||
* interrupt instructions
|
||||
* run outside the main loop
|
||||
|
||||
---
|
||||
|
||||
## 3 Frame Boundary (Sync Phase)
|
||||
|
||||
The primary synchronization point in Prometeu is the **frame boundary**, reached by the `FRAME_SYNC` instruction.
|
||||
|
||||
At this point:
|
||||
|
||||
1. Input state is sampled.
|
||||
2. Events are delivered.
|
||||
3. Coroutine scheduling occurs.
|
||||
4. Optional garbage collection may run.
|
||||
5. Control returns to the firmware.
|
||||
|
||||
This replaces the older notion of a "VBlank interrupt".
|
||||
|
||||
The frame boundary:
|
||||
|
||||
* has a fixed, measurable cost
|
||||
* does not execute arbitrary user code
|
||||
* is fully deterministic
|
||||
|
||||
---
|
||||
|
||||
## 4 System Events vs System Faults
|
||||
|
||||
Prometeu distinguishes between normal events and system faults.
|
||||
|
||||
### 4.1 Normal events
|
||||
|
||||
Examples:
|
||||
|
||||
* timer expired
|
||||
* asset loaded
|
||||
* frame boundary
|
||||
|
||||
These are delivered through the event queue.
|
||||
|
||||
### 4.2 System faults
|
||||
|
||||
Generated by exceptional conditions:
|
||||
|
||||
* invalid instruction
|
||||
* memory violation
|
||||
* handle misuse
|
||||
* verifier failure
|
||||
|
||||
Result:
|
||||
|
||||
* VM execution stops
|
||||
* state is preserved
|
||||
* a diagnostic report is generated
|
||||
|
||||
System faults are not recoverable events.
|
||||
|
||||
---
|
||||
|
||||
## 5 Timers
|
||||
|
||||
Timers are modeled as **frame-based counters**.
|
||||
|
||||
Properties:
|
||||
|
||||
* measured in frames, not real time
|
||||
* deterministic across runs
|
||||
* generate events when they expire
|
||||
|
||||
Timers:
|
||||
|
||||
* do not execute code automatically
|
||||
* produce queryable or queued events
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
if timer.expired(t1) {
|
||||
// handle event
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6 Coroutines and Cooperative Scheduling
|
||||
|
||||
Prometeu provides **coroutines** as the only form of concurrency.
|
||||
|
||||
Coroutines are:
|
||||
|
||||
* cooperative
|
||||
* deterministic
|
||||
* scheduled only at safe points
|
||||
|
||||
There is:
|
||||
|
||||
* no preemption
|
||||
* no parallel execution
|
||||
* no hidden threads
|
||||
|
||||
### 6.1 Coroutine lifecycle
|
||||
|
||||
Each coroutine can be in one of the following states:
|
||||
|
||||
* `Ready`
|
||||
* `Running`
|
||||
* `Sleeping`
|
||||
* `Finished`
|
||||
|
||||
### 6.2 Scheduling
|
||||
|
||||
At each frame boundary:
|
||||
|
||||
1. The scheduler selects the next coroutine.
|
||||
2. Coroutines run in a deterministic order.
|
||||
3. Each coroutine executes within the frame budget.
|
||||
|
||||
The default scheduling policy is:
|
||||
|
||||
* round-robin
|
||||
* deterministic
|
||||
|
||||
---
|
||||
|
||||
### 6.3 Coroutine operations
|
||||
|
||||
Typical coroutine instructions:
|
||||
|
||||
| Operation | Description |
|
||||
| --------- | ----------------------------- |
|
||||
| `spawn` | Create a coroutine |
|
||||
| `yield` | Voluntarily suspend execution |
|
||||
| `sleep` | Suspend for N frames |
|
||||
|
||||
`yield` and `sleep` only take effect at safe points.
|
||||
|
||||
---
|
||||
|
||||
## 7 Relationship Between Events, Coroutines, and the Frame Loop
|
||||
|
||||
The high-level frame structure is:
|
||||
|
||||
```
|
||||
FRAME N
|
||||
------------------------
|
||||
Sample Input
|
||||
Deliver Events
|
||||
Schedule Coroutines
|
||||
Run VM until:
|
||||
- budget exhausted, or
|
||||
- FRAME_SYNC reached
|
||||
Sync Phase
|
||||
------------------------
|
||||
```
|
||||
|
||||
Important properties:
|
||||
|
||||
* events are processed at known points
|
||||
* coroutine scheduling is deterministic
|
||||
* no execution occurs outside the frame loop
|
||||
|
||||
---
|
||||
|
||||
## 8 Costs and Budget
|
||||
|
||||
All event processing and scheduling:
|
||||
|
||||
* consumes cycles
|
||||
* contributes to the CAP (certification and analysis profile)
|
||||
* appears in profiling reports
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
Frame 18231:
|
||||
Event processing: 120 cycles
|
||||
Coroutine scheduling: 40 cycles
|
||||
Frame sync: 80 cycles
|
||||
```
|
||||
|
||||
Nothing is free.
|
||||
|
||||
---
|
||||
|
||||
## 9 Determinism and Reproducibility
|
||||
|
||||
Prometeu guarantees:
|
||||
|
||||
* same sequence of inputs and events → same behavior
|
||||
* frame-based timers
|
||||
* deterministic coroutine scheduling
|
||||
|
||||
This allows:
|
||||
|
||||
* reliable replays
|
||||
* precise debugging
|
||||
* fair certification
|
||||
|
||||
---
|
||||
|
||||
## 10 Best Practices
|
||||
|
||||
Prometeu encourages:
|
||||
|
||||
* treating events as data
|
||||
* querying events explicitly
|
||||
* structuring logic around frame steps
|
||||
* using coroutines for asynchronous flows
|
||||
|
||||
Prometeu discourages:
|
||||
|
||||
* simulating asynchronous callbacks
|
||||
* relying on hidden timing
|
||||
* using events as implicit control flow
|
||||
|
||||
---
|
||||
|
||||
## 11 Conceptual Comparison
|
||||
|
||||
| Traditional System | Prometeu |
|
||||
| ------------------ | ----------------------- |
|
||||
| Hardware interrupt | Frame boundary event |
|
||||
| ISR | System sync phase |
|
||||
| Main loop | VM frame loop |
|
||||
| Timer interrupt | Frame-based timer event |
|
||||
| Threads | Coroutines |
|
||||
|
||||
Prometeu teaches reactive system concepts without the unpredictability of real interrupts.
|
||||
|
||||
---
|
||||
|
||||
## 12 Summary
|
||||
|
||||
* Events inform; they do not execute code.
|
||||
* The frame boundary is the only global synchronization point.
|
||||
* System faults stop execution.
|
||||
* Coroutines provide cooperative concurrency.
|
||||
* All behavior is deterministic and measurable.
|
||||
|
||||
< [Back](chapter-8.md) | [Summary](table-of-contents.md) | [Next](chapter-10.md) >
|
||||
@@ -0,0 +1,21 @@
|
||||
# Table of Contents
|
||||
|
||||
- [Chapter 1: Time Model and Cycles](chapter-1.md)
|
||||
- [Chapter 2: PROMETEU VM Instruction Set](chapter-2.md)
|
||||
- [Chapter 3: Memory: Stack, Heap, and Allocation](chapter-3.md)
|
||||
- [Chapter 4: GFX Peripheral (Graphics System)](chapter-4.md)
|
||||
- [Chapter 5: AUDIO Peripheral (Audio System)](chapter-5.md)
|
||||
- [Chapter 6: INPUT Peripheral (Input System)](chapter-6.md)
|
||||
- [Chapter 7: TOUCH Peripheral (Absolute Pointer Input System)](chapter-7.md)
|
||||
- [Chapter 8: MEMCARD Peripheral (Save/Load System)](chapter-8.md)
|
||||
- [Chapter 9: Events and Interrupts](chapter-9.md)
|
||||
- [Chapter 10: Debug, Inspection, and Profiling](chapter-10.md)
|
||||
- [Chapter 11: Portability Guarantees and Cross-Platform Execution](chapter-11.md)
|
||||
- [Chapter 12: Firmware — PrometeuOS (POS) + PrometeuHub](chapter-12.md)
|
||||
- [Chapter 13: Cartridge](chapter-13.md)
|
||||
- [Chapter 14: Boot Profiles](chapter-14.md)
|
||||
- [Chapter 15: Asset Management](chapter-15.md)
|
||||
- [Chapter 16: Host ABI and Syscalls](chapter-16.md)
|
||||
|
||||
---
|
||||
[Back to README](../README.md)
|
||||
Reference in New Issue
Block a user