Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests 1 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) >
# ⚙️ **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) >