# 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`.