97 lines
5.2 KiB
Markdown
97 lines
5.2 KiB
Markdown
---
|
|
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)*
|