Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/docs/specs/topics/chapter-12.md
Nilton Constantino 0f3105d622
translate to english!
2026-01-19 07:28:14 +00:00

6.7 KiB
Raw Permalink Blame History

< Back | Summary | Next >

🧠 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 | Summary | Next >