137 lines
4.1 KiB
Markdown
137 lines
4.1 KiB
Markdown
# Firmware - POS and PrometeuHub
|
|
|
|
Domain: firmware and system orchestration
|
|
Function: normative
|
|
|
|
This chapter defines the firmware layer of the PROMETEU machine.
|
|
|
|
It covers:
|
|
|
|
- machine authority above the VM;
|
|
- POS responsibilities;
|
|
- Hub responsibilities;
|
|
- firmware states and cartridge launch flow.
|
|
|
|
## 1 Firmware Scope
|
|
|
|
The PROMETEU firmware is composed of two cooperating layers:
|
|
|
|
- **PrometeuOS (POS)**: the machine authority responsible for boot, VM/runtime orchestration, peripherals, crash handling, and system-level policy;
|
|
- **PrometeuHub**: the launcher/UI layer that runs over POS and uses the system window model.
|
|
|
|
The VM does not own the machine lifecycle. Firmware does.
|
|
|
|
## 2 Terms
|
|
|
|
- **Host**: the real platform that drives the core loop and presents output.
|
|
- **POS**: system firmware/core authority.
|
|
- **PrometeuHub**: launcher and system UI running over POS.
|
|
- **PVM**: the VM subsystem that executes cartridge bytecode.
|
|
- **Cartridge**: the executable package loaded by firmware.
|
|
- **AppMode**: cartridge mode, currently `Game` or `System`.
|
|
- **Logical frame**: execution unit completed when the app reaches `FRAME_SYNC`.
|
|
- **Host tick**: the host-driven outer update tick.
|
|
|
|
## 3 POS Responsibilities
|
|
|
|
POS is responsible for:
|
|
|
|
- deterministic reset into known machine state;
|
|
- VM initialization and teardown for cartridge execution;
|
|
- input latching and logical-frame budgeting;
|
|
- peripheral reset/orchestration;
|
|
- fault capture and crash-flow transition;
|
|
- return to Hub after app exit or crash.
|
|
|
|
At the VM boundary, POS must preserve:
|
|
|
|
- logical-frame semantics;
|
|
- `FRAME_SYNC` as the canonical frame boundary;
|
|
- deterministic transition from host tick to VM slice execution.
|
|
|
|
## 4 PrometeuHub Responsibilities
|
|
|
|
PrometeuHub is responsible for:
|
|
|
|
- presenting available apps;
|
|
- reading cartridge metadata needed for launch decisions;
|
|
- deciding launch behavior based on `AppMode`;
|
|
- managing the system window surface for system-mode apps.
|
|
|
|
The Hub does not execute bytecode directly. It always delegates execution setup to POS.
|
|
|
|
## 5 App Modes
|
|
|
|
### Game
|
|
|
|
Game-mode cartridges:
|
|
|
|
- transition firmware into the game-running state;
|
|
- run as the active app flow;
|
|
- present through the main frame path.
|
|
|
|
### System
|
|
|
|
System-mode cartridges:
|
|
|
|
- are initialized by POS;
|
|
- are integrated into the Hub/window environment;
|
|
- do not replace the firmware state with the game-running path.
|
|
|
|
## 6 Cartridge Load Flow
|
|
|
|
Current high-level flow:
|
|
|
|
1. POS receives a cartridge to load;
|
|
2. asset manager is initialized from the cartridge asset table, preload list, and packed asset bytes;
|
|
3. POS initializes the VM/runtime for the cartridge;
|
|
4. launch behavior branches by `AppMode`:
|
|
- `Game` -> transition to the game-running firmware state;
|
|
- `System` -> create/focus a Hub window and return to the Hub state.
|
|
|
|
If VM initialization fails, firmware transitions to the crash path.
|
|
|
|
## 7 Firmware States
|
|
|
|
The current firmware state model includes:
|
|
|
|
- `Reset`
|
|
- `SplashScreen`
|
|
- `LaunchHub`
|
|
- `HubHome`
|
|
- `LoadCartridge`
|
|
- `GameRunning`
|
|
- `AppCrashes`
|
|
|
|
These states express machine orchestration above the VM. They are not guest-visible bytecode states.
|
|
|
|
## 8 Execution Contract
|
|
|
|
For game-mode execution, firmware/runtime coordination preserves:
|
|
|
|
- input latched per logical frame;
|
|
- execution in host-driven slices until `FRAME_SYNC`;
|
|
- present only when a logical frame completes;
|
|
- no frame present when budget ends before `FRAME_SYNC`.
|
|
|
|
This keeps the machine model deterministic and observable.
|
|
|
|
## 9 Crash Handling
|
|
|
|
Firmware owns terminal fault presentation.
|
|
|
|
When a terminal app fault occurs:
|
|
|
|
- POS captures the crash report;
|
|
- firmware leaves normal app execution flow;
|
|
- the machine transitions to `AppCrashes`.
|
|
|
|
Crash handling is outside the guest VM execution model.
|
|
|
|
## 10 Relationship to Other Specs
|
|
|
|
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM subsystem run by firmware.
|
|
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the frame-boundary model used by firmware.
|
|
- [`13-cartridge.md`](13-cartridge.md) defines cartridge structure and metadata consumed by firmware.
|
|
- [`14-boot-profiles.md`](14-boot-profiles.md) defines startup target selection.
|