Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity
prometeu-runtime/docs/specs/topics/chapter-12.md
Nilton Constantino 57d54c8783
add more specs
2026-01-17 10:19:00 +00:00

6.7 KiB
Raw Blame History

< Voltar | Sumário | Adiante >

🧠 Firmware — PrometeuOS (POS) + PrometeuHub

1. Visão Geral

O Firmware do PROMETEU é composto por duas camadas:

  • PrometeuOS (POS): o firmware/base do sistema. É a autoridade máxima do boot, periféricos, execução da PVM e tratamento de falhas.
  • PrometeuHub: o “launcher” e ambiente de UI do sistema, embutido no firmware, executado sobre o POS e usando o PROMETEU Window System.

Todo cartucho é um App.
A diferença é o modo do App (Game ou System), informado no header do cartucho.

2. Termos e Definições

  • Host: plataforma real (desktop, mobile, console DIY, etc.) que chama o core em 60Hz e exibe o framebuffer.
  • POS (PrometeuOS): firmware (core de sistema). Controla boot, PVM, budget, latch de input, periféricos e crash.
  • PrometeuHub: UI do sistema/launcher rodando sobre POS.
  • PVM (PROMETEU Virtual Machine): VM que executa bytecode do App.
  • App / Cartucho: pacote executável PROMETEU (ex.: .pbc).
  • AppMode: modo do App no header do cartucho:
    • GAME: assume tela cheia, UI própria
    • SYSTEM: app integrado ao sistema, deve rodar “em janela” no Hub
  • Frame lógico: unidade de atualização do App, encerrada por FRAME_SYNC.
  • Tick do host: chamada do host (60Hz real).

3. Responsabilidades do POS (PrometeuOS)

O POS deve garantir:

3.1 Boot e Estados de Sistema

  • RESET determinístico (estado conhecido)
  • SPLASH opcional (curto)
  • inicialização do PrometeuHub e do Window System
  • retorno ao Hub após saída/crash de app

3.2 Controle da PVM

  • carregar cartucho na PVM
  • resetar PC/stack/heap ao iniciar app
  • executar budget por frame lógico
  • respeitar FRAME_SYNC como boundary de frame lógico
  • manter input latched por frame lógico

3.3 Controle de Periféricos

  • inicialização e reset de:
    • GFX / buffers
    • AUDIO (canais, fila de comandos)
    • INPUT / TOUCH
  • política de “safe mode” (ignorar Hub/config se solicitado)

3.4 Falhas e Recuperação

  • capturar faults fatais da PVM
  • apresentar POS_CRASH_SCREEN (fora da PVM)
  • permitir:
    • reiniciar app
    • voltar ao Hub
    • reset do sistema

4. Responsabilidades do PrometeuHub

O PrometeuHub deve:

  • listar Apps disponíveis no storage
  • ler metadata do header do cartucho (incluindo AppMode)
  • permitir seleção e launch
  • aplicar tema/UI do sistema via Window System
  • decidir o “comportamento de execução” com base no AppMode

4.1 Decisão por AppMode

Ao selecionar um App:

  • Se AppMode = GAME:
    • o Hub delega ao POS: executar como jogo (tela cheia)
  • Se AppMode = SYSTEM:
    • o Hub delega ao POS: carregar o App
    • e o Hub abre uma janela e roda o App “integrado ao sistema”

Observação: o Hub não executa bytecode diretamente; ele sempre delega ao POS.

5. PROMETEU Window System (UI do Sistema)

O Window System é parte do firmware (POS + Hub) e oferece:

  • tema global (paleta, fontes, sons de UI)
  • sistema de janelas (pelo menos: uma janela ativa + stack de dialogs)
  • roteamento de input:
    • foco, navegação, confirmação/cancelamento
    • touch como “tap” (single pointer)

5.1 Integração de System Apps

System Apps são executados em modo “janela” e devem:

  • respeitar a área de viewport fornecida pela janela
  • cooperar com foco/inputs do Window System
  • aceitar ser suspensos/fechados pelo Hub

