DOS and 16-bit games

Most of GameFrame was built on a 64-bit Windows game. DOS games (1985-2000) need different tools at three steps: reading the executable, emulating code, and running the original. This page covers every DOS step. The skills link here. The tools are tested against examples/dos-sample/ (our own 16-bit code) by tests/run.sh.

1. Which kind of DOS program is it?

python3 tools/dos/dosinfo.py target/GAME.EXE              # format, segments, imports, fingerprints
python3 tools/dos/dosinfo.py target/GAME.EXE --pstrings 6 # Pascal strings, with their addresses

dosinfo says	What it is	Ghidra	Emulate one function	Run it all
MZ	Real-mode DOS (Turbo Pascal, Turbo C, Microsoft C, QuickBASIC)	"Old-style DOS Executable", loaded at segment 1000	dos_emu (real mode)	DOSBox-X
NE	16-bit protected mode: Windows 3.x, OS/2 1.x, Borland Pascal 7 or Borland C++ with DPMI16 (RTM.EXE, DPMI16BI.OVL)	"New Executable", selectors 1000, 1008, ...	dos_emu (protected mode, same selectors)	DOSBox-X (or Windows 3.1 inside it)
LE / LX	32-bit flat code behind a DOS extender (Watcom + DOS/4GW, PMODE/W)	needs an LE/LX loader extension	not yet in the toolkit	DOSBox-X
PE	A Windows program	use tools/pe/peinfo.py	pe_emu.py	Windows or Wine

Packed executables (LZEXE, PKLITE, EXEPACK, DIET: dosinfo's fingerprints) must be unpacked first, for example with UNP or by dumping memory from DOSBox-X after the unpacker has run.

Data appended after the MZ load image is an overlay (Borland .OVR data starts with FBOV), a packed payload, or debug symbols.

2. Addresses: always Ghidra's numbering

Write every address as seg:off the way Ghidra prints it, in docs, labels and tests:

• NE: segment N of the file has selector 0x1000 + 8 * (N - 1). Segment 1 is 1000:, segment 10 is 1048:. Imports go after the last segment.
• MZ: the load image starts at segment 1000, so 1000:0000 is the first byte after the header; a second segment in the image is 1000 + paragraphs.

dosinfo.py prints Ghidra's selector for each segment. readseg.py, dos_emu, tdinfo.py and decomp_query.py all accept and print these addresses. The running program uses other numbers: real-mode segments where DOS loaded it, or the DPMI host's selectors. Only the DOSBox-X debugger shows those (section 7).

3. Debug symbols: check before anything else

Borland compilers wrote Turbo Debugger symbols into the program (TPC/BPC /V, TLINK /v), and many shipped games kept them. They give the original names of every procedure and global, the parameters and locals of each procedure, record layouts, and code-to-source-line maps.

python3 tools/dos/tdinfo.py target/GAME.EXE summary          # units, counts
python3 tools/dos/tdinfo.py target/GAME.EXE procs makeenemy  # address, size, parameters, locals
python3 tools/dos/tdinfo.py target/GAME.EXE types enemy      # record fields with offsets
python3 tools/dos/tdinfo.py target/GAME.EXE labels > analysis/td-labels.tsv
scripts/ghidra-export.sh --labels analysis/td-labels.tsv target/GAME.EXE

With --labels, Ghidra names every function and global, and creates the functions it missed.

tdinfo.py turns the record types into reimplementation code. tdinfo.py BINARY rust TYPE ... writes Rust structs with readers in the original's field order, each field commented with its Pascal type and offset, and tdinfo.py BINARY rust-reader the PascalReader they use (little-endian integers, one-byte Boolean, 6-byte Real kept exact, string[N]). Generated names that clash with Rust's prelude get Rec (Optiontype -> OptionRec). Records also get write, the inverse of read.

tdinfo.py BINARY rust-globals writes one Globals struct holding every variable of the data segment at its original offset, with load and store to and from a 64 KB image of the segment (Booleans stay u8, so store writes every byte back unchanged). Ported code then works on Globals. A test can load the DS image from before an emulated run of the original, run the port, store, and compare with the DS image from after. One test then checks every variable.

tdinfo.py BINARY rust-locals PROC does the same for one procedure's local variables and parameters, at their BP offsets in the stack segment: for code nested in a big procedure (a main loop's helpers that use its locals through the static link).

