98 lines
3.0 KiB
Markdown
98 lines
3.0 KiB
Markdown
# Agenda - VM-Owned Byte Buffer ABI
|
|
|
|
## Problema
|
|
|
|
O runtime ainda trata bytes como texto em partes da borda host <-> guest.
|
|
|
|
Exemplo atual:
|
|
|
|
- `fs.read` converte bytes para `String`.
|
|
|
|
Ao mesmo tempo, o projeto ja decidiu que:
|
|
|
|
- o host nunca devolve handles opacos;
|
|
- o host nunca devolve chunks de memoria host-owned;
|
|
- syscalls falam com o runtime apenas via stack;
|
|
- banks de hardware (`image`, `tilemap`, `sound`) trafegam apenas IDs;
|
|
- as unicas excecoes reais de payload binario sao `fs` e o futuro bank de dados.
|
|
|
|
## Dor
|
|
|
|
- bytes arbitrarios continuam vulneraveis a `UTF-8 lossy`;
|
|
- a fronteira host <-> guest fica ambigua;
|
|
- o runtime corre o risco de introduzir atalhos proibidos, como handles host-owned;
|
|
- `fs` e bank de dados ficam sem contrato canonico para copia de bytes.
|
|
|
|
## Alvo da Discussao
|
|
|
|
Definir o contrato canonico para syscalls que precisam copiar bytes do host para memoria da VM, usando:
|
|
|
|
- stack para argumentos e resultados;
|
|
- `HeapRef(Byte)` VM-owned como destino;
|
|
- preenchimento de memoria pelo host sem ownership host-side.
|
|
|
|
## Decisoes Ja Fixadas
|
|
|
|
- nao ha retorno estruturado generico por objetos heapados do host;
|
|
- nao ha handles opacos de buffers;
|
|
- nao ha backward compatibility;
|
|
- `button` fica fora desta agenda porque eh intrinsic;
|
|
- banks de hardware nao trafegam bytes para a VM.
|
|
|
|
## O Que Precisa Ser Definido
|
|
|
|
1. `Value::Byte`.
|
|
O ABI precisa de um valor primitivo `Byte` real, em vez de tratar byte como caso derivado de outro tipo.
|
|
|
|
2. `HeapRef(Byte)` como destino canonico.
|
|
A agenda precisa fechar como a VM aloca e tipa buffers de bytes que poderao ser preenchidos pelo host.
|
|
|
|
3. Protocolo de copia host -> VM.
|
|
Como a syscall recebe:
|
|
- referencia de destino;
|
|
- capacidade disponivel;
|
|
- offset/logica de janela, se aplicavel.
|
|
|
|
4. Shape de retorno via stack.
|
|
Como a syscall informa:
|
|
- quantidade de bytes escritos;
|
|
- EOF;
|
|
- leitura parcial;
|
|
- falha.
|
|
|
|
5. Impacto no verifier e no runtime.
|
|
O runtime precisa validar:
|
|
- tipo correto do heap ref;
|
|
- bounds;
|
|
- capacidade de escrita;
|
|
- integracao com `HostReturn` sem atalhos temporarios.
|
|
|
|
6. Relaçao com fault classification.
|
|
A agenda precisa explicitar quais erros pertencem ao contrato local de copia e quais dependem da agenda de falhas de syscall.
|
|
|
|
## O Que Necessita Para Resolver
|
|
|
|
- definicao normativa de `Value::Byte`;
|
|
- definicao normativa de `HeapRef(Byte)`;
|
|
- protocolo de syscall para copia de bytes;
|
|
- lista das operacoes que usarao esse contrato (`fs` e bank de dados);
|
|
- suite minima de testes de integridade de bytes e bounds.
|
|
|
|
## Fora de Escopo
|
|
|
|
- listas estruturadas retornadas pelo host;
|
|
- structs retornadas pelo host;
|
|
- `button` e outros intrinsics;
|
|
- design completo da API de `fs`;
|
|
- modelagem funcional do bank de dados.
|
|
|
|
## Critério de Saida Desta Agenda
|
|
|
|
Pode virar PR quando houver decisao escrita sobre:
|
|
|
|
- semantica de `Value::Byte`;
|
|
- uso de `HeapRef(Byte)` VM-owned;
|
|
- shape exato do protocolo stack-based de copia;
|
|
- impacto minimo em verifier e `HostReturn`;
|
|
- suite minima de testes para bytes arbitrarios, leitura parcial e bounds.
|