add firmware spec
This commit is contained in:
Nilton Constantino
parent
dd841b3e4f
commit
751619fb31
236
docs/specs/topics/chapter-12.md
Normal file
236
docs/specs/topics/chapter-12.md
Normal file
@ -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) >
|
||||
Loading…
x
Reference in New Issue
Block a user