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
49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
# interrupts -- INT 3 (breakpoint) vs INT 21h (DOS services)
|
|
|
|
Companion module for the article
|
|
[INT 3 vs INT 21h in 8086 Assembly](https://ankurm.com/understanding-int-3h-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
|
|
|
|
```bash
|
|
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.
|