POKEY Timer Interrupts in Depth: Exact Periods, Linked Timers and Raster Effects Without DLIs

Atari screen filled with horizontal colour bands eight scan lines tall cycling through the hues, under the caption TIMER 1 IRQ EVERY 8 SCAN LINES - NO DLI

POKEY's four sound channels are really four programmable countdown timers. Three of them can interrupt the CPU when they run out. Keeping Time: RTCLOK, System Timers and POKEY Hardware Timers shows the basic recipe for a timer IRQ. This guide goes further. It covers the exact period of each clock setting, joining two timers into a 16-bit one, what STIMER really does, and the property that makes POKEY timers useful for graphics: the 15 kHz clock runs at exactly one tick per scan line. Two tested programs use that to change colours at precise screen lines without a single display list interrupt.

What you'll learn: the period formulas for the 64 kHz, 15 kHz and 1.79 MHz clocks, the longest and shortest intervals each can produce, how linked timers behave, which timer actually interrupts, what STIMER does and doesn't reset, scan-line-locked timer effects, and the interactions with SIO and the OS.

What you need: MADS and an emulator, plus the IRQ basics from Inside the OS Interrupt Handlers. Both examples were assembled with MADS and run in atari800 on the genuine XL/XE OS Rev. 2 ROM, in NTSC and PAL modes.

1. Three clocks, three formulas

Each channel counts down from the value in its AUDF register. When the counter underflows, it reloads and sends a pulse to the sound circuit, the serial port and, if enabled, the IRQ logic. What the counter counts depends on AUDCTL ($D208):

AUDCTL bit Effect
0 0 = 64 kHz base clock, 1 = 15 kHz base clock (shared by every channel not on 1.79 MHz)
6 Channel 1 counts the 1.79 MHz machine clock
5 Channel 3 counts the 1.79 MHz machine clock
4 Link channels 1 and 2 into one 16-bit timer
3 Link channels 3 and 4 into one 16-bit timer

The base clocks are the machine clock divided by 28 (the "64 kHz" clock) and by 114 (the "15 kHz" clock). The exact periods in CPU cycles, for an AUDF value N, are:

Mode Period in cycles Range (NTSC)
8-bit, 64 kHz clock (N+1) × 28 28 to 7,168 cycles (249.7 Hz at the slowest)
8-bit, 15 kHz clock (N+1) × 114 114 to 29,184 cycles (61.3 Hz)
8-bit, 1.79 MHz (channels 1 and 3 only) N + 4 4 to 259 cycles
16-bit linked, 1.79 MHz low channel N + 7 up to 65,542 cycles (27.3 Hz)
16-bit linked, 64 kHz (N+1) × 28 up to 1,835,008 cycles (about 1.03 s)
16-bit linked, 15 kHz (N+1) × 114 up to 7,471,104 cycles (about 4.2 s)

For linked timers, N = AUDF1 + 256 × AUDF2 (or AUDF3 + 256 × AUDF4). The odd +4 and +7 on the fast clock come from pipeline delays inside POKEY as the counter reloads. With the slow clocks, those few cycles are absorbed while waiting for the next clock tick, so the clean (N+1) formula holds.

Two things trip people up with these formulas. First, the sound chapters of many books include an extra factor of 2, because a square wave needs two timer periods per cycle. A timer IRQ fires once per period, so leave that factor out. Second, the machine clock is 1.78977 MHz on NTSC and 1.77345 MHz on PAL, so the same AUDF value gives a slightly different rate on each.

2. Linked timers: which one interrupts?

When bit 4 of AUDCTL is set, channel 2 counts channel 1's underflows instead of a clock. The pair becomes one 16-bit counter, and the high timer, channel 2, carries the combined period. That is the one to enable in IRQEN (bit 1, vector VTIMR2 at $0212). For the 3+4 pair it is timer 4 (bit 2, VTIMR4 at $0214). Remember that the original OS-A never dispatches VTIMR4, so on a 400/800 with that ROM, use the 1+2 pair.

The low channel keeps firing as well: it underflows AUDF2+1 times for every period of the pair. So don't enable timer 1's IRQ by accident when using a linked pair, or you will get extra interrupts at a rate you didn't plan.

3. What STIMER does

Writing any value to STIMER ($D209) reloads all four counters from their AUDF registers. It doesn't fire the timers or cause an interrupt. Crucially, it doesn't reset the 64 kHz and 15 kHz clocks themselves. Those run continuously, and their phase is only reset when POKEY leaves its initialisation mode (both low bits of SKCTL cleared, then set again).

