POKEY Timer Interrupts in Depth: Exact Periods, Linked Timers and Raster Effects Without DLIs
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
- Picture: The first example: a POKEY timer interrupt every 8 scan lines changes the background colour. The display list is the ordinary GRAPHICS 0 one, with no DLIs. — Program authors; screenshot by the site
- Altirra Hardware Reference Manual — 5.2 Initialization (init mode resets 15/64 kHz clocks), 5.3 Sound generation (timer periods N+4, (N+1)x28/114, linked N+7, low timer fires AUDF2+1 times, STIMER behaviour), 5.4 Clock generation (15 kHz clock locked to a fixed offset in the scan line, usable with timer IRQs) — Avery Lee (Altirra)
- Atari 400/800 Operating System Source Listing, Rev. A — SIO POKEY setup (AUDCTL $28, AUDF3/AUDF4, AUDC, POKMSK); HARDI clears chip registers on warm start — ksquiggle
- Mapping the Atari — 528-533 VTIMR1/2/4 (VTIMR4 only vectored from OS-B), 53760-53769 POKEY audio/timer registers — AtariArchives.org
- Atari Operating System User's Manual — Section 6 (POKMSK usage, WSYNC delays from keyboard click) — ksquiggle
