< [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) >