canonical path for intrinsics
This commit is contained in:
@@ -1,121 +0,0 @@
|
||||
# 18.0. Backend VM Pipeline - Orchestration Agenda
|
||||
|
||||
Status: Ready for Closure (v1 Draft Text)
|
||||
|
||||
## Purpose
|
||||
|
||||
Definir a ordem de fechamento arquitetural para o backend executável:
|
||||
|
||||
1. contrato de entrada `IRBackend` vindo do frontend,
|
||||
2. lowering `IRBackend -> IRVM`,
|
||||
3. marshaling `IRVM -> bytecode/PBX` executável no runtime.
|
||||
|
||||
## Context
|
||||
|
||||
- O pipeline já prevê `LowerToIRVMPipelineStage` e `EmitBytecodePipelineStage`, mas ambos estão vazios.
|
||||
- O runtime já impõe contratos concretos de loader/verifier/VM que precisam ser respeitados pelo backend.
|
||||
- Nesta rodada, `packer` está explicitamente fora de escopo.
|
||||
|
||||
## Decisions to Produce
|
||||
|
||||
1. Ordem oficial de workshops e critérios de saída por etapa.
|
||||
2. Fronteiras normativas entre:
|
||||
- frontend (`IRBackend`),
|
||||
- backend (`IRVM` + emissão),
|
||||
- runtime (loader/verifier/execução).
|
||||
3. Critérios de “backend integration-ready” para um artefato bytecode mínimo rodar no runtime.
|
||||
4. Estratégia de fechamento em docs (`agendas -> decisions -> specs -> PR`).
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Quais decisões precisam ser fechadas antes de qualquer implementação de `LowerToIRVM`?
|
||||
2. Quais invariantes são obrigatórias na fronteira `IRBackend` para evitar ambiguidade no backend?
|
||||
3. Quais invariantes são obrigatórias na fronteira `IRVM` para emissão determinística?
|
||||
4. Quais verificações devem ocorrer no compilador antes de delegar ao loader/verifier do runtime?
|
||||
5. Como organizar testes de integração sem introduzir dependência de packer?
|
||||
|
||||
## Resolution (v1)
|
||||
|
||||
Nao ha open questions bloqueantes remanescentes para fechamento da Agenda 18.
|
||||
|
||||
As agendas `18.1`, `18.2` e `18.3` definem os contratos de entrada, lowering e marshaling.
|
||||
|
||||
Esta agenda fecha a orquestracao end-to-end com pipeline canônico incluindo etapa de otimizacao de `IRVM`.
|
||||
|
||||
## Normative Text (Draft for Closure)
|
||||
|
||||
### 1) Pipeline canônico do backend executável
|
||||
|
||||
O pipeline normativo v1 do backend executavel MUST seguir esta ordem:
|
||||
|
||||
1. `FrontendPhase` produz `IRBackend`;
|
||||
2. `LowerToIRVM` produz `IRVM`;
|
||||
3. `OptimizeIRVM` transforma `IRVM -> IRVM` otimizado;
|
||||
4. `EmitBytecode` transforma `IRVM` otimizado em `BytecodeModule` pre-load;
|
||||
5. runtime loader aplica patching/resolucao (`HOSTCALL -> SYSCALL`) e verifier valida imagem final.
|
||||
|
||||
### 2) Posicionamento de otimização
|
||||
|
||||
1. A etapa `OptimizeIRVM` MUST ocorrer entre `LowerToIRVM` e `EmitBytecode`.
|
||||
2. Otimizacao semantica/estrutural MUST ocorrer no backend (compile-time), nao no runtime.
|
||||
3. Runtime permanece focado em load, validacao e execucao deterministica.
|
||||
|
||||
### 3) Contratos de entrada e saida por etapa
|
||||
|
||||
1. `LowerToIRVM` recebe `IRBackend` conforme Agenda `18.1` e MUST produzir `IRVM` conforme Agenda `18.2`.
|
||||
2. `OptimizeIRVM` recebe `IRVM` valido para o `vm_profile` alvo e MUST produzir `IRVM` equivalente semanticamente.
|
||||
3. `EmitBytecode` recebe `IRVM` (pos-otimizacao) sem opcodes internos nao-eliminados e MUST emitir artefato conforme Agenda `18.3`.
|
||||
|
||||
### 4) Invariantes de seguranca da etapa OptimizeIRVM
|
||||
|
||||
`OptimizeIRVM` MUST:
|
||||
|
||||
1. preservar semantica observavel do programa;
|
||||
2. preservar contratos de aridade/slots/retorno;
|
||||
3. preservar determinismo para mesmo grafo de entrada;
|
||||
4. nao introduzir opcodes fora do `vm_profile` executavel;
|
||||
5. nao mover chamadas host/intrinsic para fronteira semantica incorreta.
|
||||
|
||||
### 5) Criterio de aprovacao de pipeline
|
||||
|
||||
Um backend so pode declarar fluxo "integration-ready" quando:
|
||||
|
||||
1. `IRBackend -> IRVM -> IRVM otimizado -> BytecodeModule` estiver implementado;
|
||||
2. fixtures Gate I cobrirem cenarios positivos e negativos definidos em `18.3`;
|
||||
3. bytecode emitido inicializar e executar no runtime alvo sem packer.
|
||||
|
||||
### 6) Deferrals explicitos
|
||||
|
||||
Sem deferrals de perguntas abertas desta agenda.
|
||||
|
||||
Permanecem fora de escopo:
|
||||
|
||||
1. formato final de packer/cartucho;
|
||||
2. politicas avancadas de otimizacao nao necessarias para conformidade v1;
|
||||
3. redesign de loader/verifier/runtime.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Nova spec de contrato `IRBackend -> IRVM` (backend-facing).
|
||||
2. Nova spec de contrato de `IRVM` (shape, invariantes, diagnóstico).
|
||||
3. Atualização de `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
|
||||
4. Atualização de `docs/general/specs/19. Verification and Safety Checks Specification.md`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Definir formato final de packer/cartucho.
|
||||
- Redesenhar ISA do runtime.
|
||||
- Redesenhar loader/verifier do runtime.
|
||||
- Fechar otimizações de backend (peephole, SSA, etc.).
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/OptimizeIRVMPipelineStage.java`
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/EmitBytecodePipelineStage.java`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `../runtime/docs/runtime/virtual-machine/ISA_CORE.md`
|
||||
- `../runtime/crates/console/prometeu-vm/src/virtual_machine/loader.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
@@ -1,157 +0,0 @@
|
||||
# 18.1. Backend Workshop 1 - IRBackend Input Contract
|
||||
|
||||
Status: Ready for Closure (v1 Draft Text)
|
||||
|
||||
## Purpose
|
||||
|
||||
Fechar o `IRBackend` como contrato de entrada do backend executável, de forma suficientemente explícita para permitir lowering determinístico para `IRVM`.
|
||||
|
||||
## Context
|
||||
|
||||
- A spec atual de `IRBackend` cobre sobretudo a fronteira frontend e não fecha `IRBackend -> IRVM`.
|
||||
- O runtime exige contratos rígidos para chamadas host-backed (`SYSC`/`HOSTCALL`) e VM-owned (`INTRINSIC`).
|
||||
- O backend precisa receber um IR que preserve semântica e também fatos de artefato necessários para bytecode.
|
||||
|
||||
## Decisions to Produce
|
||||
|
||||
1. Shape mínima obrigatória de `IRBackend` para backend executável:
|
||||
- identidade de módulo/arquivo/callable,
|
||||
- assinatura (parâmetros/retorno),
|
||||
- corpo executável em forma backend-lowerable,
|
||||
- âncoras de source attribution.
|
||||
2. Modelo de representação para operações VM-owned vs host-backed no `IRBackend`.
|
||||
3. Contrato de metadados reservados obrigatório:
|
||||
- host bindings canônicos `(module, name, version)`,
|
||||
- metadados de intrinsics/builtin VM-owned,
|
||||
- `requiredCapabilities` determinístico.
|
||||
4. Regras de ordenação/deduplicação obrigatórias ainda no `IRBackend`.
|
||||
5. Política de rejeição determinística para formas que não entram no backend executável.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. O `IRBackend` deve carregar código em forma estruturada (blocos/expressões) ou linearizada?
|
||||
2. Quais informações de tipos precisam sobreviver para o backend sem “re-tipagem” implícita?
|
||||
3. Como representar chamadas host-backed no `IRBackend`:
|
||||
- por identidade canônica,
|
||||
- por índice lógico,
|
||||
- ou por ambos?
|
||||
4. Como representar intrinsics VM-owned:
|
||||
- identidade canônica apenas,
|
||||
- id final já conhecido,
|
||||
- ou modelo híbrido?
|
||||
5. Quais invariantes de estabilidade de ordenação são obrigatórias para conformance?
|
||||
6. Quais campos mínimos de span/source mapping são mandatórios para erros backend-atribuíveis?
|
||||
|
||||
## Resolution (v1)
|
||||
|
||||
Nao ha open questions bloqueantes para fechar o contrato de entrada `IRBackend` v1.
|
||||
|
||||
As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo.
|
||||
|
||||
## Normative Text (Draft for Closure)
|
||||
|
||||
### 1) Escopo e fronteira
|
||||
|
||||
1. `IRBackend` e o contrato de entrada normativo do backend executavel.
|
||||
2. O frontend MUST emitir `IRBackend` completo para toda unidade admitida no Gate U.
|
||||
3. O backend MUST tratar `IRBackend` como fonte de verdade para `IRBackend -> IRVM`.
|
||||
4. Esta agenda NAO define o formato de `IRVM` nem o encoding final de bytecode.
|
||||
|
||||
### 2) Obrigacoes minimas por callable
|
||||
|
||||
Para cada callable executavel emitido no `IRBackend`, o frontend MUST preservar:
|
||||
|
||||
1. identidade estavel do callable no build atual;
|
||||
2. assinatura observavel:
|
||||
- aridade de entrada;
|
||||
- shape de retorno observavel;
|
||||
3. categoria de callable (ex.: funcao comum vs superficie reservada nao executavel);
|
||||
4. ancora de atribuicao de fonte (`fileId`, `start`, `end`);
|
||||
5. corpo backend-lowerable com semantica suficiente para emissao de chamadas e fluxo.
|
||||
|
||||
`IRFunction` apenas com nome/contagem de parametros/span NAO satisfaz este contrato executavel.
|
||||
|
||||
### 3) Classificacao obrigatoria de callsites
|
||||
|
||||
Todo callsite executavel no `IRBackend` MUST estar classificado em exatamente uma categoria:
|
||||
|
||||
1. `CALL_FUNC` (chamada de callable de programa);
|
||||
2. `CALL_HOST` (fronteira host-backed);
|
||||
3. `CALL_INTRINSIC` (operacao VM-owned).
|
||||
|
||||
Implementacoes MUST NOT inferir a categoria por heuristica textual na fase `LowerToIRVM`.
|
||||
|
||||
### 4) Contrato para host-backed
|
||||
|
||||
Todo `CALL_HOST` MUST carregar identidade canonica:
|
||||
|
||||
1. `abiModule`,
|
||||
2. `abiMethod`,
|
||||
3. `abiVersion`.
|
||||
|
||||
Todo `CALL_HOST` MUST carregar declaracao de ABI:
|
||||
|
||||
1. `arg_slots`,
|
||||
2. `ret_slots`.
|
||||
|
||||
O conjunto de bindings host-backed no `IRBackend` MUST ser deduplicado por `(module, name, version)` e ordenado por primeira ocorrencia deterministica.
|
||||
|
||||
### 5) Contrato para VM-owned intrinsics e builtins
|
||||
|
||||
Todo `CALL_INTRINSIC` MUST carregar identidade canonica VM-owned:
|
||||
|
||||
1. `canonicalName`,
|
||||
2. `canonicalVersion`.
|
||||
|
||||
Builtin projections, builtin constants e intrinsic callsites VM-owned MUST NOT ser modelados como host binding.
|
||||
|
||||
### 6) Metadados reservados obrigatorios
|
||||
|
||||
`IRReservedMetadata` MUST preservar, no minimo:
|
||||
|
||||
1. host bindings canonicos admitidos;
|
||||
2. builtin type surfaces relevantes para lowering;
|
||||
3. builtin const surfaces relevantes para lowering;
|
||||
4. `requiredCapabilities` deterministico para assistencia de pipeline/packer.
|
||||
|
||||
`requiredCapabilities` MUST ser deterministico para o mesmo grafo de entrada admitido.
|
||||
|
||||
### 7) Diagnosticos e rejeicao deterministica
|
||||
|
||||
Quando um modulo/callable nao satisfaz o contrato de entrada executavel:
|
||||
|
||||
1. a rejeicao MUST ser deterministica;
|
||||
2. o diagnostico MUST manter atribuicao de fonte acionavel;
|
||||
3. o frontend/backend MUST NOT degradar silenciosamente para comportamento executavel diferente.
|
||||
|
||||
### 8) Deferrals explicitos
|
||||
|
||||
Ficam deferidos para agendas seguintes:
|
||||
|
||||
1. shape estrutural completo de `IRVM` e algoritmo de lowering (Agenda 18.2);
|
||||
2. layout/encoding final de `BytecodeModule` e marshaling PBX (Agenda 18.3);
|
||||
3. estrategia de otimizacao de backend.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Atualização de `docs/pbs/specs/13. Lowering IRBackend Specification.md` com adendo backend-facing.
|
||||
2. Decision record específico para “IRBackend executável v1”.
|
||||
3. Fixture set de conformance Gate U focado no contrato de entrada do backend.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Definir ainda o bytecode final.
|
||||
- Definir políticas de otimização.
|
||||
- Definir o formato final de debug/source map rico.
|
||||
- Introduzir dependência de packer.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackend.java`
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRBackendFile.java`
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRFunction.java`
|
||||
- `prometeu-compiler/prometeu-frontend-api/src/main/java/p/studio/compiler/models/IRReservedMetadata.java`
|
||||
- `docs/pbs/specs/13. Lowering IRBackend Specification.md`
|
||||
- `docs/pbs/specs/6.1. Intrinsics and Builtin Types Specification.md`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `../runtime/docs/runtime/decisions/005-v1-vm-owned-input-intrinsics-and-language-agnostic-surface.md`
|
||||
@@ -1,165 +0,0 @@
|
||||
# 18.2. Backend Workshop 2 - LowerToIRVM and IRVM Contract
|
||||
|
||||
Status: Ready for Closure (v1 Draft Text)
|
||||
|
||||
## Purpose
|
||||
|
||||
Definir o contrato intermediário `IRVM` e as regras normativas de lowering `IRBackend -> IRVM`, garantindo que a emissão de bytecode seja mecânica e determinística.
|
||||
|
||||
## Context
|
||||
|
||||
- O runtime já define ISA e calling rules concretas.
|
||||
- No runtime atual, jumps usam imediato `u32` absoluto relativo ao início da função.
|
||||
- O verificador e o loader já têm validações rígidas que devem ser antecipadas pelo backend sempre que possível.
|
||||
|
||||
## Decisions to Produce
|
||||
|
||||
1. Modelo oficial de `IRVM`:
|
||||
- unidades (módulo/função/bloco),
|
||||
- instruções VM-like,
|
||||
- referência a constantes/globais/locals/callables,
|
||||
- metadados mínimos por função.
|
||||
2. Regras de lowering para controle de fluxo:
|
||||
- labels simbólicos,
|
||||
- normalização de blocos,
|
||||
- política de branch/jump target.
|
||||
3. Regras de lowering para chamadas:
|
||||
- `CALL`,
|
||||
- `HOSTCALL` pré-load,
|
||||
- `INTRINSIC` VM-owned.
|
||||
4. Regras de layout de função e slots:
|
||||
- `param_slots`,
|
||||
- `local_slots`,
|
||||
- `return_slots`.
|
||||
5. Política de diagnósticos determinísticos no lowering para rejeições backend-originadas.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. `IRVM` permite pseudo-opcodes que não existem na ISA final?
|
||||
2. Onde ocorre a resolução final de labels para offsets: no próprio lowering ou apenas no emitter?
|
||||
3. Como garantir que cada função tenha finalização válida (`RET`/terminador) sem depender só do verificador?
|
||||
4. Qual o limite de checagens estáticas no compiler vs checagens delegadas ao verifier do runtime?
|
||||
5. Como representar efeitos de stack no `IRVM` para detectar underflow/mismatch antes de emitir bytes?
|
||||
6. Como versionar `IRVM` em relação à linha de ISA do runtime selecionada?
|
||||
|
||||
## Resolution (v1)
|
||||
|
||||
Nao ha open questions bloqueantes remanescentes nesta agenda.
|
||||
|
||||
As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo.
|
||||
|
||||
## Normative Text (Draft for Closure)
|
||||
|
||||
### 1) Escopo e fronteira
|
||||
|
||||
1. Esta agenda define o contrato intermediario `IRVM` e as regras obrigatorias de lowering `IRBackend -> IRVM`.
|
||||
2. O objetivo do `IRVM` v1 e permitir emissao mecanica e deterministica de bytecode para runtime `core-v1`.
|
||||
3. Esta agenda NAO define o marshaling binario final `IRVM -> BytecodeModule` (Agenda 18.3).
|
||||
|
||||
### 2) Modelo de IRVM (quase-ISA estendido)
|
||||
|
||||
1. `IRVM` v1 adota modelo quase-ISA:
|
||||
- opcodes da Core ISA alvo;
|
||||
- e opcodes internos estendidos (`IRVM_EXT`) quando necessarios para normalizacao/otimizacao.
|
||||
2. `IRVM_EXT` MUST ser interno ao compilador e MUST NOT aparecer no artefato executavel final.
|
||||
3. Todo opcode `IRVM_EXT` MUST declarar metadados estruturais equivalentes a spec de opcode:
|
||||
- `pops`,
|
||||
- `pushes`,
|
||||
- `is_branch`,
|
||||
- `is_terminator`.
|
||||
4. O backend MUST expandir/reduzir todo `IRVM_EXT` para Core ISA antes da fase de emissao de bytecode.
|
||||
|
||||
### 3) Controle de fluxo e labels
|
||||
|
||||
1. O `IRVM` pode usar labels simbolicos internamente.
|
||||
2. A resolucao final de labels para immediates `u32` de salto MUST ocorrer no `LowerToIRVM`.
|
||||
3. O target final de salto MUST seguir contrato da VM:
|
||||
- offset relativo ao inicio da funcao (`func_start + target_rel` em runtime).
|
||||
4. Todo salto MUST apontar para fronteira valida de instrucao da funcao alvo.
|
||||
5. Caminho alcancavel que cai no fim da funcao sem terminador MUST ser erro de compilacao.
|
||||
|
||||
### 4) IDs deterministas de funcao
|
||||
|
||||
1. O backend MUST produzir `func_id` deterministico para `CALL`, `SPAWN` e `MAKE_CLOSURE`.
|
||||
2. Regra v1:
|
||||
- entrypoint executavel no indice `0`;
|
||||
- demais callables por ordenacao deterministica `(module_key, callable_name, source_start)`.
|
||||
3. O mesmo grafo de entrada admitido MUST produzir os mesmos `func_id`.
|
||||
|
||||
### 5) Contrato de chamadas
|
||||
|
||||
1. `CALL` MUST referenciar `func_id` valido.
|
||||
2. `SPAWN` MUST respeitar aridade exata da funcao de destino.
|
||||
3. `CALL_HOST` no `IRBackend` MUST lower para `HOSTCALL <sysc_index>` em `IRVM` pre-load.
|
||||
4. `CALL_INTRINSIC` no `IRBackend` MUST lower para `INTRINSIC <id_final>` em `IRVM`.
|
||||
5. `CALL_CLOSURE` com callee nao determinavel estaticamente e proibido no v1.
|
||||
|
||||
### 6) Contrato de slots por funcao
|
||||
|
||||
Para cada funcao em `IRVM`, o backend MUST fixar:
|
||||
|
||||
1. `param_slots`,
|
||||
2. `local_slots`,
|
||||
3. `return_slots`,
|
||||
4. `max_stack_slots`.
|
||||
|
||||
`RET` MUST ser consistente com `return_slots` em todos os caminhos alcancaveis.
|
||||
|
||||
### 7) Pre-verificacao obrigatoria no compilador
|
||||
|
||||
Antes de emitir bytecode, o compilador MUST executar pre-verificacao estrutural em `IRVM` (ja em Core ISA, sem `IRVM_EXT`), cobrindo no minimo:
|
||||
|
||||
1. validade de target de saltos;
|
||||
2. coerencia de altura de stack em joins;
|
||||
3. ausencia de underflow e overflow contra `max_stack_slots`;
|
||||
4. consistencia de `RET` com `return_slots`;
|
||||
5. validade de `func_id` referenciado;
|
||||
6. validade de aridade em `CALL`/`SPAWN`/`CALL_CLOSURE`;
|
||||
7. regra de `YIELD` com stack vazia;
|
||||
8. validade estrutural de `HOSTCALL`/`INTRINSIC` no shape de IR.
|
||||
|
||||
O verificador do runtime permanece autoritativo e continua obrigatorio.
|
||||
|
||||
### 8) Regra de YIELD
|
||||
|
||||
`YIELD` com stack nao vazia MUST ser rejeitado no compilador como erro deterministico de lowering/verificacao.
|
||||
|
||||
### 9) Versionamento do IRVM
|
||||
|
||||
1. `IRVM` MUST carregar `vm_profile` explicito.
|
||||
2. Para v1, o perfil normativo e `core-v1`.
|
||||
3. Mismatch entre `vm_profile` e alvo de emissao/verificacao MUST falhar de forma deterministica.
|
||||
|
||||
### 10) Deferrals explicitos
|
||||
|
||||
Sem deferrals de perguntas abertas desta agenda.
|
||||
|
||||
Permanecem fora de escopo por fronteira de agenda:
|
||||
|
||||
1. formato binario final de `BytecodeModule` e seccionamento PBX (Agenda 18.3);
|
||||
2. politicas avancadas de otimizacao nao necessarias para conformidade v1.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Nova spec: `IRBackend -> IRVM` lowering contract.
|
||||
2. Nova spec: `IRVM` model e invariantes.
|
||||
3. Tabela de mapeamento `IRVM op -> ISA op` por linha de runtime suportada.
|
||||
4. Critérios de testes unitários do `LowerToIRVMPipelineStage`.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Implementar ainda otimizações avançadas.
|
||||
- Expandir ISA com novos opcodes.
|
||||
- Resolver políticas de linking multi-artifact além do necessário para execução v1.
|
||||
- Definir packer/cart assembly.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/LowerToIRVMPipelineStage.java`
|
||||
- `../runtime/docs/runtime/virtual-machine/ISA_CORE.md`
|
||||
- `../runtime/docs/runtime/specs/02-vm-instruction-set.md`
|
||||
- `../runtime/docs/runtime/specs/02a-vm-values-and-calling-convention.md`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/opcode.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/opcode_spec.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/decoder.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
-197
@@ -1,197 +0,0 @@
|
||||
# 18.3. Backend Workshop 3 - Bytecode Marshaling and Runtime Conformance
|
||||
|
||||
Status: Ready for Closure (v1 Draft Text)
|
||||
|
||||
## Purpose
|
||||
|
||||
Fechar o contrato de emissão de bytecode/PBX a partir de `IRVM`, com conformidade explícita ao loader/verifier/runtime atual.
|
||||
|
||||
## Context
|
||||
|
||||
- O runtime já define layout de módulo, parser de seções e invariantes de load-time.
|
||||
- `SYSC` é seção obrigatória (mesmo vazia), `HOSTCALL` é forma pré-load, `SYSCALL` final só após patching do loader.
|
||||
- O verifier rejeita `HOSTCALL` não patchado e valida estrutura de controle/stack sobre imagem final.
|
||||
|
||||
## Decisions to Produce
|
||||
|
||||
1. Contrato de marshaling de `IRVM -> BytecodeModule`:
|
||||
- `const_pool`,
|
||||
- `functions`,
|
||||
- `code`,
|
||||
- `debug_info` (mínimo obrigatório),
|
||||
- `exports`,
|
||||
- `syscalls`.
|
||||
2. Política de encoding de instruções:
|
||||
- little-endian,
|
||||
- `[opcode u16][immediate]`,
|
||||
- encoding de saltos/calls conforme ISA.
|
||||
3. Política de emissão de `SYSC`:
|
||||
- deduplicação por identidade canônica,
|
||||
- ordenação por primeira ocorrência,
|
||||
- `arg_slots`/`ret_slots` coerentes com metadado host.
|
||||
4. Contrato explícito “pre-load artifact vs executable image”:
|
||||
- backend emite `HOSTCALL` quando host-backed,
|
||||
- backend não emite `SYSCALL` bruto no artefato pré-load,
|
||||
- intrinsics VM-owned seguem caminho distinto.
|
||||
5. Estratégia de conformidade e regressão contra runtime real.
|
||||
|
||||
## Core Questions
|
||||
|
||||
1. Qual política oficial de ordenação de funções no bytecode (ordem de source, topo sort, entry-first)?
|
||||
2. Como calcular `code_offset`/`code_len` por função em flatten final de `code`?
|
||||
3. Quais hooks mínimos de source attribution serão emitidos no `debug_info` v1?
|
||||
4. Quais validações o emitter faz antes de serializar vs o que é delegado ao loader/verifier?
|
||||
5. Como padronizar mensagens/erros de marshaling para manter diagnóstico determinístico?
|
||||
6. Qual suíte mínima de integração prova “bytecode emitido roda no runtime” sem packer?
|
||||
|
||||
## Resolution (v1)
|
||||
|
||||
Nao ha open questions bloqueantes remanescentes nesta agenda.
|
||||
|
||||
As perguntas desta agenda ficam consideradas resolvidas para v1 pelos termos normativos abaixo.
|
||||
|
||||
## Normative Text (Draft for Closure)
|
||||
|
||||
### 1) Escopo e fronteira
|
||||
|
||||
1. Esta agenda define o contrato normativo de marshaling `IRVM -> BytecodeModule` para runtime `core-v1`.
|
||||
2. O backend executavel MUST produzir artefato pre-load compativel com loader e verifier do runtime.
|
||||
3. Esta agenda nao define packer/cart assembly.
|
||||
|
||||
### 2) Direcao JVM-inspired (adaptada)
|
||||
|
||||
1. O backend adota modelo de referencia simbolica interna antes de indice numerico final:
|
||||
- referencias simbolicas existem em `IRVM` e no emitter interno;
|
||||
- indices finais (`func_id`, `sysc_index`, `intrinsic_id`) sao materializados de forma deterministica no marshaling.
|
||||
2. O runtime continua numeric-only na execucao final.
|
||||
|
||||
### 3) Contrato do BytecodeModule emitido
|
||||
|
||||
O emitter MUST preencher:
|
||||
|
||||
1. `const_pool`,
|
||||
2. `functions`,
|
||||
3. `code`,
|
||||
4. `exports`,
|
||||
5. `syscalls`,
|
||||
6. `debug_info` conforme regra minima desta agenda.
|
||||
|
||||
O emitter MUST gerar secao `SYSC` sempre presente (inclusive vazia), conforme contrato do loader.
|
||||
|
||||
### 4) Politica de ordenacao e IDs
|
||||
|
||||
1. A ordem de funcoes no artefato MUST seguir regra deterministica v1:
|
||||
- entrypoint no indice `0`;
|
||||
- demais funcoes por `(module_key, callable_name, source_start)`.
|
||||
2. O mesmo grafo de entrada admitido MUST produzir os mesmos indices e offsets.
|
||||
3. `SYSC` MUST ser deduplicado por `(module, name, version)` e ordenado por primeira ocorrencia.
|
||||
|
||||
### 5) Layout de codigo por funcao
|
||||
|
||||
1. O emitter SHOULD construir codigo por funcao (modelo method-local) e flatten apenas no passo final.
|
||||
2. No artefato final:
|
||||
- `code_offset` MUST ser crescente e unico por funcao;
|
||||
- `code_len` MUST refletir exatamente o trecho da funcao;
|
||||
- `code_offset + code_len` de cada funcao MUST estar dentro de `code.len`.
|
||||
3. A concatenacao final MUST ser deterministica.
|
||||
|
||||
### 6) Encoding de instrucao
|
||||
|
||||
1. Encoding MUST ser little-endian.
|
||||
2. Layout de instrucao MUST ser `[opcode: u16][immediate]`.
|
||||
3. Saltos MUST usar imediato `u32` relativo ao inicio da funcao.
|
||||
4. O emitter MUST respeitar tamanhos de imediato definidos pela Core ISA alvo.
|
||||
|
||||
### 7) Pre-load vs executable image
|
||||
|
||||
1. Para chamadas host-backed, o backend MUST emitir `HOSTCALL <sysc_index>` no artefato pre-load.
|
||||
2. O backend MUST NOT emitir `SYSCALL <id>` bruto no artefato pre-load.
|
||||
3. Chamadas VM-owned MUST seguir caminho de `INTRINSIC <id_final>` e permanecer distintas de `SYSC`/`HOSTCALL`/`SYSCALL`.
|
||||
4. O backend MUST assumir que patch `HOSTCALL -> SYSCALL` e responsabilidade do loader.
|
||||
|
||||
### 8) Coerencia ABI de host bindings
|
||||
|
||||
1. Cada entrada `SYSC` MUST carregar `module`, `name`, `version`, `arg_slots`, `ret_slots`.
|
||||
2. O emitter MUST validar coerencia de ABI declarada com metadado host conhecido no alvo de compilacao.
|
||||
3. Mismatch detectavel no compile target MUST falhar no compilador antes da serializacao final.
|
||||
|
||||
### 9) Debug minimo v1 (inspirado em line tables)
|
||||
|
||||
1. `debug_info` v1 MUST incluir:
|
||||
- `function_names` para todos os `func_idx` emitidos;
|
||||
- `pc_to_span` para todo inicio de instrucao emitida.
|
||||
2. O objetivo minimo e preservar atribuicao de fonte acionavel para falhas backend/runtime que permaneçam source-atribuiveis.
|
||||
|
||||
### 10) Fronteira de validacao por camada
|
||||
|
||||
Modelo inspirado em separacao JVM (format/link/verify), adaptado:
|
||||
|
||||
1. emitter valida formato e invariantes de marshaling;
|
||||
2. loader valida resolucao canonica, capability e ABI host;
|
||||
3. verifier valida estrutura de controle e pilha na imagem patchada.
|
||||
|
||||
O backend MUST executar prechecks de marshaling sem substituir a autoridade do loader/verifier.
|
||||
|
||||
### 11) Taxonomia de erros de marshaling
|
||||
|
||||
O backend MUST expor codigos estaveis para erros de marshaling em familias:
|
||||
|
||||
1. `MARSHAL_FORMAT_*`,
|
||||
2. `MARSHAL_LINKAGE_*`,
|
||||
3. `MARSHAL_VERIFY_PRECHECK_*`.
|
||||
|
||||
Quando atribuivel, diagnostico MUST incluir ancora de fonte primaria.
|
||||
|
||||
### 12) Otimizacao: criterio de responsabilidade
|
||||
|
||||
1. Otimizacao semantica/estrutural de programa MUST ocorrer no backend (compile-time).
|
||||
2. Runtime MUST permanecer focado em carregamento, validacao e execucao deterministica.
|
||||
3. Ajustes internos de runtime sao permitidos apenas se nao alterarem semantica do programa nem contrato observavel de bytecode.
|
||||
|
||||
### 13) Suite minima Gate I (sem packer)
|
||||
|
||||
A conformidade minima de integracao MUST incluir fixtures:
|
||||
|
||||
1. `SYSC` presente e vazio (caso sem hostcall);
|
||||
2. `HOSTCALL` valido com patch para `SYSCALL`;
|
||||
3. `HOSTCALL` com indice fora de faixa;
|
||||
4. `SYSC` declarado e nao usado;
|
||||
5. `SYSCALL` bruto em artefato pre-load;
|
||||
6. mismatch de ABI (`arg_slots`/`ret_slots`);
|
||||
7. capability insuficiente em load-time;
|
||||
8. caminho com `INTRINSIC` valido.
|
||||
|
||||
### 14) Deferrals explicitos
|
||||
|
||||
Sem deferrals de perguntas abertas desta agenda.
|
||||
|
||||
Permanecem fora de escopo por fronteira:
|
||||
|
||||
1. formato de packer/cartucho final;
|
||||
2. superfices avancadas de simbolizacao alem do minimo v1.
|
||||
|
||||
## Expected Spec Material
|
||||
|
||||
1. Atualização de `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`.
|
||||
2. Atualização de `docs/general/specs/19. Verification and Safety Checks Specification.md`.
|
||||
3. Decision record de “bytecode backend v1 marshaling contract”.
|
||||
4. Plano de testes Gate I para backend executável.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Definir fluxo de empacotamento final de cartucho.
|
||||
- Alterar o contrato do loader/runtime.
|
||||
- Definir formato final de symbolication completo.
|
||||
- Cobrir perf tuning de emissor.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `prometeu-compiler/prometeu-build-pipeline/src/main/java/p/studio/compiler/workspaces/stages/EmitBytecodePipelineStage.java`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/model.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/assembler.rs`
|
||||
- `../runtime/crates/console/prometeu-bytecode/src/program_image.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/virtual_machine/loader.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/vm_init_error.rs`
|
||||
- `../runtime/crates/console/prometeu-vm/src/verifier.rs`
|
||||
- `docs/pbs/specs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
||||
- `docs/general/specs/15. Bytecode and PBX Mapping Specification.md`
|
||||
Reference in New Issue
Block a user