agenda discussion and decisions
This commit is contained in:
@@ -0,0 +1,162 @@
|
||||
# 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
|
||||
|
||||
- O protocolo deve preferir `status` ao maximo.
|
||||
- Falhas operacionais e erros observaveis de contrato devem retornar `status`, nao `Trap`.
|
||||
- `Trap` fica reservado para bug/inconsistencia interna do runtime.
|
||||
|
||||
Isso inclui, por decisao arquitetural, que erros como:
|
||||
|
||||
- `host_handle` invalido;
|
||||
- `HeapRef(Byte)` invalido;
|
||||
- kind incorreto;
|
||||
- offset invalido;
|
||||
- janela invalida;
|
||||
- indisponibilidade operacional do host;
|
||||
|
||||
devem ser modelados como `status`, nao como `Trap`, salvo se revelarem inconsistencia interna do runtime.
|
||||
|
||||
### 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:
|
||||
|
||||
- `009-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`
|
||||
@@ -0,0 +1,19 @@
|
||||
# Runtime Decisions
|
||||
|
||||
Este diretório reúne decision records do runtime.
|
||||
|
||||
Objetivo:
|
||||
|
||||
- registrar decisoes arquiteturais ja tomadas;
|
||||
- servir como referencia normativa para agendas derivadas;
|
||||
- evitar reabrir discussoes que ja foram fechadas.
|
||||
|
||||
Regra de uso:
|
||||
|
||||
- agendas existem para discutir e fechar ambiguidade;
|
||||
- decision records existem para registrar o que foi decidido;
|
||||
- quando uma agenda for resolvida, ela deve sair de `agendas/` e virar decision record aqui.
|
||||
|
||||
Decisoes atuais:
|
||||
|
||||
- `003-vm-owned-byte-transfer-protocol.md`
|
||||
Reference in New Issue
Block a user