In practice:

  • Write STIMER after setting up AUDF and AUDCTL, so the first period starts from a known count.
  • With the 1.79 MHz clock, STIMER starts the period almost at once.
  • With a slow clock, the first period can be up to one clock tick short, because the counter only decrements on the clock's next tick. After that the period is exact.

4. The 15 kHz clock is a scan line

An Atari scan line is 114 machine cycles long, on both NTSC and PAL. The 15 kHz clock divides the machine clock by 114 too. The two aren't connected, but they run at precisely the same rate. So once the 15 kHz clock is running, each tick lands at the same horizontal position on every scan line. A timer on that clock with AUDF = N interrupts every N+1 scan lines, exactly, for as long as you like. That makes POKEY a second source of raster interrupts, alongside ANTIC's DLIs.

Example 1: colour bands every 8 lines

; Raster bands without DLIs: POKEY timer 1 on the 15 kHz clock fires
; every 8 scan lines; the VBI restarts it at the same point each frame.
POKMSK  = $10
SAVMSC  = $58
VTIMR1  = $0210
COLOR1  = $02C5
COLPF2  = $D018
AUDF1   = $D200
AUDC1   = $D201
AUDCTL  = $D208
STIMER  = $D209
IRQEN   = $D20E
WSYNC   = $D40A
SETVBV  = $E45C
SYSVBV  = $E45F
LINES   = 8                 ; scan lines per band

        org $3000
start   lda #$0E
        sta COLOR1          ; white text
        ldy #0
msg     lda text,y          ; put a caption on the screen
        sta (SAVMSC),y
        iny
        cpy #textlen
        bne msg
        sei
        lda #<timer1
        sta VTIMR1
        lda #>timer1
        sta VTIMR1+1
        lda #$01
        sta AUDCTL          ; bit 0: 15 kHz clock (114 cycles = 1 scan line)
        lda #0
        sta AUDC1           ; channel 1 silent
        lda #LINES-1
        sta AUDF1           ; period = (AUDF1+1) x 114 cycles
        lda POKMSK
        ora #$01            ; enable timer 1 IRQ (and keep the OS copy)
        sta POKMSK
        sta IRQEN
        cli
        ldy #<vbi           ; immediate VBI restarts the timer
        ldx #>vbi
        lda #6
        jsr SETVBV
loop    jmp loop

vbi     lda #$04            ; first band colour for this frame
        sta colr
        sta WSYNC           ; same horizontal position every frame
        sta STIMER          ; reload timer 1: bands start at a fixed line
        jmp SYSVBV          ; continue with the OS VBI

timer1  lda colr            ; OS has already pushed A
        sta WSYNC           ; wait for the start of the next line
        sta COLPF2          ; text-window background
        clc
        adc #$10            ; next hue, same brightness
        sta colr
        pla
        rti

colr    dta 0
text    dta d'TIMER 1 IRQ EVERY 8 SCAN LINES - NO DLI'
textlen = *-text
        run start

How it works:

  • AUDCTL = $01 puts every slow channel on the 15 kHz clock, and AUDF1 = 7 gives an interrupt every 8 lines.
  • The handler waits for the end of the current line with WSYNC, then writes the colour, so the change lands in the horizontal blank whatever the IRQ latency was. In GRAPHICS 0 the text area's background is COLPF2. COLBK only colours the border.
  • The VBI resets the colour and writes STIMER at the same point every frame. Without that, 262 lines (not a multiple of 8) would make the bands creep up the screen.

We took three screenshots several seconds apart. They were pixel-for-pixel identical, with band edges exactly 8 scan lines apart. The same program ran unchanged in PAL mode.

Example 2: one interrupt per frame, no VBI

A linked 15 kHz timer can count a whole frame: 262 lines on NTSC, 312 on PAL. Started once, it then fires at the same line every frame on its own:

; One IRQ per frame from a linked 16-bit POKEY timer on the 15 kHz clock.
; Period = (AUDF1 + 256*AUDF2 + 1) scan lines; 262 lines = one NTSC frame.
POKMSK  = $10
VTIMR2  = $0212
COLPF2  = $D018
AUDF1   = $D200
AUDC1   = $D201
AUDF2   = $D202
AUDC2   = $D203
AUDCTL  = $D208
STIMER  = $D209
IRQEN   = $D20E
WSYNC   = $D40A
VCOUNT  = $D40B
FRAME   = 262               ; scan lines per frame: 262 NTSC, 312 PAL

        org $3000
