More information added

05_reversing/dynamic/serial_debug.md

@@ -111,6 +111,66 @@ MiSTer FPGA: the UART bridge is exposed on the MiSTer IO board or via the DE10-N
 
 ---
 
+## Decision Guide — Which Debug Output Method?
+
+| Method | Works During... | Requires | Throughput | Use Case |
+|---|---|---|---|---|
+| `kprintf()` | ROM init, crashes | Debug ROM or Kickstart 1.3 | Low (polled) | Kernel-level debugging |
+| `RawDoFmt + RawPutChar` | Any time after exec init | exec.library only | Medium | Universal: all Kickstart versions |
+| Direct `SERDAT` write | Anytime, even without OS | Nothing — bare metal | High (custom batching) | Crash handler, bootloader |
+| `dprintf` (debug.lib) | Application runtime | SAS/C debug.lib | Medium | Application-level tracing |
+| `serial.device` | Full OS running | serial.device open | High (interrupt-driven) | High-volume data transfer |
+
+---
+
+## Named Antipatterns
+
+### 1. "The Deadly Debug Printf"
+
+**What it looks like** — calling `printf()` or `VPrintf()` from inside a `Forbid()`/`Disable()` block:
+
+```c
+Forbid();
+printf("Processing item %d\n", i);  // BROKEN — calls dos.library!
+Permit();
+```
+
+**Why it fails:** `printf()` goes through `dos.library Write()` which may call `Wait()` for buffered I/O. Inside `Forbid()`, task switching is blocked — `Wait()` never returns → system deadlock. Inside `Disable()`, even worse — interrupts are off, so the system clock stops and the serial device can't transmit.
+
+**Correct:** Use `kprintf()` or `RawDoFmt + RawPutChar` inside Forbid/Disable — both bypass dos.library entirely.
+
+### 2. "The Baud Rate Mismatch"
+
+**What it looks like** — the Amiga outputs at 9600 baud but the host is configured for 115200:
+
+```bash
+# Host configured for 115200
+screen /dev/cu.usbserial 115200
+# Output: ¥φΩ≡ƒ╤ ╚α≡α≤φσ≡ ╔╞╒ ... (garbage)
+```
+
+**Why it fails:** The Amiga's default `SERPER` value after reset is for 9600 baud (on NTSC; PAL may differ). The host-side baud rate MUST match exactly. A single bit error in the start bit cascades into every subsequent bit being wrong.
+
+**Correct:** Set `SERPER` to a known value before output, or cycle through common baud rates on the host side (9600, 19200, 38400, 57600, 115200) until text becomes readable.
+
+---
+
+## FAQ
+
+### Why doesn't kprintf work on my Kickstart 3.1 ROM?
+
+`kprintf()` was removed from release Kickstart ROMs starting with 2.04. It only exists in debug/test ROMs and Kickstart 1.3. For 2.0+, use `RawDoFmt + RawPutChar` or the direct hardware approach.
+
+### Can I use the serial port without a null-modem cable?
+
+No. The Amiga's serial port is RS-232 level (not TTL). You need a null-modem cable or a USB-serial adapter with RS-232 voltage levels. Direct connection to a USB UART (3.3V TTL) will damage the hardware.
+
+---
+
+## References
+
+---
+
 ## References
 
 - NDK39: `exec/execbase.h` — `RawDoFmt`, `RawPutChar` LVOs