Files
..

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:

  1. the loader has written RESULT_STATUS (it is 0xFFFFFFFF until then),
  2. PC is outside [LOADER_BASE, LOADER_BASE+0x400), and
  3. 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>.