Advanced DLI Techniques: Kernels, Dispatch Tables and Cycle Budgets
Display List Interrupts covers the basics: set bit 7 on a display list instruction, point VDSLST at a routine, save registers, STA WSYNC, store a colour, RTI, and chain several DLIs by rewriting the vector. This guide is the next step: DLIs that run for dozens of scan lines, cheaper ways to run many different DLIs per frame, exactly how many cycles you have, and how to divide the work between DLIs and the vertical blank.
What you'll learn: writing a DLI kernel that changes registers every scan line from a table, four ways to dispatch multiple DLIs, saving registers cheaply, the cycle budget of a scan line, VBI/DLI coordination, and the traps (missed NMIs, WSYNC side effects, VCOUNT edge cases).
What you need: MADS (or any 6502 assembler), an emulator with a debugger (Altirra is ideal for cycle counting), and a working knowledge of simple DLIs and VBIs.
1. The scan-line budget
Every scan line lasts 114 CPU cycles, but ANTIC takes some of them. Here is what happens on the last scan line of a mode line with the DLI bit set, using the stock OS handler:
| Cycle | Event |
|---|---|
| 8 | ANTIC asserts NMI (after display list and player/missile DMA) |
| ~10–17 | 6502 finishes its current instruction and enters the interrupt (7 cycles) |
| +11 | OS handler: BIT NMIST / BPL / JMP (VDSLST) |
| 28–36 | your code starts (on a blank or light mode line) |
| 36–44 | your code starts if the line is a normal-width GRAPHICS 0 line |
| ≤103 | last cycle on which a write to WSYNC still waits for this line |
| 105 | CPU resumes after WSYNC, start of horizontal blank |
A DLI divides into three phases. Phase one runs from entry to STA WSYNC: up to 55 usable cycles on a blank line, but as few as 15 on a 40-byte line such as GRAPHICS 0, 7 or 8, because ANTIC steals a cycle for each byte it fetches. Phase two is horizontal blank after WSYNC: about 27 cycles of real time, of which 17–26 are usable after player/missile, display-list and refresh DMA. Changes made here appear cleanly at the left edge of the next line. Phase three is everything after that, which is not time-critical but delays the main program.
Rules of thumb that follow:
- Preload, then store. Load A, X and Y before WSYNC; after it, do nothing but
STA/STX/STY. That changes three registers in about 12 cycles. - The first scan line of a character row is the worst. ANTIC fetches the character names and font data then, leaving very few CPU cycles. A DLI that must do a lot is best placed on a blank line ($00–$70 instructions).
INC WSYNChas fixed timing. Because the 6502 ignores the halt signal during the extra write cycle of a read-modify-write instruction, the instruction afterINC WSYNCalways starts on cycle 105, whatever the DMA. (65C02 and 65C816 accelerators behave differently, so don't rely on it if you want compatibility with them.)
2. Cheaper register saving
The usual PHA / TXA / PHA / TYA / PHA costs 13 cycles going in and 16 coming out. Storing to zero page is quicker: STA zp / STX zp / STY zp is 9 cycles, and the matching loads are another 9. That saves 11 cycles per DLI, nearly half of phase two. It only works if the DLI can't interrupt itself, which is true as long as each DLI returns before the next DLI line arrives. A routine that only needs A should push just A.
3. A DLI kernel: one interrupt, 64 lines
A DLI doesn't have to be short. A kernel is a routine that takes control for many lines, hitting WSYNC on each one. The term and the technique come from the Atari 2600; DLIs were designed to replace this more primitive method. They are still the right tool when something must change on every line:
; DLI kernel + same-page chain - mads kernel.asm -o:kernel.xex
VDSLST = $0200
SDLSTL = $0230
COLOR2 = $02C6 ; shadows used to restore colours
COLOR4 = $02C8
COLPF1 = $D017
COLPF2 = $D018
COLBK = $D01A
WSYNC = $D40A
NMIEN = $D40E
SETVBV = $E45C
SYSVBV = $E45F
save_a = $80 ; zero-page register saves (3 cycles each)
save_x = $81
save_y = $82
phase = $83 ; start of the colour table this frame
tmp = $84
org $2000
main ldx #0 ; build a 256-byte table of colour bars
mk txa
and #$1F
tay
lda lumtab,y ; luminance rises and falls every 32
sta tmp
txa
and #$E0
lsr @ ; hue changes every 32 entries
clc
adc #$20
ora tmp
sta bars,x
inx
bne mk
lda #<dlist
sta SDLSTL
lda #>dlist
sta SDLSTL+1
lda #6
ldy #<vbi
ldx #>vbi
jsr SETVBV
lda #<kern
sta VDSLST
lda #>kern ; all DLIs live in this page
sta VDSLST+1
lda #$C0
sta NMIEN
jmp *
vbi lda #<kern ; restart the chain: low byte only
sta VDSLST
inc phase ; scroll the bars one line per frame
jmp SYSVBV
.align $100
; DLI 1: a kernel that runs for 64 scan lines
kern sta save_a
stx save_x
sty save_y
ldx phase
ldy #64
kloop lda bars,x ; preload...
sta WSYNC ; ...wait for horizontal blank...
sta COLPF2 ; ...and store at once
sta COLBK
inx
dey
bne kloop
lda COLOR2 ; put the normal colours back
ldx COLOR4
sta WSYNC
sta COLPF2
stx COLBK
lda #<panel ; next DLI in the chain
sta VDSLST
lda save_a
ldx save_x
ldy save_y
rti
; DLI 2: a status panel with three colour changes
panel sta save_a
stx save_x
sty save_y
lda #$34 ; red background
ldx #$0F ; white text
ldy #$32 ; red border
sta WSYNC
sta COLPF2
stx COLPF1
sty COLBK
lda save_a
ldx save_x
ldy save_y
rti
lumtab dta 0,0,2,2,4,4,6,6,8,8,10,10,12,12,14,14
dta 14,14,12,12,10,10,8,8,6,6,4,4,2,2,0,0
dlist dta $70,$70,$70
dta $42,a(screen)
dta $82 ; DLI: kernel starts on the next line
:8 dta $02 ; 8 lines = 64 scan lines of bars
:10 dta $02
dta $82 ; DLI: status panel below
dta $02,$02
dta $41,a(dlist)
screen dta d' ADVANCED DLI TECHNIQUES '
dta d' '
:8 dta d' ONE DLI, 64 SCAN LINES OF COLOUR '
:10 dta d' '
dta d' '
dta d' STATUS PANEL: SCORE 001250 LIVES 3 '
dta d' SECOND DLI, CHAINED IN THE SAME PAGE '
.align $100
bars .ds 256
run main
How it works:
- The kernel loop is
LDA bars,X / STA WSYNC / STA COLPF2 / STA COLBK / INX / DEY / BNE, 23 CPU cycles per pass. That is short enough to fit even on the DMA-heavy first scan line of each text row, so the colour changes on every one of the 64 lines.barsis page-aligned, soLDA bars,Xnever takes an extra cycle for a page crossing. - The VBI scrolls the effect by incrementing
phase, the starting point in the 256-byte table. The DLI does no calculation beyond indexing; all the "thinking" happens once per frame in vertical blank. - The kernel restores the colours from the OS shadows COLOR2 and COLOR4 on its way out, so the lines below look normal.
- Both DLIs live in one 256-byte page (
.align $100), so the kernel switches to the panel DLI by writing only the low byte of VDSLST, and the VBI resets the chain the same way. - The panel DLI preloads three values and stores all three after one WSYNC: background, text luminance and border.
The price of a kernel is CPU time. Here 64 lines × 114 cycles are spent waiting, roughly a third of the visible frame. A full-screen kernel leaves the 6502 free only in vertical blank and overscan, about 4,000 cycles per frame. That suited skill games such as Atari's Basketball, whose multicoloured players were kernel-driven, and it is why most games use ordinary short DLIs instead.
4. Four ways to dispatch many DLIs
There is only one vector, so a screen with many different DLIs needs a strategy:
- Vector chain. Each DLI writes the address of the next into VDSLST at the end, and the VBI resets it to the first. It is the most general solution, and the vectoring work happens after the time-critical part. Keep all DLIs in one page and you only rewrite the low byte (6 cycles saved), as in the program above.
- Index table. One routine reads its values from tables using a counter that it increments and the VBI resets. This is ideal when every DLI does the same job with different values (colours per band, font pages, player positions). Character Set Switching with DLIs uses it.
- VCOUNT test. The routine reads VCOUNT ($D40B, 54283), which holds the current scan line divided by two, and branches. It costs cycles before WSYNC, but needs no state and so can never get out of step.
- Patched operands. The VBI writes this frame's value straight into the DLI's
LDA #instruction. The DLI then needs no index register at all.
Methods 3 and 4 look like this. The routine serves two DLI lines, choosing by VCOUNT, and the upper colour is patched by the VBI each frame (both tested in a small harness program):
; in the VBI: patch this frame's colour into the DLI
vbi lda RTCLOK+2 ; any per-frame value
and #$F0
ora #$06
sta col+1 ; patch the DLI's immediate operand
jmp SYSVBV
; the DLI: one routine, VCOUNT decides which job to do
dli pha
lda VCOUNT ; current scan line / 2
cmp #60 ; below scan line 120?
bcs lower
col lda #$00 ; operand rewritten by the VBI
sta WSYNC
sta COLBK
pla
rti
lower lda #$C4
sta WSYNC
sta COLBK
pla
rti
5. DLI and VBI working together
The cleanest designs split the work strictly: the VBI computes, the DLIs only copy.
- Reset state in the VBI. Chain vectors and table indexes must be reset every frame, or a single missed DLI (see below) leaves every later DLI one band out of step until the next reset. Use the immediate VBI (SETVBV with A = 6, ending
JMP SYSVBV); the OS can skip the deferred VBI when it interrupts time-critical code. - Precompute expensive values. Do attract-mode processing (
EOR COLRSH,AND DRKMSK, locations 79 and 78) in the VBI: keep one table of the colours you want and a second of their attracted versions, and let the DLIs read the second table. - Avoid half-updated tables. If the main program changes a table while the beam is half way down, the top and bottom of the screen show different frames. Update tables in the VBI, or build a second table and swap a pointer during vertical blank.
- Enable DLIs at a safe moment. Set VDSLST, reset your index and only then write NMIEN, ideally right after vertical blank (wait for RTCLOK at 20 to change), so the first DLI of the first frame is the right one.
6. Traps
- Missed NMIs. If the 6502 starts acknowledging an IRQ on exactly cycle 4 of a scan line, ANTIC's NMI on cycle 8 is lost. DLIs, VBIs and (on the 400/800) the Reset key can all be missed this way, which is why DLI screens glitch during disk and serial I/O. The NMIST status bits are still set, but the handler never runs.
- WSYNC delays interrupts. The CPU can't take an interrupt while halted by WSYNC. A main-loop routine that hits WSYNC just before a DLI line pushes that DLI later. The OS keyboard click does exactly this, making colour splits jump down a line while keys are pressed.
- Long DLIs get interrupted. A DLI still running when the next DLI line arrives is itself interrupted by the next NMI. Make every DLI (kernels included) return before the next DLI line, and keep a long kernel clear of the VBI at scan line 248.
- VCOUNT edges. VCOUNT counts in steps of two lines, from 0 to $82 on NTSC and to $9B on PAL. Test with greater-or-equal comparisons rather than equality, especially for code that must run on both video standards.
- Vertical scrolling moves DLIs. If a scrolled region shortens a mode line, its DLI fires at the end of the shortened line, possibly on a DMA-heavy first scan line of the next row.
- Never set the DLI bit on JVB ($C1) unless you mean it: it fires a DLI on every scan line until vertical blank.
Troubleshooting
- Bands drift by one each frame or flicker between positions: the chain or index isn't reset in the VBI, or DLIs were enabled mid-frame.
- A colour edge jitters left and right: a store happens before WSYNC, or too many stores come after it and spill into the visible line.
- The kernel's lower lines are late or doubled: the loop is too long for the DMA-heavy lines. Count cycles, align tables to avoid page crossings, or move the kernel over blank or bitmap lines.
- Main program slows to a crawl: too much time spent in DLIs. Move calculations into the VBI and shorten kernels.
- Glitches only during loading: missed NMIs during SIO. Hide the effect (blank the screen or freeze DLI changes) while doing I/O.
Further reading
- De Re Atari (Atari, 1982), Chapter 5: DLI timing phases, multiple DLIs, attract mode and kernels.
- Altirra Hardware Reference Manual, sections 4.8–4.10 and 4.14: NMI timing, WSYNC behaviour, VCOUNT and per-mode DMA cycle maps.
- Atari Graphics and Arcade Game Design by Jeffrey Stanton and Dan Pinal (Arrays, 1984), Chapter 6: a kernel-driven multicoloured player.
- Rob McMullen's "Atari 8-bit Display List Interrupts: A Complete(ish) Tutorial" (Player/Missile Podcast): multiple-DLI techniques, kernels and many runnable examples.
- Mapping the Atari by Ian Chadwick (COMPUTE! Books): 512–513, 54282, 54283, 54286 and 54287.
Credits
- Picture: The example program: one DLI stays in control for 64 scan lines and changes two colour registers on every line, then a second DLI draws a red status panel. — Program authors; screenshot by the site
- De Re Atari, Chapter 5: Display List Interrupts (timing phases, multiple DLIs, attract mode, kernels) — AtariArchives.org
- Altirra Hardware Reference Manual, sections 4.8 (NMIs, DLI timing, missed NMIs), 4.9 (WSYNC, INC WSYNC) and 4.10 (VCOUNT) — Avery Lee (Altirra)
- Player/Missile Podcast — Atari 8-bit Display List Interrupts: A Complete(ish) Tutorial (multiple DLIs, same-page vectors, kernels) — playermissile.com
- Atari Graphics and Arcade Game Design (Stanton & Pinal), Chapter 6: Vertical Blank & Display List Interrupts, Kernels — AtariArchives.org
- Mapping the Atari (revised) — 20 RTCLOK, 78 DRKMSK, 79 COLRSH, 512-513 VDSLST, 54282 WSYNC, 54283 VCOUNT, 54286 NMIEN, 54287 NMIST/NMIRES, 58460 SETVBV, 58463 SYSVBV — AtariArchives.org
- AtariAge forum — Changing a character set in a display list interrupt (zero-page register saves, preloading) — AtariAge forum members
