200 lines
6.3 KiB
Markdown
200 lines
6.3 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.
|
|
- **Process**: technical execution owned by POS lifecycle.
|
|
- **Task**: navigable presence associated with an app flow.
|
|
- **Window**: visual presence for a shell/system task when that task is
|
|
represented by the system window model.
|
|
- **WindowOwner**: ownership marker for a system window. The v1 owners are
|
|
`Hub`, `Task(TaskId)`, and `Overlay`.
|
|
- **Shell task window**: a `WindowManager` window whose owner is
|
|
`WindowOwner::Task(TaskId)`.
|
|
|
|
## 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.
|
|
- run as fullscreen firmware sessions;
|
|
- are not `WindowManager` windows.
|
|
|
|
### 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.
|
|
- are represented as shell task windows when they expose a visual shell
|
|
presence.
|
|
|
|
## 6 Task-Owned Shell Windows
|
|
|
|
The shell window contract separates execution, navigation, and visual
|
|
presence:
|
|
|
|
```text
|
|
Process = technical execution
|
|
Task = navigable presence
|
|
Window = visual presence of the task
|
|
```
|
|
|
|
For shell/system apps managed by the window model, the visible shell presence
|
|
must be a `WindowManager` window owned by `WindowOwner::Task(TaskId)`.
|
|
|
|
`Hub` windows are not shell task windows. `Overlay` windows are not shell task
|
|
windows in this v1 contract. Overlay/modal policy, minimization, app switching,
|
|
dock behavior, background services, and complex multi-window semantics are
|
|
future contracts and are not defined here.
|
|
|
|
Game cartridges must not be represented as `WindowManager` windows. They remain
|
|
fullscreen sessions driven by `GameRunningStep`.
|
|
|
|
For v1, `ShellRunningStep` continues a shell task only while both conditions are
|
|
true:
|
|
|
|
```text
|
|
TaskState::Foreground
|
|
+
|
|
focused window owner == WindowOwner::Task(task_id)
|
|
```
|
|
|
|
The runtime query for the focused-window ownership predicate is:
|
|
|
|
```text
|
|
os.windows().focused_window_belongs_to_task(task_id)
|
|
```
|
|
|
|
If a foreground shell task loses its eligible focused window,
|
|
`ShellRunningStep` must close the task through `SystemOS` lifecycle before
|
|
returning to Hub:
|
|
|
|
```text
|
|
Shell task loses its eligible focused window
|
|
-> os.lifecycle().close_task(task_id)
|
|
-> TaskState::Closed
|
|
-> ProcessState::Stopped
|
|
-> FirmwareState::HubHome
|
|
```
|
|
|
|
## 7 Cartridge Load Flow
|
|
|
|
Current high-level flow:
|
|
|
|
1. POS receives a cartridge to load;
|
|
2. asset manager is initialized from the cartridge asset table, preload list, and packed asset bytes;
|
|
3. POS initializes the VM/runtime for the cartridge;
|
|
4. launch behavior branches by `AppMode`:
|
|
- `Game` -> transition to the game-running firmware state;
|
|
- `System` -> create/focus a Hub window and return to the Hub state.
|
|
|
|
If VM initialization fails, firmware transitions to the crash path.
|
|
|
|
POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
|
|
|
|
## 8 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.
|
|
|
|
## 9 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.
|
|
|
|
## 10 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.
|
|
|
|
## 11 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.
|