# TMS34010 SDK (curated subset)

Source: **https://github.com/tms34010guy/tms34010-sdk** — a cleaned-up mirror of
TI's TMS34010 development material that was previously scattered across bitsavers.

Cloned here because the project's goal is to run **custom, self-compiled
TMS34010 code** on a real VT1200, and this repo already had a disassembler
(`tools/smart34010`) and a Ghidra processor module (`tools/ghidra-tms34010`) but
**no assembler, linker or compiler**.

## What is committed

The two tool packages — the only parts with durable technical value:

```
1987-05 TMS34010 SDK/
  1985-05-20 ... Assembly Language Package (1 of 4) ASM-LNK-ARCH ....img
  1985-05-20 ... Assembly Language Package (2 of 4) GSPSIM-COMP ......img
  1985-05-20 ... Assembly Language Package (3 of 4) GSPSIM-TIPC ......img
  1985-05-20 ... Assembly Language Package (4 of 4) ROM-DEMO ........img
  1987-11-06 TMS34010 Simulator-C Tools-ASM Tools ...................img
  ... plus sample/graphics libraries
1990-11 TMS340 Family SDK/
  1990-11-19 ... Code Generation Tools (1 of 2) r5.01 ...........zip
  1990-11-19 ... Code Generation Tools (2 of 2) r5.01 ...........zip
  1990-11-19 ... C Source Debugger r5.00 ........................zip
  1990-11-19 ... Graphics Library (1..3 of 3) r2.01 .............zip
  1990-11-19 ... TIGA SDK r2.01 .................................zip
```

## It works, and the round trip is byte-exact

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` misreported two encodings** — long relative branches as `JA` and the
  B-file `SP` as plain `sp`. **Both fixed** (`af7d3565a502`): `0x00` + a 16-bit
  displacement is `JRcc` (2 words), only `0x80` + a 32-bit address is `JAcc` (3
  words), and register field `0x1F` is `b15`. The round-trip fixup list dropped
  from **5 to 3** as a result. For scale: the correction changes **2623** ROM
  lines for `sp`→`b15` and **6235** for `JA`→`JR`, so disassembly read before
  that date may have misreported those branches. The proof is reproducible —
  the harness is committed at `harness/sdk-roundtrip/`.
* **`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

`Docs/`, `Patents/` and `1991-07 TIGA Promo Kit and Art Software/` — about
**243 MB** of scanned manuals, patents and promotional material. They are
re-obtainable from the upstream repo above, and they would triple the size of
this repository for no build-time benefit.

`docs/TMS34010-users-guide.pdf` / `.txt` were already in this project and cover
the instruction set, so prefer those over the SDK's scans for programming
reference.

## Licence

TI material of this vintage, mirrored by a third party. It is vendored here as
reference/tooling for interoperability work on hardware the project owner
possesses. The upstream repository is the authority on provenance.