diff --git a/docs/topics/chapter-2.md b/docs/topics/chapter-2.md index 1f3c3c09..b12302a9 100644 --- a/docs/topics/chapter-2.md +++ b/docs/topics/chapter-2.md @@ -1,306 +1,405 @@ < [Voltar](chapter-1.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-3.md) > -# ⚙️ **PROMETEU VM Instruction Set** +# ⚙️ ** PVM (PROMETEU VM) — Instruction Set** ## 1. Visão Geral -A **PROMETEU VM** é uma **máquina virtual stack-based**, determinística e orientada a ciclos. +A **PROMETEU VM** é uma máquina virtual: -Seu Instruction Set foi projetado para: +* **stack-based** +* determinística +* orientada a ciclos +* projetada para ensino e inspeção -- ser **facilmente compreendido** -- mapear diretamente conceitos de linguagens de alto nível -- expor claramente custo de execução -- permitir inspeção completa da pilha e da memória +Ela existe para: -> A PROMETEU VM é intencionalmente simples. -Simplicidade é uma característica pedagógica, não uma limitação. -> +* mapear conceitos de linguagens de alto nível +* tornar custo computacional visível +* permitir análise de execução +* servir como base do cartucho PROMETEU + +> A PROMETEU VM é simples por escolha. +> Simplicidade é uma ferramenta pedagógica. --- -## 2. Modelo de Execução da VM +## 2. Modelo de Execução -### 2.1 Componentes principais +### 2.1 Componentes Principais -A PROMETEU VM possui: +A VM possui: -- **Program Counter (PC)** — endereço da próxima instrução -- **Operand Stack** — pilha de valores -- **Call Stack** — pilha de chamadas (frames) -- **Heap** — memória dinâmica -- **Global Space** — variáveis globais -- **Constant Pool** — literais e referências +* **PC (Program Counter)** — próxima instrução +* **Operand Stack** — pilha de valores +* **Call Stack** — pilha de frames +* **Heap** — memória dinâmica +* **Globals** — variáveis globais +* **Constant Pool** — literais e referências +* **ROM** — bytecode do cartucho +* **RAM** — dados mutáveis --- -### 2.2 Ciclo de execução da VM +### 2.2 Ciclo de Execução -Cada instrução segue o ciclo: +Cada instrução executa: ``` -FETCH → DECODE →EXECUTE → ADVANCE PC - +FETCH → DECODE → EXECUTE → ADVANCE PC ``` -Cada instrução: +Propriedades: -- consome um número fixo de **ciclos** -- tem efeitos observáveis na pilha/memória -- nunca executa trabalho implícito oculto +* toda instrução tem custo fixo em ciclos +* não há trabalho implícito invisível +* execução é totalmente determinística --- -## 3. Tipos Fundamentais da VM +## 3. Tipos Fundamentais -A PROMETEU VM suporta um conjunto **mínimo e explícito** de tipos: +| Tipo | Descrição | +| --------- | ---------------------- | +| `number` | ponto flutuante 64-bit | +| `boolean` | verdadeiro/falso | +| `string` | UTF-8 imutável | +| `null` | ausência de valor | +| `ref` | referência ao heap | -| Tipo | Descrição | -| --- | --- | -| `number` | ponto flutuante (64-bit) | -| `boolean` | verdadeiro / falso | -| `string` | UTF-8 imutável | -| `null` | ausência de valor | -| `ref` | referência para heap | +Não existem: -> Não existem tipos implícitos, coerções mágicas ou overflows silenciosos. -> +* coerções mágicas +* casts implícitos +* overflows silenciosos --- ## 4. Convenções da Pilha -- Operações consomem operandos **do topo da pilha** -- Resultados são empilhados -- A pilha cresce para cima -- Ordem: **último empilhado = primeiro consumido** +* Operações usam o topo da pilha +* Resultado sempre volta para a pilha +* Último empilhado = primeiro consumido Exemplo: ``` -PUSH3 -PUSH4 +PUSH_CONST 3 +PUSH_CONST 4 ADD - ``` -Stack: +Estado: ``` [3] [3, 4] [7] - ``` --- ## 5. Categorias de Instruções -O Instruction Set é organizado por função: - 1. Controle de fluxo 2. Pilha 3. Aritmética e lógica 4. Variáveis 5. Funções 6. Heap e estruturas -7. Interação com periféricos +7. Periféricos (syscalls) 8. Sistema --- -## 6. Instruções da VM (v0.1) +## 6. Instruções — VM Set 1 ### 6.1 Controle de Execução -| Instrução | Ciclos | Descrição | -| --- | --- | --- | -| `NOP` | 1 | Não faz nada | -| `HALT` | 1 | Encerra execução | -| `JMP addr` | 2 | Salta para endereço | -| `JMP_IF_FALSE addr` | 3 | Salta se topo da pilha for falso | +| Instrução | Ciclos | Descrição | +| ------------------- | ------ | ----------------------- | +| `NOP` | 1 | Não faz nada | +| `HALT` | 1 | Encerra execução | +| `JMP addr` | 2 | Salto incondicional | +| `JMP_IF_FALSE addr` | 3 | Salta se topo for falso | --- -### 6.2 Operações de Pilha +### 6.2 Pilha -| Instrução | Ciclos | Descrição | -| --- | --- | --- | -| `PUSH_CONST k` | 2 | Empilha constante | -| `POP` | 1 | Remove topo da pilha | -| `DUP` | 1 | Duplica topo | -| `SWAP` | 1 | Troca dois topos | +| Instrução | Ciclos | Descrição | +| -------------- | ------ | ----------------- | +| `PUSH_CONST k` | 2 | Empilha constante | +| `POP` | 1 | Remove topo | +| `DUP` | 1 | Duplica topo | +| `SWAP` | 1 | Troca dois topos | --- ### 6.3 Aritmética -| Instrução | Ciclos | Descrição | -| --- | --- | --- | -| `ADD` | 2 | Soma | -| `SUB` | 2 | Subtração | -| `MUL` | 4 | Multiplicação | -| `DIV` | 6 | Divisão | - -> Custos refletem complexidade relativa, não tempo real. -> +| Instrução | Ciclos | +| --------- | ------ | +| `ADD` | 2 | +| `SUB` | 2 | +| `MUL` | 4 | +| `DIV` | 6 | --- -### 6.4 Comparações e Lógica +### 6.4 Comparação e Lógica | Instrução | Ciclos | -| --- | --- | -| `EQ` | 2 | -| `NEQ` | 2 | -| `LT` | 2 | -| `GT` | 2 | -| `AND` | 2 | -| `OR` | 2 | -| `NOT` | 1 | +| --------- | ------ | +| `EQ` | 2 | +| `NEQ` | 2 | +| `LT` | 2 | +| `GT` | 2 | +| `AND` | 2 | +| `OR` | 2 | +| `NOT` | 1 | --- -### 6.5 Variáveis e Escopos +### 6.5 Variáveis -| Instrução | Ciclos | Descrição | -| --- | --- | --- | -| `GET_GLOBAL idx` | 3 | Lê global | -| `SET_GLOBAL idx` | 3 | Escreve global | -| `GET_LOCAL idx` | 2 | Lê local | -| `SET_LOCAL idx` | 2 | Escreve local | +| Instrução | Ciclos | Descrição | +| -------------- | ------ | -------------- | +| `GET_GLOBAL i` | 3 | Lê global | +| `SET_GLOBAL i` | 3 | Escreve global | +| `GET_LOCAL i` | 2 | Lê local | +| `SET_LOCAL i` | 2 | Escreve local | --- -### 6.6 Funções e Chamadas +### 6.6 Funções -| Instrução | Ciclos | Descrição | -| --- | --- | --- | -| `CALL addr` | 5 | Chamada de função | -| `RET` | 4 | Retorno | -| `PUSH_FRAME n` | 3 | Cria frame local | -| `POP_FRAME` | 3 | Remove frame | +| Instrução | Ciclos | Descrição | +|----------------| ------ |---------------------------------| +| `CALL addr` | 5 | Chamada | +| `RET` | 4 | Retorno | +| `PUSH_SCOPE n` | 3 | Cria escopo (frame de execução) | +| `POP_SCOPE` | 3 | Remove escopo | --- -### 6.7 Heap e Estruturas +### 6.7 Heap -| Instrução | Ciclos | Descrição | -| --- | --- | --- | -| `ALLOC size` | 10 | Aloca no heap | -| `LOAD_REF off` | 3 | Lê campo | -| `STORE_REF off` | 3 | Escreve campo | +| Instrução | Ciclos | Descrição | +| --------------- | ------ | ------------- | +| `ALLOC size` | 10 | Aloca no heap | +| `LOAD_REF off` | 3 | Lê campo | +| `STORE_REF off` | 3 | Escreve campo | -> Toda alocação tem custo explícito. -> -> -> O heap é finito e monitorado. -> +Heap é: + +* finito +* monitorado +* contabilizado no CAP --- -### 6.8 Periféricos (Chamadas Nativas) +### 6.8 Periféricos (Syscalls) -| Instrução | Ciclos | Descrição | -| --- | --- | --- | -| `CALL_NATIVE id` | variável | Chamada ao sistema | +| Instrução | Ciclos | Descrição | +| ---------------- | -------- | ------------------- | +| `CALL_NATIVE id` | variável | Chamada ao hardware | Exemplos: -- `gfx.sprite` -- `input.btn` -- `audio.play` +* `gfx.clear` +* `gfx.fillRect` +* `gfx.present` +* `input.get` +* `audio.play` -O custo depende do periférico e é **documentado separadamente**. +O custo depende do periférico e entra no CAP. --- ## 7. Erros de Execução -Erros são **explícitos e fatais**, nunca silenciosos: +Erros são: -- stack underflow -- acesso inválido ao heap -- tipo incompatível -- frame inválido +* explícitos +* fatais +* nunca silenciosos -Todos geram: +Tipos: -- mensagem clara -- estado da VM -- stack trace +* stack underflow +* tipo inválido +* heap inválido +* frame inválido + +Geram: + +* mensagem clara +* dump de estado +* stack trace --- -## 8. Determinismo e Garantias +## 8. Determinismo -A PROMETEU VM garante: +Garantias: -- mesma sequência de instruções → mesmo resultado -- mesmos ciclos → mesma certificação -- nenhuma otimização invisível -- nenhuma execução especulativa +* mesma entrada → mesmo resultado +* mesma sequência → mesmos ciclos +* sem execução especulativa +* sem otimizações invisíveis > Se você vê a instrução, você paga por ela. -> --- -## 9. Relação com Linguagens de Alto Nível +## 9. Relação com Linguagens -Java, TypeScript e Lua são: +Java, TypeScript, Lua etc: -- **linguagens-fonte** -- compiladas para este Instruction Set -- nunca executadas diretamente +* são linguagens-fonte +* compiladas para esse bytecode +* nunca executadas diretamente -Diferentes linguagens: - -- geram bytecode diferente -- mas executam na **mesma máquina** +Todas rodam na **mesma VM**. --- -## 10. Exemplo Completo +## 10. Exemplo -### Código fonte (conceitual) +Fonte: ```java -x =3 +4; - +x = 3 + 4; ``` -### Bytecode PROMETEU +Bytecode: ``` -PUSH_CONST3 -PUSH_CONST4 +PUSH_CONST 3 +PUSH_CONST 4 ADD -SET_GLOBAL0 - +SET_GLOBAL 0 ``` -### Custo total +Custo: ``` -2 + 2 + 2 + 3 = 9 cycles - +2 + 2 + 2 + 3 = 9 ciclos ``` --- -## 11. Extensibilidade +## 11. Execução por Tick -O Instruction Set é **versionado**. +A VM não roda infinitamente. -Novas versões podem adicionar: +Ela executa: -- instruções vetoriais -- instruções de DMA -- instruções de streaming -- coprocessadores fictícios +* até consumir o budget do **frame lógico** +* ou até `HALT` + +O budget é definido pelo hardware lógico do PROMETEU (ex.: `CYCLES_PER_FRAME`). + +Exemplo: + +``` +vm.step_budget(10_000) +``` + +Isso alimenta: + +* CAP +* profiling +* certificação + +--- + +## 12. Frame Lógico e `FRAME_SYNC` + +O PROMETEU define **frame lógico** como a unidade mínima de atualização consistente do jogo. + +* **Input é latched por frame lógico** (não muda enquanto o frame lógico não for concluído). +* O **budget de ciclos** é aplicado ao frame lógico. +* Um novo frame lógico só começa quando o frame atual termina. + +### 12.1 Instrução de Sistema: `FRAME_SYNC` + +A instrução `FRAME_SYNC` marca o **fim do frame lógico**. + +| Instrução | Ciclos | Descrição | +| ------------ | ------ | ----------------------------- | +| `FRAME_SYNC` | 1 | Finaliza o frame lógico atual | + +Propriedades: + +* `FRAME_SYNC` é uma **instrução do sistema**. +* Não deve ser exposta como API “manual” ao usuário. +* O tooling/compilador pode **injetar** `FRAME_SYNC` automaticamente ao final do loop principal. + +### 12.2 Semântica (o que acontece quando executa) + +Ao executar `FRAME_SYNC`, o core: + +1. **Finaliza** o frame lógico atual. +2. **Apresenta** o frame (`gfx.present()` ou `gfx.compose_and_present()` conforme o modelo do GFX). +3. **Libera** o latch de input. +4. **Reseta** o budget para o próximo frame lógico. + +### 12.3 Overbudget (quando o frame não termina a tempo) + +Se o budget do frame lógico acabar **antes** da VM alcançar `FRAME_SYNC`: + +* a VM **pausa** (PC e pilhas permanecem no ponto exato) +* **não há present** +* o latch de input é **mantido** +* no próximo tick do host, a VM **continua** de onde parou, ainda no mesmo frame lógico + +Efeito prático: + +* se o código precisa de 2 budgets para alcançar `FRAME_SYNC`, o jogo passa a atualizar a ~30 FPS (frame lógico leva 2 ticks) +* isso é determinístico e reportável no CAP + +--- + +## 13. Boot e Cartucho + +O core: + +* valida cartucho +* carrega ROM e dados +* seta PC inicial +* entra em modo RUN + +O cartucho: + +* contém bytecode +* assets +* metadata +* entry point + +--- + +## 13. Extensibilidade + +O Instruction Set é versionado. + +Futuro: + +* DMA +* streaming +* vetores +* coprocessadores fictícios Nenhuma instrução existente muda de significado. +--- + +## 14. Resumo + +* VM stack-based +* custo explícito +* execução determinística +* integrada ao CAP +* base de todo cartucho PROMETEU + < [Voltar](chapter-1.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-3.md) > \ No newline at end of file