portugalfuturista/universalisos
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

AGENTS.md: ULTRA RULE — never run code outside a debug session (rule 10)

Browse source
This commit is contained in:
Fábio Coutada 2026-07-18 18:38:38 +01:00
parent b5b29759af
commit 5f358c6724
1 changed files with 8 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
AGENTS.md
View file

@ -2,6 +2,11 @@
Safety-critical type-1 hypervisor (ARMv7 primary, AArch64/RISC-V in progress) implementing PikeOS 5.0 patterns.
## ULTRA RULE — READ FIRST, ALWAYS
**DEBUG IS YOUR ONLY OPTION. You NEVER run code outside of a debug session. EVER.**
Every execution — QEMU or hardware, any test, any boot — runs with GDB attached (or the GDB stub active and driving the session). No exceptions. No "quick runs". No serial-only observations. If the target executes, a debugger is controlling it.
## ABSOLUTE RULES — READ BEFORE DOING ANYTHING
### LESSONS LEARNED — 2026-07-17 Incident (All Errors Committed)
@ -60,7 +65,9 @@ Safety-critical type-1 hypervisor (ARMv7 primary, AArch64/RISC-V in progress) im
9. **Se o utilizador disser PARA, PÁRA.** Não faças mais mudanças. Não "fixes" sem permissão. Espera instruções.
10. **GDB/GDB STUB É OBRIGATÓRIO EM TODOS OS TESTES.** Sempre que correres QEMU ou testes em hardware (especialmente ESP32), deves usar GDB com GDB stubs. Isto aplica-se a:
10. **ULTRA RULE — NUNCA corras código fora de uma sessão de debug. SEMPRE.** Qualquer execução de código — hardware ou QEMU, teste ou validação, bootloader, kernel, ou app — TEM de correr com GDB attached (GDB stub, JTAG/OpenOCD, ou QEMU `-s -S`). Não há exceções. Se o código corre sem debugger, é uma violação da regra. "Debug é a tua única opção." Ver detalhes na secção "Verification Workflow" abaixo.
10a. **GDB/GDB STUB É OBRIGATÓRIO EM TODOS OS TESTES.** Sempre que correres QEMU ou testes em hardware (especialmente ESP32), deves usar GDB com GDB stubs. Isto aplica-se a:
- **QEMU:** `qemu-system-* -s -S` (GDB stub na porta 1234). O GDB attach é feito com `target remote :1234`.
- **ESP32 hardware:** O GDB stub integrado (em `microkernel/ports/esp32/uos_gdbstub.c`) é ativado pelo `break 0,0` em `_start`. Comunicação via UART0 a 115200 usando o protocolo RSP (Remote Serial Protocol).
- **Bootloader bring-up:** Usar GDB para single-step, ler registos, e verificar estado em cada etapa da cadeia de boot.