docs: level-1 test sequence, port tests vs device tests (keyboard/mouse device models needed for tests 26/27)

reference/level1-test-sequence.md

@@ -0,0 +1,101 @@
+# Level-1 test sequence — and which tests need real peripherals
+
+Source: `docs/EK-V1000-SV-002_service-guide.txt`
+(Table 2–2 = "the 15 level 1 tests", Table 2–4 = NCP test numbers,
+Table 2–5 = P3 mode bits, Table 3–4 = screen error messages).
+
+## The 15 level-1 tests (Table 2–2)
+
+Listed in the guide as two columns; the true execution order is not certain from
+this table alone. Reading the columns separately:
+
+| Left column | Right column |
+|---|---|
+| Video RAM test | DUART1 timer test |
+| Video test | Keyboard port test |
+| NVR checksum test | Mouse port test |
+| Ethernet address ROM test | DUART2 timer test |
+| Option RAM test (if present) | Ethernet port (LANCE) test |
+| Host port test | Mouse test |
+| Printer port test | Keyboard test |
+| Image test (if installed) | |
+
+## The distinction that matters: port tests vs device tests
+
+These are **different tests**, not two names for the same thing.
+
+| Test | Error code | Requirement |
+|---|---|---|
+| Host port test | 15 | host UART **local loopback** — no external equipment |
+| Printer port test | 16 | printer UART **local loopback** — no external equipment |
+| Keyboard **port** test | 18 | keyboard UART **local loopback** — no device |
+| Mouse **port** test | 19 | mouse UART **local loopback** — no device |
+| DUART timer 1 / 2 | 17 / 21 | the DUARTs themselves |
+| Ethernet port (LANCE) test | 24 | the LANCE chip's own loopback |
+| **Keyboard test** | **27** | **the real keyboard** |
+| **Mouse test** | **26** | **the real mouse / tablet** |
+
+The guide's own wording draws the line:
+
+> **Host Port Test** — Verifies the internal data paths of the host port's universal
+> asynchronous receiver transmitter (UART) **by using its local loopback mode**. If you
+> also choose the external loopback test, this test checks the driver and receiver
+> hardware as well.
+
+> **Keyboard Port Test** — Verifies the internal data paths of the keyboard UART **by
+> using its local loopback mode**. **There is no external loopback test for the keyboard
+> port.**
+
+> **Keyboard Test** — **Firmware requests that the keyboard do its self-test** and
+> display any error code.
+
+> **Mouse Test** — **Firmware requests that the mouse or tablet do its self-test** and
+> display any error code.
+
+So a *port* test drives the UART and needs nothing attached. A *device* test asks the
+attached device to run its own self-test and report back — which **requires the real
+device on the other end of the serial line**.
+
+External loopback is always a **separate opt-in**, not the default: P3 mode bits
+(Table 2–5) are `bit 0` = host port, `bit 1` = printer port, `bit 2` = mouse port,
+`bit 3` = LANCE. Default (P3 = 0) is local loopback only.
+
+## The peripherals are serial devices, on DUART2
+
+The VT1200 keyboard and mouse are serial devices, and the ROM's own test list names
+their ports directly:
+
+```
+E - DUART1, CHANNEL A (HOST)
+H - DUART2, CHANNEL A (KEYBOARD)
+I - DUART2, CHANNEL B (MOUSE)
+```
+
+So DUART1 = host + printer, DUART2 = keyboard + mouse — matching the split already
+used in `harness/mame/vt1200.cpp`.
+
+## Consequence for this project
+
+1. **The current gate is not a peripheral problem.** The host port test (error 15) is
+   host-UART local loopback. It needs no external responder, and the host is not a
+   keyboard or mouse in any case. This confirms the "ORCHESTRATOR CORRECTION" in
+   `harness/mame/DUART_REPORT.md`.
+2. **But two level-1 tests do need the devices** — *Keyboard test* (27) and *Mouse test*
+   (26) are in the level-1 list. The harness will have to model the LK201-style keyboard
+   and mouse. Best source for that is **not invention**: capture the real devices'
+   serial behaviour from the live terminal, the same way the earlier live-hardware work
+   captured other traffic.
+3. **Keep the models from leaking between tests.** The port tests are loopback; if a
+   keyboard model answers during the *keyboard port* test, that test can pass for the
+   wrong reason (and the reverse). The existing DUART TX→RX loopback wiring is already
+   selectable per DUART for exactly this reason (`VT1200_DUART_LB1`/`LB2`).
+
+## Related open question (level 0)
+
+`DUART_REPORT.md` §3 reports that the **level-0** I/O data-path test (`L3FDCE470`) writes
+`0xE1` to DUART2 channel A and then requires a **10-byte reply**. On real hardware the
+keyboard channel is answered by the keyboard. Note the anomaly: level 0 currently
+**passes** with the *board model* (which fabricates read values) but **fails** with a
+*real* DUART (which correctly reports "no data") — i.e. the fake is accidentally
+satisfying the test. Resolve when the DUART work resumes: either it is a loopback the
+firmware drives itself, or it needs the keyboard device model.