Advanced DLI Techniques: Kernels, Dispatch Tables and Cycle Budgets

Atari text screen with eight lines of text over horizontal blue and purple gradient bars that also fill the border, and a red status panel at the bottom

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 WSYNC has fixed timing. Because the 6502 ignores the halt signal during the extra write cycle of a read-modify-write instruction, the instruction after INC WSYNC always 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. bars is page-aligned, so LDA bars,X never 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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