add more specs

This commit is contained in:
Nilton Constantino
2026-01-17 10:19:00 +00:00
parent 1b9881b3c0
commit 57d54c8783
17 changed files with 547 additions and 27 deletions
+1 -1
View File
@@ -296,4 +296,4 @@ A avaliação pode considerar:
PROMETEU avalia **processo**, não apenas resultado.
< [Sumário](topics/table-of-contens.md) >
< [Sumário](topics/table-of-contents.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Sumário](../table-of-contens.md) | [Adiante](chapter-2.md) >
< [Sumário](table-of-contents.md) | [Adiante](chapter-2.md) >
# ⏱️ **Modelo de Tempo e Ciclos**
@@ -251,4 +251,4 @@ O modelo de tempo e ciclos permite ensinar:
- trade-offs técnicos
- leitura de perfis reais
< [Sumário](../table-of-contens.md) | [Adiante](chapter-2.md) >
< [Sumário](table-of-contents.md) | [Adiante](chapter-2.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-9.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-11.md) >
< [Voltar](chapter-9.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-11.md) >
# 🛠️ **Debug, Inspeção e Profiling**
@@ -347,4 +347,4 @@ O aluno aprende:
- tempo e memória são visíveis
- certificação é baseada em evidência
< [Voltar](chapter-9.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-11.md) >
< [Voltar](chapter-9.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-11.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-10.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-12.md) >
< [Voltar](chapter-10.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-12.md) >
# 🌍 **Garantias de Portabilidade e Execução Multiplataforma**
@@ -255,4 +255,4 @@ O aluno aprende:
- certificação é universal
- portabilidade é garantida por design
< [Voltar](chapter-10.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-12.md) >
< [Voltar](chapter-10.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-12.md) >
+4 -4
View File
@@ -1,6 +1,6 @@
< [Voltar](chapter-11.md) | [Sumário](table-of-contens.md) >
< [Voltar](chapter-11.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-13.md) >
# 🧠 Firmware Spec — PrometeuOS (POS) + PrometeuHub
# 🧠 Firmware — PrometeuOS (POS) + PrometeuHub
## 1. Visão Geral
@@ -232,5 +232,5 @@ Este firmware permite ensinar:
- 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) >
< [Voltar](chapter-11.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-13.md) >
+110
View File
@@ -0,0 +1,110 @@
< [Voltar](chapter-12.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-14.md) >
# Cartuchos
**Versão:** 1.0 (baseline estável)
**Status:** Proposta
---
## 1. Objetivo
Definir um contrato mínimo e estável para cartuchos Prometeu, permitindo:
* Identificação do app
* Seleção de modo (Game/System)
* Resolução de entrypoint
* Carregamento previsível pelo runtime
---
## 2. Conceito
Um cartucho é a unidade distribuível do Prometeu. Ele pode existir como:
* **Diretório (dev)** — ideal para desenvolvimento e hot-reload
* **Arquivo empacotado (.pmc)** — ideal para distribuição
Ambos compartilham o mesmo layout lógico.
---
## 3. Layout Lógico
```
<cartridge>/
├── manifest.json
├── program.pbc
└── assets/
└── ...
```
Campos obrigatórios:
* `manifest.json`
* `program.pbc` (bytecode Prometeu)
---
## 4. manifest.json (Contrato v1)
```json
{
"magic": "PMTU",
"cartridge_version": 1,
"app_id": 1234,
"title": "Meu Jogo",
"app_version": "1.0.0",
"app_mode": "Game", // Game | System
"entrypoint": "main"
}
```
### Campos
* `magic`: string fixa `PMTU`
* `cartridge_version`: versão do formato
* `app_id`: identificador numérico único
* `title`: nome do app
* `app_version`: versão do app
* `app_mode`: `Game` ou `System`
* `entrypoint`: símbolo ou índice reconhecido pela VM
---
## 5. Regras do Runtime
* Validar `magic` e `cartridge_version`
* Ler `app_mode` para decidir fluxo de execução
* Resolver `entrypoint` no `program.pbc`
* Ignorar `assets/` se não suportado ainda
---
## 6. Modos de Uso
### Diretório (desenvolvimento)
```
prometeu --run ./mycart/
```
### Arquivo empacotado
```
prometeu --run mygame.pmc
```
Ambos devem se comportar de forma idêntica no runtime.
---
## 7. Estabilidade do Contrato
A partir do v1:
* `manifest.json` é a fonte de verdade
* Campos só podem ser adicionados de forma backward-compatible
* Mudanças incompatíveis exigem `cartridge_version` novo
< [Voltar](chapter-12.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-14.md) >
+135
View File
@@ -0,0 +1,135 @@
< [Voltar](chapter-13.md) | [Sumário](table-of-contents.md) >
# Boot Profiles
**Versão:** 1.0
**Status:** Proposta
---
## 1. Objetivo
Definir como o Prometeu decide o que executar ao iniciar:
* Hub
* Cartucho automaticamente
* Modo debug
---
## 2. Conceito de BootTarget
No início do boot, o POS resolve um alvo:
```rust
enum BootTarget {
Hub,
Cartridge { path: String, debug: bool },
}
```
---
## 3. Regras Gerais
### Se BootTarget == Hub
* Firmware entra em `HubHome`
* Nenhum cartucho é carregado automaticamente
### Se BootTarget == Cartridge
1. Carregar cartucho
2. Ler `app_mode` no manifest
3. Aplicar regras:
* `Game`:
* Entrar em `RunningGame`
* `System`:
* Permanecer em `HubHome`
* Abrir o app como janela/system tool
---
## 4. CLI do Host
### Boot padrão
```
prometeu
```
Resultado: entra no Hub
### Executar cartucho
```
prometeu run <cartucho>
```
Resultado:
* Game → entra direto no jogo
* System → abre como tool no Hub
### Executar com debugger
```
prometeu debug <cartucho>
```
Resultado:
* Mesmo fluxo do `run`
* Runtime inicia em modo debug
* Aguarda conexão do Debugger Java
---
## 5. Estados do Firmware
Firmware mantém apenas:
* `Boot`
* `HubHome`
* `RunningGame`
* `AppCrashed`
System apps nunca mudam o estado do firmware.
---
## 6. Comportamento em Hardware Real (futuro)
* Se miniSD/cartucho físico presente no boot:
* POS pode:
* sempre ir ao Hub, ou
* auto-executar conforme configuração do usuário
---
## 7. Integração com Debugger
Quando `debug == true`:
* Runtime:
* Inicializa
* Abre socket DevTools
* Aguarda comando `start`
* Somente após isso inicia execução do cartucho
---
## 8. Estabilidade
* BootTarget é contrato interno do POS
* CLI do host deve respeitar essas regras
* Novos modos de boot devem ser extensões compatíveis
< [Voltar](chapter-13.md) | [Sumário](table-of-contents.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-1.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-3.md) >
< [Voltar](chapter-1.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-3.md) >
# ⚙️ ** PVM (PROMETEU VM) — Instruction Set**
@@ -392,4 +392,4 @@ Nenhuma instrução existente muda de significado.
* integrada ao CAP
* base de todo cartucho PROMETEU
< [Voltar](chapter-1.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-3.md) >
< [Voltar](chapter-1.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-3.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-2.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-4.md) >
< [Voltar](chapter-2.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-4.md) >
# 🧠 **Memória: Stack, Heap e Alocação**
@@ -306,4 +306,4 @@ Tudo com **feedback imediato e visível**.
- GC é visível e mensurável
- memória participa da certificação
< [Voltar](chapter-2.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-4.md) >
< [Voltar](chapter-2.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-4.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-3.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-5.md) >
< [Voltar](chapter-3.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-5.md) >
# 🎨 **Periférico GFX (Sistema Gráfico)**
@@ -597,4 +597,4 @@ O GFX do PROMETEU é simples **por escolha**, não por limitação.
- Projeção rasterizada por frame
- Profundidade definida por ordem de desenho
< [Voltar](chapter-3.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-5.md) >
< [Voltar](chapter-3.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-5.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-4.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-6.md) >
< [Voltar](chapter-4.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-6.md) >
# 🔊 Periférico AUDIO (Sistema de Som)
@@ -328,4 +328,4 @@ Mas abstraído para:
- Conceito de “CPU de áudio”
- Implementação é papel do host
< [Voltar](chapter-4.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-6.md) >
< [Voltar](chapter-4.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-6.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-5.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-7.md) >
< [Voltar](chapter-5.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-7.md) >
# 🎮 **Periférico INPUT (Sistema de Entrada)**
@@ -257,4 +257,4 @@ Com feedback claro e reproduzível.
- input participa do CAP
- modelo é determinístico
< [Voltar](chapter-5.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-7.md) >
< [Voltar](chapter-5.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-7.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-6.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-8.md) >
< [Voltar](chapter-6.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-8.md) >
# 🖐️ Periférico TOUCH (Sistema de Entrada via ponteiro absoluto)
@@ -259,4 +259,4 @@ O TOUCH no PROMETEU é:
- universal
- determinístico
< [Voltar](chapter-6.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-8.md) >
< [Voltar](chapter-6.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-8.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-7.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-9.md) >
< [Voltar](chapter-7.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-9.md) >
# 📀 Periférico MEMCARD (Sistema de save/load)
@@ -235,4 +235,4 @@ O periférico MEMCARD no PROMETEU:
- é difícil de abusar
- cresce sem quebrar compatibilidade
< [Voltar](chapter-7.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-9.md) >
< [Voltar](chapter-7.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-9.md) >
+2 -2
View File
@@ -1,4 +1,4 @@
< [Voltar](chapter-8.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-10.md) >
< [Voltar](chapter-8.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-10.md) >
# ⚡ **Eventos e Interrupções**
@@ -286,4 +286,4 @@ Tudo com **ordem, clareza e mensuração**.
- custos são explícitos
- comportamento é determinístico
< [Voltar](chapter-8.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-10.md) >
< [Voltar](chapter-8.md) | [Sumário](table-of-contents.md) | [Adiante](chapter-10.md) >
@@ -11,6 +11,9 @@
- [Capitulo 9: Eventos e Interrupções](chapter-9.md)
- [Capitulo 10: Debug, Inspeção e Profiling](chapter-10.md)
- [Capitulo 11: Garantias de Portabilidade e Execução Multiplataforma](chapter-11.md)
- [Capitulo 12: Firmware — PrometeuOS (POS) + PrometeuHub](chapter-12.md)
- [Capitulo 13: Cartucho](chapter-13.md)
- [Capitulo 14: Boot Profiles](chapter-14.md)
---
[Voltar para o README](../README.md)