diff --git a/docs/specs/topics/chapter-12.md b/docs/specs/topics/chapter-12.md new file mode 100644 index 00000000..b9b4500d --- /dev/null +++ b/docs/specs/topics/chapter-12.md @@ -0,0 +1,236 @@ +< [Voltar](chapter-11.md) | [Sumário](table-of-contens.md) > + +# 🧠 Firmware Spec — 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](chapter-11.md) | [Sumário](table-of-contens.md) > \ No newline at end of file