Fixing the Broken Examples in Mapping the Atari

Two Atari text screens side by side: on the left the words THIS, TEST and BLINKING are invisible in the line 'IS A OF TEXT'; on the right they appear in inverse video, with a column of CHACT=2 and CHACT=1 readings below

Ian Chadwick's Mapping the Atari (1983; Revised Edition 1985) is still the reference most Atari programmers keep open. It is a superb memory map, but its short example programs were not all tested on every machine, and some of them don't work. In 2025 an AtariAge thread worked through several of them, and experienced contributors explained why each one failed. This guide takes three of those examples and one error in the text, checks the original against the book, runs it, and gives a fixed version.

What you need: Atari BASIC and a 400/800 or XL/XE (or an emulator). All the programs were run in atari800 in XL mode, with its built-in AltirraOS and Atari BASIC revision C. The listings below follow the original edition. Small differences between copies are noted where they matter. The AtariAge thread reports that the CHACT and VSCROL examples are unchanged in the Revised Edition.

1. The flashing cursor that crashes (VVBLKD, 548–549)

The entry for the deferred vertical-blank vector offers "a flashing cursor" made with a VBI:

10 FOR BLINK = 1664 TO 1680: READ BYTE: POKE BLINK, BYTE: NEXT BLINK
20 POKE 548,128: POKE 549,6
30 DATA 8,72,165,20,41,16,74,74,74,141
40 DATA 243,2,104,40,76,62,233

The DATA bytes disassemble to:

0680  PHP
0681  PHA
0682  LDA $14        ; RTCLOK, the frame counter
0684  AND #$10       ; bit 4: changes every 16 frames
0686  LSR
0687  LSR
0688  LSR            ; now 0 or 2
0689  STA $02F3      ; CHACT
068C  PLA
068D  PLP
068E  JMP $E93E      ; <-- the problem

Bug 1: an OS-A-only address. $E93E is where the original OS-A ROM's vertical-blank exit happened to sit. The book itself says, under VVBLKD, that the vector holds $E93E in the old ROMs but $E905 in OS-B, and the XL/XE OS is different again. On anything but OS-A, the jump lands in the middle of unrelated ROM code. In our test the emulated machine crashed as soon as line 20 ran, stopping on an illegal instruction. The fix is to leave through the official, fixed vector XITVBV at $E462 (58466). In the DATA, change 62,233 to 98,228.

Bug 2: changing a vector from BASIC. Line 20 sets the two bytes of the vector with separate POKEs. If a vertical blank falls between them (and with BASIC's speed, that's quite likely), the OS jumps through a half-changed address. The fix is to set CRITIC (location 66) first. While CRITIC is non-zero, the OS skips the deferred stage of the VBI, so it can't use the vector while you change it:

10 FOR BLINK = 1664 TO 1680: READ BYTE: POKE BLINK, BYTE: NEXT BLINK
20 POKE 66,255: POKE 548,128: POKE 549,6: POKE 66,0
30 DATA 8,72,165,20,41,16,74,74,74,141
40 DATA 243,2,104,40,76,98,228

With these two changes the program ran. Printing PEEK(755) in a loop showed CHACT switching between 0 and 2, so inverse characters (including the cursor) flick between inverse and normal video.

The book suggests restoring normal behaviour with POKE 548,62: POKE 549,233. That is the same OS-A address again. A portable way is to save the original vector before you change it, then put that back (inside the same CRITIC guard). Two more notes: a deferred VBI doesn't need to save registers, as the thread pointed out, so the PHP/PHA/PLA/PLP bytes are harmless but unnecessary. In assembly, install VBIs with the OS's SETVBV routine ($E45C), which changes the vector safely.

2. Blinking text with a misprinted opcode (CHACT, 755)

The CHACT entry uses system timer 2 to toggle the inverse-character control every half second:

10 PAGE=1536:EXIT=1568
20 FOR N=PAGE TO EXIT:READ BYTE:POKE N,BYTE:NEXT N
30 PGM=USR(PAGE)
40 PRINT "{inv}THIS{/inv} IS A {inv}TEST{/inv} OF {inv}BLINKING{/inv} TEXT":REM MAKE SOME WORDS INVERSE
50 GOTO 50
60 DATA 104,169,17,141,40,2,169,6,141,41
70 DATA 2,169,30,141,26,2,98,173,243,2
80 DATA 41,1,73,1,141,243,2,169,30,141,26,2,96

({inv}…{/inv} marks text typed in inverse video with the Atari key.) The routine has two halves. The first, called by USR, sets the timer-2 vector CDTMA2 ($228) to $0611 and the timer CDTMV2 ($21A) to 30 frames. The second, at $0611, toggles CHACT and restarts the timer. The byte between the halves, at $0610, should be an RTS (96) to end the first half. The book prints 98, which is not a 6502 instruction at all, and the processor jams. The thread found this misprint in a scan of the original book, so it isn't a transcription error. In our test the emulator stopped at $0610, exactly as predicted.

Fix 1: change the 98 in line 70 to 96.

That stops the crash, but the effect still isn't right. The toggle is AND #1 / EOR #1, which works only on bit 0 (the "blank" bit) and clears bit 1 (the "invert" bit) on the first pass. In our test CHACT went 2 → 1 → 0 → 1 → 0…: the inverse words blanked out once and then came back as plain text for good, which is what the AtariAge poster saw.

