dwt/loader: COFF loader places GSPLNK images and runs them via create_process

2026-10-18 15:19:44 +03:00
1 parent dcca6bee4d
commit 139d89a10c
@@ -0,0 +1,60 @@
+# dwt/loader — the COFF loader half of the app loader
+
+Loads a GSPLNK-linked COFF image that is already in RAM into a **first-class
+process** on the VT1200 OS. The transport (TFTP) is separate; this half takes a
+buffer and length, picks the addresses from the COFF, and calls
+`create_process`.
+
+Read `dwt/notes/LOADER.md` for the full report and
+`dwt/notes/LOADER_CROSS.md` for the transport interface.
+
+## Files
+
+| file | purpose |
+|---|---|
+| `loader.asm` | the loader; linked at bit `0x01880000`, raw `.bin` 1220 B |
+| `marker.asm` | acceptance app with `.text`/`.data`/`.bss` at three addresses |
+| `coff.py` | TI COFF reader/dumper (`summary`, `raw`, `manifest`) |
+| `build.sh` | GSPA/GSPLNK wrapper; keeps the linked COFF |
+| `reldemo.sh`, `rel_a.asm`, `rel_b.asm` | relocation and position-dependence demo |
+| `loader.lua` | debugger-assisted harness (no network, no rdebug) |
+| `probe_os.lua` | heap-list and register-write probe used to design the harness |
+| `build/` | linked loader/app COFFs, raw `.bin`s, maps, listings |
+| `evidence/` | run logs, COFF dumps, the xhello window frame |
+
+`work/` (the DOS tools extracted from the SDK floppy) and `run/` (private
+NVRAM/cfg) are local scratch and ignored.
+
+## Build
+
+```sh
+./dwt/loader/build.sh dwt/loader/loader.asm 01880000
+./dwt/loader/build.sh dwt/loader/marker.asm 018C0000 018D0000 018D8000
+./dwt/loader/build.sh dwt/gui/xhello.asm    01840000
+./dwt/loader/reldemo.sh
+```
+
+`build.sh` takes `SOURCE.asm [TEXT_ORIGIN [DATA_ORIGIN [BSS_ORIGIN]]]`
+(origins are **bit** addresses) and writes `build/<name>.coff`, `.bin`, `.map`,
+`.lst`, `.obj`.
+
+## Run (debugger-assisted, no network)
+
+```sh
+VT1200_SKIP_LEVEL1=1 LOADER_AT=2500 LOADER_END=2620 \
+LOADER_COFF=dwt/loader/build/marker.coff LOADER_OUT=$PWD/dwt/loader/evidence \
+/home/arti/code/k-space/mame0289/vt1200 vt1200 \
+  -rompath harness/mame/roms -video none -sound none -nothrottle -skip_gameinfo \
+  -nvram_directory $PWD/dwt/loader/run/nvram \
+  -cfg_directory $PWD/dwt/loader/run/cfg \
+  -debug -debugger none \
+  -autoboot_script dwt/loader/loader.lua -autoboot_delay 0
+```
+
+The script pokes the loader at `0x01880000` and the COFF at `LOADER_BUF`
+(default `0x01900000`), writes the descriptor, and sets `PC`. It never uses the
+network, the rdebug service or a firmware transport.
+
+Knobs: `LOADER_MODE=1` (callable/return instead of debug-resume),
+`LOADER_A8_DESC=1` (descriptor in `A8`), `LOADER_SNAP=1` (PNG at `LOADER_END`),
+`LOADER_VERBOSE=1`, `LOADER_TRACE=1`.