The runtime library (System, Crt, Dos) has no symbols of its own. Borland Pascal 7's random generator, for example, is RandSeed := RandSeed * $08088405 + 1 (a near NextRand built from 16-bit multiplies and shifts), Random(n) = (new seed * n) >> 32 using all 32 bits, and Randomize seeds from INT 21h AH=2Ch (CX low word, DX high word). Find it by the constant 0x8405 and the global RandSeed, and measure it before trusting this. Record field offsets are summed from field sizes: tdinfo says when a record's fields do not add up to its size (a variant record), so check one offset in the code before relying on it.

4. Decompiling 16-bit code with Ghidra

scripts/ghidra-export.sh works for MZ and NE as it does for PE. Things that differ:

• Library search crashes the import. An NE program that imports a module (RTM) whose file sits next to it (RTM.EXE, a plain DOS program) made Ghidra's loader throw "Invalid index". The export script passes -loader-libraryLoadDepth 0, so Ghidra never searches.
• No-return calls. Ghidra does not know that INT 21h with AH=4Ch (exit) or Pascal's Halt/RunError never return: the next procedure's code is joined to the end of the caller. Split it by creating the function at the right address (labels do this).
• Missed functions. Procedures reached only through relocations or tables are not found. Debug-symbol labels fix this; otherwise use scripts/ghidra-run.sh BINARY decompile.
• Pascal calling convention. Arguments are pushed left to right and the callee removes them (retf N). Ghidra shows these as __stdcall16far with param_1 being the last Pascal argument. Read parameters from [bp+6] upwards: the first at the highest offset.
• Parameter numbers drift. Ghidra may split one far-pointer parameter into two param_N halves, so every later number is off by one; in_stack_X and local_X names are offsets from a frame base two bytes away from BP. Take each parameter's BP offset from the disassembly, and name it from the caller's push list (mov di, 0x649e; push ds; push di is the global at 0x649e), not from how the pseudocode uses it: a "change" counter may really be a speed.
• A big procedure's helpers see its frame. A nested procedure reads its parent's locals and var parameters through the static link (mov di, [bp+4], then [di+...]); map those offsets to the parent's names before reading the helper.
• Scans with string instructions. repe scasb over an array finds the next element that differs from AL; the loop then resumes the scan with the saved CX and DI. Port it as a loop over the array. Check how it stops (often or cl, cl on the low byte only).
• Which carry counts. In add dx, bx; add dx, 1180h; add dx, ax; jae ok, only the last add sets the carry the jump tests; the sum wraps freely before it. Port the test on the same instruction, not on the whole sum.
• Stale globals are inputs. A routine may test a temporary that another routine set earlier in the frame (a tempi2 left by the movement code). Keep the read, because the original's result depends on it. A test catches it only if the port leaves the global as the original does.
• Strings. Pascal strings (a length byte, then the text) are not found by Ghidra's string search. Use dosinfo.py --pstrings and readseg.py BINARY pstr ADDR.
• Segment arithmetic. DAT_1048_12de is offset 0x12de in the data segment; a far pointer is offset then segment in memory (readseg.py ... ptr).
• String constants sit just before their procedure. Borland Pascal emits a procedure's string literals right before its first instruction, so the procedure that starts after a string usually uses it. Code refers to a Pascal string by its length byte: search for the address one before the text that dosinfo.py --pstrings prints.
• Constants that look like globals. A 16-bit constant equal to an offset in DS shows up in pseudocode as &someGlobal (a BlockRead count of 0x138a printed as &tempdat3). Check the instruction (tools/dos/nedis.py) before believing a pointer.
• Floating point by interrupt. Borland's FPU emulator replaces each x87 instruction with INT 34h-3Dh followed by the instruction's bytes; disassemblers show int 0x3c and nonsense after it. Read those runs as floating-point code (Real, Double), not as interrupts.
• Calls through placeholders. Disassembling the file directly shows every far call as lcall 0:ffff: the relocation fills it in. tools/dos/nedis.py BINARY SEG:OFF LEN applies the relocations and prints label names for call targets and DS globals.
• Text files are buffered in the record. ReadChar takes the next byte of the 128-byte buffer inside the TextRec (BufPos, BufEnd), and refills it with one DOS read of BufSize bytes when it is empty. That buffer sits in the data segment, so a port that reads the file another way leaves different bytes there: port the runtime's routines over the record, with a table of open DOS handles and their positions.
• Text files end at ^Z. On a Turbo Pascal Text file, Eof is true when the next byte is 0x1A, not only at the real end, and Read at the end returns 0x1A. A game that stores binary data in a Text file (demo recordings, scripts) stops early at a 0x1A byte in the right place: model it, and check which positions Eof can see.
• Finding the game clock. Look for writes to ports 43h/40h (the PIT: mov al, 36h; out 43h, al, then the divisor's two bytes to 40h) and for SetIntVec(8, ...): the new IRQ 0 handler and the divisor give the tick rate (1,193,182 / divisor Hz), and the loop that waits for a counter the handler decrements gives ticks per frame. A handler that also calls the old vector when a running sum carries keeps the BIOS clock at 18.2 Hz.
• Turbo Pascal types: Real is 6 bytes and not IEEE (readseg.py ... real48), Comp is a 64-bit integer kept in the FPU, string[N] takes N+1 bytes, sets are bit arrays of up to 32 bytes, Boolean is one byte. Records are not padded.
• Real arithmetic is in the runtime library, with registers. Without {$N+}, Real maths calls the System unit's helpers: the first operand and the result in DX:BX:AX, the second in CX:SI:DI (the low byte of AX or CX is the exponent). A typical block is call int-to-real; mov cx/si/di, constant; call multiply; call round. Two helpers that differ only by mov ch, 0 (Trunc) or mov ch, 1 (Round) before the same near call tell Trunc from Round. Measured in one Borland Pascal 7 program: multiply rounds the 80-bit product to 40 bits, halves up; Round rounds halves away from zero. Do not use floats for this: emulate the helpers over every input the game can give (emu.call(helper, regs={'ax': ..., 'dx': ...})) and port the exact algorithm.

5. Emulating one function: dos_emu

import sys; sys.path.insert(0, 'tools/emu')
from dos_emu import DosEmu, Long, FarPtr
emu = DosEmu('target/GAME.EXE')               # NE: protected mode with Ghidra's selectors
emu.call('1000:873a', 5, Long(100000))         # Pascal order; returns AX (call_long: DX:AX)
emu.u16(FarPtr(0x1048, 0x12de))                # read a global after the call
emu.trace({'1040:0a12': 'Random'}, args=1)     # record calls (the random draws) with call sites

• Relocations are applied: selector, far-pointer and offset fixups to the program's own segments, chained or additive. Imports become stubs.
• DS and SS are the auto data segment, as in a Pascal program. Pass regs={'ds': ...} for code that expects something else, and other registers (regs={'ax': ..., 'cx': ...}) for runtime helpers that take their arguments in registers.
• An import or interrupt without a handler stops the run with its name and the caller's address. Add stubs={'KERNEL.3': fn} or interrupts={0x21: fn}; a handler reads and sets registers (emu.reg('ax'), emu.set(ax=...)). An import handler returns the number of argument bytes to remove.
• Not emulated: DOS itself, DPMI services, timers, VGA, sound, the x87 (Borland's FPU emulator fixups are left alone). Code that needs them runs in DOSBox-X instead.

5b. Running the whole program headless: dos_env

tools/emu/dos_env/ gives dos_emu a small DOS, BIOS, DPMI host and PC, so a whole Borland Pascal 7 DPMI16 program can start and run, with no DOSBox and no window:

from dos_emu import DosEmu, ProgramStopped
from dos_env import DosEnv
emu = DosEmu('target/game/GAME.EXE', max_steps=2_000_000_000)
env = DosEnv(emu, root='target/game', overlay='derived/run', program='C:\\GAME\\GAME.EXE')
emu.run_range(emu.entry, '1000:ca59')            # start-up, until the main loop
env.save_screen('derived/run/frame.png')         # VGA memory + the DAC palette
emu.run_to('1000:ca59')                          # the next frame: carry on as it is

• Carry on with run_to, never run_range. run_range(start, end) starts afresh: it puts SS:SP back at the start-up stack. If you use it to continue a running program, every call moves the stack above the live frames. Deep calls then overwrite the main procedure's locals and return address (seen as stray file names in a local array, and the program "exiting" after some thousands of frames). run_to(end) keeps every register.

• Files come from root (names without case); writes go to overlay. env.log lists what the program asked for, in order: compare it with DOSBox-X's file log.

• The timer: IRQ 0 reaches the program's INT 8 handler at the rate it programs on the PIT, counted in instructions (ips, default 25 million per second), so frame-paced loops run.

• Keys: env.keys (scan << 8 | ascii). A read with none queued stops the run and says so.

• Each stop names what is missing (an interrupt, a DPMI call, an import): add it to dos_env, with a test against the sample. Things it needed for a real game: the NE header's own stack segment, a PSP with an environment, the BIOS data area (CRT port, mode, columns), a BIOS tick that advances, a PIT counter that counts, Borland RTM's memory calls (RTM.5/6/21).

• Then capture state frame by frame: emu.read((0x1048, 0), 0x10000) is the data segment for Globals::load; any segment a pointer names can be dumped the same way. tools/emu/fragments.py does this for chosen fragments of the main loop: the state before and after each one, every frame, ready for the port's tests (re-verify).

6. Running the original: DOSBox-X

A store release usually ships its own DOSBox configuration (GOG: __support/app/*.conf). Start from it so runs use the publisher's settings: scripts/dosbox-run.sh --conf THAT.conf ... (the script turns fullscreen off and keeps its own logging and autoexec).

scripts/setup.sh --install installs DOSBox-X (on macOS brew install --formula dosbox-x; the cask fails Gatekeeper). Homebrew's build has the heavy debugger (CPU logs, memory breakpoints); brew install --HEAD --formula dosbox-x adds the newest debugger commands (STEPIN, SAVESTATE).

scripts/dosbox-run.sh target/game GAME.EXE                   # no window; prints the exit code
scripts/dosbox-run.sh --fileio --time 20 target/game GAME.EXE
python3 tools/dos/fileio_trace.py analysis/dosbox/dosbox.log --game target/game

• The game runs on a fresh copy of its folder (analysis/dosbox/drive), so saves and settings it writes never change your copy. --in-place mounts the folder itself.
• --fileio logs every open, read, seek and write. fileio_trace.py turns that into a map per file: offsets and sizes in reading order, with repeated patterns collapsed ([2, 1, 4] x 120 (stride 7) is a table of 120 seven-byte records). When a program reads a file field by field, the read sizes give its record layout (measured).
• A program that reads through a Pascal text file (Assign/Reset on a Text variable) is read in 128-byte blocks: the log shows the buffer, not the fields. Read the code instead.
• --cycles N fixes the CPU speed. Use the same value for every run you compare.
• Exit codes come back through IF ERRORLEVEL (DOSBox-X's shell does not expand %ERRORLEVEL%, and a redirect inside a false IF still creates the file).
• Windowless runs use -silent with SDL's dummy drivers, so there is no window and no sound.

7. The debugger, from an agent or a script

DOSBox-X can connect its debugger to an external controller (setting mcp_server=PORT, the --mcp PORT option of dosbox-run.sh). Two controllers:

• For agents: dosbox-x-mcp-server (https://github.com/caiiiycuk/dosbox-x-mcp-server), registered in .mcp.json as dosbox. Install it with cargo install --git https://github.com/caiiiycuk/dosbox-x-mcp-server --tag v0.1.2 --locked. It listens on 58991; ask it with its dosbox_mcp_port tool, then start DOSBox-X with --mcp 58991. Tools: debug_break, debug_exec (any debugger command), debug_snapshot, debug_run. It has no licence file: use it, do not copy its code.
• For scripts and tests: tools/dos/dbx_control.py speaks the same line protocol (REQ id EXEC command -> BEGIN id OK, output, END id). Use another port than the MCP server's.

Useful debugger commands (type HELP for the build's own list): BP seg:off (breakpoint), BPINT 21 3D (break on an interrupt and AH), BPM seg:off (break when memory changes), D seg:off (dump memory), MEMDUMPBIN seg:off len (to a file), SR reg value (set a register), LDT/GDT (selectors), LOGS/LOGL (CPU trace to a file), STEPIN, RUN.

Finding a selector at run time. A protected-mode program's selectors are chosen by the DPMI host. To map Ghidra's 1000 to the live one: break anywhere in the program, read CS (the segment being executed), list LDT, and dump the first bytes at each code selector; compare them with the file's segment bytes (readseg.py BINARY hex 1000:0000 --count 2). Bytes at relocations differ; everything else matches.