Mastering the Altirra Debugger
Altirra, Avery Lee's Atari 8-bit emulator, includes a debugger that would have been unimaginable in the 1980s. Breakpoints never modify memory and work in ROM or on hardware registers. You can trace interrupts, decode display lists, watch CIO calls, profile cycle by cycle, and step through your original source. Using it well is the biggest single productivity gain in modern Atari development. For the full details of any command, use the built-in reference: type .help or .help <command> in the debugger.
What you'll learn: entering the debugger, stepping, every kind of breakpoint, inspecting and changing memory, symbols and source-level debugging, Atari-specific inspection commands, BASIC support and the profiler.
What you need: Altirra, and ideally a program assembled with symbols. MADS with -l and -t gives the best results. ATasm -l gives labels, and cc65 gives an ld65 .dbg file.
1. Getting in and out
- Debug > Enable Debugger switches to the debugging layout: registers, disassembly, memory, history, and the Output pane with its command line. Debug mode has its own window layout, saved separately. Panes can be docked anywhere, and more are under Debug > Windows.
- F8 is Run/Break. Ctrl+Break breaks too. While stopped, the title bar says so and every pane shows the current state.
- From the command line,
Altirra /debug /debugbrkrun /run prog.xexopens straight into the debugger and stops at the program's run address.
2. Stepping
| Command | Key | Effect |
|---|---|---|
t |
F11 (Step Into) | Execute one instruction. Steps into interrupts and subroutines |
o |
F10 (Step Over) | Like t, but runs whole JSRs and interrupts |
gr |
Shift+F11 (Step Out) | Run until the current subroutine returns |
g |
F8 / F5 in source views | Go |
gf |
Run to the end of the current frame | |
gs <line> |
Run to the start of a scan line | |
gv |
Run to the start of the next vertical-blank interrupt | |
gcr <n> |
Run n machine cycles | |
gt |
Go with per-instruction tracing to the log |
gs and gv are invaluable for raster code. To see what happens on scan line 100, type gs 100, then single-step.
3. Breakpoints
Altirra's breakpoints work by address matching. Memory is never patched, timing is unchanged, and they work in ROM, on hardware registers and regardless of bank switching.
bp start break when PC = start (F9 toggles one in the disassembly view)
bl list breakpoints
bc 2 clear breakpoint 2; bc * clears all
ba w $D01A break on any CPU write to COLBK
ba r $0300 L12 break on reads anywhere in the 12-byte DCB at $0300
bx "pc=$4000 and y=4" conditional breakpoint
bx "write=rtclok+2 and pc>$c000" write from ROM code only
bsc 0 "@ra != $3980" add a condition to breakpoint 0
Notes:
-ncreates a non-stopping breakpoint, and a quoted command runs each time it fires. Together they make a tracepoint:bp -n pc "? db(rtclok+2)"prints the frame counter every time that instruction runs.-kclears the breakpoint on reset.-qkeeps it quiet.bxrecognises simple PC or access patterns and turns them into fast breakpoints. Anything else is checked before every instruction, which is powerful but slow.- Access breakpoints only see the CPU, not ANTIC DMA. Indexed instructions can produce "false reads" that also trip them.
- An extended-memory address such as
$EF'41ACmakes a bank-sensitive breakpoint that fires only when PORTB =$EF. bs <sector>breaks when D1: reads a given sector, which is perfect for following a boot loader.
4. Looking at and changing memory
db $2000 L40 bytes (add -w 16 for width)
dw dlist words
da msg ATASCII text; di = internal screen codes
dbi savmsc bytes plus internal-code text
df $D4 decimal (BCD) float, e.g. FR0
u start L20 disassemble
e $CB 08 00 enter bytes (acts like CPU writes); ew for words
f 4000 L1000 0 fill 4K at $4000 with zero
m 4000 L100 5000 move memory; c E000 L2000 rom:$E000 compare
s 0 L10000 A9 FF search for bytes; sa 0 L10000 "HELLO" search ATASCII
r a $FF set a register; r p.c toggles the carry flag
? dw vdslst evaluate an expression: the current DLI vector
The display commands read memory without side effects, so looking at PIA or cartridge-bank registers won't disturb them. Addresses can name other memory views: n:$0000 (what ANTIC sees), rom:$E000, x: (extended RAM), v: (VBXE), cart: and t:$01'A000 (a banked cartridge). Lengths can be counts (L100) or end addresses (L>5FFF).
Watches update every frame: wb score, ww ptr (up to eight), or wx db(rtclok+2)*2 for any expression. List them with wl and clear them with wc.
Expressions support registers (pc, a, x, y, s, p), beam position (hpos, vpos), @frame, @clk, @cclk, the return address @ra, temporaries @t0–@t9, db/dw memory reads, C-style operators and @hwwritereg(addr), which reads back the value last written to a write-only ANTIC/GTIA/POKEY register.
5. Symbols and source-level debugging
When you boot an executable, Altirra automatically loads symbol files with the same base name (.lst, .lab, .lbl, and ld65 .dbg). To load one by hand, use .loadsym file. Remove them with .unloadsym, and reload after a rebuild with .reload. What you can do depends on the tool:
- MADS (
-tlabels,-llisting) and XASM (/t,/l): labels, listing-level and source-level debugging. - ATasm (
-l): labels only, because its listings carry no source-line data.
Choose Debug > Open Source File… and open the listing, or the original source if line information exists. Lines with a white background map to code. The current line shows in amber and breakpoints in red. F9, F10, F11 and Shift+F11 work in the source window and step by source line. Breakpoints can be set on source lines directly: bp `game.asm:207`. If symbols aren't loaded yet, the breakpoint is deferred and binds when they arrive. x <pattern> searches symbols and ln <addr> finds the nearest one. Altirra ships symbols for the hardware and OS locations, so vdslst, ciov, rtclok and the rest work out of the box.
6. Atari-specific inspection
| Command | Shows |
|---|---|
.antic / .gtia / .pokey / .pia |
Chip register state |
.dumpdlist [addr] |
Decoded display list (current one by default; -n doesn't collapse repeated lines) |
.dlhistory |
What ANTIC actually executed, line by line, last frame |
.dma / .dmamap |
ANTIC DMA cycle usage |
.beam |
Current scan position |
.vectors |
System vectors (VBI, DLI, IRQ…) |
.iocb / .ciodevs |
CIO channels and the device handler table |
.sio |
The SIO device control block |
.tracecio on / .tracesio on |
Log every CIOV / SIOV call with its parameters |
.bank / .map |
Memory banking and memory-layer map |
k |
Call stack |
h |
CPU history (enable "record instruction history" in CPU options) |
.tracecio on alone often explains why a program can't open a file. The log shows every OPEN, its device and filename, and the status that came back.
7. BASIC programs
The debugger understands Atari BASIC, BASIC XL and BASIC XE memory:
.basicshows the table pointers (LOMEM, VNTP, VVTP, STMTAB, STMCUR, STARP, RUNSTK, MEMTOP)..basic_dumpline *decodes the line being executed..basic_dumpline -c 0lists the whole program..basic_varsshows every variable and its value..basic_rebuildvnt/.basic_rebuildvvtrepair damaged variable tables, and.basic_savesaves the program. Together they can recover listings "protected" by a corrupted line table.
8. Finding slow code: the profiler
Debug > Profile > Profile View opens the profiler. Start a session, run the slow part, then stop. The modes are instruction, function (grouped by JSR/RTS and interrupts), call graph (grouped by full call stack), basic block (best for finding hot loops), and BASIC line, which works with Atari BASIC, Altirra BASIC, Turbo-BASIC XL, and BASIC XL/XE outside EXTEND mode. Results are split into main-line, IRQ, VBI and DLI threads, so you can see straight away whether your DLIs are eating the frame.
9. Other power tools
- Heat map (
hme on, thenhma,hmd,hmr) tracks which memory has been read or written, and whether register values come from uninitialised memory. It's very good at finding "works on my machine" bugs caused by RAM that was never cleared. - Verifier targets (
vta/vtl) flag jumps into undocumented OS ROM entry points, the classic cause of programs that break on XL/XE or third-party OSes. - Batch files and aliases:
.batch fileruns a command script.a8installs atari800-style aliases if your fingers know that monitor. .writemem file addr L len/.readmemdump and load raw memory..savestate/.loadstatesave the whole machine..printfformats output. Combined withbp -n, it makes a printf-style debug log with no code changes.
A worked example
Suppose your rainbow effect has a stripe in the wrong place. Boot the program with symbols, then:
ba w $D01A "? vpos; g" ; log the scan line of every COLBK write, keep running
Let it run for a frame and read the log. If one write lands on an unexpected line, clear it (bc *), set gs <that line - 1>, and single-step with F11 to watch the loop's timing against hpos.
Troubleshooting
- Commands do nothing. The emulation is running. Break first (F8).
- The
hcommand shows nothing. Turn on instruction-history recording in the CPU options. - Breakpoints in your code never fire. The code may be in banked memory under another PORTB value. Use the extended
$xx'addrform, or check.bank. - Source window lines are all grey. The listing or source doesn't match the loaded program, or the assembler can't produce line information (ATasm). Rebuild and
.reload. - The debugger is slow. A complex
bxexpression is being checked on every instruction. Rewrite it as a PC or access condition.
Further reading
- Altirra's help file (Help > Contents): "Debugging", "Source-level debugging", "Debugging BASIC programs", "Profiling" and "Symbol options".
- The Altirra Hardware Reference Manual by the same author, for what the chip registers you're inspecting actually do.
- Mapping the Atari (Ian Chadwick, COMPUTE! Books, 1983) for the OS locations the debugger names.
Credits
- Altirra help: debug-intro, debug-source, debug-basic, debug-profiling, debug-symboloptions (Altirra 4.40 source) — Screenshot from Avery Lee's Altirra page, virtualdub.org
- Altirra debugger command reference (src/Altirra/res/dbghelp.txt) — Screenshot from Avery Lee's Altirra page, virtualdub.org
- Altirra command-line help (src/Altirra/res/cmdhelp.txt) — Screenshot from Avery Lee's Altirra page, virtualdub.org
- Altirra home page — Screenshot from Avery Lee's Altirra page, virtualdub.org
- Mapping the Atari — memory map (addresses used in examples) — AtariArchives.org
