154 lines
4.5 KiB
Markdown
154 lines
4.5 KiB
Markdown
# Decision Record - VM-Owned Byte Transfer Protocol
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Contexto
|
|
|
|
O runtime precisa de um protocolo canonico para trafegar bytes entre host e userland sem:
|
|
|
|
- converter payload binario em `String`;
|
|
- devolver handles host-owned;
|
|
- inventar formatos ad hoc por dominio.
|
|
|
|
O estado atual relevante e:
|
|
|
|
- a heap ja possui `ObjectKind::Bytes`;
|
|
- o runtime ja consegue armazenar payload binario bruto na heap;
|
|
- `Value` ainda nao possui `Byte`;
|
|
- a spec de valores ainda nao reconhece `byte` como valor primitivo;
|
|
- `HostReturn` ainda modela apenas empilhar valores na stack;
|
|
- `fs` e o futuro data bank precisarao trafegar bytes pela borda host <-> guest.
|
|
|
|
O projeto tambem ja fixou que:
|
|
|
|
- syscalls usam stack;
|
|
- o host nao devolve handles opacos;
|
|
- o host nao devolve memoria host-owned;
|
|
- banks de hardware trafegam IDs, nao bytes;
|
|
- nao ha backward compatibility.
|
|
|
|
## Decisao
|
|
|
|
### 1. Tipo base
|
|
|
|
- O runtime passa a exigir `Value::Byte` como valor primitivo real.
|
|
- A spec de valores deve ser atualizada para incluir `byte`.
|
|
|
|
### 2. Buffer canonico
|
|
|
|
- O buffer canonico de bytes da VM e `HeapRef(Byte)`.
|
|
- `HeapRef(Byte)` significa um `HeapRef` cujo objeto alvo e `ObjectKind::Bytes`.
|
|
- Nao sera introduzido mecanismo paralelo para buffer binario.
|
|
|
|
### 3. Nomes canonicos
|
|
|
|
- `src` = origem dos bytes.
|
|
- `dst` = destino dos bytes.
|
|
- `src_ref`/`dst_ref` = handle VM-owned para buffer de bytes.
|
|
- `src_offset`/`dst_offset` = offset no buffer da VM.
|
|
- `host_handle` = identificador opaco do lado host.
|
|
- `host_offset` = offset do lado host.
|
|
- `max_bytes` = quantidade maxima pedida para a operacao.
|
|
- `bytes_transferred` = quantidade efetivamente transferida.
|
|
|
|
### 4. Domain ops iniciais
|
|
|
|
Os dois domain ops iniciais deste protocolo sao:
|
|
|
|
- `read`: host -> VM
|
|
- `write`: VM -> host
|
|
|
|
### 5. Assinatura canonica de `read`
|
|
|
|
`read` deve seguir este formato:
|
|
|
|
```text
|
|
read(host_handle, host_offset, dst_ref, dst_offset, max_bytes) -> (status, bytes_transferred, eof)
|
|
```
|
|
|
|
Regras:
|
|
|
|
- `status` e `bytes_transferred` sao inteiros;
|
|
- `eof` e booleano;
|
|
- `dst_ref` deve apontar para `HeapRef(Byte)`;
|
|
- `read` parcial pode ser sucesso;
|
|
- `eof` representa fim/exaustao observada no lado host.
|
|
|
|
### 6. Assinatura canonica de `write`
|
|
|
|
`write` deve seguir este formato:
|
|
|
|
```text
|
|
write(host_handle, host_offset, src_ref, src_offset, max_bytes) -> (status, bytes_transferred)
|
|
```
|
|
|
|
Regras:
|
|
|
|
- `status` e `bytes_transferred` sao inteiros;
|
|
- `src_ref` deve apontar para `HeapRef(Byte)`;
|
|
- `write` parcial e falha.
|
|
|
|
### 7. Janela explicita de transferencia
|
|
|
|
Toda operacao atua sobre uma janela explicita da heap da VM:
|
|
|
|
- `read` escreve em `dst_ref[dst_offset .. dst_offset + max_bytes)`;
|
|
- `write` le de `src_ref[src_offset .. src_offset + max_bytes)`.
|
|
|
|
### 8. Politica de falha
|
|
|
|
- Esta decisao define o data plane de bytes, nao a taxonomia final de faults por dominio.
|
|
- Condicoes operacionais devem retornar `status`.
|
|
- Violacoes estruturais de chamada/ABI seguem `16a` e a decisao de fault policy do dominio.
|
|
- Para `fs`, a classificacao normativa esta na decisao `007-filesystem-fault-core-policy.md`.
|
|
|
|
### 9. API minima necessaria na VM
|
|
|
|
Para suportar este protocolo, a VM precisa expor API canonica para:
|
|
|
|
- alocar buffer de bytes VM-owned;
|
|
- validar se um `HeapRef` aponta para `ObjectKind::Bytes`;
|
|
- expor comprimento/capacidade relevantes;
|
|
- escrever bytes em faixa valida;
|
|
- ler bytes em faixa valida.
|
|
|
|
## Consequencias
|
|
|
|
### Positivas
|
|
|
|
- `fs` e data bank passam a compartilhar o mesmo protocolo estrutural.
|
|
- A borda host <-> guest deixa de depender de texto para payload binario.
|
|
- O host nao precisa alocar memoria propria para devolver bytes.
|
|
- O guest passa a controlar explicitamente buffer, janela e interpretacao do payload.
|
|
|
|
### Custos
|
|
|
|
- `Value` e a spec de valores precisam mudar.
|
|
- A heap precisa de API publica mais util para `Bytes`.
|
|
- `HostReturn` e a camada host-backed precisam acomodar o protocolo sem atalhos.
|
|
- Dominios como `fs` ainda precisam decidir suas semanticas funcionais sobre este protocolo.
|
|
|
|
## Fora de Escopo
|
|
|
|
- API funcional completa de `fs`;
|
|
- API funcional do data bank;
|
|
- listas e structs retornadas pelo host;
|
|
- transporte de banks graficos/sonoros para a VM;
|
|
- input/intrinsics.
|
|
|
|
## Follow-up Obrigatorio
|
|
|
|
As seguintes agendas devem consumir esta decisao:
|
|
|
|
- `013-game-memcard-slots-surface-and-semantics.md`
|
|
- `014-app-home-filesystem-surface-and-semantics.md`
|
|
- discussoes futuras de data bank
|
|
|
|
As seguintes specs precisarao ser atualizadas:
|
|
|
|
- `02a-vm-values-and-calling-convention.md`
|
|
- `03-memory-stack-heap-and-allocation.md`
|
|
- `16-host-abi-and-syscalls.md`
|