O Hub pode oferecer “chrome” de janela:

  • título
  • botão voltar/fechar
  • overlays (toast, dialogs)

6. Header do Cartucho (requisito mínimo para o firmware)

O firmware exige que todo cartucho forneça no header, no mínimo:

  • magic / version
  • app_id (string curta ou hash)
  • title (string)
  • entrypoint (endereço de PC)
  • app_mode: GAME ou SYSTEM
  • (opcional) icon_id / cover_id
  • (opcional) requested_cap / versão da VM

O POS/HUB devem usar app_mode para decidir execução.

7. Estados Oficiais do Boot (Firmware)

7.1 POS_RESET

  • inicializa periféricos
  • prepara PVM
  • carrega config
  • detecta safe mode

Transição: POS_SPLASH ou POS_LAUNCH_HUB

7.2 POS_SPLASH (opcional)

  • exibe logo/versão
  • tempo fixo ou “skip”

Transição: POS_LAUNCH_HUB

7.3 POS_LAUNCH_HUB

  • inicia Window System
  • entra no loop do Hub

Transição: HUB_HOME

7.4 HUB_HOME

  • lista Apps
  • permite seleção:
    • GAME → POS_RUN_GAME(app)
    • SYSTEM → HUB_OPEN_WINDOW(app) (que delega POS_RUN_SYSTEM(app))

7.5 POS_RUN_GAME(app)

  • carrega cartucho na PVM
  • executa frame lógico (budget + FRAME_SYNC)
  • apresenta frames
  • mantém latch por frame lógico

Saídas:

  • APP_EXIT → POS_LAUNCH_HUB
  • APP_FAULT → POS_CRASH_SCREEN

7.6 POS_RUN_SYSTEM(app)

  • carrega cartucho na PVM (ou instância separada, se suportado no futuro)
  • executa sob o ciclo do Hub/Window System
  • apresenta na área da janela (viewport)

Saídas:

  • APP_EXIT → retorna ao Hub
  • APP_FAULT → POS_CRASH_SCREEN (ou crash window + fallback)

7.7 POS_CRASH_SCREEN

  • exibe erro (tipo, PC, stack trace)
  • ações: restart app / hub / reset

Transição: conforme escolha.

8. Modelo de Execução (Budget, Latch e FRAME_SYNC)

O POS é responsável por garantir:

  • Input latched por frame lógico
  • execução em fatias (ticks do host) até o app alcançar FRAME_SYNC
  • apenas em FRAME_SYNC:
    • present() (ou compose+present)
    • avança logical_frame_index
    • libera latch de input
    • reseta budget do próximo frame lógico

Se o budget acabar antes do FRAME_SYNC:

  • não apresenta
  • mantém latch
  • continua a execução no próximo tick do host no mesmo frame lógico

9. Regras de Retorno ao Hub

O firmware deve oferecer um mecanismo de “voltar ao sistema”:

  • atalho de botão (ex.: START+SELECT por X ticks)
  • ou syscall controlada (apenas System Apps)

Ao retornar ao Hub:

  • o POS encerra ou suspende o App atual
  • retorna ao Window System com estado consistente

10. Objetivos Pedagógicos

Este firmware permite ensinar:

  • boot stages e firmware como autoridade
  • separação entre sistema e aplicação
  • execução determinística com budget e frame lógico
  • diferença entre apps (Game vs System)
  • tolerância a falhas e crash handling realista

11. Resumo

  • POS é a camada base e controla PVM, budget, latch, periféricos e crash.
  • PrometeuHub é o launcher/UI embutido do firmware sobre o POS.
  • Todo cartucho é um App; o header define app_mode (GAME/SYSTEM).
  • GAME roda tela cheia; SYSTEM roda integrado ao Hub em janela.
  • FRAME_SYNC é o boundary do frame lógico.

< Voltar | Sumário | Adiante >