prometeu-runtime/docs/specs/12-firmware-pos-and-prometeuhub.md

Firmware - POS and PrometeuHub

Domain: firmware and system orchestration Function: normative

This chapter defines the firmware layer of the PROMETEU machine.

It covers:

• machine authority above the VM;
• POS responsibilities;
• Hub responsibilities;
• firmware states and cartridge launch flow.

1 Firmware Scope

The PROMETEU firmware is composed of two cooperating layers:

• PrometeuOS (POS): the machine authority responsible for boot, VM/runtime orchestration, peripherals, crash handling, and system-level policy;
• PrometeuHub: the launcher/UI layer that runs over POS and uses the system window model.

The VM does not own the machine lifecycle. Firmware does.

2 Terms

• Host: the real platform that drives the core loop and presents output.
• POS: system firmware/core authority.
• PrometeuHub: launcher and system UI running over POS.
• PVM: the VM subsystem that executes cartridge bytecode.
• Cartridge: the executable package loaded by firmware.
• AppMode: cartridge mode, currently Game or System.
• Logical frame: execution unit completed when the app reaches FRAME_SYNC.
• Host tick: the host-driven outer update tick.

3 POS Responsibilities

POS is responsible for:

• deterministic reset into known machine state;
• VM initialization and teardown for cartridge execution;
• input latching and logical-frame budgeting;
• peripheral reset/orchestration;
• fault capture and crash-flow transition;
• return to Hub after app exit or crash.

At the VM boundary, POS must preserve:

• logical-frame semantics;
• FRAME_SYNC as the canonical frame boundary;
• deterministic transition from host tick to VM slice execution.

4 PrometeuHub Responsibilities

PrometeuHub is responsible for:

• presenting available apps;
• reading cartridge metadata needed for launch decisions;
• deciding launch behavior based on AppMode;
• managing the system window surface for system-mode apps.

The Hub does not execute bytecode directly. It always delegates execution setup to POS.

5 App Modes

Game

Game-mode cartridges:

• transition firmware into the game-running state;
• run as the active app flow;
• present through the main frame path.

System

System-mode cartridges:

• are initialized by POS;
• are integrated into the Hub/window environment;
• do not replace the firmware state with the game-running path.

6 Cartridge Load Flow

Current high-level flow:

1. POS receives a cartridge to load;
2. asset manager is initialized from the cartridge asset table, preload list, and packed asset bytes;
3. POS initializes the VM/runtime for the cartridge;
4. launch behavior branches by AppMode:
   • Game -> transition to the game-running firmware state;
   • System -> create/focus a Hub window and return to the Hub state.

If VM initialization fails, firmware transitions to the crash path.

POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in 13-cartridge.md, currently func_id = 0.

7 Firmware States

The current firmware state model includes:

• Reset
• SplashScreen
• LaunchHub
• HubHome
• LoadCartridge
• GameRunning
• AppCrashes

These states express machine orchestration above the VM. They are not guest-visible bytecode states.

8 Execution Contract

For game-mode execution, firmware/runtime coordination preserves:

• input latched per logical frame;
• execution in host-driven slices until FRAME_SYNC;
• present only when a logical frame completes;
• no frame present when budget ends before FRAME_SYNC.

This keeps the machine model deterministic and observable.

9 Crash Handling

Firmware owns terminal fault presentation.

When a terminal app fault occurs:

• POS captures the crash report;
• firmware leaves normal app execution flow;
• the machine transitions to AppCrashes.

Crash handling is outside the guest VM execution model.

10 Relationship to Other Specs

• 02-vm-instruction-set.md defines the VM subsystem run by firmware.
• 09-events-and-concurrency.md defines the frame-boundary model used by firmware.
• 13-cartridge.md defines cartridge structure and metadata consumed by firmware.
• 14-boot-profiles.md defines startup target selection.