asmhatreandClaude Sonnet 5.5
09af523f8c
NASM sources, DOSBox/FreeDOS Debug/Unicorn harness, captured output and 31 assertions backing the ankurm.com article "INT 3 vs INT 21h in 8086 Assembly". Co-Authored-By: Claude Sonnet 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01KqJyCidz3ZgRyHABv2GVJh
interrupts -- INT 3 (breakpoint) vs INT 21h (DOS services)
Companion module for the article
INT 3 vs INT 21h in 8086 Assembly.
Everything the article quotes as program output was produced by scripts/run-all.sh and is stored in output/.
What was actually run, and what was not
| Tool | Version | Used for |
|---|---|---|
| NASM | 2.16.01 | assembling every .asm file (bits 16, flat .COM layout) |
| DOSBox | 0.74-3 | running the .COM programs: a real INT 21h implementation, DOSBox's own default INT 3 vector |
| FreeDOS Debug | 2.50 (MIT) | a DEBUG.EXE-compatible debugger, driven by a script, to watch CC vs CD 03 traps |
| Unicorn | 2.1.4 | a software "debugger" experiment on a 16-bit x86 core (opcode lengths, return addresses) |
Not run: emu8086, Microsoft's own DEBUG.EXE, MASM/TASM, real MS-DOS on real hardware, a real 8086.
DOSBox and Unicorn are emulators; the article says so wherever it matters. Claims about those unrun environments
are labelled "documented, not executed".
Files
| Path | Purpose |
|---|---|
asm/opcodes.asm |
which bytes int3, int 3, db 0CDh,3, int 21h assemble to (listing only) |
asm/hello21.asm |
smallest INT 21h program: AH=09h print, AH=4Ch exit with code 7 |
asm/fn_tour.asm |
one line of output per important INT 21h function (console, vectors, memory, files, EXEC) |
asm/int3_handler.asm |
installs an INT 3 handler with AH=25h; triggers it with CC and with CD 03 |
asm/int3_default.asm |
executes INT 3 with no handler of its own |
asm/dbg_cc.asm, asm/dbg_cd03.asm |
targets for the DEBUG sessions |
asm/bp_target.asm |
flat routine patched by the Unicorn breakpoint experiment |
asm/common.inc |
print helpers (puts, putdec, puthex16) |
scripts/run-all.sh |
rebuild everything in output/ and run the checks |
scripts/dosbox_run.py |
assemble + run the .COM files headless in DOSBox |
scripts/bp_experiment.py |
Unicorn breakpoint experiment |
scripts/check.py |
31 assertions that pin every claim the article makes about the output |
scripts/fetch-debug.sh |
downloads FreeDOS Debug into build/ (not committed) |
output/ |
captured results, numbered in the order the article uses them |
Quickstart
sudo apt-get install nasm dosbox # Debian/Ubuntu
pip install unicorn
./scripts/run-all.sh # prints PASS/FAIL per assertion
DOSBox runs headless (SDL_VIDEODRIVER=dummy). The memory figure on the AH=48h line and the segment numbers in the
DEBUG transcripts depend on the DOSBox build and configuration.