Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity

update VM specs

Browse Source
This commit is contained in:
Nilton Constantino 2026-01-15 11:27:42 +00:00
parent acd09a6468
commit 415b10bebc
No known key found for this signature in database
1 changed files with 258 additions and 159 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

417
docs/topics/chapter-2.md
View File

@ -1,306 +1,405 @@
< [Voltar](chapter-1.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-3.md) > < [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 ## 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** Ela existe para:
- 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
> A PROMETEU VM é intencionalmente simples. * mapear conceitos de linguagens de alto nível
Simplicidade é uma característica pedagógica, não uma limitação. * 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 * **PC (Program Counter)** — próxima instrução
- **Operand Stack** — pilha de valores * **Operand Stack** — pilha de valores
- **Call Stack** — pilha de chamadas (frames) * **Call Stack** — pilha de frames
- **Heap** — memória dinâmica * **Heap** — memória dinâmica
- **Global Space** — variáveis globais * **Globals** — variáveis globais
- **Constant Pool** — literais e referências * **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** * toda instrução tem custo fixo em ciclos
- tem efeitos observáveis na pilha/memória * não há trabalho implícito invisível
- nunca executa trabalho implícito oculto * 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 | Não existem:
| --- | --- |
| `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 tipos implícitos, coerções mágicas ou overflows silenciosos. * coerções mágicas
> * casts implícitos
* overflows silenciosos
--- ---
## 4. Convenções da Pilha ## 4. Convenções da Pilha
- Operações consomem operandos **do topo da pilha** * Operações usam o topo da pilha
- Resultados são empilhados * Resultado sempre volta para a pilha
- A pilha cresce para cima * Último empilhado = primeiro consumido
- Ordem: **último empilhado = primeiro consumido**
Exemplo: Exemplo:
``` ```
PUSH3 PUSH_CONST 3
PUSH4 PUSH_CONST 4
ADD ADD
``` ```
Stack: Estado:
``` ```
[3] [3]
[3, 4] [3, 4]
[7] [7]
``` ```
--- ---
## 5. Categorias de Instruções ## 5. Categorias de Instruções
O Instruction Set é organizado por função:
1. Controle de fluxo 1. Controle de fluxo
2. Pilha 2. Pilha
3. Aritmética e lógica 3. Aritmética e lógica
4. Variáveis 4. Variáveis
5. Funções 5. Funções
6. Heap e estruturas 6. Heap e estruturas
7. Interação com periféricos 7. Periféricos (syscalls)
8. Sistema 8. Sistema
--- ---
## 6. Instruções da VM (v0.1) ## 6. Instruções — VM Set 1
### 6.1 Controle de Execução ### 6.1 Controle de Execução
| Instrução | Ciclos | Descrição | | Instrução | Ciclos | Descrição |
| --- | --- | --- | | ------------------- | ------ | ----------------------- |
| `NOP` | 1 | Não faz nada | | `NOP` | 1 | Não faz nada |
| `HALT` | 1 | Encerra execução | | `HALT` | 1 | Encerra execução |
| `JMP addr` | 2 | Salta para endereço | | `JMP addr` | 2 | Salto incondicional |
| `JMP_IF_FALSE addr` | 3 | Salta se topo da pilha for falso | | `JMP_IF_FALSE addr` | 3 | Salta se topo for falso |
--- ---
### 6.2 Operações de Pilha ### 6.2 Pilha
| Instrução | Ciclos | Descrição | | Instrução | Ciclos | Descrição |
| --- | --- | --- | | -------------- | ------ | ----------------- |
| `PUSH_CONST k` | 2 | Empilha constante | | `PUSH_CONST k` | 2 | Empilha constante |
| `POP` | 1 | Remove topo da pilha | | `POP` | 1 | Remove topo |
| `DUP` | 1 | Duplica topo | | `DUP` | 1 | Duplica topo |
| `SWAP` | 1 | Troca dois topos | | `SWAP` | 1 | Troca dois topos |
--- ---
### 6.3 Aritmética ### 6.3 Aritmética
| Instrução | Ciclos | Descrição | | Instrução | Ciclos |
| --- | --- | --- | | --------- | ------ |
| `ADD` | 2 | Soma | | `ADD` | 2 |
| `SUB` | 2 | Subtração | | `SUB` | 2 |
| `MUL` | 4 | Multiplicação | | `MUL` | 4 |
| `DIV` | 6 | Divisão | | `DIV` | 6 |
> Custos refletem complexidade relativa, não tempo real.
>
--- ---
### 6.4 Comparações e Lógica ### 6.4 Comparação e Lógica
| Instrução | Ciclos | | Instrução | Ciclos |
| --- | --- | | --------- | ------ |
| `EQ` | 2 | | `EQ` | 2 |
| `NEQ` | 2 | | `NEQ` | 2 |
| `LT` | 2 | | `LT` | 2 |
| `GT` | 2 | | `GT` | 2 |
| `AND` | 2 | | `AND` | 2 |
| `OR` | 2 | | `OR` | 2 |
| `NOT` | 1 | | `NOT` | 1 |
--- ---
### 6.5 Variáveis e Escopos ### 6.5 Variáveis
| Instrução | Ciclos | Descrição | | Instrução | Ciclos | Descrição |
| --- | --- | --- | | -------------- | ------ | -------------- |
| `GET_GLOBAL idx` | 3 | Lê global | | `GET_GLOBAL i` | 3 | Lê global |
| `SET_GLOBAL idx` | 3 | Escreve global | | `SET_GLOBAL i` | 3 | Escreve global |
| `GET_LOCAL idx` | 2 | Lê local | | `GET_LOCAL i` | 2 | Lê local |
| `SET_LOCAL idx` | 2 | Escreve local | | `SET_LOCAL i` | 2 | Escreve local |
--- ---
### 6.6 Funções e Chamadas ### 6.6 Funções
| Instrução | Ciclos | Descrição | | Instrução | Ciclos | Descrição |
| --- | --- | --- | |----------------| ------ |---------------------------------|
| `CALL addr` | 5 | Chamada de função | | `CALL addr` | 5 | Chamada |
| `RET` | 4 | Retorno | | `RET` | 4 | Retorno |
| `PUSH_FRAME n` | 3 | Cria frame local | | `PUSH_SCOPE n` | 3 | Cria escopo (frame de execução) |
| `POP_FRAME` | 3 | Remove frame | | `POP_SCOPE` | 3 | Remove escopo |
--- ---
### 6.7 Heap e Estruturas ### 6.7 Heap
| Instrução | Ciclos | Descrição | | Instrução | Ciclos | Descrição |
| --- | --- | --- | | --------------- | ------ | ------------- |
| `ALLOC size` | 10 | Aloca no heap | | `ALLOC size` | 10 | Aloca no heap |
| `LOAD_REF off` | 3 | Lê campo | | `LOAD_REF off` | 3 | Lê campo |
| `STORE_REF off` | 3 | Escreve campo | | `STORE_REF off` | 3 | Escreve campo |
> Toda alocação tem custo explícito. Heap é:
>
> * finito
> O heap é finito e monitorado. * monitorado
> * contabilizado no CAP
--- ---
### 6.8 Periféricos (Chamadas Nativas) ### 6.8 Periféricos (Syscalls)
| Instrução | Ciclos | Descrição | | Instrução | Ciclos | Descrição |
| --- | --- | --- | | ---------------- | -------- | ------------------- |
| `CALL_NATIVE id` | variável | Chamada ao sistema | | `CALL_NATIVE id` | variável | Chamada ao hardware |
Exemplos: Exemplos:
- `gfx.sprite` * `gfx.clear`
- `input.btn` * `gfx.fillRect`
- `audio.play` * `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 ## 7. Erros de Execução
Erros são **explícitos e fatais**, nunca silenciosos: Erros são:
- stack underflow * explícitos
- acesso inválido ao heap * fatais
- tipo incompatível * nunca silenciosos
- frame inválido
Todos geram: Tipos:
- mensagem clara * stack underflow
- estado da VM * tipo inválido
- stack trace * 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 * mesma entrada → mesmo resultado
- mesmos ciclos → mesma certificação * mesma sequência → mesmos ciclos
- nenhuma otimização invisível * sem execução especulativa
- nenhuma execução especulativa * sem otimizações invisíveis
> Se você vê a instrução, você paga por ela. > 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** * são linguagens-fonte
- compiladas para este Instruction Set * compiladas para esse bytecode
- nunca executadas diretamente * nunca executadas diretamente
Diferentes linguagens: Todas rodam na **mesma VM**.
- geram bytecode diferente
- mas executam na **mesma máquina**
--- ---
## 10. Exemplo Completo ## 10. Exemplo
### Código fonte (conceitual) Fonte:
```java ```java
x =3 +4; x = 3 + 4;
``` ```
### Bytecode PROMETEU Bytecode:
``` ```
PUSH_CONST3 PUSH_CONST 3
PUSH_CONST4 PUSH_CONST 4
ADD 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 * até consumir o budget do **frame lógico**
- instruções de DMA * ou até `HALT`
- instruções de streaming
- coprocessadores fictícios 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. 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) > < [Voltar](chapter-1.md) | [Sumário](table-of-contens.md) | [Adiante](chapter-3.md) >