[PERF] Host Debug Overlay Isolation

This commit is contained in:
2026-04-10 10:55:15 +01:00
parent f5580ae0ce
commit 47ab664280
21 changed files with 526 additions and 154 deletions
@@ -0,0 +1,53 @@
---
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/`.
@@ -0,0 +1,35 @@
# 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).