link-and-diff
Use when the matched objects of a DOS decompilation are to be linked into a whole executable with the original linker in headless DOS and compared with the original, region by region; and to prove the result runs and that a source change reaches the screen. Also for an armcc5 Cortex-M firmware, whose whole image is rebuilt in pieces under MDK-Lite's 32 KB limit and compared byte for byte, and for a TI C2000 image, linked whole in one lnk2000 run and compared word for word.
abedegno · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add abedegno/Exhume --skill link-and-diff技能说明
name: link-and-diff description: Use when the matched objects of a DOS decompilation are to be linked into a whole executable with the original linker in headless DOS and compared with the original, region by region; and to prove the result runs and that a source change reaches the screen. Also for an armcc5 Cortex-M firmware, whose whole image is rebuilt in pieces under MDK-Lite's 32 KB limit and compared byte for byte, and for a TI C2000 image, linked whole in one lnk2000 run and compared word for word.
Link and diff
Paths are relative to the Exhume checkout. The link is the strongest check there is: it sees what byte matching with masked fixups cannot (wrong callees, missing relocations, wrong statics, public order), and a byte-identical EXE that runs is the end of the method.
What a link needs
- Every object, in the original module order. The relocation table records it: the linker writes relocations module by module, and a library's modules in library order. An overlay segment table (Borland FBOV) lists every segment in link order too.
- Whatever no source produces yet, taken from the user's own EXE at build time and never committed: data-only assembler modules for far data, gaps in DGROUP between files, code with no source. Each relocation inside them becomes a
dd NAME/dw seg NAMEfixup. - The linker's environment: TLINK stores the output file name (
__EXENAME__) and the DOS date (__EXEDATE__) in the image, so run it under the original name and set the date first (UW2:uwedit.exe, 12 May 1993). The DOS must keep a date set through INT 21h AH=2Bh for the programs after the one that set it: DOSBox-X and js-dos do, emu2 only withtools/emu2-date.patch(built in bytools/setup-emu2.sh); otherwise the date bytes differ and exediff points at the overlay data. The startup module (C0.ASM) may differ from the stock one; find the differences by comparing bytes. - Segments placed in order of first sight, within blocks by class: declare empty segments early in tiny modules, with the class of the objects that fill them, to reproduce the original order and alignment.
Steps
- Build everything:
python3 tools/build.py --all. - Link, in the DOS
tools/dosbackend.mjspicks (emu2 if built: about 2 seconds for UW2; js-dos about 4). With emu2 a link batch may hold only programs with an optional redirection (nocopy, nocd); set the date with a small program, as UW2's SETDATE.COM does. For UW2 this is the reference implementation:python3 examples/uw2/link.py(it runsexamples/uw2/extract.pyfirst). It stops with the source to correct when an object disagrees with the EXE (an unknown name, a public UW2 had static, an overlay's publics out of stub order, a missing relocation). For another game, copy and adapt it; docs/link.md says which parts are general. - Compare:
python3 tools/exediff.py build/LINK/out/GAME.EXE. Give only the linked EXE; the original comes from exhume.toml. It reports header fields, relocations (set, then order), the resident image segment by segment and the overlay area overlay by overlay. - Run it (always in js-dos, whatever DOS built it):
node tools/rungame.mjs --data GAMEDIR --as GAME.EXE build/LINK/out/GAME.EXE shot- w:12000 s:title k:Escape w:3000 s:menu, then read the screenshots. - Prove the build is live: change one string in a copy of a source, build it into a scratch directory (
EXHUME_BUILD=/tmp/x python3 tools/build.py copy/FILE.C), link it in place of the matched object (link.py --no-extract --obj STEM=/tmp/x/STEM/STEM.OBJ --out /tmp/x/out), and see the change on screen. exediff should show exactly the changed bytes. This works only for a change of the same length. - When every object verified, the exact link leaves a snapshot in
<build>/LINK/basefor the modding build (link.py --mod), which links changes of any size. That is skills/modding-build.
What the exact link cannot see
A DGROUP address written as a number (mov si,6742h for offset DGROUP:_Palettes) assembles to the same bytes as the name, so it matches and links exactly. Only a link that moves data exposes it. Run tools/addrscan.py and the layout audit in skills/modding-build before any change that alters sizes.
TLINK leaves memory uncleared
TLINK does not clear the memory it builds the image in unless told to. Padding and data no record covers come out as whatever was there, so the same link can give different bytes in different DOS set-ups or as the module list changes (UW1: 16 to 40 stale bytes in DGROUP under emu2 at 640 KB, none at 512 KB or under DOSBox-X; UW2's modding build met it in overlay padding). Link with /i ("initialize all segments"): the uncovered bytes are then 0, and the link is the same under every DOS (UW1's tools/link.py: /c /m /s /i). The EXE cannot show whether the original link used it.
Reading exediff
- Relocations with the same set in a different order: a segment that was several modules is one source here, or modules are in the wrong order. Split by the linker's padding and the relocation order.
- A resident difference inside one object: a fixup the object lacks or a name resolving elsewhere; verify that file again.
- Only flags in the overlay segment table differ, or whole runs of segments sit in a different order: the original's segments were in other classes. TLINK orders segments in blocks by class and sets a segment's code flag only when its class ends in upper-case
CODE(profiles/borland-tc101/linker.md, "Segment classes"). Try class splits before suspecting the linker version:python3 tools/omfclass.py OBJ SEGNAME CLASSrewrites a segment's class in an object; do it in every object that declares the segment, in a copy of the build directory (EXHUME_BUILD), with the order-fixing module's declarations included (UW2's XORDER takes its classes from the objects), relink, compare. When a pattern links the original, change the sources (a TASM.modelsegment cannot change class: profiles/bor