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.xex opens 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:

  • -n creates 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.
  • -k clears the breakpoint on reset. -q keeps it quiet.
  • bx recognises 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'41AC makes 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 (-t labels, -l listing) 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:

  • .basic shows the table pointers (LOMEM, VNTP, VVTP, STMTAB, STMCUR, STARP, RUNSTK, MEMTOP).
  • .basic_dumpline * decodes the line being executed. .basic_dumpline -c 0 lists the whole program.
  • .basic_vars shows every variable and its value.
  • .basic_rebuildvnt / .basic_rebuildvvt repair damaged variable tables, and .basic_save saves 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, then hma, 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 file runs a command script. a8 installs atari800-style aliases if your fingers know that monitor.
  • .writemem file addr L len / .readmem dump and load raw memory. .savestate / .loadstate save the whole machine.
  • .printf formats output. Combined with bp -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 h command 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'addr form, 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 bx expression 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