# 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.