vt1200/reference/tms34010-sdk.md

The TMS34010 SDK in tools/tms34010-sdk: what runs, and what it buys us

Investigated 2026-10-18. Short version:

• The 1987 DOS toolchain runs under DOSBox (and dosemu) on Linux: GSPA (assembler), GSPLNK (linker), GSPROM (hex converter), GSPAR (archiver), and the K&R C compiler (GSPCPP/GSPCC/GSPCG).
• smart34010 output does assemble with it, but not literally: five small fixups are needed. With them, a 32 KB region of the v2.2 ROM reassembles byte-for-byte, md5-identical to the original. See the results table.
• The 1990 r5.01 tools are OS/2 1.x NE binaries, not DOS. They do not run in DOSBox; using them would need an OS/2 environment. The 1987 DOS tools are the usable set.
• There is no as34 / lnk34 in this SDK. The assembler is GSPA.EXE and the linker GSPLNK.EXE (the names smart34010's README mentions are from a later TI package). GSPA 2.00 is enough for the round trip.
• The C compiler works and links with rts.lib into an absolute COFF image. It is K&R C, not ANSI: int f(int a) is a syntax error, int f(a) int a; works.
• For a VT1200 payload the useful part is the address model: the linker's SECTIONS origin is a bit address, the COFF carries the full 32-bit bit address, and the bytes are extracted from GSPROM's high/low EPROM files. The old converter's own hex addresses wrap at 64 KB and must not be used for placement.

Everything below was run against the ROM with md5 b46a3e442ccb86134d2356bd70d22fd2; the ROM was only read.

---

1. What is in the SDK, and what actually executes

package	files	host	runs here?
1985-05-20 … Assembly Language Package	GSPA/GSPLNK/GSPAR v1.04	DOS MZ	yes, but older
1987-11-06 … Simulator-C Tools-ASM Tools.img	GSPA 2.00, GSPLNK 2.00, GSPAR 2.00, GSPROM 2.01, GSPCV 2.00 (A2); GSPCPP/GSPCC/GSPCG 2.01, RTS.LIB, FLIB.LIB (C2)	DOS MZ	yes — the set used here
1990-11-19 … Code Generation Tools r5.01	gspa, gspac, gspar, gspcg, gspcl, gsplnk, gspopt, gsprom, clist	OS/2 1.x NE	no (DOSBox cannot run NE/OS2)
1990-11-19 … C Source Debugger r5.00	db340.exe (DOS MZ), gspmon	DOS + target monitor	debugger runs, but needs a monitor/target link
1991-07 TIGA Promo Kit	DOS art/demo disks, TIGA docs	DOS	not relevant to VT1200
Docs/	Users Guide, Assembly Tools Guide, C Compiler Guide, reference cards, TIGA, production data	PDF	reference only
Patents/	five graphics-architecture patents	PDF	not relevant

The 1990 NE files were checked both with file and by parsing the NE header: signature NE, version 5.1, target OS byte 0x01 = OS/2. The 1985/1987 files are plain MZ for MS-DOS, 16-bit real mode, and need at most 640 KB.

The 1987 disk is the sweet spot: v2.00 is the version whose tools guide documents the W/L immediate-form operands and the .usect/.if features used below. The 1985 v1.04 tools are older and were not needed.

Running them headless

DOSBox 0.74-3 works with the SDL dummy drivers; a bare -conf file with core=dynamic / cycles=max makes it ~5× faster than the cycles=3000 config used earlier. The commands in roundtrip.sh show the exact form.

dosemu 1.4.0.8 also works: dosemu -t -quiet -E 'c:\bench\bench.bat', where the batch ends in exitemu. -E alone does not exit DOS. See the benchmark section.

---

2. The round-trip experiment (the proof)

Method

For a region at file offset OFF, size SIZE, linked at bit address BASE:

1. dis34 -b BASE -o region.bin > region.dis — disassemble with the opcode words in a trailing comment (-o is required; the fixups use them).

2. dis2as34.py BASE SIZE region.dis > RT.ASM — apply the five fixups (section 3), prepend .text, append .end.

3. Assemble and link:

   gspa   rt rt.obj rt.lst -l
   gsplnk rt.cmd
   gsprom -i rt.out rthi rtlo
   

   with rt.cmd:

   -a
   -o rt.out
   -m rt.map
   rt.obj
   SECTIONS
   {
     .text 3F208000h: {}
   }
   

   The origin is a bit address. -a makes an absolute module; -m writes a map; -e would set an entry point.

4. gsprom -i writes two Intel-hex files (high byte and low byte for a 16-bit EPROM pair). Interleave low byte then high byte per word.

5. Compare with dd-extracted original bytes.

roundtrip.sh does exactly this and prints the md5.

Results

region	file offset	base (bit)	size	result
boot/POST code	0x1000	3F208000	4 KB	0 differing, md5 a4018fed12e062658bc81957f149265b
same, larger	0x1000	3F208000	16 KB	0 differing, md5 0a2e679bc864d52d32c59740142c5b96
same, larger	0x1000	3F208000	32 KB	0 differing, md5 43adb6669571041985f3e26fd9ff7cb9
another code region	0x8000	3F240000	4 KB	0 differing, md5 438e743431d56e0c12ededce1c36952a

The ROM md5 after all runs is unchanged: b46a3e442ccb86134d2356bd70d22fd2.

A 64 KB region trips dis34 itself (unexpected end of input at byte 65536); split larger spans into ≤32 KB pieces. This is a disassembler limitation, not an assembler one.

What this proves, and what it does not

It proves the assembler accepts the disassembler's instruction syntax and reproduces the exact instruction encodings for 32 KB of real firmware, including PC-relative branches, absolute calls, data words, and immediate forms. It does not prove the payload runs on a VT1200; nothing here was executed on the target.

---

3. The five fixups (and why they are needed)

dis34 output is close to GSPA syntax but not directly assemblable. The converter harness/sdk-scratch/dis2as34.py is the executable form of this list.

1. Hex constants. GSPA has no 0x: a hex constant must start with a decimal digit and end in h. 0x220 → 0220h; 0xC00000B0 → 0C00000B0h (nine digits are accepted and truncated to 32 bits). GSPCV does the same conversion for the old >xxxx syntax.

2. MOVI short vs long. GSPA has one MOVI mnemonic with a 16-bit sign-extended form and a 32-bit form, and auto-selects by "does the value fit in 16 bits (unsigned)". That is not encoding-preserving: a long MOVI 0x53E0 (three words) becomes a short MOVIW (two words), and the short form sign-extends to 0xFFFF53E0. Force the form with the third operand: movi 053E0h, sp, L or ..., W. The opcode word count in the -o comment tells which form the ROM used. The same applies to ADDI, CMPI, and SUBI.

3. B-file SP. dis34 prints register 15 as sp regardless of file. Bit 4 of the encoded register field says which file: 0x0F = A-file SP, 0x1F = B-file SP. GSPA's bare sp matched the ROM for most forms (memory operands such as *sp(offset) assembled as B15; MOVI/MMFM register operands as A15), but an RL destination chose A15 where the ROM has B15 (0x312F vs 0x313F). b15 forces the B-file register; a15 is rejected. Check the register field, not the printed name.

4. Long relative JR printed as JA. In dis34, the 2-word relative jump (opcode low byte 0x00, 16-bit displacement) is printed with the ja<cc> mnemonic, the same one used for the 3-word absolute JA. The word count distinguishes them: 2 words → rewrite to jr<cc>, 3 words → leave ja<cc>. Without this, every long relative branch grows by a word and the image diverges.

5. Branches whose target is not an instruction boundary. This happens for targets outside the disassembled region (common) and, in data-table areas, for targets inside a multi-word instruction. GSPA also mishandles a negative absolute .set value in a JR (it emits the absolute JA form and errors). Emit the exact opcode words from the -o comment as .word for those branches. For DSJS, whose short range is only ±32 words, this is the only reliable way.

One practical note: with the slow cycles=3000 DOSBox config, a 16 KB source with -l takes about 35 s wall time; a 32 KB source takes about 1.5–2 minutes. That is DOSBox being cycle-limited, not the assembler hanging. The benchmark section uses core=dynamic/cycles=max, which removes most of it.

---

4. Addresses, sections, and output formats

The unit is bits

The TMS34010 is bit-addressed. In this toolchain:

• The assembler's location counter and labels are in bits; each instruction word advances it by 16. A listing address of 00000030 is 3 words in.
• SECTIONS binding is a bit address: .text 3F208000h: {} produced .text 0 3F208000 00020000 in the map (origin bit, length bits).
• The linker's MEMORY origins/lengths are bits too.
• The COFF output carries the true 32-bit bit address. In RT16.OUT the optional header says text = 0x3F208000, code size = 0x20000 bits, and the .text section header says paddr = vaddr = 0x3F208000, size = 0x20000 bits. The file header magic is 0x0090, flags 0x103 (including 0x40, the TMS34010 little-endian "16 bits per word, LSB first" flag).
• To place a payload at bit address A, link .text A: {} and put file byte i at physical byte address A>>3 + i. Do not re-link at a different address than the load address: the C compiler emits CALLA and absolute pointers.

GSPROM's hex addresses are not the load address

gsprom -i in out_hi out_lo produces two 8-bit Intel-hex files, one high byte and one low byte per 16-bit word. The address in those records is a 16-bit word index inside a 64 KB byte window, not the bit address and not the full byte address. Measured:

section bit origin	first record address
0x00020000	0x2000
0x3F208000	0x0800
0x3F240000	0x4000

That matches ((bit >> 3) & 0xFFFF) >> 1. The data order is still correct, so take the byte stream in order and place it at the address from the map/COFF. gsprom -t (TI-tagged) has the same 16-bit address limitation.

For a loader, the clean source of truth is the COFF (-a output): section paddr/vaddr and the optional header's entry point are full 32-bit bit addresses. A small COFF reader can emit a raw image with its true load address; GSPROM is only a convenience for an EPROM programmer.

Linker command syntax gotchas

• Comments are /* … */; ; is a syntax error in a command file.
• .text > prog is a syntax error. Use either .text 3F208000h: {} (bind directly) or .text: {} > prog (named memory).
• -a = absolute executable, -m = map, -o = output, -e = entry symbol, -l lib = library. -c / -cr select the C ROM/RAM autoinit models.

---

5. The C compiler

It runs, and the whole pipeline works:

gspcpp cmain          # .c -> .cpp
gspcc  cmain          # .cpp -> .if
gspcg  cmain          # .if -> .asm
gspa   cmain          # .asm -> .obj
gsplnk cmain.cmd      # .obj + rts.lib -> .out, map
gsprom -i cmain.out …

A test with fib and main linked cleanly with:

-c
-o cmain.out
-m cmain.map
cmain.obj
-l rts.lib
MEMORY
{
  prog: origin = 3F208000h, length = 10000h
  ram:  origin = 0h,        length = 100000h
}
SECTIONS
{
  .text:  {} > prog
  .cinit: {} > prog
  .data:  {} > prog
  .bss:   {} > ram
}

The map confirms:

ENTRY POINT SYMBOL: "_c_int00"  address: 3F2082F0
.text   3F208000  00000A90
.cinit  3F208A90  00000060
.bss    00000000  0000FE40   (uninitialized)

So the compiler, assembler, runtime library, linker, and converter form a complete C path. It was not executed on a VT1200.

Language and ABI facts worth knowing

From SPVU005A and the generated code:

• K&R C only. ANSI prototypes (int f(int a)) are a syntax error; int f(a) int a; { … } works. Plan for old-style declarations.
• char 8 bits, short 16, int and long 32, pointers 32-bit bit addresses, float 32, double 64.
• Alignment: objects are on 16-bit boundaries (bit addresses with four LSBs zero); structure/array members are packed.
• Dedicated registers: SP = system stack, A14 (STK) = program stack, A13 (FP) = frame pointer; A8 = integer/pointer return value. B0–B14 are unused by the compiler and available to assembly. Callee saves the A registers it uses except A8; FS1 must be 32 inside C code.
• Arguments are pushed on the program stack in reverse order, widened to 32 bits; calls are CALLA (absolute), so code is position-dependent.
• Runtime: link rts.lib with -c (ROM autoinit; boot.obj is pulled in and _c_int00 becomes the entry) or -cr (loader does the .cinit copy). The boot code allocates SYS_STACK in .bss, sets FP/STK/SP, calls _main, then _exit.
• C sections: .text (code + string literals + float constants), .cinit (initialized-global table), .bss (globals + both stacks + heap). .data is the assembler's, not the C compiler's. .bss must be RAM.

For a payload, the simplest C model is: link .text/.cinit at the load address, put .bss in a free RAM range, and enter at _c_int00. A pure-assembly payload avoids the runtime entirely.

---

6. Building a VT1200 payload: practical recipe

Assembly-only payload (smallest, no runtime):

        .text
start:
        movi   01234h, a0
        move   a0, @0C0000010h, 0     ; example on-chip register
        rets
        .end

Link command:

-a
-e start
-o payload.out
-m payload.map
payload.obj
SECTIONS
{
  .text 02000000h: {}        /* example: bit 0x02000000 = byte 0x400000, in RAM */
}

Then either read payload.out as COFF (true bit address in the section header) or gsprom -i payload.out hi lo, interleave low/high, and place the bytes at 0x02000000 >> 3 = 0x400000.

The RAM region is 0x0000000–0x1FFFFFF (4 MiB) and the ROM is 0x3F200000–0x3FFFFFFF in the MAME model; choose a free RAM range for a payload, or load into RAM and jump. The SDK supplies the image and its entry point, not the network delivery mechanism. Delivery is a separate problem: the COFF gives a loader the exact bit address and entry point; GSPROM's hex is only for burning EPROMs.

For C, use the same idea with .text/.cinit at the payload address and .bss in RAM; -c will include boot.obj and make _c_int00 the entry.

---

7. Documentation: what the SDK adds over the repo

The repo already has docs/TMS34010-users-guide.pdf/.txt (the 1988 hardware user's guide). The SDK's unique, useful additions are:

• SPVU004A TMS34010 Assembly Language Tools Users Guide (1987).pdf — the key document: assembler directives and expression rules, the COFF appendix (file/section/relocation/symbol formats), linker MEMORY/SECTIONS, gsprom, and the simulator. This is where the bit-address and W/L behaviour is specified.
• SPVU004A … Assembly Language Tools Reference Card (1987).pdf — compact invocation/option/directive summary; the fastest lookup.
• SPVU005A TMS34010 C Compiler Reference Guide (1988-08).pdf — data types, ABI, runtime environment, library reference. The ABI section is what makes C/assembly interworking possible.
• SPVU005A … C Compiler Reference Card (1988-08).pdf — quick ABI/options.
• SPVU005 TMS34010 C Compiler Users Guide (1986-12).pdf — older; the 1988 guide supersedes it.
• SPVU002A Software Development Board Users Guide + pocket reference — the SDB and its monitor; useful only if you have that board.
• SPVU021A C Source Debugger Users Guide (1991-09) — the db340/gspmon monitor workflow; not directly applicable to the VT1200 unless a compatible monitor can be loaded.
• SPVU006 Math Graphics Function Library and the 1987 Graphics Math Function Library disk (GRAFIX.LIB, TEXT.LIB, MATH.LIB + sources) — optional drawing primitives; not evaluated against the VT1200's mono framebuffer.
• SPVS002A/C production data — hardware electrical/timing detail; the repo's user's guide covers the programming model.
• SPVU015A/C TIGA, SPVU018A TIGA art, SPVU027 graphics library — TIGA is a PC graphics-interface standard, not the VT1200 terminal; not relevant.
• Docs/Video Interfaces/* — TLC3407x RAMDAC/palette datasheets; the VT1200 is monochrome, so not relevant.
• Patents/ — graphics-architecture patents; no code or format value.

---

8. Findings about smart34010 itself

These are worth fixing upstream (they cost real time here):

1. Long relative JR is printed as JA. In dis34.c, the 0x00 low-byte case (16-bit displacement, 2-word instruction) calls printf("ja%s …"); only the 8-bit case prints jr%s. This makes the output non-assemblable without the word-count fix. Example: jagt L3F211EE0 ; c700 0167 is a relative jump, but jagt is the 3-word absolute instruction.
2. B-file SP is printed as sp. The register name hides bit 4; sp (A-file) and b15 (B-file) are different encodings.
3. movi hides the short/long choice. The disassembler prints one mnemonic for both encodings, while the assembler auto-selects (and may change the meaning via sign extension). The -o word count is the only clue.
4. 64 KB input fails with unexpected end of input at byte 65536; use ≤32 KB regions or fix the offset arithmetic.
5. Data tables decoded linearly can produce branches into the middle of instructions; -a (analyze) may help, but for byte-exact reassembly the .word fallback in the converter is what matters.

The good news: the instruction syntax itself (mnemonics, operands, @/* addressing, labels, .word data) matches GSPA 2.00 closely; the problems are these specific ambiguities, not a different dialect.

---

9. DOSBox vs dosemu: benchmark

Separate from the toolchain result. The owner asked whether dosemu is actually faster. Workload is the real assembler, GSPA 2.00 (there is no as34 in this SDK), on the round-trip sources.

• A: gspa t1 t1.obj t1.lst -l — 4 KB region, 1,478 lines, with listing.
• B: gspa -q rt16 rt16.obj — 16 KB region, 6,124 lines, no listing.
• DOSBox 0.74-3, core=dynamic, cycles=max, SDL_VIDEODRIVER=dummy, SDL_AUDIODRIVER=dummy.
• dosemu 1.4.0.8, -t -quiet, private HOME, batch ending exitemu.
• 1 warm-up + 3 measured runs; median; all exit status 0.
• COFF output compared with the 4-byte time stamp zeroed (raw COFF differs only in that stamp).

workload	DOSBox median	dosemu median	ratio
A: 4 KB with listing	1.99 s	0.35 s	5.7×
B: 16 KB no listing	2.23 s	0.43 s	5.2×

The timestamp-normalised object md5 is identical for every run of each workload and across the two emulators:

• A: e9c59beb4a5e29e391495ba2b312fc79
• B: 69a525b4689f60f51afc3059b66b66a8

Raw md5s differ because bytes 4–7 of the COFF header are the creation time; the assembled bytes are the same.

Setup cost: DOSBox needed only an existing config; dosemu auto-created ~/.dosemu, required a drive C mapping and a batch (because -E does not exit without exitemu), and prints harmless CD-ROM/unknown window sizes warnings. That is a one-off few-minute setup, not per-run.

Recommendation: dosemu is materially faster (≈5×) under these settings and is worth using for batch/iterative assembly. DOSBox remains the known-good fallback and is what roundtrip.sh uses. Note that with DOSBox's original cycles=3000 config the gap is much larger (the 16 KB listing workload took ~35 s), because DOSBox was being cycle-limited, not because dosemu is 70× faster.

---

10. Reproduction

Scripts live in harness/sdk-scratch/ (scratch; not part of the SDK):

• roundtrip.sh OFF SIZE BASE — extract, disassemble, convert, assemble, link, convert, interleave, diff. Example: ./roundtrip.sh 0x1000 32768 3F208000
• dis2as34.py BASE SIZE IN.ASM — the five fixups.
• bench2.py — the DOSBox/dosemu benchmark (needs the private dosemu HOME under harness/sdk-scratch/dosemu-home).
• dosbox.conf / dosbox-bench.conf — headless DOSBox configs.

The SDK itself is untouched; all extraction goes to harness/sdk-scratch/ (work/, cgtools/, sdb/, disk1987/), which is not staged.

---

11. Open questions / not tested

• No payload was executed on a VT1200 or in MAME. The round trip proves the encoder, not the runtime or the network delivery.
• No OS/2 environment was set up, so the r5.01 tools (and their gspopt optimizer) were not exercised. If the newer code generator matters, that is a separate OS/2-in-QEMU project.
• The 1987 GSPSIM simulator was not run; MAME is the better execution model for this project.
• The Math Graphics Function Library and TIGA libraries were not evaluated against the VT1200's monochrome display.
• The optimal free RAM range for a payload depends on what the OS has allocated; the toolchain can link anywhere, but the loader must choose a safe range.