From 1ca2ac4168baa17ecd0058fa65d4c02cadb43fdb Mon Sep 17 00:00:00 2001 From: opencode Date: Mon, 16 Nov 2026 17:23:04 +0000 Subject: [PATCH 1/2] docs(tms34010-sdk): what the 2ine 139 exit status was gspac and gspcg returning 139 was a real SIGSEGV, not a strange exit code: they free their automatic data segment (DGROUP), which also holds the running 16-bit stack, just before DosExit; lxFreeSegment unmapped it and the 16->32 bridge faulted returning through it. Record the root cause, the loader fix (PR #1, commit cad0c71), and that gspcl now chains the whole pipeline. Keep the "check output files" rule for unpatched loader builds. --- tools/tms34010-sdk/2INE-501.md | 46 ++++++++++++++++++++++++++-------- tools/tms34010-sdk/OS2-501.md | 12 ++++++--- 2 files changed, 43 insertions(+), 15 deletions(-) diff --git a/tools/tms34010-sdk/2INE-501.md b/tools/tms34010-sdk/2INE-501.md index 99d9f6b..ee21398 100644 --- a/tools/tms34010-sdk/2INE-501.md +++ b/tools/tms34010-sdk/2INE-501.md @@ -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 C +stages once the loader has the stack-unmap fix in §7. -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; §7 +updated 2026-11-16. | tool | result | |---|---| @@ -22,7 +23,7 @@ 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** with the §7 loader fix — otherwise stops after `gspac` | --- @@ -191,15 +192,38 @@ 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`, and what the 139 exit status was -`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. +**Fixed 2026-11-16:** [PR #1](https://git.wut.ee/opencode.energia.arti.ee/2ine-tms34010/pulls/1) +(`lx_loader: don't unmap a segment that holds the live stack`, commit +`cad0c71`) makes `gspac` and `gspcg` exit normally and lets `gspcl` chain the +whole pipeline. A loader build without it still shows the old behaviour +described below. -**Check for output files, not exit codes.** The manual pipeline in §4 produces -correct objects and images; the one-command driver does not yet. +The old failure was a real **SIGSEGV**, not a strange exit code. `gspac` and +`gspcg` free their automatic data segment (DGROUP) as the last thing they do +before `DosExit`; that segment also holds the 16-bit stack, and the 16→32 +bridge is still running on it. 2ine's `Dos16FreeSeg` called `lxFreeSegment`, +which did `munmap()` + `lxFreeSelector()` immediately, so the bridge faulted +returning through the stack it had just released. The process died with +**139** = `128 + SIGSEGV` before `DosExit` ran — on success and on error +alike. `gspcl` checks its children's status, so it treated every child as +failed and stopped after `gspac`. + +The fix keeps the mapping **and** its LDT selector when the segment contains +the current `ESP` (the bridge reloads `%ss` on the way out, so the selector +must stay valid too); `_exit()` reclaims the mapping. This is the rule +`freeLxModule()` already applied to the stack at process shutdown. + +With the fix, every stage exits **0**, or **1** for a genuine error (missing +input, unwritable output), and `gspcl -k -o2 -c file.c` runs the whole C +pipeline by itself. The generated files are byte-identical to the ones the +crashing builds produced. + +On an unpatched loader, **check for output files, not exit codes**: `gspac` +and `gspcg` still write complete output before they die. That is why the +`bad-apple` build notes record 139-next-to-valid-output; they were made before +this fix. ## 8. What the null-selector fix was diff --git a/tools/tms34010-sdk/OS2-501.md b/tools/tms34010-sdk/OS2-501.md index bc4cc00..ea7eb37 100644 --- a/tools/tms34010-sdk/OS2-501.md +++ b/tools/tms34010-sdk/OS2-501.md @@ -73,7 +73,8 @@ 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. +Historically this was the only route that ran **`gspcl`**; the patched 2ine +loader can run it too now (§2.2). Media: the preinstalled image on archive.org, item `Os21.3VirtualHardDisk`, file `MicrosoftOs-21.30HardDisk.vhd` (a Virtual-PC dynamic VHD, 500 MiB @@ -143,9 +144,12 @@ cd 2ine/build # lx_loader dlopen()s ./lib.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`. `gspcl` used to stop +after `gspac` because that child died with SIGSEGV (139) while freeing the +segment its own stack lived in; the stack-unmap fix in +[PR #1](https://git.wut.ee/opencode.energia.arti.ee/2ine-tms34010/pulls/1) +lets it chain the stages. See `2INE-501.md` §7 for the root cause and the +full end-to-end flow. --- -- 2.47.3 From 147bc849e9cda5cb0bce9d180b24ad147ce2f3ac Mon Sep 17 00:00:00 2001 From: opencode Date: Mon, 16 Nov 2026 17:25:48 +0000 Subject: [PATCH 2/2] docs(tms34010-sdk): drop the broken-2ine caveats The docs now describe the working r5.01 pipeline: gspcl chains the C stages, every tool exits 0 (or 1 for a real error), and there is no "check output files instead of exit codes" rule. The old 139/SIGSEGV story stays in git history. --- bad-apple/README.md | 3 +- bad-apple/REPORT.md | 3 +- tools/tms34010-sdk/2INE-501.md | 52 +++++++++++----------------------- tools/tms34010-sdk/OS2-501.md | 11 ++----- 4 files changed, 22 insertions(+), 47 deletions(-) diff --git a/bad-apple/README.md b/bad-apple/README.md index dcdc136..1630d8f 100644 --- a/bad-apple/README.md +++ b/bad-apple/README.md @@ -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) diff --git a/bad-apple/REPORT.md b/bad-apple/REPORT.md index b372acf..0ac8b82 100644 --- a/bad-apple/REPORT.md +++ b/bad-apple/REPORT.md @@ -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. diff --git a/tools/tms34010-sdk/2INE-501.md b/tools/tms34010-sdk/2INE-501.md index ee21398..f23f3f8 100644 --- a/tools/tms34010-sdk/2INE-501.md +++ b/tools/tms34010-sdk/2INE-501.md @@ -9,10 +9,9 @@ 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) chains the C -stages once the loader has the stack-unmap fix in §7. +stages. -Verified 2026-11-01 on x86_64 Arch, against the VT1200 firmware image; §7 -updated 2026-11-16. +Verified 2026-11-01 on x86_64 Arch, against the VT1200 firmware image. | tool | result | |---|---| @@ -23,15 +22,15 @@ updated 2026-11-16. | `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) | **works** with the §7 loader fix — otherwise stops after `gspac` | +| `gspcl` (driver) | **works** — chains the full C pipeline (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 this document's status update (`3bcdfc3`). Dependencies (Arch): @@ -192,38 +191,21 @@ 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 what the 139 exit status was +## 7. `gspcl` -**Fixed 2026-11-16:** [PR #1](https://git.wut.ee/opencode.energia.arti.ee/2ine-tms34010/pulls/1) -(`lx_loader: don't unmap a segment that holds the live stack`, commit -`cad0c71`) makes `gspac` and `gspcg` exit normally and lets `gspcl` chain the -whole pipeline. A loader build without it still shows the old behaviour -described below. +`gspcl` drives the whole C pipeline: -The old failure was a real **SIGSEGV**, not a strange exit code. `gspac` and -`gspcg` free their automatic data segment (DGROUP) as the last thing they do -before `DosExit`; that segment also holds the 16-bit stack, and the 16→32 -bridge is still running on it. 2ine's `Dos16FreeSeg` called `lxFreeSegment`, -which did `munmap()` + `lxFreeSelector()` immediately, so the bridge faulted -returning through the stack it had just released. The process died with -**139** = `128 + SIGSEGV` before `DosExit` ran — on success and on error -alike. `gspcl` checks its children's status, so it treated every child as -failed and stopped after `gspac`. +```sh +$LX ./gspcl.exe -k -o2 -c HELLO.C +``` -The fix keeps the mapping **and** its LDT selector when the segment contains -the current `ESP` (the bridge reloads `%ss` on the way out, so the selector -must stay valid too); `_exit()` reclaims the mapping. This is the rule -`freeLxModule()` already applied to the stack at process shutdown. +`-c` stops before linking and `-k` keeps the assembly, so success leaves +`hello.obj` and `hello.asm` (the tools write lowercase names). Use `-z` for +the link stage (see `OS2-501.md` §3), or run the stages explicitly as in §4. -With the fix, every stage exits **0**, or **1** for a genuine error (missing -input, unwritable output), and `gspcl -k -o2 -c file.c` runs the whole C -pipeline by itself. The generated files are byte-identical to the ones the -crashing builds produced. - -On an unpatched loader, **check for output files, not exit codes**: `gspac` -and `gspcg` still write complete output before they die. That is why the -`bad-apple` build notes record 139-next-to-valid-output; they were made before -this fix. +The driver and the individual tools exit **0** on success and **1** for a +genuine error such as a missing input or an unwritable output; check the +status (or the output file) before using the result. ## 8. What the null-selector fix was diff --git a/tools/tms34010-sdk/OS2-501.md b/tools/tms34010-sdk/OS2-501.md index ea7eb37..46cfa65 100644 --- a/tools/tms34010-sdk/OS2-501.md +++ b/tools/tms34010-sdk/OS2-501.md @@ -73,8 +73,7 @@ under real OS/2. ### 2.1 OS/2 1.3 under 86Box — the full toolchain (compile, link, convert) -Historically this was the only route that ran **`gspcl`**; the patched 2ine -loader can run it too now (§2.2). +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 @@ -144,12 +143,8 @@ cd 2ine/build # lx_loader dlopen()s ./lib.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` used to stop -after `gspac` because that child died with SIGSEGV (139) while freeing the -segment its own stack lived in; the stack-unmap fix in -[PR #1](https://git.wut.ee/opencode.energia.arti.ee/2ine-tms34010/pulls/1) -lets it chain the stages. See `2INE-501.md` §7 for the root cause and 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. --- -- 2.47.3