115 lines
4.1 KiB
Markdown
115 lines
4.1 KiB
Markdown
# Decision Record - V1 VM-Owned Input Intrinsics and Language-Agnostic Surface
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Contexto
|
|
|
|
Para destravar bytecode/backend no v1, precisamos fechar o caminho de input sem:
|
|
|
|
- quebrar a fronteira host-backed atual (`HOSTCALL`/`SYSCALL`);
|
|
- copiar estruturas grandes de input na stack a cada consulta;
|
|
- acoplar a decisao a uma unica linguagem de frontend.
|
|
|
|
As discussoes das agendas historicas de input (intrinsics surface + frame semantics) e da agenda VM-owned convergiram para:
|
|
|
|
- input deve sair do caminho de syscall legado;
|
|
- input deve ser VM-owned, leitura-only e deterministico por frame;
|
|
- a linguagem pode expor API encadeada ergonomica (ex.: PBS), mas isso nao define o contrato normativo do runtime.
|
|
|
|
## Decisao
|
|
|
|
### 1. Fronteira host-backed permanece inalterada
|
|
|
|
- `HOSTCALL` + tabela `SYSC` + `SYSCALL` continuam como caminho host-backed oficial.
|
|
- Esta decisao nao unifica nem altera o contrato de syscall atual.
|
|
|
|
### 2. Input v1 e VM-owned por intrinsics finais
|
|
|
|
- Input v1 e exposto por intrinsics VM-owned.
|
|
- O backend emite `INTRINSIC <id_final>` diretamente.
|
|
- Nao sera introduzida tabela de pre-load adicional para VM-owned no v1.
|
|
|
|
### 3. Surface de linguagem e livre (nao hardcoded)
|
|
|
|
- O contrato normativo e de VM/bytecode, nao de sintaxe de uma linguagem.
|
|
- Frontends podem expor APIs diferentes, desde que mapeiem 1:1 para intrinsics versionados.
|
|
- Exemplo PBS (nao normativo): `Input.pad().up().hold()`.
|
|
|
|
### 4. Semantica de snapshot por frame
|
|
|
|
- O host captura estado de input no inicio do frame logico.
|
|
- A VM usa esse snapshot congelado durante todo o frame.
|
|
- Leitura repetida no mesmo frame retorna o mesmo valor observavel.
|
|
|
|
### 5. Modelo de dispositivos v1
|
|
|
|
- Elementos obrigatorios de input em todas as plataformas: `button`, `pad`, `touch`.
|
|
- Perfil Prometeu handheld v1: um `pad` e um `touch` single-point.
|
|
- `touch` preserva ultimo valor conhecido (incluindo arraste) conforme snapshot vigente.
|
|
|
|
### 6. Politica de acesso e fault
|
|
|
|
- Input e leitura-only para userland.
|
|
- Nao ha capability gate nem impacto de certificacao para leitura de input.
|
|
- Falhas operacionais devem seguir a taxonomia de fault vigente (`status` quando aplicavel; `Trap` para erro estrutural).
|
|
|
|
### 7. Consequencia de arquitetura imediata
|
|
|
|
- Builtins de input devem ser tratados como referencias/superficies VM-owned, sem copia "mastodonte" por chamada.
|
|
- O executor de intrinsic atual pode atender casos read-only de snapshot no v1.
|
|
- Casos stateful com alocacao/lifecycle (ex.: RNG com instancia, mapas VM-owned, window resources) ficam para agenda posterior.
|
|
|
|
## Exemplo de Mapeamento (Ilustrativo, nao normativo)
|
|
|
|
Objetivo da linguagem:
|
|
|
|
```text
|
|
Input.pad().up().hold()
|
|
```
|
|
|
|
Possivel lowering:
|
|
|
|
```text
|
|
INTRINSIC input.pad@1
|
|
INTRINSIC input.pad.up@1
|
|
INTRINSIC input.button.hold@1
|
|
```
|
|
|
|
Os nomes acima sao apenas ilustrativos; o contrato real e o ID/versionamento canonico do intrinsic definido pelo toolchain/runtime.
|
|
|
|
## Consequencias
|
|
|
|
### Positivas
|
|
|
|
- destrava o fechamento do bytecode para backend no v1;
|
|
- elimina dependencia de syscall para consulta de input;
|
|
- preserva compatibilidade da infraestrutura host-backed existente;
|
|
- evita acoplamento prematuro a uma unica linguagem.
|
|
|
|
### Custos
|
|
|
|
- exige registry de intrinsics VM-owned consistente entre FE/backend/runtime;
|
|
- exige disciplina de versionamento 1:1 por operacao;
|
|
- adia para etapa posterior o protocolo stateful completo com `HeapRef`.
|
|
|
|
## Fora de Escopo
|
|
|
|
- protocolo generico VM-owned stateful com lifecycle de recursos;
|
|
- random com instancia alocada e ownership explicito;
|
|
- window system/app model completo;
|
|
- redesign de `HOSTCALL`/`SYSCALL`.
|
|
|
|
## Follow-up Obrigatorio
|
|
|
|
- as agendas historicas de input (`010-input-intrinsics-surface.md` e `011-input-frame-semantics-and-portability.md`) foram encerradas e seu conteudo foi absorvido por esta decisao;
|
|
- agenda `001-vm-owned-builtins-protocol-and-system-services.md` fica restrita a pos-v1 (stateful/`HeapRef`).
|
|
|
|
Specs a alinhar/confirmar:
|
|
|
|
- `../virtual-machine/ISA_CORE.md`
|
|
- `../specs/16-host-abi-and-syscalls.md`
|
|
- `../specs/06-input-peripheral.md`
|
|
- `../specs/07-touch-peripheral.md`
|