Fix 2: keep both bits and flip them together. Change 41,1,73,1 in line 80 to 41,3,73,3 (AND #3, EOR #3). CHACT then alternates between 2 (inverse shown normally) and 1 (inverse characters invisible), so the words vanish and reappear (pictured). If you'd rather have the words flash between inverse and normal video, use 41,2,73,2.

As the book explains, the 30 in line 80 sets the rate in frames. It's half a second on an NTSC machine and 0.6 seconds on PAL.

3. Coarse scrolling into garbage (VSCROL, 54277)

The VSCROL entry shows how to scroll coarsely by changing the display list's first LMS address. The book's program:

10 DLIST=PEEK(560)+PEEK(561)*256
20 SCRNLO=DLIST+4:SCRNHI=DLIST+5:REM LSB/MSB OF SCREEN ADDRESS
25 PRINT "SCREEN ADDRESS = ";PEEK(SCRNLO)+PEEK(SCRNHI)*256
30 LOBYTE=0:HIBYTE=0
40 IF STICK(0)=14 THEN LOBYTE=LOBYTE+40:GOTO 100
50 IF STICK(0)=13 THEN LOBYTE=LOBYTE-40
60 IF LOBYTE<0 THEN LOBYTE=LOBYTE+256:HIBYTE=HIBYTE-1
70 IF HIBYTE<0 THEN HIBYTE=0
80 GOTO 200
100 IF LOBYTE>255 THEN LOBYTE=LOBYTE-256
110 HIBYTE=HIBYTE+1
200 POKE SCRNLO,LOBYTE:POKE SCRNHI,HIBYTE
210 GOTO 40

It fills the screen with rubbish at once, for two reasons:

  • Line 30 starts at address 0 instead of the real screen address, so the very first POKE points ANTIC at page zero.
  • Line 110 adds 1 to the high byte on every upward move, not only when the low byte wraps, because it is a separate line instead of part of line 100's THEN. Each push adds 296 bytes, not 40.

The fix starts from the current address and puts the carry inside the IF:

30 LOBYTE=PEEK(SCRNLO):HIBYTE=PEEK(SCRNHI)
100 IF LOBYTE>255 THEN LOBYTE=LOBYTE-256:HIBYTE=HIBYTE+1

and deletes line 110. To check the arithmetic without a joystick, a test version fed the same seven "up" and three "down" moves to both versions and recorded the addresses. The fixed version went from the GRAPHICS 0 screen at 40000 to 40040, 40080 … 40280 and back to 40160, exactly 40 bytes per step. The book's logic went 296, 592, 888 … 1816, wandering through pages 1 to 7 of low memory. (Some electronic copies of the book also spell the variable SCRNLOW in line 200, which would POKE location 0, and leave out the semicolon in line 25. Check your copy.)

Even fixed, the program has no upper limit. Hold the stick up long enough and you'll scroll past the end of screen memory into whatever is above it. Add a test against the starting address plus the amount of memory you've reserved.

4. One error in the text: AUDCTL bit 2

Not every mistake is in a listing. In the AUDCTL entry (53768, $D208) the book says bit 2 inserts a high-pass filter into channel one "clocked by channel two". It is clocked by channel three, as bit 1 filters channel two clocked by channel four. The Altirra Hardware Reference Manual describes the pairing. If your filter effects don't behave as the book predicts, this is why.

General lessons

  • Disassemble before you POKE. Every one of these programs is a few bytes of DATA. Typing them into a monitor or a disassembler (the Altirra debugger will do) turns a mystery crash into an obvious bad byte.
  • Treat any ROM address other than an official vector as OS-A-only. Programs from 1981–83 were often tested on OS-A. Use the documented vectors: XITVBV $E462, SYSVBV $E45F, SETVBV $E45C.
  • Guard two-byte vector changes with CRITIC, or do them in machine code.
  • Keep the original book as published. People in the thread argued that errata should go in a separate appendix rather than into the scanned text, and that's good practice for your own copy too.

Troubleshooting

  • "The Atari computer has crashed" (emulator) or a locked machine: check every DATA byte against the disassembly. A single wrong number becomes an illegal opcode.
  • Works on one machine, crashes on another: look for absolute ROM addresses. They differ between OS-A, OS-B and the XL/XE OS.
  • Blinking stops after one cycle: check that your toggle keeps the CHACT bits you didn't mean to change.

Further reading

  • Ian Chadwick, Mapping the Atari (Small System Services, 1983) and Mapping the Atari, Revised Edition (1985), locations 66 (CRITIC), 548–549 (VVBLKD), 550–561 (system timers), 755 (CHACT), 53768 (AUDCTL) and 54277 (VSCROL). The full text is on atariarchives.org.
  • The AtariAge thread "Mapping bugs" (Atari 5200/8-bit Programming forum, 2025), which collects these and other corrections.
  • On this site: Vertical Blank Interrupts: Running Code 60 Times a Second, Coarse Scrolling with LMS: Moving the Window, Not the Data, Display Lists Explained: How ANTIC Builds the Atari Screen.

Credits