docs(tms34010-sdk): the r5.01 2ine pipeline and gspcl #13

Merged
arti merged 3 commits from opencode.energia.arti.ee/vt1200:docs/r5.01-2ine-pipeline into master 2026-11-17 04:32:37 +02:00
4 changed files with 45 additions and 28 deletions

No files matched your search

+1 -2
View File
@@ -96,8 +96,7 @@ The 1990 **r5.01 OS/2** toolchain under `2ine-tms34010` also builds it (see
`gspopt -O2`: the optimizer hoists the `CTRL_READY` polling load and the
payload waits forever at takeover. `MOVIE.C` is fine at `-O2`. The verified
r5.01 build is `.text` 3,168 bytes, entry `0x018C5C70`, and is MAME-exact at
frames 0 and 180. `gspac`/`gspcg` exit 139 at teardown but still write valid
files.
frames 0 and 180.
## Run in MAME (debugger path)
+1 -2
View File
@@ -110,8 +110,7 @@ MAME frame 0 and frame 180 are **EXACT** with
Caveat: `gspopt -O2` on `MAIN.C` hoists the `CTRL_READY` polling load and
the payload waits forever at takeover. `MOVIE.C` is fine at `-O2`; build
`MAIN.C` without `gspopt`, or add `volatile` to the polling reads. `gspac`
and `gspcg` exit 139 at teardown but still write valid output files.
`MAIN.C` without `gspopt`, or add `volatile` to the polling reads.
`gspa` 5.01 accepted `entry.asm`/`fill.asm` (including `sp`); the `b15`
round-trip difference does not affect this demo.
+30 -14
View File
@@ -8,10 +8,11 @@ the patched fork of [2ine](https://github.com/icculus/2ine) at
Unlike the assembler-only state documented when the fork was first published,
the **full C pipeline works**: front end, optimizer, code generator,
assembler, linker and converter. `gspcl` (the one-command driver) still does
not chain its children reliably; drive the four C stages explicitly.
assembler, linker and converter. `gspcl` (the one-command driver) chains the
first four; `-z` adds the link.
Verified 2026-11-01 on x86_64 Arch, against the VT1200 firmware image.
Verified 2026-11-01 on x86_64 Arch, against the VT1200 firmware image; the C
pipeline and `gspcl` re-verified 2026-11-16.
| tool | result |
|---|---|
@@ -22,15 +23,16 @@ Verified 2026-11-01 on x86_64 Arch, against the VT1200 firmware image.
| `gsplnk` (linker) | **works** — absolute placement; `rts.lib` + `flib.lib` |
| `gsprom` (COFF → Tek-hex) | **works** — plain and `-i` EPROM pair |
| `gspar` (archiver) | **works** — lists `rts.lib` members |
| `gspcl` (driver) | **partial** — runs `gspac`, then stops (see §7) |
| `gspcl` (driver) | **works** — chains the compile, optimize, codegen and assemble stages; `-z` adds the link (see §7) |
---
## 1. Build 2ine
The fork's `main` carries the three fixes this needs: the null-selector
mapping (commit `91b78f2`), Arch/CMake-4 ncurses discovery (`a440128`), and
this document's status update (`3bcdfc3`).
The fork's `main` carries the fixes this needs: the null-selector mapping
(commit `91b78f2`), Arch/CMake-4 ncurses discovery (`a440128`), the 16-bit
stack-unmap guard (`cad0c71`), and the fork's `TMS34010.md` status update
(`3bcdfc3`).
Dependencies (Arch):
@@ -191,15 +193,29 @@ register. The 5.01 object is therefore functionally identical to the ROM, but
not byte-identical at that instruction. This is the one exception to the
otherwise one-way assembler compatibility noted in `OS2-501.md`.
## 7. `gspcl` and the exit-status trap
## 7. `gspcl`
`gspcl` finds `gspac` and runs it, then stops without invoking `gspopt` /
`gspcg` / `gspa`. The individual tools frequently exit non-zero after
successful work: `gspac` and `gspcg` return **139** (segfault during teardown),
`gsprom` can return 1. `gspcl` treats the child status as failure.
`gspcl` drives the compile, optimize, codegen and assemble stages (`$LX` as in
§4):
**Check for output files, not exit codes.** The manual pipeline in §4 produces
correct objects and images; the one-command driver does not yet.
```sh
$LX ./gspcl.exe -k -o2 -c HELLO.C
```
`-c` stops before linking and `-k` keeps the assembly, so success leaves
`hello.obj` and `hello.asm` (the tools write lowercase names). `-z` starts the
link, and everything after it is a linker option, so the libraries follow:
```sh
$LX ./gspcl.exe -k -o2 HELLO.C -z -o hello.out rts.lib flib.lib
```
Or run the stages explicitly as in §4.
In the verified runs the driver and the tools exit **0** on success and **1**
for a genuine error such as a missing input or an unwritable output. The loader
keeps only the low 8 bits of an OS/2 exit code (`lxTerminate`), so read a
nonzero status as "inspect the output" rather than as a precise error code.
## 8. What the null-selector fix was
+13 -10
View File
@@ -73,7 +73,7 @@ under real OS/2.
### 2.1 OS/2 1.3 under 86Box — the full toolchain (compile, link, convert)
This is the only route that runs **`gspcl`** today.
This route runs the full toolchain, including **`gspcl`**.
Media: the preinstalled image on archive.org, item `Os21.3VirtualHardDisk`,
file `MicrosoftOs-21.30HardDisk.vhd` (a Virtual-PC dynamic VHD, 500 MiB
@@ -126,13 +126,17 @@ unreliable. Type only letters (name your batch `CG.CMD`, `BK.CMD`, …) one
character at a time, and have the batch print a unique end token so the host
can detect completion by OCR (or just wait and take a screenshot).
### 2.2 2ine — assembler/linker/converter natively, no VM
### 2.2 2ine — the whole toolchain natively, no VM
`gspa`, `gsplnk` and `gsprom` run under
[2ine](https://github.com/icculus/2ine) with a small patch series; the patched
fork lives at **<https://git.wut.ee/opencode.energia.arti.ee/2ine-tms34010>**
(see its `TMS34010.md`). Build it 32-bit (`cmake -S . -B build && cmake --build
build -j2`, needs `gcc-multilib`, `libc6-dev-i386`, `libncurses-dev:i386`).
The whole toolchain runs under
[2ine](https://github.com/icculus/2ine) with a small patch series: the
assembler, linker and converter, and the C front end, optimizer, code
generator and driver. The patched fork lives at
**<https://git.wut.ee/opencode.energia.arti.ee/2ine-tms34010>** (see its
`TMS34010.md`). Build it 32-bit (`cmake -S . -B build
-DCMAKE_POLICY_VERSION_MINIMUM=3.5 && cmake --build build -j2`, needs
`gcc-multilib`, `libc6-dev-i386`, `libncurses-dev:i386`; the policy floor is
for CMake 4.x).
```sh
cd 2ine/build # lx_loader dlopen()s ./lib<module>.so, so cwd matters
@@ -143,9 +147,8 @@ cd 2ine/build # lx_loader dlopen()s ./lib<module>.so, so cwd matters
```
The C pipeline **does** work under the patched fork: a null-selector fix in
`lx_loader.c` unblocks `gspac`, `gspopt` and `gspcg`. `gspcl` itself still
stops after `gspac` because the children exit non-zero at teardown, so drive
the stages explicitly. See `2INE-501.md` for the full end-to-end flow.
`lx_loader.c` unblocks `gspac`, `gspopt` and `gspcg`, and `gspcl` chains the
stages. See `2INE-501.md` for the full end-to-end flow.
---