This commit is contained in:
@@ -1,49 +0,0 @@
|
||||
---
|
||||
id: AGD-0012
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: Agenda - [PERF] Host Debug Overlay Isolation
|
||||
status: done
|
||||
created: 2026-03-27
|
||||
resolved: 2026-04-10
|
||||
decision: DEC-0007
|
||||
tags: [performance, host, gfx]
|
||||
---
|
||||
|
||||
# Agenda - [PERF] Host Debug Overlay Isolation
|
||||
|
||||
## Contexto
|
||||
O overlay de debug é uma ferramenta exclusiva para o ambiente **Desktop** (`prometeu-host-desktop-winit`). Ele visa fornecer telemetria em tempo real para desenvolvedores sem impactar a fidelidade da emulação ou o desempenho medido do hardware final (handhelds/consoles de baixo custo), onde este overlay não existirá.
|
||||
|
||||
## Problema
|
||||
Atualmente, o overlay de debug está indevidamente acoplado ao pipeline de `gfx` emulado e ao processamento do runtime.
|
||||
- **Distorção de Performance:** O custo de renderizar o HUD técnico (formatação de strings e draw calls extras) é contabilizado como custo do jogo.
|
||||
- **Acoplamento de Pipeline:** O pipeline de `gfx` precisa processar elementos que não pertencem à lógica da máquina virtual.
|
||||
- **Hotspots:** `runner.rs` realiza `present()` extra e manipulação de texto no loop principal.
|
||||
|
||||
## Pontos Críticos
|
||||
- **Fato:** O overlay é uma necessidade de desenvolvimento Desktop, não uma funcionalidade da máquina `prometeu`.
|
||||
- **Risco:** Qualquer processamento de overlay dentro do runtime `prometeu` invalida a pureza dos ciclos medidos para certificação.
|
||||
- **Tradeoff:** Mover o overlay para o Host exige acesso assíncrono ou passivo aos dados de telemetria.
|
||||
- **Hipótese:** Um overlay 100% nativo no Host (Winit/Pixels) usando fontes TrueType terá custo desprezível e legibilidade superior.
|
||||
|
||||
## Opções
|
||||
- **Opção A (Recomendada):** Camada Host Nativa. O `HostRunner` renderiza o HUD em uma surface separada ou faz um *compositing* nativo após o upscaling do framebuffer do console.
|
||||
- **Opção B:** Overlay via IPC/Sidecar. Ferramenta externa de inspeção (descartada por complexidade visual).
|
||||
- **Opção C:** Manter no `gfx` emulado com otimização (descartada por não resolver o acoplamento).
|
||||
|
||||
## Sugestão / Recomendação
|
||||
1. **Agnosticismo de GFX:** O overlay deve ser tratado como uma "película" transparente aplicada pelo Host Desktop sobre o resultado final da renderização.
|
||||
2. **Isolamento de Processamento:** Nenhuma instrução de desenho ou formatação de strings do overlay deve ocorrer dentro do runtime.
|
||||
3. **Acesso via API:** O Host acessará os dados de telemetria através de uma API dedicada (baseada no modelo push-based da `DEC-0005`).
|
||||
4. **Interface de Controle:** O acionamento permanece via tecla **F1** como um *toggle*, gerenciado pela camada de Host.
|
||||
5. **Composição via Host:** Utilizar bibliotecas nativas do Host para renderizar o HUD com fontes TrueType nítidas e Alpha Blending real.
|
||||
|
||||
## Perguntas em Aberto
|
||||
- Nenhuma. As questões sobre acesso via API e acionamento via F1 foram resolvidas durante a discussão.
|
||||
|
||||
## Critério para Encerrar
|
||||
A agenda é considerada encerrada quando:
|
||||
- Houver consenso sobre o isolamento total do pipeline de `gfx`.
|
||||
- O método de acesso aos dados (API) estiver definido.
|
||||
- O controle de interface (F1) estiver estabelecido.
|
||||
*(Critérios atingidos em 2026-04-10)*
|
||||
@@ -1,31 +0,0 @@
|
||||
# AGD-0021: Full Migration to Atomic Telemetry
|
||||
|
||||
## Contexto
|
||||
Durante a implementação do isolamento do overlay de debug no Host Desktop (DEC-0007), foi introduzido o `AtomicTelemetry` para permitir acesso assíncrono e sem locks aos dados de performance. Por motivos de cautela inicial, os campos legados `telemetry_current` e `telemetry_last` foram mantidos no `VirtualMachineRuntime` para compatibilidade com processos de certificação e logs internos.
|
||||
|
||||
## Problema
|
||||
A manutenção de dois sistemas paralelos de telemetria gera redundância de código, aumenta a superfície de erro e consome ciclos de CPU desnecessários para atualizar dados que já estão disponíveis de forma mais eficiente via atômicos. A "compatibilidade" pretendida não justifica o débito técnico de manter estruturas duplicadas.
|
||||
|
||||
## Pontos Críticos
|
||||
- **Fato:** `AtomicTelemetry` já provê todos os dados necessários (ciclos, memória, logs).
|
||||
- **Risco:** Remoção de `telemetry_last` pode quebrar ferramentas que dependem de snapshots estáticos por frame se não houver um substituto claro de snapshot via atômicos.
|
||||
- **Tradeoff:** A migração exige refatorar o `VirtualMachineRuntime` e possivelmente o `LogService` para convergirem em uma única fonte de verdade.
|
||||
- **Hipótese:** Um snapshot derivado do `AtomicTelemetry` ao final de cada frame é suficiente para substituir o `telemetry_last` legado sem perda de precisão.
|
||||
|
||||
## Opções
|
||||
- **Opção A (Recomendada):** Migração total e remoção dos campos legados. O `AtomicTelemetry` torna-se a única fonte de verdade. Onde snapshots estáveis são necessários, eles são extraídos via `AtomicTelemetry::snapshot()`.
|
||||
- **Opção B:** Manter redundância (Descartada pelo usuário).
|
||||
|
||||
## Sugestão / Recomendação
|
||||
1. Remover `telemetry_current` e `telemetry_last` do `VirtualMachineRuntime`.
|
||||
2. Refatorar o loop de execução para atualizar exclusivamente o `AtomicTelemetry`.
|
||||
3. Garantir que o `LogService` e outras auditorias consumam dados do novo modelo.
|
||||
4. Atualizar as especificações para refletir o modelo único.
|
||||
|
||||
## Perguntas em Aberto
|
||||
1. Existe algum uso específico de `telemetry_last` em ferramentas externas (não mapeadas) que dependem do layout de memória antigo? (Assumimos que não para este escopo).
|
||||
|
||||
## Criterio para Encerrar
|
||||
- Remoção completa dos campos no código.
|
||||
- Compilação e execução bem-sucedida do Host Desktop com o novo modelo único.
|
||||
- Atualização da documentação normativa.
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
id: AGD-0022
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: Agenda - [PERF] Host Overlay Tooling Boundary Revision
|
||||
status: accepted
|
||||
created: 2026-04-10
|
||||
resolved: 2026-04-10
|
||||
decision: DEC-0009
|
||||
tags: [performance, host, gfx, overlay]
|
||||
---
|
||||
|
||||
# Agenda - [PERF] Host Overlay Tooling Boundary Revision
|
||||
|
||||
## Contexto
|
||||
|
||||
`DEC-0007` fechou o movimento do overlay de debug para o `Host Desktop`, fora do runtime e fora do pipeline de `gfx` emulado. Durante a execução, a formulação acabou ficando forte demais em um ponto: passou a sugerir que `fill_rect` e `draw_text` deveriam deixar de existir no contrato atual, quando na verdade o usuário quer preservar essas ferramentas como parte válida do contrato de syscall atual.
|
||||
|
||||
O ajuste pedido agora é mais específico:
|
||||
- `fill_rect` e `draw_text` permanecem como parte do contrato atual da máquina e continuam disponíveis para uso legítimo do software emulado;
|
||||
- o overlay técnico de host não pode depender desse caminho;
|
||||
- o overlay deve possuir ferramentas próprias para compor o que for necessário no host, fora do `hardware.gfx`.
|
||||
|
||||
## Problema
|
||||
|
||||
Sem registrar essa revisão, a execução fica ambígua em dois pontos:
|
||||
- podemos remover ou enfraquecer APIs gráficas que não deveriam ser tocadas;
|
||||
- podemos continuar interpretando o overlay host como “qualquer desenho fora do runtime”, mesmo se ele ainda reutilizar primitives do hardware emulado.
|
||||
|
||||
O resultado é ruído entre contrato da máquina, contrato do host, e ferramentas de inspeção.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- **Fato:** O overlay continua sendo exclusivo do host desktop.
|
||||
- **Fato:** `fill_rect` e `draw_text` fazem parte do contrato atual de syscall e não devem ser removidos por causa do overlay.
|
||||
- **Risco:** Se o host overlay continuar apoiado em `hardware.gfx`, ele continua contaminando o framebuffer emulado.
|
||||
- **Risco:** Se criarmos “tools próprias” sem delimitar bem a fronteira, podemos introduzir um mini-subsistema paralelo sem contrato claro.
|
||||
- **Tradeoff:** Preservar o contrato atual da máquina simplifica compatibilidade, mas exige um caminho de composição separado no host para não misturar domínio emulado com inspeção técnica.
|
||||
|
||||
## Opcoes
|
||||
|
||||
- **Opção A (Recomendada):** Preservar `fill_rect`/`draw_text` como contrato do hardware emulado e criar um conjunto de ferramentas nativas do host para o overlay.
|
||||
- O overlay passa a usar renderer/layout/composição próprios do host.
|
||||
- O runtime continua apenas expondo dados.
|
||||
- O `hardware.gfx` fica reservado ao conteúdo da máquina emulada.
|
||||
|
||||
- **Opção B:** Generalizar `fill_rect`/`draw_text` para servirem também ao host overlay.
|
||||
- Reaproveita código existente.
|
||||
- Mantém o acoplamento semântico entre overlay técnico e hardware emulado.
|
||||
- Dificulta provar pureza do framebuffer.
|
||||
|
||||
- **Opção C:** Criar novas syscalls específicas de overlay no runtime.
|
||||
- Formaliza ferramentas novas, mas empurra responsabilidade de inspeção para dentro da máquina.
|
||||
- Viola a direção de host-only já aceita e reabre debate maior do que o necessário.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Seguir com a **Opção A** e revisar a decisão operacional nestes termos:
|
||||
|
||||
1. `fill_rect` e `draw_text` permanecem intactos como parte do contrato atual de syscall e do hardware emulado.
|
||||
2. O overlay técnico do desktop host não pode chamar nem depender dessas primitives do `hardware.gfx`.
|
||||
3. O host deve ter ferramentas próprias de overlay, com responsabilidades explícitas:
|
||||
- montagem dos dados exibidos;
|
||||
- layout do painel;
|
||||
- rasterização/composição nativa;
|
||||
- controle visual de transparência e tipografia.
|
||||
4. O runtime continua responsável apenas por telemetria e sinais de inspeção, nunca por desenho do overlay.
|
||||
5. A validação precisa provar dois limites:
|
||||
- o contrato gráfico emulado continua disponível;
|
||||
- o overlay técnico não escreve no framebuffer emulado.
|
||||
|
||||
Para este ciclo, o overlay deve permanecer deliberadamente simples:
|
||||
- painel semitransparente;
|
||||
- texto para métricas e estados;
|
||||
- barras básicas para uso relativo de orçamento/capacidade quando isso melhorar leitura;
|
||||
- sem badges decorativos, widgets complexos, docking, janelas móveis, ou mini-framework de UI.
|
||||
|
||||
Essa direção preserva o objetivo principal do ticket, que é a fronteira arquitetural correta, sem transformar o host overlay em um projeto próprio.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- A implementação deve ficar embutida em `runner.rs` inicialmente ou nascer como módulo dedicado (`overlay.rs`) desde o começo?
|
||||
- A composição será feita diretamente no buffer final do `pixels` ou via camada/render pass separada dentro do host?
|
||||
Nenhuma. Em 2026-04-10 foi acordado:
|
||||
- módulo dedicado para o overlay;
|
||||
- camada separada no host;
|
||||
- sem blit do overlay no framebuffer emulado;
|
||||
- o framebuffer emulado pode ser transportado para a surface/camada de overlay do host, nunca o contrário.
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode ser encerrada quando houver consenso explícito sobre:
|
||||
- preservação de `fill_rect` e `draw_text` no contrato atual;
|
||||
- proibição de uso dessas primitives pelo overlay técnico;
|
||||
- conjunto mínimo de ferramentas próprias do overlay no host;
|
||||
- ponto exato de composição no pipeline do desktop host.
|
||||
*(Critérios atingidos em 2026-04-10)*
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
id: AGD-0023
|
||||
ticket: perf-host-debug-overlay-isolation
|
||||
title: Agenda - [PERF] Overlay Log Metric Must Show Last Frame
|
||||
status: accepted
|
||||
created: 2026-04-10
|
||||
resolved: 2026-04-10
|
||||
decision: DEC-0010
|
||||
tags: [performance, host, telemetry, logs]
|
||||
---
|
||||
|
||||
# Agenda - [PERF] Overlay Log Metric Must Show Last Frame
|
||||
|
||||
## Contexto
|
||||
|
||||
Após mover o overlay para a camada de Host, o campo visual `LOGS` passou a expor um contador transitório compartilhado com o `LogService`. Esse contador é incrementado durante o frame e zerado no fechamento do frame lógico. Na prática, quando o Host lê a telemetria para desenhar o overlay, o valor visual tende a aparecer como `0`, mesmo em cenários com alta emissão de logs.
|
||||
|
||||
## Problema
|
||||
|
||||
O campo `LOGS` no overlay não está representando a informação útil para inspeção visual. Um valor transitório intra-frame é adequado para coleta interna, mas não para HUD técnico renderizado assíncronamente pelo Host.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- **Fato:** O Host lê a telemetria fora do momento exato em que o contador transitório atinge seu pico.
|
||||
- **Fato:** A certificação precisa continuar vendo a pressão de logs do frame completo.
|
||||
- **Risco:** Manter a semântica atual torna o campo visual enganoso e inutilizável.
|
||||
- **Tradeoff:** Precisamos preservar o contador transitório para coleta interna, mas expor ao overlay apenas um valor persistido do último frame fechado.
|
||||
|
||||
## Opcoes
|
||||
|
||||
- **Opção A (Recomendada):** Persistir `logs from last completed frame` no `AtomicTelemetry` e fazer o overlay ler apenas esse valor.
|
||||
- **Opção B:** Manter contador ao vivo e tentar amostrar em outro ponto do loop.
|
||||
- **Opção C:** Mostrar ambos os valores no overlay.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Seguir com a **Opção A**:
|
||||
|
||||
1. O contador transitório de logs continua existindo apenas para coleta interna durante o frame.
|
||||
2. No fechamento do frame lógico, o runtime persiste em `AtomicTelemetry` o total de logs do frame recém-concluído.
|
||||
3. O campo `LOGS` visível no overlay deve representar exclusivamente `logs from last completed frame`.
|
||||
4. A certificação deve continuar operando sobre esse mesmo valor persistido do frame concluído.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- Nenhuma. Em 2026-04-10 foi decidido que o overlay deve mostrar apenas logs do último frame concluído.
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
- semântica visual de `LOGS` definida como `last completed frame`;
|
||||
- certificação preservada;
|
||||
- implementação alinhada no HAL, runtime, overlay e specs.
|
||||
*(Critérios atingidos em 2026-04-10)*
|
||||
Reference in New Issue
Block a user