236 lines
6.7 KiB
Markdown
236 lines
6.7 KiB
Markdown
< [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) > |