Vertical Blank Interrupts: Running Code 60 Times a Second
Every time the TV picture finishes, ANTIC raises a non-maskable interrupt and the operating system runs its vertical blank routine. That happens 60 times a second on NTSC machines and 50 on PAL. The routine updates the clock, decrements timers, reads the joysticks and copies the colour "shadow" registers into the hardware. The OS lets you hook your own code into this routine at two points. Once hooked, your code runs at a steady rate no matter what the main program is doing: in BASIC, waiting for INPUT, or even while you edit a listing. This guide explains the mechanism and gives you two working VBIs.
You need: basic 6502 knowledge, Atari BASIC for the type-in example, and optionally an assembler. The concepts apply to all 400/800/XL/XE machines.
1. What happens during vertical blank
James Capparell's Best of Antic article "Interrupts" and De Re Atari, Chapter 8, describe the same sequence:
- ANTIC signals an NMI. The OS NMI handler checks the NMI status register at $D40F. If the interrupt is not a display list interrupt or the RESET key, it must be vertical blank.
- The OS pushes A, X and Y onto the stack.
- It jumps through VVBLKI at $0222 (546–547), the immediate vector.
- Normally that points to the OS stage 1 code. Stage 1 increments the realtime clock RTCLOK ($12–$14), processes attract mode and decrements system timer 1.
- The OS then checks whether a time-critical section was interrupted: either the CRITIC flag at $42 (66) is non-zero, as during serial I/O, or the 6502's I flag was set. If so, it restores the registers and returns immediately.
- Otherwise stage 2 runs. It enables IRQs, handles keyboard repeat and debounce, decrements timers 2–5, copies the shadow registers (colours, DMA control and so on) into the chips, and reads the joysticks, paddles and triggers into RAM.
- Finally the OS jumps through VVBLKD at $0224 (548–549), the deferred vector. By default that leads straight to the exit code, which restores A, X, Y and executes RTI.
The OS gives you three fixed entry points in its ROM jump table:
| Name | Address | Use |
|---|---|---|
| SETVBV | $E45C (58460) | Safely change VBI vectors or system timers |
| SYSVBV | $E45F (58463) | Continue into the OS VBI (end of an immediate VBI) |
| XITVBV | $E462 (58466) | Exit the VBI (end of a deferred VBI) |
2. Immediate or deferred?
| Immediate (VVBLKI, A=6) | Deferred (VVBLKD, A=7) | |
|---|---|---|
| Runs | Before the OS stage 1 code | After all OS processing |
| Runs during disk/cassette I/O? | Yes, every frame | No: skipped while CRITIC is set |
| Time available | Small: a few thousand cycles at most (keep it to about 2,000) | About 20,000 cycles, but much of it while the beam is drawing the screen |
| Ends with | JMP SYSVBV ($E45F), or JMP XITVBV to skip the OS VBI completely |
JMP XITVBV ($E462) |
De Re Atari's rules of thumb:
- If you write to registers the OS also shadows, remember that "he who writes last, writes best". A deferred VBI writing a hardware register overrides the OS copy for that frame. An immediate VBI writing the shadow gets its value copied into the chip by stage 2.
- Long routines belong in the deferred VBI, so they do not delay the OS colour updates past the end of vertical blank.
- If your code must run during disk I/O (a music player that must never pause, say), make it immediate, and be wary of disturbing time-critical I/O.
3. Installing a VBI safely: SETVBV
A vector is two bytes, and an interrupt could arrive after you have changed only one of them. The result would be a jump into random memory. SETVBV performs the change safely:
LDY #<MYVBI ; low byte of routine
LDX #>MYVBI ; high byte
LDA #7 ; 6 = immediate, 7 = deferred
JSR SETVBV ; $E45C
The same call sets the system timers when A = 1–5, with X/Y holding the timer value (see Realtime clock and timers). A, X and Y may be changed by the call, and that display list interrupts are always enabled on return.
Chain, don't replace. Another program, such as a music driver or a DOS extension, may already be using the vector. The polite technique is to save the old contents of $0224/$0225 and end your routine with JMP (OLDVEC) instead of JMP XITVBV. The example below does exactly that.
4. Example 1: blinking inverse text from BASIC
CHACT at 755 ($2F3) controls how inverse characters are displayed: 2 is normal and 0 shows them as plain text. Toggling this value makes inverse text blink. Doing it in a VBI makes the blink perfectly regular and costs BASIC nothing. The routine reads the jiffy counter (RTCLOK+2, location 20), keeps bit 4 and shifts it down to give 0 or 2:
SETVBV = $E45C
CHACT = $02F3
RTCLOK = $12
*= $0680 ; upper half of page 6 (1664)
INSTALL PLA ; remove USR argument count
LDA $0224 ; save current deferred vector
STA OLD
LDA $0225
STA OLD+1
LDY #<BLINK
LDX #>BLINK
LDA #7
JSR SETVBV
RTS
BLINK LDA RTCLOK+2 ; jiffies
AND #$10 ; changes every 16 frames
LSR A
LSR A
LSR A ; 0 or 2
STA CHACT
JMP (OLD) ; chain to previous deferred VBI
OLD .WORD 0
REMOVE PLA
LDY OLD
LDX OLD+1
LDA #7
JSR SETVBV ; put the old vector back
LDA #2
STA CHACT ; normal display again
RTS
Hand-assembled, it occupies 1664–1719. INSTALL is at 1664 and REMOVE at 1702:
10 FOR I=1664 TO 1719:READ B:POKE I,B:NEXT I
20 X=USR(1664)
30 PRINT "{inverse}THIS TEXT BLINKS{inverse off} THIS DOES NOT"
40 PRINT "TYPE X=USR(1702) TO STOP"
100 DATA 104,173,36,2,141,164,6,173,37,2
110 DATA 141,165,6,160,151,162,6,169,7,32
120 DATA 92,228,96,165,20,41,16,74,74,74
130 DATA 141,243,2,108,164,6,0,0,104,172
140 DATA 164,6,174,165,6,169,7,32,92,228
150 DATA 169,2,141,243,2,96
In line 30, type the first phrase in inverse video by pressing the inverse-video key before and after it. The {inverse} markers are only a typing convention: do not type them literally. The cursor blinks too, because CHACT also controls the cursor.
Two cautions:
- Run line 20 only once. Installing twice would save BLINK's own address as the "old" vector, and the routine would chain to itself forever. To reinstall, run REMOVE first.
- We used the upper half of page 6 (from $680) because an INPUT of more than 128 characters spills into $600–$67F.
5. Example 2: an immediate VBI in assembly
This routine slowly cycles the background hue. It writes the shadow register COLOR4 (712, $2C8), and the OS stage 2 code that runs straight after it copies the value to the hardware:
SETVBV = $E45C
SYSVBV = $E45F
COLOR4 = $02C8
*= $3000
START LDA #8
STA DELAY
LDY #<VBI
LDX #>VBI
LDA #6 ; immediate vector
JSR SETVBV
RTS
VBI DEC DELAY
BNE EXIT
LDA #8
STA DELAY
LDA COLOR4
CLC
ADC #$10 ; next hue, same luminance
STA COLOR4
EXIT JMP SYSVBV ; continue with OS stage 1/2
DELAY .BYTE 0
You do not need to save registers. The OS pushed A, X and Y before calling you and pulls them again in its exit code. Do not end an immediate VBI with RTI, and do not end a deferred one with RTS.
6. What VBIs are good for
The classic uses, which Atari software has relied on ever since:
- Flicker-free screen changes. Swap display lists, scroll registers or character sets while the beam is off-screen. Page flipping and smooth scrolling are usually driven this way.
- Sound and music with exact timing (see Programming music).
- Reading controls every frame without the main program having to poll.
- A crude form of multitasking: a foreground task in the VBI, a background task in mainline code. Keep their data separate.
Troubleshooting
- Machine locks up as soon as the VBI is installed. Check the exit jump: immediate → $E45F, deferred → $E462. Also check that the routine is in memory that nothing else overwrites, such as a BASIC string that moved, or a page-6 area clobbered by long INPUT.
- The VBI stops after SYSTEM RESET. That is by design: the OS reloads its RAM vectors on every reset. Programs that must survive RESET re-install themselves through the DOSINI vector.
- Effect freezes during disk access. Deferred VBIs and stage 2 are skipped while CRITIC is set. Move time-sensitive code to an immediate VBI.
- Colours written in the VBI get overwritten. You wrote a hardware register in an immediate VBI and the OS then copied the shadow over it. Write the shadow instead, or use a deferred VBI.
- PAL timing differs. VBIs run at 50 Hz on PAL machines, so frame-counted delays are 20% slower.
Further reading
- De Re Atari (Atari, Inc., 1982), Chapter 8, and Chapter 5 for display list interrupts.
- Mapping the Atari by Ian Chadwick (Small System Services, 1983), locations 546–549 and the table of VBLANK processes.
- Atari Assembly Language Programmer's Guide by Alan Moose and Marian Lorenz (Weber Systems, 1986).
- On this site: Display list interrupts and Page 6 usage.
Credits
- De Re Atari, Chapter 8: The Operating System — Vertical Blank Interrupt Processing — Jim Dunion (Section 8 of De Re Atari)
- Mapping the Atari (Ian Chadwick) — VVBLKI/VVBLKD 546–549, RTCLOK, CRITIC, CHACT — AtariArchives.org
- Interrupts (James Capparell), Best of Antic Volume 1 — AtariMagazines.com (Kevin Savetz)
- cc65 atari.inc (OS equates) — GitHub project authors