start   sei
        lda #<timer2
        sta VTIMR2
        lda #>timer2
        sta VTIMR2+1
        lda #$11            ; bit 4: link 1+2, bit 0: 15 kHz clock
        sta AUDCTL
        lda #0
        sta AUDC1
        sta AUDC2
        lda #<[FRAME-1]
        sta AUDF1
        lda #>[FRAME-1]
        sta AUDF2
        lda POKMSK
        ora #$02            ; the IRQ comes from the high timer (2)
        sta POKMSK
        sta IRQEN
w1      lda VCOUNT          ; start the timer on line 2*60 = 120
        cmp #60
        bne w1
        sta STIMER
        cli
loop    jmp loop

timer2  lda #$34            ; red from here down
        sta WSYNC
        sta COLPF2
        pla
        rti
        run start

The OS's vertical blank restores the normal colour at the top of each frame, and the timer turns the lower part red. With FRAME = 262 on NTSC (and 312 on PAL), the split stayed on the same line in every screenshot we took. With FRAME deliberately set to 261, the period is one line short of a frame: the split crawled up the screen by a line per frame and was at a different height in every capture.

This shows the (N+1) rule better than any table: AUDF must be the line count minus one. It also suggests a use. A frame-length timer is a VBI-independent "line N" interrupt, and setting the period one line off makes a smoothly rolling split for free.

5. Costs and limits

  • Latency. The timer interrupts through the OS dispatcher (see Inside the OS Interrupt Handlers), which spends a few dozen cycles before reaching VTIMR1, and an IRQ waits for the current instruction to finish. Never assume the handler starts at a fixed cycle. Use WSYNC, as the examples do.
  • NMIs win. A DLI or VBI that arrives first delays the timer IRQ, and SEI blocks it entirely. A DLI that sits in a long WSYNC loop can push a timer effect down by a line or more.
  • The keyboard click. The OS makes its key click with repeated WSYNC writes, which can hold off interrupts by a line each time. A raster effect may wobble while keys are pressed.
  • Very fast timers. On the 1.79 MHz clock, a period of a few hundred cycles leaves little time once the dispatcher, DMA and your handler are counted. For sample playback or other high-rate work, hook VIMIRQ directly or disable the OS's other IRQ sources while it runs.
  • One slow clock for everyone. AUDCTL bit 0 switches all slow channels between 64 kHz and 15 kHz. A tune that expects 64 kHz will play at the wrong pitch while your 15 kHz timer runs.

6. Living with SIO and the OS

SIO takes POKEY over for each disk or cassette transfer. It writes AUDCTL with $28 (channel 3 on 1.79 MHz, channels 3 and 4 linked) and AUDF3/AUDF4 for the bit rate, setting the AUDC registers, and changing POKMSK. After any disk access, rewrite AUDCTL, your AUDF values and your IRQEN/POKMSK bits, then write STIMER again. If a timer effect must survive RESET, reinstall it from your DOSINI routine, because a warm start clears the vectors and POKEY (see The RESET Key: Warm Start, Cold Start and Writing RESET-Proof Programs).

Troubleshooting

  • The bands creep or roll: the period doesn't divide the frame evenly. Restart the timer every frame from the VBI (example 1), or use a frame-length linked timer (example 2).
  • Split one line out after changes: the period is N+1. AUDF holds one less than the number of lines.
  • No interrupt from a linked pair: you enabled timer 1 instead of timer 2 (or timer 3 instead of timer 4).
  • Effect dies after loading a file: SIO rewrote AUDCTL and POKMSK. Reprogram POKEY after I/O.
  • Effect jitters by a line: the handler is missing WSYNC, or something else holds interrupts off: SEI, a long DLI, or the keyboard click.
  • Music goes off-key: your timer set AUDCTL bit 0, moving every slow channel to 15 kHz.

Further reading

  • Avery Lee, Altirra Hardware Reference Manual, chapter 5: timer periods, linked timers, STIMER behaviour, initialisation mode and the 15 kHz clock's fixed position in the scan line.
  • Atari, Operating System Source Listing: the SIO module's POKEY setup.
  • Ian Chadwick, Mapping the Atari: locations 53760–53769 (AUDF1–4, AUDC1–4, AUDCTL, STIMER) and 528–533 (VTIMR1, VTIMR2, VTIMR4).
  • On this site: Keeping Time: RTCLOK, System Timers and POKEY Hardware Timers, Inside the OS Interrupt Handlers, Playing Digitised Samples Through POKEY, Advanced POKEY: AUDCTL, 16-Bit Voices, Filters and Volume-Only Sound.

Credits