tools/tms34010-sdk: record the results -- GSPA (not as34), byte-exact round trip at bit 0x3F208000, 1990 tools are OS/2, dosemu 5x faster, plus the traps

tools/tms34010-sdk/README.md

@@ -28,15 +28,44 @@ The two tool packages — the only parts with durable technical value:
   1990-11-19 ... TIGA SDK r2.01 .................................zip
 ```
 
-The tools are **DOS-era disk images and ZIPs**, not loose binaries, so a
-DOSBox/dosemu step (or an extraction plus native reimplementation) is likely
-required before anything runs. **That question is open** — see
-`reference/tms34010-sdk.md` for the investigation.
+## It works, and the round trip is byte-exact
 
-**The most valuable single experiment** is the round trip: `smart34010`'s output
-claims to be assemblable by `as34`, so disassembling a known ROM region,
-reassembling it and diffing against the original bytes would prove the toolchain
-against this exact firmware.
+The **1987** toolchain runs headless in DOSBox: **GSPA 2.00** (assembler),
+**GSPLNK 2.00** (linker), **GSPROM 2.01**, and the **K&R C compiler**.
+
+**There is no `as34`/`lnk34`** — the assembler is `GSPA`. (`smart34010`'s README
+names `as34`; that appears to be a later name or another part, not this SDK.)
+
+**The round trip is proven against this exact firmware**: 32 KB at bit
+`0x3F208000` reassembles **byte-for-byte identical** (region md5
+`43adb6669571041985f3e26fd9ff7cb9`), plus a 16 KB and two 4 KB regions. Five
+fixups are needed on the disassembly first: `0x`→`h` suffix, `MOVI` W/L forms,
+the B-file `SP`, long relative `JR` misprinted as `JA` by `dis34`, and raw
+`.word` for branches landing on non-instruction boundaries. Detail:
+`reference/tms34010-sdk.md`.
+
+**The linker's origin is a bit address**, and its COFF output carries the full
+32-bit address — which is what makes this usable for placing *our* code at a
+VT1200 bit address, not merely for verifying the firmware.
+
+The **1990 r5.01 tools are OS/2 1.x NE binaries and do not run in DOS**, so that
+half of the package is unusable here. The TIGA kit, debugger/monitor and
+video-DAC material are equally irrelevant.
+
+## Speed: prefer dosemu
+
+Benchmarked on the same workload, timestamp-normalised output identical:
+**DOSBox ≈1.99–2.23 s vs dosemu ≈0.35–0.43 s — 5.2–5.7× faster.** dosemu needs a
+private drive and a batch file (`exitemu`); **DOSBox remains the known-good
+fallback**, and `DOSBOX.md` documents its verified headless invocation.
+
+## Traps worth knowing
+
+* **`dis34` prints long relative branches as `JA`** and **hides the B-file `SP`** —
+  correctness bugs in our disassembler, not in the assembler.
+* **`gsprom`'s hex addresses wrap at 64 KB** — use the COFF file or the map for
+  placement.
+* **GSPA's `MOVI` auto-shortening can silently change sign extension.**
 
 ## What is NOT committed