This commit is contained in:
@@ -1,53 +0,0 @@
|
||||
---
|
||||
id: DEC-0007
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: Decision - [PERF] Host Debug Overlay Isolation
|
||||
status: accepted
|
||||
created: 2026-04-10
|
||||
updated: 2026-04-10
|
||||
agenda: AGD-0012
|
||||
tags: [performance, host, gfx]
|
||||
---
|
||||
|
||||
# Decision - [PERF] Host Debug Overlay Isolation
|
||||
|
||||
## Status
|
||||
**Accepted**
|
||||
|
||||
## Contexto
|
||||
O overlay de debug do PROMETEU, utilizado para exibir telemetria, logs e métricas em tempo real, está atualmente acoplado ao pipeline de renderização emulado (`gfx`) e ao processamento do runtime. Isso resulta em:
|
||||
1. **Distorção de Performance:** O custo de formatar strings e realizar chamadas de desenho para o HUD técnico é contabilizado como ciclos do jogo, invalidando medições de certificação.
|
||||
2. **Acoplamento Indevido:** O pipeline `gfx` emulado processa elementos visuais (HUD) que não existem no hardware original.
|
||||
3. **Complexidade no Host:** O Host precisa lidar com a injeção dessas informações no buffer de emulação.
|
||||
|
||||
## Decisao
|
||||
Fica decidido que o overlay de debug será movido integralmente para a camada **Host Desktop** (`prometeu-host-desktop-winit`), operando de forma 100% isolada do runtime e do pipeline de `gfx` emulado.
|
||||
|
||||
1. **Isolamento de Pipeline:** O overlay técnico deve ser tratado como uma "película" (layer) transparente aplicada pelo Host sobre o resultado final da renderização (pós-upscaling).
|
||||
2. **Isolamento de Processamento:** Nenhuma instrução de desenho ou formatação de strings relacionada ao overlay deve ocorrer dentro do runtime ou durante os ciclos emulados.
|
||||
3. **Acesso via API:** O Host acessará os dados necessários para o overlay através de uma API de telemetria passiva (baseada em atômicos, conforme definido na `DEC-0005`).
|
||||
4. **Acionamento via F1:** O controle de visibilidade (toggle) do overlay é de responsabilidade exclusiva do Host, acionado pela tecla **F1**.
|
||||
|
||||
## Rationale
|
||||
- **Pureza de Medição:** Ao remover o processamento do overlay do runtime, garantimos que 100% dos ciclos medidos pertencem à lógica do cartucho e periféricos emulados.
|
||||
- **Desempenho no Hardware Alvo:** Como o overlay é exclusivo de Desktop, dispositivos handheld/consoles de baixo custo não devem pagar o preço de implementação ou ramificações lógicas para lidar com HUD técnico.
|
||||
- **Qualidade Visual:** Utilizar o Host para renderizar o HUD permite o uso de fontes TrueType nítidas e Alpha Blending real, melhorando drasticamente a legibilidade para o desenvolvedor sem afetar a fidelidade da emulação.
|
||||
|
||||
## Invariantes / Contrato
|
||||
- **Zero Overhead no Runtime:** A presença ou ausência do overlay não deve alterar o contador de ciclos consumidos por frame no runtime.
|
||||
- **Agnosticismo de GFX:** O framebuffer emulado deve conter apenas os pixels gerados pelo cartucho, sem HUD técnico "queimado" na imagem.
|
||||
- **Composição Assíncrona/Passiva:** O Host não deve bloquear o runtime para coletar dados para o overlay; a leitura deve ser feita a partir de buffers de telemetria já expostos.
|
||||
|
||||
## Impactos
|
||||
- **Host (Desktop Winit):** Exige a implementação de uma camada de renderização nativa (ex: `egui` ou composição direta via `pixels`/`winit`) que suporte transparência.
|
||||
- **Runtime API:** Deve expor campos de telemetria (FPS, Memory Usage, Cycles) via API para consumo pelo Host.
|
||||
- **Especificações:** Atualização dos capítulos de Portabilidade e Debug para refletir o isolamento.
|
||||
|
||||
## Referencias
|
||||
- `AGD-0012`: [PERF] Host Debug Overlay Isolation (Agenda de Origem).
|
||||
- `DEC-0005`: [PERF] Push-based Telemetry Model (Modelo de acesso aos dados).
|
||||
|
||||
## Propagacao Necessaria
|
||||
1. Remover hotspots de desenho de texto no `runner.rs` do host.
|
||||
2. Implementar o novo sistema de HUD no host usando bibliotecas nativas.
|
||||
3. Atualizar a documentação técnica em `docs/specs/runtime/`.
|
||||
@@ -1,35 +0,0 @@
|
||||
# DEC-0008: Full Migration to Atomic Telemetry
|
||||
|
||||
## Status
|
||||
Accepted
|
||||
|
||||
## Contexto
|
||||
Após o sucesso inicial do `AtomicTelemetry` (DEC-0007), identificou-se que a coexistência com os campos legados `telemetry_current` e `telemetry_last` no `VirtualMachineRuntime` é contraproducente. O usuário solicitou a remoção completa da camada de compatibilidade para simplificar o motor e garantir que o modelo atômico seja a única fonte de verdade para performance e inspeção.
|
||||
|
||||
## Decisao
|
||||
1. **Remoção Total:** Eliminar os campos `telemetry_current` e `telemetry_last` da struct `VirtualMachineRuntime`.
|
||||
2. **Modelo Único:** O `AtomicTelemetry` passa a ser a única estrutura responsável por rastrear métricas de execução (ciclos, memória, logs).
|
||||
3. **Snapshot On-Demand:** Qualquer necessidade de telemetria estática (ex: para logs de erro ou final de frame) deve ser atendida pelo método `AtomicTelemetry::snapshot()`, que gera um `TelemetryFrame` imutável a partir do estado atômico atual.
|
||||
4. **Atualização Condicional:** A atualização dos campos atômicos dentro do loop de `tick` da VM permanece protegida por `inspection_active`, garantindo overhead zero em modo de produção.
|
||||
|
||||
## Rationale
|
||||
- **Simplicidade:** Reduz o número de campos no `VirtualMachineRuntime`.
|
||||
- **Performance:** Evita a cópia de dados entre `telemetry_current` e `telemetry_last` ao final de cada frame.
|
||||
- **Consistência:** Garante que o Host e o Runtime vejam os mesmos dados através da mesma API.
|
||||
|
||||
## Invariantes / Contrato
|
||||
- O `VirtualMachineRuntime` deve possuir uma instância de `Arc<AtomicTelemetry>`.
|
||||
- O `AtomicTelemetry` deve ser thread-safe (já garantido pelo uso de `std::sync::atomic`).
|
||||
|
||||
## Impactos
|
||||
- **Runtime:** Alteração na struct principal e no loop de tick.
|
||||
- **HAL:** Possível ajuste no `LogService` se ele dependia diretamente dos campos legados.
|
||||
- **Docs:** Necessidade de atualizar as especificações de Debug e Portabilidade.
|
||||
|
||||
## Referencias
|
||||
- AGD-0021 (Migration Agenda)
|
||||
- DEC-0007 (Overlay Isolation Decision)
|
||||
|
||||
## Propagacao Necessaria
|
||||
- Refatoração de `VirtualMachineRuntime`.
|
||||
- Atualização de `prometeu-host-desktop-winit` para garantir que continua funcionando (já migrado no PLN-0006, mas deve ser validado).
|
||||
@@ -1,61 +0,0 @@
|
||||
---
|
||||
id: DEC-0009
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: Decision - [PERF] Host Overlay Tooling Boundary
|
||||
status: accepted
|
||||
created: 2026-04-10
|
||||
updated: 2026-04-10
|
||||
agenda: AGD-0022
|
||||
tags: [performance, host, gfx, overlay]
|
||||
---
|
||||
|
||||
# Decision - [PERF] Host Overlay Tooling Boundary
|
||||
|
||||
## Status
|
||||
**Accepted**
|
||||
|
||||
## Contexto
|
||||
`DEC-0007` já determinou que o overlay técnico do desktop deve existir no Host e fora do pipeline de `gfx` emulado. Durante a execução, surgiu uma ambiguidade adicional: a implementação corretiva poderia ser interpretada como remoção ou desvalorização de `fill_rect` e `draw_text`, quando essas primitives continuam fazendo parte legítima do contrato gráfico atual da máquina emulada.
|
||||
|
||||
Também ficou explícito que “estar no host” não é suficiente se o overlay ainda desenhar usando `hardware.gfx`. O limite correto é mais estrito: o overlay deve possuir ferramentas próprias e compor em camada separada no host.
|
||||
|
||||
## Decisao
|
||||
Fica decidido que o contrato do overlay técnico do desktop host será refinado da seguinte forma:
|
||||
|
||||
1. **Preservação do Contrato Emulado:** `fill_rect` e `draw_text` MUST remain part of the current syscall and emulated hardware contract. They MUST NOT be removed, weakened, or repurposed because of host overlay work.
|
||||
2. **Separação de Ferramentas:** O overlay técnico do desktop host MUST use dedicated host-side tooling for panel composition, text rendering, simple bars, and alert presentation.
|
||||
3. **Proibição de Dependência do Hardware Emulado:** O overlay MUST NOT call, depend on, or route through `hardware.gfx`, `fill_rect`, `draw_text`, or any equivalent emulated-framebuffer primitive.
|
||||
4. **Camada Separada no Host:** O overlay MUST be rendered in a separate host layer/surface after the emulated frame is produced. The emulated framebuffer MAY be transported into the host presentation surface, but overlay pixels MUST NOT be written back into the emulated framebuffer.
|
||||
5. **Módulo Dedicado:** A dedicated host module SHALL own overlay rendering behavior. The implementation MUST NOT remain embedded as ad hoc overlay drawing logic inside `runner.rs`.
|
||||
6. **Escopo Visual Mínimo:** Para este ciclo, o overlay SHOULD remain intentionally simple: semitransparent panel, text, and simple bars where useful. It MUST NOT introduce a general UI framework, docking model, or movable window system.
|
||||
7. **Responsabilidade do Runtime:** O runtime MUST remain responsible only for telemetry exposure and inspection state gating. It MUST NOT own overlay drawing behavior, layout policy, or visual composition.
|
||||
|
||||
## Rationale
|
||||
- **Clareza de Fronteira:** Preservar o contrato da máquina e mover apenas o overlay evita misturar API emulada com inspeção técnica de host.
|
||||
- **Pureza do Framebuffer:** Uma camada separada elimina a contaminação visual do framebuffer emulado e torna a validação objetiva.
|
||||
- **Simplicidade Controlada:** Texto e barras simples resolvem legibilidade sem transformar o host overlay em um projeto paralelo de UI.
|
||||
- **Manutenibilidade:** Um módulo dedicado reduz o risco de regressão arquitetural em `runner.rs`.
|
||||
|
||||
## Invariantes / Contrato
|
||||
- `fill_rect` e `draw_text` continuam válidos para o domínio emulado.
|
||||
- O overlay técnico do host não escreve no framebuffer emulado.
|
||||
- O overlay técnico do host não depende de primitives do hardware emulado.
|
||||
- O módulo de overlay é de responsabilidade exclusiva do host desktop.
|
||||
- O ponto de composição do overlay ocorre depois que o frame emulado já está pronto para apresentação no host.
|
||||
|
||||
## Impactos
|
||||
- **Host (Desktop Winit):** Exige um módulo próprio de overlay e uma estratégia de composição em camada separada.
|
||||
- **Runtime API:** Nenhuma mudança conceitual adicional além de continuar expondo telemetria passiva e gating de inspeção.
|
||||
- **Specs:** As especificações de debug e portabilidade devem distinguir explicitamente o contrato emulado das ferramentas de overlay do host.
|
||||
- **Plano de Execução:** `PLN-0008` deve ser atualizado para refletir módulo dedicado e camada separada no host.
|
||||
|
||||
## Referencias
|
||||
- `AGD-0022`: [PERF] Host Overlay Tooling Boundary Revision.
|
||||
- `DEC-0007`: [PERF] Host Debug Overlay Isolation.
|
||||
- `DEC-0008`: Full Migration to Atomic Telemetry.
|
||||
|
||||
## Propagacao Necessaria
|
||||
1. Atualizar `PLN-0008` para refletir o módulo dedicado e a camada separada no host.
|
||||
2. Implementar o módulo de overlay no `prometeu-host-desktop-winit`.
|
||||
3. Remover o uso de `hardware.gfx` pelo overlay técnico.
|
||||
4. Atualizar as specs para preservar o contrato gráfico emulado e separar a composição do overlay host.
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
id: DEC-0010
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
|
||||
status: accepted
|
||||
created: 2026-04-10
|
||||
updated: 2026-04-10
|
||||
agenda: AGD-0023
|
||||
tags: [performance, host, telemetry, logs]
|
||||
---
|
||||
|
||||
# Decision - [PERF] Overlay Log Metric Uses Last Completed Frame
|
||||
|
||||
## Status
|
||||
**Accepted**
|
||||
|
||||
## Contexto
|
||||
O campo `LOGS` do overlay técnico do desktop host estava lendo um contador transitório incrementado durante o frame e zerado no fechamento do frame lógico. Como o Host compõe o overlay de forma assíncrona em relação ao loop interno da máquina, esse valor visual tende a aparecer como `0` mesmo sob stress com alta emissão de logs.
|
||||
|
||||
## Decisao
|
||||
1. O valor visual `LOGS` exposto ao overlay MUST represent the number of logs emitted during the last completed logical frame.
|
||||
2. O contador transitório intra-frame MAY continue to exist for internal collection and frame-end aggregation, but it MUST NOT be exposed diretamente como métrica visual do overlay.
|
||||
3. O `AtomicTelemetry::snapshot()` MUST expose the persisted last-frame value for `logs_count`.
|
||||
4. A certificação MUST evaluate log pressure against the persisted last completed frame value, not against a host-timing-dependent transient value.
|
||||
|
||||
## Rationale
|
||||
- O overlay precisa de um valor estável e observável pelo Host.
|
||||
- O frame fechado é a unidade correta para comparação com outras métricas como ciclos e syscalls.
|
||||
- A mesma semântica serve tanto para overlay quanto para certificação, evitando ambiguidade.
|
||||
|
||||
## Invariantes / Contrato
|
||||
- `logs_count` em `TelemetryFrame` significa `logs from last completed logical frame`.
|
||||
- O reset do contador transitório não pode apagar o valor persistido exposto ao Host.
|
||||
- O overlay não deve depender de timing fino entre renderização do Host e fechamento do frame lógico.
|
||||
|
||||
## Impactos
|
||||
- **HAL:** `AtomicTelemetry` precisa persistir o valor de logs do frame concluído.
|
||||
- **Runtime:** no fechamento do frame, o valor de logs do frame deve ser copiado antes do reset do contador transitório.
|
||||
- **Host overlay:** nenhuma mudança conceitual adicional além de passar a receber um valor útil e estável.
|
||||
- **Specs:** capítulo de debug deve deixar explícita a semântica de `logs_count`.
|
||||
|
||||
## Referencias
|
||||
- `AGD-0023`: [PERF] Overlay Log Metric Must Show Last Frame.
|
||||
- `DEC-0008`: Full Migration to Atomic Telemetry.
|
||||
- `DEC-0009`: Host Overlay Tooling Boundary.
|
||||
|
||||
## Propagacao Necessaria
|
||||
1. Atualizar `PLN-0008` para incluir a semântica last-frame de `LOGS`.
|
||||
2. Ajustar HAL e runtime para persistir `logs_count` ao final do frame.
|
||||
3. Atualizar a especificação de debug.
|
||||
Reference in New Issue
Block a user