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:

  1. 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.
  2. The OS pushes A, X and Y onto the stack.
  3. It jumps through VVBLKI at $0222 (546–547), the immediate vector.
  4. 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.
  5. 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.
  6. 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.
  7. 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