# 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.