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) |
xg.c |
app-side vt_install_xg(): installs the per-process Xlib context before XOpenDisplay (see below); not part of the loader payload |
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 .bins, 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.
The per-process XG block (needed before XOpenDisplay)
A process this loader starts with create_process begins with no Xlib
context. The ROM Xlib finds it through the current-process word:
proc = *(u32 *)0x001B3900 ; current PCB (bit address)
pp = *(u32 *)(proc + 0x100) ; per-process user block (bit +0x100 = byte +0x20)
XG = *(u32 *)pp ; per-process Xlib context; 0 in a fresh child
free_list = *(u32 *)(XG + 0xCC0) ; bits; byte +0x198 of the block
Verified in the ROM: the current-process helper 0x3F708700 is just
move @0x1b3900,a8,1; rets, and both the dequeue path inside XNextEvent
(0x3F9C1CF0) and its enqueue helper (0x3F9B89A0, Xlib's _XEnq, called at
0x3F9C2180) do calla 0x3F708700 → move *a8(0x100),a7 → move *a7,a7 →
access *a7(0xcc0).
With XG == 0 the whole XG structure — queue head, queue length, and the free
list at +0xCC0 — is read from low RAM. Nothing crashes and nothing reports an
error: XOpenDisplay, XCreateSimpleWindow, XMapWindow, XSync and all
drawing still work, and the window appears on screen. Only events fail —
XNextEvent returns zeroed records (type=0, keycode=0) and never a real
event. That is the symptom to recognise: a client that looks alive and never
reacts.
Install a zeroed ≥1 KiB block before the first Xlib call:
extern int vt_install_xg(void);
if(!vt_install_xg())
return 1; /* no plausible current process / user block */
dpy = XOpenDisplay("0::0"); /* only after the block exists */
xg.c is that helper. Build it with the app (the C toolchain path used by
apps/termtris):
apps/termtris/build.sh myapp.c dwt/loader/xg.c
or copy the file into the app's tree; there is no header — declare
extern int vt_install_xg(void);. The termtris port makes the same install
(apps/termtris/src/vt1200/xgfix.c) with a static vt_u32 vt_xg[256] block
(1 KiB); xg.c zeroes its block on each call rather than trusting startup to
clear .bss. The helper stores its block's address at *(u32 *)pp — it
overwrites XG, not the pointer cell at proc + 0x100 — and changes RAM only,
never the ROM.
An assembly client does the same two loads and one store:
move @1B3900h, a8, 1 ; current PCB
move *a8(100h), a7, 1 ; per-process user block (bit offset 0x100)
movi xg_block, a9 ; a 1 KiB block, zeroed at startup
move a9, *a7, 1 ; XG = block
Ordering: before XOpenDisplay, every time. A draw-only window can get
away without it; the moment the client calls XNextEvent, the missing block
turns into "no events, ever".
Measured (2026-11-13): the unmodified termtris smoke client
(apps/termtris/tests/smoke.c) linked with dwt/loader/xg.c and loaded by
this harness received a real KeyPress:
SMOKE: magic=534D4F4B dpy=00942290 win=00400001 n=9 type=2 keycode=194 lookup_n=1 ch=61 ks=0061 keymark=4B455950
The same client with a stub vt_install_xg() that installs nothing runs its
event loop but only sees zeroed records:
type=0 keycode=0 lookup_n=0 ch=00 ks=0000 keymark=00000000 after 10
iterations. The transcript, including the control, is
evidence/xg_helper_run.log.
Build
./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)
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 the exit frame),
LOADER_VERBOSE=1, LOADER_TRACE=1.
Environment
| variable | default | meaning |
|---|---|---|
LOADER_AT |
2500 |
frame at which the loader and COFF are poked and PC is set |
LOADER_END |
2700 |
fixed inspection/exit frame; 0 = run until completion |
LOADER_MAX |
6000 |
LOADER_END=0 only: give up (with a warning) at this frame |
LOADER_BIN |
dwt/loader/build/loader.bin |
loader payload poked at bit 0x01880000 |
LOADER_COFF |
dwt/loader/build/marker.coff |
app COFF poked at LOADER_BUF |
LOADER_BUF |
0x01900000 |
COFF buffer bit address |
LOADER_OUT |
dwt/loader/evidence |
directory for the optional PNG |
LOADER_SNAP |
0 |
1 writes loader_frame<frame>.png at the exit frame |
Completion and LOADER_END=0
The harness detects completion when all three hold:
- the loader has written
RESULT_STATUS(it is0xFFFFFFFFuntil then), PCis outside[LOADER_BASE, LOADER_BASE+0x400), and- the result block has been unchanged for 10 frames.
On detection it prints one line and sets done once:
LOADER: complete at frame 2510 status=00000000
With a fixed LOADER_END the run still exits at that frame, so the snapshot
filename and every existing fixed-frame capture are unchanged; the completion
line is informational and suppresses the startup warning. With LOADER_END=0
the run exits as soon as completion is detected, and if it is not detected by
LOADER_MAX it prints
LOADER: warning: app still in startup at LOADER_MAX=6000
and exits there. With a fixed LOADER_END that is reached first, the warning is
LOADER: warning: app still in startup at LOADER_END=<n>.