implemented intrinsecs de input and specs adjustment
This commit is contained in:
@@ -1,135 +1,31 @@
|
||||
# Agenda - Input Intrinsics Surface
|
||||
# Agenda 010 - Input Intrinsics Surface (Fechada no v1)
|
||||
|
||||
## Problema
|
||||
## Status
|
||||
|
||||
`input` ja esta conceitualmente do lado de intrinsics, nao de syscalls, mas a superficie concreta desse dominio ainda nao esta congelada.
|
||||
Fechada para v1 pela decisao:
|
||||
|
||||
Nesta agenda, `input` significa o dominio formado por:
|
||||
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
|
||||
|
||||
- `pad`;
|
||||
- `touch`.
|
||||
## O Que Foi Fechado
|
||||
|
||||
Sem uma agenda propria, o dominio de input corre o risco de ficar:
|
||||
1. Input sai da fronteira de syscall e entra em VM-owned intrinsics.
|
||||
2. Superficie obrigatoria do dominio: `button`, `pad`, `touch`.
|
||||
3. Sem `axis` no v1.
|
||||
4. Snapshot de input congelado no inicio do frame logico.
|
||||
5. API de linguagem pode ser encadeada/ergonomica, mas o contrato normativo e language-agnostic.
|
||||
6. Sem capability gate e sem custo de certificacao por syscall para leitura de input.
|
||||
|
||||
- espalhado pela spec de input;
|
||||
- implícito no ISA;
|
||||
- indefinido no verifier;
|
||||
- lembrado tarde demais na fase de implementacao.
|
||||
## Efeito Pratico
|
||||
|
||||
Hoje existe uma ambiguidade concreta no runtime:
|
||||
- Toolchain/backend devem emitir `INTRINSIC <id_final>` para input.
|
||||
- Syscalls de input legadas devem ser removidas/desativadas da superficie oficial.
|
||||
|
||||
- as specs tratam input como estado amostrado por frame;
|
||||
- a linguagem/runtime quer expor `pad` e `touch` como surface built-in do guest;
|
||||
- mas a implementacao ainda coleta esse estado por syscalls.
|
||||
## Risco Residual
|
||||
|
||||
Exemplos atuais no runtime:
|
||||
- Nenhum bloqueador do bytecode v1 permanece nesta agenda.
|
||||
- Novas discussoes de input so devem reabrir em caso de mudanca de versao de contrato.
|
||||
|
||||
- `InputGetPad`
|
||||
- `InputGetPadPressed`
|
||||
- `InputGetPadReleased`
|
||||
- `InputGetPadHold`
|
||||
- `InputPadSnapshot`
|
||||
- `InputTouchSnapshot`
|
||||
- `TouchGetX`
|
||||
- `TouchGetY`
|
||||
- `TouchIsDown`
|
||||
- `TouchIsPressed`
|
||||
- `TouchIsReleased`
|
||||
- `TouchGetHold`
|
||||
- `TouchGetFinger`
|
||||
- `PadGetUp` ate `PadGetSelect`
|
||||
## Follow-up
|
||||
|
||||
## Dor
|
||||
|
||||
- o runtime pode implementar intrinsics de input com shape arbitrario;
|
||||
- custo, assinatura e IDs logicos podem divergir entre docs;
|
||||
- o verifier pode aceitar chamadas sem contrato fechado;
|
||||
- `button` pode ganhar peso desproporcional e esconder que ele eh apenas uma parte da surface de `pad`;
|
||||
- o dominio de input fica misturado com decisoes de syscall, onde ele nao pertence.
|
||||
- o runtime mantem duas historias ao mesmo tempo: input como estado latched e input como host service;
|
||||
- a superficie explode em muitas syscalls pequenas para ler algo que ja esta disponivel como estado do hardware.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Definir a superficie canonica dos intrinsics de input observavel pela VM.
|
||||
|
||||
`pad` e `touch` sao os dois blocos do dominio.
|
||||
`button` entra aqui apenas como parte da surface de `pad`, nao como centro exclusivo da agenda.
|
||||
|
||||
Esta agenda tambem precisa decidir a migracao explicita:
|
||||
|
||||
- quais syscalls de input serao removidas;
|
||||
- quais intrinsics as substituem;
|
||||
- qual surface final o guest enxerga como built-in.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Conjunto de intrinsics.
|
||||
Quais operacoes existem no MVP:
|
||||
- operacoes de `pad`;
|
||||
- operacoes de `touch`, se entrarem no MVP.
|
||||
|
||||
No caso de `pad`, os candidatos iniciais sao:
|
||||
- `btn`
|
||||
- `btnp`
|
||||
- `btnr`
|
||||
- `axis`, se entrar ou nao.
|
||||
|
||||
2. Assinatura exata.
|
||||
Definir:
|
||||
- argumentos;
|
||||
- tipo de retorno;
|
||||
- custo/cycles;
|
||||
- comportamento para ID invalido;
|
||||
- comportamento para ausencia de suporte do dispositivo.
|
||||
|
||||
3. Superfícies do dominio.
|
||||
Fechar quais familias de input a VM pode consultar no contrato inicial:
|
||||
- pad;
|
||||
- axis;
|
||||
- touch.
|
||||
|
||||
4. Identificadores logicos.
|
||||
Fechar o conjunto de IDs logicos que a VM pode consultar.
|
||||
Isso inclui:
|
||||
- botoes do pad;
|
||||
- eixos, se existirem;
|
||||
- pontos/canais de touch, se existirem.
|
||||
|
||||
5. Integracao com ISA e verifier.
|
||||
Como os intrinsics sao referenciados, validados e emitidos no bytecode.
|
||||
|
||||
6. Migração da surface atual.
|
||||
Definir:
|
||||
- quais syscalls de input deixam de existir;
|
||||
- se toda leitura de `pad` e `touch` sai da ABI de syscall;
|
||||
- como a toolchain e a surface do guest passam a apontar apenas para intrinsics.
|
||||
|
||||
7. Observabilidade.
|
||||
O que entra em trace, certificacao e relatorios de custo.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- ISA/intrinsic model da VM;
|
||||
- spec de input para o dominio logico;
|
||||
- definicao de fault ou resposta para IDs invalidos, se houver;
|
||||
- alinhamento com a spec de touch, se o dominio entrar no MVP.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- mapeamento fisico de teclado/gamepad;
|
||||
- pipeline de coleta de input no host;
|
||||
- gestos de alto nivel;
|
||||
- novos syscalls de input;
|
||||
- transporte de bytes.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- lista final de intrinsics de input;
|
||||
- assinatura e retorno de cada intrinsic;
|
||||
- superfícies de input suportadas no MVP;
|
||||
- IDs logicos suportados;
|
||||
- lista das syscalls de input a serem removidas;
|
||||
- integracao com ISA, verifier e tracing.
|
||||
- Validar alinhamento de specs (`06`, `16`, `16a`) com a decisao `005`.
|
||||
- Validar runtime/verifier contra IDs finais de input intrinsics.
|
||||
|
||||
@@ -1,95 +1,35 @@
|
||||
# Agenda - Input Frame Semantics and Portability
|
||||
# Agenda 011 - Input Frame Semantics and Portability (Fechada no v1)
|
||||
|
||||
## Problema
|
||||
## Status
|
||||
|
||||
O dominio de input ja tem uma direcao documental, mas ainda precisa de fechamento operacional na borda runtime <-> plataforma.
|
||||
Fechada para v1 pela decisao:
|
||||
|
||||
Nesta agenda, `input` significa o dominio formado por:
|
||||
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
|
||||
|
||||
- `pad`;
|
||||
- `touch`.
|
||||
## O Que Foi Fechado
|
||||
|
||||
Sem isso, intrinsics de input podem existir com nome certo e semantica errada.
|
||||
1. A amostragem de input ocorre antes do frame logico.
|
||||
2. O estado observado pelo guest fica congelado durante todo o frame.
|
||||
3. Semantica de `button`:
|
||||
- `pressed` no frame de transicao up -> down
|
||||
- `released` no frame de transicao down -> up
|
||||
- `down` enquanto pressionado
|
||||
- `hold` contando frames pressionado
|
||||
4. `touch` e single-point no perfil handheld v1, com coordenadas `(x, y)` e persistencia do ultimo estado no snapshot vigente.
|
||||
5. `pad` e `touch` sao obrigatorios como elementos do contrato de plataforma.
|
||||
6. Leitura de input nao participa de capability gate de syscall nem de scoring de certificacao por syscall.
|
||||
|
||||
Hoje a dor nao eh apenas teorica:
|
||||
## Efeito Pratico
|
||||
|
||||
- `pad` e `touch` ja sao latched no host no inicio do frame;
|
||||
- `Button` ja eh a unidade de estado usada por `pad` e pelo toque ativo;
|
||||
- mas o runtime ainda expoe a leitura desse estado por syscalls em vez de intrinsics.
|
||||
- O runtime deve expor input como leitura deterministica de snapshot VM-owned.
|
||||
- O host deve fornecer os sinais necessarios para pad/touch a cada frame.
|
||||
|
||||
## Dor
|
||||
## Risco Residual
|
||||
|
||||
- ambiguidades sobre quando o input e amostrado;
|
||||
- risco de divergencia entre plataformas sobre pressed/held/released do `pad`;
|
||||
- risco de divergencia sobre touch ativo, posicao, multitouch e ausencia de touch;
|
||||
- replay, certificacao e reproducibilidade ficam dependentes de interpretacao;
|
||||
- edge cases de foco, multiplos dispositivos e conflitos de direcao ficam sem dono.
|
||||
- a borda guest pode acabar observando input como consulta host-driven, quando o modelo correto eh leitura de estado ja congelado no frame.
|
||||
- Nenhum bloqueador de bytecode v1 permanece nesta agenda.
|
||||
- Edge cases de app model/window system ficam para agendas futuras (fora de input v1).
|
||||
|
||||
## Alvo da Discussao
|
||||
## Follow-up
|
||||
|
||||
Fixar a semantica temporal e de portabilidade do dominio de input.
|
||||
|
||||
`pad` e `touch` sao os dois subconjuntos principais do contrato.
|
||||
`button` entra apenas como parte da semantica de `pad`.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Momento de amostragem.
|
||||
Em que ponto do frame o estado e capturado e congelado.
|
||||
|
||||
2. Semantica de estado.
|
||||
Definir formalmente:
|
||||
- pressed no `pad`;
|
||||
- released no `pad`;
|
||||
- held no `pad`;
|
||||
- transicao entre frames.
|
||||
|
||||
3. Semantica de touch.
|
||||
Definir formalmente, se touch fizer parte do contrato:
|
||||
- ponto ativo ou inativo;
|
||||
- coordenadas;
|
||||
- multitouch ou touch unico;
|
||||
- persistencia entre frames.
|
||||
|
||||
4. Determinismo e replay.
|
||||
Como input gravado, injetado ou reproduzido conversa com o runtime.
|
||||
|
||||
5. Regras de portabilidade.
|
||||
O que deve ser igual em todas as plataformas e o que pode variar.
|
||||
|
||||
6. Edge cases.
|
||||
Exemplos:
|
||||
- perda de foco;
|
||||
- multiplos devices;
|
||||
- direcoes opostas simultaneas no `pad`;
|
||||
- ausencia de determinado dispositivo fisico;
|
||||
- plataforma sem touch;
|
||||
- diferenca de resolucao ou area de toque.
|
||||
|
||||
7. Relacao com CAP e certificacao.
|
||||
Como consultas de input aparecem em custo e relatorios.
|
||||
Esta agenda tambem precisa decidir se input continua ou nao exigindo capability de syscall depois da migracao para intrinsic.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `010-input-intrinsics-surface.md`;
|
||||
- spec de input;
|
||||
- modelo de frame do runtime.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- opcode ou encoding do intrinsic;
|
||||
- mapeamento detalhado por plataforma;
|
||||
- bytes e heap.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- momento de amostragem;
|
||||
- semantica formal dos intrinsics de input do MVP;
|
||||
- regras de replay e reproducibilidade;
|
||||
- edge cases minimos que o runtime precisa tratar;
|
||||
- posicao explicita sobre a saida de `input` da fronteira de syscall;
|
||||
- impactos em CAP e certificacao.
|
||||
- Manter `06-input-peripheral.md` e `07-touch-peripheral.md` alinhadas com esta semantica.
|
||||
- Cobrir no runtime testes de regressao para determinismo por frame.
|
||||
|
||||
@@ -1,180 +1,88 @@
|
||||
# Agenda - VM-Owned Builtins Protocol and System Services
|
||||
# Agenda - VM-Owned Stateful Protocol (Pos-v1)
|
||||
|
||||
## Problema
|
||||
## Base Ja Fechada (Nao Reabrir Nesta Agenda)
|
||||
|
||||
O modelo de `syscall` atual atende bem chamadas host-backed e nao deve ser quebrado.
|
||||
Esta agenda passa a considerar fechado no v1:
|
||||
|
||||
Ao mesmo tempo, falta um protocolo formal para chamadas e dados VM-owned entre guest e VM para casos como:
|
||||
- input VM-owned por `INTRINSIC <id_final>`;
|
||||
- sem tabela dedicada de preload VM-owned no v1;
|
||||
- `HOSTCALL`/`SYSCALL` host-backed preservados sem redesign;
|
||||
- surface de linguagem livre (exemplo PBS apenas ilustrativo, nao normativo);
|
||||
- snapshot de input congelado por frame;
|
||||
- input sem capability/telemetria de certificacao.
|
||||
|
||||
- input;
|
||||
- random;
|
||||
- window system integrado ao SO;
|
||||
- builtins com leitura/escrita e lifecycle.
|
||||
Fonte normativa do recorte v1:
|
||||
|
||||
Hoje ja existe base para bytes VM-owned (decisao `003`), mas ainda nao existe contrato equivalente para valores builtin, recursos tipados e handles VM-owned.
|
||||
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
|
||||
|
||||
## Dor
|
||||
## Problema Desta Agenda
|
||||
|
||||
- sem protocolo, cada dominio tende a criar shape ad-hoc de stack e retorno;
|
||||
- surfaces de linguagem (FE) e backend podem divergir do runtime real;
|
||||
- faltam regras canonicas para criar/ler/escrever/destruir recursos VM-owned;
|
||||
- verifier e toolchain ficam sem alvo estavel para validacao de chamadas VM-owned;
|
||||
- discussoes de input/random/window tendem a virar agendas grandes e misturadas.
|
||||
Falta fechar o protocolo VM-owned para casos stateful que exigem recurso vivo, ownership e lifecycle, por exemplo:
|
||||
|
||||
- random com instancia/estado (`RngRef`);
|
||||
- estruturas VM-owned (ex.: map/set/colecoes runtime-owned);
|
||||
- window system para app model futuro;
|
||||
- filas/eventos VM-owned.
|
||||
|
||||
Ja existe uma base de data plane low-level de bytes (decisao `003`), mas ainda falta o contrato stateful tipado para builtins/servicos com `HeapRef` ou handle equivalente VM-owned.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Definir um protocolo canonico de comunicacao guest <-> VM para operacoes VM-owned, preservando:
|
||||
Definir um protocolo canonico de recursos VM-owned stateful, preservando:
|
||||
|
||||
- `syscall` como fronteira host-backed existente;
|
||||
- compatibilidade com o ABI atual de slots;
|
||||
- determinismo por frame.
|
||||
- fronteira host-backed atual intacta;
|
||||
- ABI estavel por slots;
|
||||
- versionamento e verificacao 1:1 por operacao;
|
||||
- determinismo quando requerido pelo dominio.
|
||||
|
||||
## Achados Consolidados Desta Rodada
|
||||
## O Que Ainda Precisa Ser Definido
|
||||
|
||||
- manter separacao por camadas:
|
||||
- decisao `003` como `Byte Transfer Core` (data plane low-level);
|
||||
- protocolo VM-owned desta agenda como `Service Control Plane` para builtins e servicos.
|
||||
- o guest nao recebe handle host-owned e nao acessa memoria host-owned diretamente.
|
||||
- servicos VM-owned podem internamente delegar para host/sistema operacional, sem expor essa borda para userland.
|
||||
- `syscall` host-backed atual permanece valido; esta agenda nao redesenha essa fronteira.
|
||||
- input e random passam a ser tratados como servicos VM-owned, com retorno de builtins/handles VM-owned.
|
||||
- para input, a direcao preferida e leitura de snapshot congelado por frame com semantica de registrador (sem copia grande de dados por chamada).
|
||||
|
||||
## Consolidado Parcial - `HOSTCALL` com `kind` (`host` | `vm`)
|
||||
|
||||
- proposta candidata:
|
||||
- manter `HOSTCALL <index>` no artefato pre-load;
|
||||
- substituir `SYSC` por uma tabela unificada de bindings (nome provisorio: `CALLS`/`BIND`);
|
||||
- cada entrada declara `kind`, `module`, `name`, `version`, `arg_slots`, `ret_slots`.
|
||||
- regra de resolucao:
|
||||
- a decisao `host` vs `vm` ocorre somente no loader;
|
||||
- loader resolve e patcha deterministamente:
|
||||
- `kind=host` -> `SYSCALL <id>`;
|
||||
- `kind=vm` -> `INTRINSIC <id>`.
|
||||
- o runtime nunca executa branch dinamico `host|vm` em tempo de execucao.
|
||||
- `kind` separa semanticas sem colapsar contratos:
|
||||
- `host` continua host-backed (capability/politicas do dominio host);
|
||||
- `vm` segue contrato VM-owned (builtins/recursos/estado interno da VM).
|
||||
- ponto tecnico critico identificado:
|
||||
- o executor atual de intrinsic usa `fn(&[Value])` e nao recebe contexto da VM/runtime;
|
||||
- servicos VM-owned stateful (input/map/window/random com recurso) exigem evolucao dessa interface.
|
||||
- regra de ABI para VM-owned:
|
||||
- operacoes devem mapear 1:1 para diretivas versionadas;
|
||||
- `arg_slots` e `ret_slots` fixos por operacao/versao (sem shape dinamico).
|
||||
- extensoes previstas (nao bloqueadoras do recorte inicial):
|
||||
- lifecycle de handles VM-owned com anti-stale/generation;
|
||||
- politica explicita de roots/GC para recursos vivos.
|
||||
- ponto ainda pendente de fechamento nesta agenda:
|
||||
- semantica de determinismo para random e, futuramente, fila/eventos de window system.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Plano de chamada VM-owned.
|
||||
1. Modelo canonico de recurso VM-owned stateful.
|
||||
Definir:
|
||||
- ponto de entrada no bytecode para VM-owned:
|
||||
- `INTRINSIC` com registry formal; ou
|
||||
- `HOSTCALL + kind=vm` com patch de loader para `INTRINSIC`;
|
||||
- namespace de IDs;
|
||||
- versionamento por operacao;
|
||||
- metadados canonicos (`arg_slots`, `ret_slots`, layout, custo, efeito, determinismo).
|
||||
- representacao de handle/referencia (`HeapRef<TBuiltin>`, handle tipado, ou hibrido);
|
||||
- ownership e regra anti-stale (generation/version);
|
||||
- lifecycle minimo (`create`, `read`, `update`, `destroy`).
|
||||
|
||||
2. Plano de dados builtin.
|
||||
2. Evolucao da execucao de intrinsic para servicos stateful.
|
||||
Definir:
|
||||
- como builtins sao representados em slots;
|
||||
- quando um builtin e inline e quando vira handle;
|
||||
- regras de leitura/escrita/atualizacao em stack e heap;
|
||||
- regras de compatibilidade de layout entre versoes.
|
||||
- como a operacao intrinsic recebe contexto VM/runtime de forma segura;
|
||||
- como manter compatibilidade com intrinsics atuais read-only.
|
||||
|
||||
3. Modelo de recursos VM-owned.
|
||||
3. Contrato de ABI/meta para operacoes VM-owned stateful.
|
||||
Definir:
|
||||
- formato de handle (incluindo estrategia anti-stale);
|
||||
- ownership;
|
||||
- lifecycle (`create`, `read`, `update`, `destroy`);
|
||||
- invariantes de validade.
|
||||
- politica de singleton vs instancia alocada para builtins de snapshot (ex.: `Pad`, `Touch`).
|
||||
- metadados canonicos por operacao (`arg_slots`, `ret_slots`, efeito, custo, determinismo);
|
||||
- namespace/versionamento de IDs;
|
||||
- criterio de compatibilidade binaria entre versoes.
|
||||
|
||||
4. Perfil de input no protocolo.
|
||||
4. Perfil de random stateful.
|
||||
Fechar:
|
||||
- como `Input.getPad()` e `Input.getTouch()` mapeiam para o protocolo VM-owned;
|
||||
- se a API retorna ref singleton (`Input.getPad() -> PadRef`) ou recebe destino (`Input.getPad(dst_ref)`), e por que;
|
||||
- relacao com as syscalls atuais de input no periodo de transicao (se houver);
|
||||
- garantia de snapshot congelado por frame para leitura deterministica.
|
||||
- superficie minima (`seed` explicita, instancia, leitura de proximo valor);
|
||||
- regra de determinismo/replay;
|
||||
- politica de status/fault.
|
||||
|
||||
5. Perfil de random no protocolo.
|
||||
Fechar:
|
||||
- API minima (`RndG.pcg32(seed) -> RngRef` e/ou `getRandom`), incluindo superficie inicial oficial;
|
||||
- PRNG deterministico e regras de seed;
|
||||
- politicas de reproducibilidade.
|
||||
|
||||
6. Perfil de window system no protocolo.
|
||||
5. Perfil de window system/app model.
|
||||
Fechar contrato minimo para:
|
||||
- criacao e destruicao de janelas;
|
||||
- leitura/escrita de estado de janela;
|
||||
- criacao/destruicao de janelas;
|
||||
- leitura/escrita de estado;
|
||||
- fila de eventos;
|
||||
- relacao com foco e input.
|
||||
- relacao com foco/input sem quebrar determinismo do runtime.
|
||||
|
||||
7. Modelo de fault/status.
|
||||
6. Verifier/toolchain/disasm.
|
||||
Definir:
|
||||
- fronteira entre erro estrutural (`Trap`) e resultado operacional (`status`);
|
||||
- como erros de handle/recurso/estado invalido sao expostos.
|
||||
|
||||
8. Integracao com verifier e toolchain.
|
||||
Definir:
|
||||
- validacoes estaticas minimas;
|
||||
- regras de emissao no backend;
|
||||
- requisitos para decode/disasm/assembler.
|
||||
|
||||
9. Politica de CAP, certificacao e telemetria para VM-owned.
|
||||
Definir:
|
||||
- se VM-owned usa ou nao capability;
|
||||
- como custo entra em certificacao;
|
||||
- o que e observavel em telemetria.
|
||||
|
||||
10. Migração.
|
||||
Definir:
|
||||
- como coexistem superficies antigas e novas;
|
||||
- quando e como descontinuar chamadas legadas.
|
||||
|
||||
## Shape Inicial de Referencia (Nao Decisao)
|
||||
|
||||
Este shape e apenas base de discussao para fechar bytecode/ABI, sem efeito normativo ate decisao formal:
|
||||
|
||||
```text
|
||||
vm_service_call(service_id, op_id, args...) -> (status, ret...)
|
||||
```
|
||||
|
||||
Exemplos candidatos:
|
||||
|
||||
- `Input.getPad() -> (status, pad_ref)`
|
||||
- `Input.getTouch() -> (status, touch_ref)`
|
||||
- `RndG.pcg32(seed) -> (status, rng_ref)`
|
||||
|
||||
Onde `pad_ref`, `touch_ref` e `rng_ref` sao builtins/handles VM-owned.
|
||||
|
||||
## Sistemas Candidatos Para Cobertura
|
||||
|
||||
Esta agenda deve discutir explicitamente, alem de input/random/window:
|
||||
|
||||
- frame clock/tick index para consultas deterministicas de tempo de jogo;
|
||||
- event queue VM-owned para UI/app;
|
||||
- text input para apps com janelas;
|
||||
- notificacoes de sistema para app.
|
||||
- validacoes estaticas obrigatorias;
|
||||
- requisitos de assembler/disassembler para intrinsics stateful;
|
||||
- estrategia de diagnostico para mismatch de assinatura/layout.
|
||||
|
||||
## Open Questions de Arquitetura
|
||||
|
||||
1. Qual e o entrypoint de pre-load para VM-owned: `HOSTCALL + kind=vm` em tabela unificada, ou tabela dedicada?
|
||||
2. Como representar retorno de builtin em slots: `HeapRef<TBuiltin>`, handle numerico tipado, ou forma hibrida?
|
||||
3. Como evoluir a interface de intrinsic para receber contexto VM/runtime (alem de `args`) sem quebrar o que ja existe?
|
||||
4. Input usa singleton por dispositivo/frame ou instancia nova por chamada?
|
||||
5. Quais campos de `Pad` e `Touch` sao estritamente read-only para guest, e como bloquear escrita indevida?
|
||||
6. Qual politica de lifetime dos snapshots de input entre frames (substituicao, aliasing, invalidacao)?
|
||||
7. Random sera estritamente deterministico por seed explicitamente passado, ou existe modo sem seed (host entropy)?
|
||||
8. Qual taxonomia canonica de `status` compartilhada entre servicos VM-owned (input/random/window)?
|
||||
9. Como o verifier valida compatibilidade entre assinatura esperada pelo FE e metadados reais do service registry?
|
||||
10. Como garantir compatibilidade binaria quando um builtin evoluir layout entre versoes?
|
||||
11. Como tratar custo/certificacao para VM-owned sem reintroduzir modelo de capability desnecessario?
|
||||
12. Window system exigira fila/event loop VM-owned; como evitar acoplamento indevido com scheduler do runtime?
|
||||
13. Qual estrategia de migracao para remover chamadas legadas de input sem quebrar toolchain antiga?
|
||||
1. `HeapRef<TBuiltin>` sera o padrao unico para recurso stateful ou teremos handles numericos tipados em alguns dominios?
|
||||
2. Qual shape final da interface de intrinsic com contexto VM/runtime?
|
||||
3. Qual politica de roots/GC/lifetime para recursos VM-owned vivos entre frames?
|
||||
4. Como impedir aliasing perigoso quando multiplas referencias apontarem para o mesmo recurso stateful?
|
||||
5. Random stateful deve permitir modo nao deterministico (entropy host) ou apenas deterministico por seed?
|
||||
6. Qual taxonomia minima de `status` para servicos VM-owned stateful sem criar enum global monolitico?
|
||||
7. Quais gatilhos tecnicos justificariam introduzir no futuro um mecanismo simbolico adicional (ex.: tabela dedicada), em vez de manter IDs finais?
|
||||
8. Como garantir que extensoes para window/app model nao enrijeçam a base e continuem language-agnostic?
|
||||
|
||||
## Dependencias
|
||||
|
||||
@@ -183,20 +91,21 @@ Esta agenda deve discutir explicitamente, alem de input/random/window:
|
||||
- `../specs/16a-syscall-policies.md`
|
||||
- `../decisions/003-vm-owned-byte-transfer-protocol.md`
|
||||
- `../decisions/004-host-fault-taxonomy.md`
|
||||
- `../decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- redesenhar o modelo de syscall host-backed;
|
||||
- UX final do window manager;
|
||||
- detalhes de compositor/renderizacao de UI;
|
||||
- reabrir a decisao de input v1;
|
||||
- redesenhar o caminho host-backed (`HOSTCALL`/`SYSCALL`);
|
||||
- UX final de compositor/tema/desktop do window manager;
|
||||
- protocolo de rede/distribuicao remota.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
## Criterio de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- contrato canonico do protocolo VM-owned (call plane + data plane);
|
||||
- shape e lifecycle de builtins/handles;
|
||||
- perfil minimo fechado para input, random e window system;
|
||||
- regras de fault/status e verificacao;
|
||||
- plano de migracao sem quebra da fronteira de syscall existente.
|
||||
- contrato stateful VM-owned (resource model + lifecycle);
|
||||
- forma definitiva de referencia/handle com validade;
|
||||
- evolucao do executor de intrinsic com contexto VM/runtime;
|
||||
- perfil minimo fechado para random stateful e base de window resources;
|
||||
- regras de verificacao e compatibilidade binaria por versao.
|
||||
|
||||
+115
@@ -0,0 +1,115 @@
|
||||
# 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 `010`, `011` e `017` 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
|
||||
|
||||
- agenda `010-input-intrinsics-surface.md` deve considerar input v1 fechado;
|
||||
- agenda `011-input-frame-semantics-and-portability.md` deve considerar semantica base fechada;
|
||||
- agenda `017-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`
|
||||
@@ -18,3 +18,4 @@ Decisoes atuais:
|
||||
|
||||
- `003-vm-owned-byte-transfer-protocol.md`
|
||||
- `004-host-fault-taxonomy.md`
|
||||
- `005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Input Peripheral (Input System)
|
||||
# Input Peripheral (VM-Owned Snapshot Input)
|
||||
|
||||
Domain: virtual hardware: input
|
||||
Domain: virtual hardware: input
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/input-mental-model.md`](../learn/input-mental-model.md)
|
||||
@@ -11,154 +11,99 @@ This chapter defines the runtime-facing input contract of PROMETEU.
|
||||
|
||||
Core contract:
|
||||
|
||||
- input is exposed as state, not asynchronous callback flow;
|
||||
- sampling occurs at a defined moment in the logical frame;
|
||||
- queries are deterministic during the frame;
|
||||
- logical identifiers are stable across host devices.
|
||||
- input is exposed as VM-owned snapshot state;
|
||||
- sampling happens at a deterministic point of each logical frame;
|
||||
- queries are deterministic inside the same frame;
|
||||
- input access uses VM-owned intrinsics (not host syscalls in v1).
|
||||
|
||||
## 2 Input Devices
|
||||
## 2 Devices and Surface
|
||||
|
||||
PROMETEU abstracts different devices into a common interface.
|
||||
For v1, the input domain includes:
|
||||
|
||||
Typical devices:
|
||||
- `pad`
|
||||
- `touch`
|
||||
- `button` (as a nested state surface used by `pad` and `touch`)
|
||||
|
||||
- digital control (D-Pad + botões)
|
||||
- keyboard (mapped to buttons)
|
||||
- gamepad
|
||||
- touch (mobile, mapped)
|
||||
No analog axis is part of the v1 input contract.
|
||||
|
||||
Regardless of source, PROMETEU exposes the same logical model.
|
||||
## 3 Frame Sampling Model
|
||||
|
||||
## 3 State Model
|
||||
|
||||
### 3.1 Per-Frame State
|
||||
|
||||
For each frame, the system maintains:
|
||||
|
||||
- current state of buttons
|
||||
- state from the previous frame
|
||||
|
||||
This allows querying:
|
||||
|
||||
- button pressed
|
||||
- button released
|
||||
- button held down
|
||||
|
||||
### 3.2 Query Types
|
||||
|
||||
Typical operations:
|
||||
|
||||
```
|
||||
input.btn(id)// button is pressed
|
||||
input.btnp(id)// button was pressed this frame
|
||||
input.btnr(id)// button was released this frame
|
||||
```
|
||||
|
||||
These functions:
|
||||
|
||||
- are purely advisory
|
||||
- do not change state
|
||||
- have an explicit cost
|
||||
|
||||
## 4 Sampling Moment
|
||||
|
||||
The input state is captured **at the beginning of each frame**, before the `UPDATE` phase.
|
||||
Input state is captured at the beginning of each logical frame, before update logic runs.
|
||||
|
||||
Conceptual flow:
|
||||
|
||||
```
|
||||
```text
|
||||
FRAME N:
|
||||
SAMPLEINPUT
|
||||
SAMPLE_INPUT
|
||||
UPDATE
|
||||
DRAW
|
||||
AUDIO
|
||||
SYNC
|
||||
```
|
||||
|
||||
Throughout the entire frame:
|
||||
Within the same frame:
|
||||
|
||||
- the input state is immutable
|
||||
- repeated calls return the same value
|
||||
- input state is immutable;
|
||||
- repeated reads return the same values.
|
||||
|
||||
## 5 Determinism and Reproducibility
|
||||
## 4 State Semantics
|
||||
|
||||
The PROMETEU input model guarantees:
|
||||
`button` exposes:
|
||||
|
||||
- same sequence of inputs
|
||||
- same frames
|
||||
- same results
|
||||
- `pressed: bool` (true only on transition up -> down in this frame)
|
||||
- `released: bool` (true only on transition down -> up in this frame)
|
||||
- `down: bool` (true while physically pressed in this frame snapshot)
|
||||
- `hold: int` (count of consecutive pressed frames)
|
||||
|
||||
This allows:
|
||||
`pad` is a fixed set of buttons:
|
||||
|
||||
- execution playback
|
||||
- deterministic replays
|
||||
- reliable certification
|
||||
- `up`, `down`, `left`, `right`
|
||||
- `a`, `b`, `x`, `y`
|
||||
- `l`, `r`, `start`, `select`
|
||||
|
||||
Input can be:
|
||||
`touch` exposes:
|
||||
|
||||
- recorded
|
||||
- played back
|
||||
- artificially injected
|
||||
- `x: int`
|
||||
- `y: int`
|
||||
- `button` with the same `pressed/released/down/hold` semantics
|
||||
|
||||
## 6 Input and CAP
|
||||
PROMETEU handheld v1 uses single-touch active pointer semantics.
|
||||
|
||||
Input operations:
|
||||
## 5 Access Model
|
||||
|
||||
- consume few cycles
|
||||
- participate in the per-frame budget
|
||||
- appear in certification reports
|
||||
Input is VM-owned in v1:
|
||||
|
||||
Example:
|
||||
- frontend surfaces may be ergonomic and language-specific;
|
||||
- lowering maps to VM-owned `INTRINSIC <id_final>`;
|
||||
- no input syscall is required in the host ABI path.
|
||||
|
||||
```
|
||||
Frame 18231:
|
||||
input.btn():12cycles
|
||||
Illustrative (language-level) shape:
|
||||
|
||||
```text
|
||||
Input.pad().up().hold()
|
||||
Input.touch().x()
|
||||
```
|
||||
|
||||
Although cheap, input **is not free**.
|
||||
The normative contract is intrinsic identity/version and semantics, not source syntax.
|
||||
|
||||
## 7 Button Mapping
|
||||
## 6 Determinism and Replay
|
||||
|
||||
### 7.1 Logical Identifiers
|
||||
Given the same per-frame input snapshots, execution must produce the same observable results.
|
||||
|
||||
PROMETEU defines logical button identifiers:
|
||||
This enables:
|
||||
|
||||
- `UP`, `DOWN`, `LEFT`, `RIGHT`
|
||||
- `A`, `B`, `X`, `Y`
|
||||
- `START`, `SELECT`
|
||||
- deterministic replay;
|
||||
- deterministic certification analysis;
|
||||
- controlled input injection in tests/tooling.
|
||||
|
||||
The physical mapping:
|
||||
## 7 Capability and Certification
|
||||
|
||||
- depends on the platform
|
||||
- is resolved outside the VM
|
||||
- is transparent to the program
|
||||
Input reads are not capability-gated by syscall capability policy in v1.
|
||||
|
||||
### 7.2 Portability
|
||||
Input access is VM-owned and should not be reported as host syscall consumption.
|
||||
|
||||
The same PROMETEU cartridge:
|
||||
## 8 Portability
|
||||
|
||||
- runs on a keyboard
|
||||
- runs on a gamepad
|
||||
- runs on touch
|
||||
All platforms must provide the mandatory input elements (`pad`, `touch`, `button`) to the runtime.
|
||||
|
||||
Without any code changes.
|
||||
|
||||
## 8 Analog Input (Optional)
|
||||
|
||||
PROMETEU can expose analog axes explicitly:
|
||||
|
||||
```
|
||||
input.axis(id)
|
||||
```
|
||||
|
||||
Characteristics:
|
||||
|
||||
- normalized value (e.g.: -1.0 to 1.0)
|
||||
- explicit cost
|
||||
- per-frame update
|
||||
|
||||
Analog input:
|
||||
|
||||
- is not mandatory
|
||||
- does not replace digital input
|
||||
- must be used consciously
|
||||
Platform differences in physical device mapping are resolved outside VM semantics.
|
||||
|
||||
@@ -37,7 +37,6 @@ Example:
|
||||
|
||||
```
|
||||
("gfx", "present", 1)
|
||||
("input", "state", 1)
|
||||
("audio", "play", 2)
|
||||
```
|
||||
|
||||
@@ -47,6 +46,8 @@ This identity is:
|
||||
- toolchain-stable;
|
||||
- used for linking and capability gating.
|
||||
|
||||
Input queries are VM-owned intrinsic calls in v1 and are outside the syscall identity space.
|
||||
|
||||
## 3 Syscall Resolution
|
||||
|
||||
The host maintains a registry:
|
||||
|
||||
@@ -41,12 +41,13 @@ Example groups:
|
||||
|
||||
- `gfx`
|
||||
- `audio`
|
||||
- `input`
|
||||
- `asset`
|
||||
- `memcard`
|
||||
|
||||
Capability checks exist to constrain which host-managed surfaces a cartridge may use.
|
||||
|
||||
Input in v1 is VM-owned intrinsic surface and is not capability-gated through syscall policy.
|
||||
|
||||
## 3 Interaction with the Garbage Collector
|
||||
|
||||
The VM heap and host-managed memory are separate.
|
||||
|
||||
Reference in New Issue
Block a user