docs: correct DUART report - host port test is local loopback (service guide), wiring verified sound, missing THRA write is the real bug

harness/mame/DUART_REPORT.md

@@ -276,3 +276,83 @@ modification (verified: `git status` in the MAME tree shows only `tms34010.cpp`
 * `harness/mame/duart_probe.lua` — breakpoints on the host-port test's comparisons and
   register writes (the evidence in §4).
 * `harness/mame/DUART_REPORT.md` — this report.
+
+---
+
+# ORCHESTRATOR CORRECTION — §0 and §4 conclusions are superseded
+
+Reviewed after delivery. **The wiring and the remap in §1–§2 are correct and stand**
+(I re-verified the remap against MAME's source, below). The **conclusion** in §0/§4 —
+that the host-port test "needs an external responder" and cannot pass without one —
+**does not stand.** Three grounds.
+
+## 1. The service guide says this test is local loopback
+
+`docs/EK-V1000-SV-002_service-guide.txt`:
+
+> 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.
+
+External loopback is a separate opt-in selection ("External loopback: host port",
+bit 0). It is off by default. So the failing test must pass with **no external
+equipment** — which is what we independently know from the real terminal booting
+normally, and from level 0 already passing in this harness.
+
+## 2. §4's own evidence is the loopback signature — with the transmit missing
+
+§4 already establishes that the firmware sets MR2 = 0x80 (local loopback) and then
+expects **5 bytes to have arrived and set overrun** (`SRA & 0xF0 == 0x10`, and
+`STATUS_OVERRUN_ERROR = 0x10`) in a 4-deep FIFO. A 5-byte burst overflowing a 4-deep
+FIFO is exactly what **transmitting 5 bytes in local loopback** produces. And the ROM
+table `0xAA,0xFF,0xAA,0x55` is far more plausibly the **transmit** pattern (a BIST
+pattern) than an inbound host stream — no host sends that.
+
+So the open question is not "who supplies the pattern". It is **why the firmware never
+writes THRA.**
+
+## 3. MAME's semantics, verified (this changes what §2/§4 mean)
+
+Read from `src/devices/machine/mc68681.cpp`:
+
+* `duart_base_device::read/write(offs_t offset)` do **`offset &= 0xf`** — they take a
+  **register index 0..0xF** directly. Channel A = regs `0x0–0x3`, channel B = `0x8–0xB`.
+  * reg `0x3` **write = THRA**, read = RHRA; reg `0xB` likewise for channel B.
+  * reg `0xD` read = **IP** (the monitor switch). **So §2's remap is right.**
+* `write_CR()` takes the command from **`(data >> 4) & 0x07`**, and **enables the channel
+  from `BIT(data, 0)`**. Consequences that contradict §2/§4's reading:
+  * the init sequence `0xCA,0x2A,0x3A,0x4A,0x5A,0x1A` has **bit 0 = 0 in every value**,
+    i.e. every one of them **disables**; they are not "the command nibbles" in the low
+    nibble sense;
+  * the host-port test's `CRA=0x05` is the **enable** (bit 0 set); the following
+    `CRA=0x0A` **disables again**.
+* `recalc_framing()` sets `set_data_frame(1, (MR1 & 3) + 5, ...)`. So **5-bit characters
+  require `MR1 & 3 == 0`**. §4 says the test writes `MR1A = 0x12`; `0x12 & 3 == 2`
+  → **7 bits**. But §4 also says the expected received bytes are the pattern masked by
+  **`0x1F`** (5 bits). **Those two cannot both be true** — one is misread, and resolving
+  it tells us what the test is really doing.
+
+## 4. Ruled out, so not the cause
+
+* The DUARTs are registered **after** the board-window model (`vt1200.cpp` 630–651), so
+  they win offs `0–0xF` and fall through to the board model above that. Not shadowed.
+* The DUART handlers log through the **same** `log_pc_access()` as the board model
+  (lines 731/744), and `duart1_w` covers the whole window (`< 0x10` → DUART, else board).
+  So a THRA write **would** have appeared in the `VT1200_BOARD_LOG` transcript too.
+  "No write to `06400003`" is a **real** observation, not a logging gap.
+
+## 5. Leading hypothesis for the missing transmit
+
+The task did not wire `m_duart1->irq_cb()` to the CPU, and §7 notes both that the ROM
+has a DUART ISR (`L3FA78D90`) and that transmit routines exist at
+`3FA79C00`/`3FA7B8E0`/`3FA7BAA0` but are **not reached**. MAME's TMS34010 receives
+external interrupts through `execute_set_input()`: line 0 → `INTPEND` bit
+`TMS34010_INT1`, line 1 → `TMS34010_INT2` (tms34010.cpp 817–838), gated by `REG_INTENB`.
+"Transmitter never fed" + "ISR not wired" + "transmit routines unreached" have one
+obvious common cause: **an ISR-driven transmit whose interrupt is never delivered.**
+
+**Caveat to check first:** an earlier note in this project records that INTENB never
+enables, because the level-0 restart enters at `3F208060` with `DINT`. If the CPU really
+runs with interrupts disabled during the tests, an IRQ-driven transmit cannot work
+either — establish whether the test enables interrupts before relying on this.