Atari 8-Bit Display List Interrupts: An Advanced Tutorial, Hacker News

How Interlacing Works (With Some Hand Waving) and Why We Ignore It¶

Real TVs are interlaced with 525 scan lines for NTSC and 625 for PAL. Because ofreasons, the NTSC vertical refresh interval is not exactly the whole number of 60 Hz either, It’s 60 / 1001 Hz or 59. 94 Hz. PAL refresh rate is apparentlyexactly 50 Hz.

Every refresh interval, the electron beam draws onefield, starting at the top left and drawing every other scan line. When it reaches the bottom, the vertical retrace starts, but this time it positions the electron beam at the first missing scan line. Then it draws the next field, again skipping every other scan line but this time filling in the scan lines it missed.

This drawing is a simplification, seeming to show that there are 524 scan lines. In reality, and there are 525 and each field actually draws 262and one halfscan lines (and not 262 on one field and 263 on another), but this is all very complicated and not necessary for our purposes. However, at the risk of further complicating matters, the Atari produces 262 scan lines for the even field and 262 scan lines for the odd field. In the situation where the Atari is producing an image that is not changing as time goes on, like the computer is sitting at the BASIC language READY prompt and you aren’t typing anything, the scan lines produced for the even field will be exactly the same as the scan lines produced for the odd field.

Practically speaking, you do not need to care that the screen is interlaced with 525 scan lines (for NTSC). Our mental model will be as if the Atari is drawing to a non-interlaced screen with 262 scan lines and a frame rate of 59. 94 Hz. For PAL, substitute 625, 312, and 50, respectively.)

How Color Works and There’s More Hand Waving, Isn’t There?¶

How TVs produce the colors that they display is very complicated and so far outside the scope of this tutorial that it might as well be magic. Suffice it to say that color happens.

On the Atari, a unit called the color clock is the smallest portion of a scan line that can be displayed with an arbitrary color. There are 228 color clocks per scan line, of which about 160 were typically visible on a cathode-ray TV display in the 1970 s when the Atari was developed. This corresponds to the 160 pixel horizontal resolution of Antic Modes B through E in the standard width playfield. Antic Mode F (Graphics 8 in BASIC) has 320 addressable pixels, corresponding to half a color clock, and only artifacting color is available.

How The CPU Frequency Was Chosen and Why Is There Even More Hand Waving, Oh Author Person?¶

For NTSC machines, each frame draws 262 scan lines with 228 color clocks per scan line, the operating frequency of the 6502 was chosen such that it takes Exactly 114 machine cycles per scan line, producing 29868 machine cycles per frame. With a 59. 94 Hz vertical refresh rate this should result in a processor speed of 1. 790287 MHz. Here’s where the author does more hand waving because he doesn’t exactly understand what the subtleties are and why those numbers aren’t exact, and instead points to the Altirra Hardware Reference Manual and lets it explain what is really happening. It shows that while thereareindeed 29868 cycles per frame, the processor speed is actually 1. 790772 MHz, to prevent the color subprime mortgage from investigating phantoms on each scan line. Something like that; the author didn’t understand.At all. At any rate, a signal is produced that can be displayed on a TV, even if it does not exactly sync up with broadcast NTSC signals.

PAL systems produce the same 228 color clocks and 114 machine cycles per line, but display 312 scan lines. This results in 35568 cycles per frame, and with the vertical refresh rate of 50 Hz the processor should run at 1. 778400 MHz. Again, the Altirra reference manual shows slight deviations for complicated technical reasons resulting in a processor speed of 1. 773447 MHz. Similarly to NTSC, the computer still produces 35568 cycles per frame, just that the signal output for the TV is not exactly the same as broadcast PAL TV signals.

Display List Instruction Set¶

An ANTIC display list instruction consists of 1 byte with an optional 2 byte address. There are 3 types of instructions: blank lines, graphics modes, and jump instructions. Instructions are encoded into the byte using a bitmask where low 4 bits encode the graphics mode or feature and the high 4 bits encode the flags that affect that instruction:

7	(6)	(5)	(4)	(3)	(2)	(1)
DLI	(LMS)	(VSCROLL)	(HSCROLL)	Mode

The 4 flags are:

• DLI ($ 80): enable a display list interrupt when processing this instruction

LMS ($ 40): trigger a Load Memory Scan, changing where ANTIC looks for screen data, and requires an additional 2 byte address immediately following this instruction byte.

VSCROLL ($ 20): enable vertical scrolling for this mode line

• HSCROLL ($ 10): enable horizontal scrolling for this mode line

The 14 available graphics modes are encoded into low 4 bits using values ​​as shown in this table:

2

4

5

*mode F is also used as the basis for the GTIA modes (BASIC Graphics modes 9, 10 , & 11), but this is a topic outside the scope of this tutorial.

Blank lines are encoded as a mode value of zero, the bits 6, 5, and 4 taking the meaning of the number of blank lines rather than LMS, VSCROLL, and HSCROLL. Note that the DLI bit is still available on blank lines, as bit 7 is not co-opted by the blank line instruction.

Jumps provide the capability to split a display list into multiple parts in different memory locations. They are encoded using a mode value of one, and require an additional 2 byte address where ANTIC will look for the next display list instruction. If bit 6 is also set, it becomes the Jump and wait for Vertical Blank (JVB) instruction, which is how ANTIC knows that the display list is finished. The DLI bit may also be set on a jump instruction, but if set on the JVB instruction it triggers a DLI on every scan line from there until the vertical blank starts on the 249 th scan line.

The typical method to change the currently active display list is to change the address stored atSDLSTL(in low byte / high byte format in addresses$ 230and$ 231). At the next vertical blank, the hardware display list atDLISTL($ D 402and($ D)) will be updated with the values ​​stored here and the screen drawing will commence using the new display list.

A Sample Display List¶

Here is a display list that contains different text modes mixed in a single screen.

• Source Code:sample_display_list.s
• Executable:sample_display_list.xex

dlist.Byte$ 70,$ 70,$ 70; 24 blank lines        .Byte$ 46,$ 00,$ 40; Mode 6   LMS, setting screen memory to $ 4000        .Byte(6); Mode 6        .Byte$ 70; 8 blank lines        .Byte(7),(7),(7),(7),(7); 5 lines of Mode 7        .Byte$ 70; 8 blank lines        .Byte(2); single line of Mode 2        .Byte$ 70,($),$ 70; 24 blank lines        .Byte(2),(4); Mode 2 followed by mode 4        .Byte$ 70; 8 blank lines        .Byte(2),5); Mode 2 followed by mode 5        .Byte$ 41,dlist,>(dlist); JVB, restart same display list on next frame

Cycle Stealing by ANTIC ¶

The ANTIC coprocessor needs to access memory to perform its functions, and since the 6502 and ANTIC can’t both access at once, ANTIC will pause execution of the 6502 when it needs to read memory. It happens at specific points within The 114 cycles of each scan line, but where it happens (and how many times the 6502 gets paused during the scan line) depends on the graphics mode .

For overhead, ANTIC will typically steal 3 cycles to read the display list, 5 cycles if player / missile graphics are enabled, and 9 cycles for memory refreshing. Scrolling requires additional cycle stealing because ANTIC needs to fetch more memory.

Bitmapped modes (modes 8 – F) have cycles stolen corresponding to the number of bytes per line used in that mode. For example, mode E will use an additional 40 cycles, so in the context of writing a DLI for a game, the typical number of stolen cycles could be 57 out o f the 114 cycles per scan line: 17 cycles for ANTIC overhead and 40 for the number of bytes per line.

Text modes require additional cycles over bitmapped graphics modes, because ANTIC must fetch the font glyphs in addition to its other work. The first scan line of a font mode is almost entirely used by ANTIC and only a small number of cycles is available to the 6502. For normal 40 – byte wide playfields, the first line of ANTIC modes 2 through 5 will yield at most about 30 cycles and subsequent lines about 60 cycles per scan line.

About the worst-case scenario is one of the best modes for games: ANTIC mode 4. This text mode, combined with scrolling and player / missile graphics and can reduce the available cycles to fewer than 10 on the first line and about 50 on subsequent lines!

You must set the address of your DLI before enabling them, otherwise the DLI could be called and use whatever address is stored at$ 200.

Hardware & Shadow Registers ¶

The Atari is a memory-mapped system, where hardware devices like the ANTIC and GTIA chips aremappedto locations in memory and data is passed back and forth by reading or writing to specific addresses. They are usually either read-only or write-only, and many times an address is used for wildly different features depending on whether the address is read from or written to.

Some of these hardware locations also haveshadowregisters in low RAM (typically page 2) that are labeled as performing the same function as a hardware register, with two important differences.

First, they can be both read and written to, so (assuming you always use the shadow register to update the hardware register) it is possible to find out the current state of a hardware register by reading its shadow.

Second, the hardware register is only updatedonce every vertical blankby an operating system routine that copies the shadow value to its hardware counterpart. Note that it does not happen the other way around, so changing a hardware registerdoes notupdate a shadow register.

The shadow registers are a convenience for development in higher level languages ​​like BASIC where speed is not paramount. But code within a DLI must use hardware registers directly to affect change on a scan line.

The shadow registers can still be useful in DLI development, in that they will automatically reset the hardware registers to the values ​​in the shadow registers every vertical blank. This can be used to reset features like graphics colors and the character set address for the top of the screen at the next frame.

Some hardware registers have no shadows, like player position and size, so your own code (in the deferred VBI or the final DLI) must reset these to their correct values ​​for the top of the screen.

A Simple Example¶

A common use of display lists is to change colors in the middle of the screen.

• Source Code:first_dli.s
• Executable:first_dli.xex

Here is our first display list interrupt:

(dli)pha; only using A register, so save old value to the stack         (LDA)#$ 7A; new background color        STACOLBK; store it in the hardware register        PLA; restore the A register         (RTI); always end DLI with RTI!

This is all the code it takes to change the color of the background. The obvious effect is the flickering line in the background, which we will solve in the next section.

Examining the code shows the boilerplate discussedabovewhere DLIs always end with theRTIInstruction and any registers used must be saved before your code changes them, and restored upon exit. *******

The work performed in the interrupt is just two instructions: a load of a color value and a store where it puts it in thehardwareregister for the background color. Again, as noted (above) , hardware registers must be used in DLIs, not the shadow registers as shadow registers are ignored until the vertical blank.

A Simple Example with WSYNC¶

The Atari provides a way to sync with a scan line to avoid the flickering effect of the previous example.

• Source Code:first_dli_with_wsync.s
• Executable:(first_dli_with_wsync.xex)

The flickering is avoided by saving some value (any value, the bit pattern is not important) to theWSYNCmemory location at$ D (a). This causes the 6502 to stop processing instructions until the electron beam nears the end of the scan line, at which point the 6502 will resume executing instructions . Because the electron beam is usually off-screen at this point, it is safe to change color registers for at least the next several instructions without artifacts appearing on screen.

(dli)pha; only using A register, so save old value to the stack         (LDA)#$ 7A; new background color        STA(WSYNC); any value saved to WSYNC will trigger the pause        STACOLBK; store it in the hardware register        PLA; restore the A register         (RTI); always end DLI with RTI!

A DLI Can Affect Many Scan Lines¶

• Source Code:rainbow_wsync.s
• Executable:rainbow_wsync.xex

DLIs can really be thought of as a way for your program to be told when a certain display list instruction is reached. Apart from the setup and teardown of the DLI subroutine itself and some timing limitations discussed in the next section, arbitrary amounts of code can be executed in a DLI.

This example shows how to have a single DLI affect multiple scan lines, even crossing into subsequent ANTIC mode 4 lines in the display list:

dli pha; save A & X registers to stack         txa         pha         LDX # 16; make 16 color changes         lda # $ a; initial color         sta WSYNC; first WSYNC gets us to start of scan line we want ? loop sta COLBK; change background color         clc         adc # $ 11; change color value, luminance remains the same         dex; update iteration count         sta WSYNC; make it the color change last ...         sta WSYNC; for two scan lines         bne? loop; sta doesn't affect flags so this still checks result of dex         LDA # $ 00; reset background color to black         sta COLBK         pla; restore X & A registers from stack         tax         pla         rti; always end DLI with RTI!

It changes background colors 16 times , where each color change lasts 2 scan lines. So 32 scan lines means that it covers 4 display list entries of ANTIC mode 4.

DLI Interrupting Another DLI¶

• Source Code:dli_interrupting_dli.s
• Executable:dli_interrupting_dli.xex

When a DLI is interrupted, its state is saved just as if a normal program was interrupted. The interrupting code is then executed, and upon its completion, the control returns to the DLI at the point where it left off. But at this point, due to the interrupting event, the restored DLI will be resumed some number of scan lines below where it was interrupted, likely resulting in unplanned behavior.

Here’s a similar DLI to the above, except it changes the luminance value instead of the color value to make the effect easier to see. It starts with a bright pink and gets dimmer down to a dark red after 32 scan lines:

dli pha; save A & X registers to stack         txa         pha         LDX # 16; make 16 color changes         lda # $ 5f; initial bright pink color         sta WSYNC; first WSYNC gets us to start of scan line we want ? loop sta COLBK; change background color         sec         sbc # 1; make dimmer by decrementing luminance value         dex; update iteration count         sta WSYNC; make it the color change last ...         sta WSYNC; for two scan lines         bne? loop; sta doesn't affect processor flags so we are still checking result of dex         LDA # $ 00; reset background color to black         sta COLBK         pla; restore X & A registers from stack         tax         pla         rti; always end DLI with RTI!

But this time, the display list hastwolines that have the DLI bit set:

(dlist).Byte$ 70,$ 70,($)         .Byte$ 44,$ 00,$ 40        .Byte$ C4; first DLI triggered on last scan line        .Byte$ 44        .Byte$ C4; second DLI triggered on last scan line        .Byte$ 44,$ 44,$ 44,$ 44,$ 44,$ 44,$ 44,$ 44        .Byte$ 44,$ 44,$ 44,$ 44,$ 44,$ 44,$ 44,$ 44        .Byte$ 44,$ 44,$ 44,$ 44        .Byte$ 41,dlist,>(dlist)

Because the(VDLSTL)pointer is not changed, the same code will be called each time an interrupt occurs.

The first DLI hits and starts with a bright background color on the first scan line of the third line of text. But because this display list takes a long time, the second DLI on the 4th text line gets triggered before the first DLI has hit itsRTIInstruction. ANTIC interrupts the first DLI and starts the 2nd DLI anyway. This effect is visible in the 5th line of text: the background color is bright again.

But notice another artifact: the effect on the 5th line of text isn’t on its first scan line, but its second:

This is due to the fact that a WSYNC was called on the previous scan line, but the interrupt happened as well. The interrupt takes some cycles to begin, and by the time that happenedandANTIC stole all of its cycles to set up the text mode line, there weren’t enough cycles left for the first(WSYNC)in the DLI code to happen on the same scan line. This forces thatWSYNCto happen on the next line, causing the delay and the appearance of a 3rd scan line of the same color before the second DLI starts its color cycling.

The second DLI completes and performs its(RTI), but then it returns control to the first DLI, which is already halfway done with its color cycling. When it resumes control, it is in 9th line of text on the screen, so it has four more color changes before it hits its own(RTI).

Emulator Differences¶

The DLI interrupting another DLI is clearly an edge case, and edge cases are always good stress tests for emulators. A difference is clearly visible below when comparing a zoomed in portion of the display generated by the Altirra emulator as compared to the atari 800 emulator) standalone or as embedded in Omnivore, they are the same code and produce the same result):

Notice how Altirra gets the color from the first DLI for two scan lines, 64 and 65, before the correct color appears on scan line 66. The output from Altirra shows that the NMI doesn’t happen until between scan line 63 and 64. But clearly, the(STA)COLBKat scan line 63 is taking effect on scan line 64, because scan line 64 has the background color$ 57. It appears the store of$ 5Fon scan line 65, started on cycle 1 of that line, isnt actually executed until much, much later since the(sec)doesn’t begin until cycle 108. This puts that color change in the horizontal blank period of scan line 65, which would seem to explain why Altirra shows two scan lines with the background color from the first DLI.

This is the CPU history from the Altirra emulator:

60: 3 | A=(X=) *********************************************************************************************************************************************************************************************************************************************************************************************************** (Y=) ******************************************************************************************************************************************************************************************************************************************************************************************************************** (IC) | 3030: 8D 0A D4 STA WSYNC    60: 7 | A=(X=) *********************************************************************************************************************************************************************************************************************************************************************************************************** (Y=) ******************************************************************************************************************************************************************************************************************************************************************************************************************** (IC) | 3033: 8D 0A D4 STA WSYNC    60: 108 A=(X=) *********************************************************************************************************************************************************************************************************************************************************************************************************** (Y=) ******************************************************************************************************************************************************************************************************************************************************************************************************************** (IC) | 3036: D0 F1 BNE $ 3029    61: 107 A=(X=) *********************************************************************************************************************************************************************************************************************************************************************************************************** (Y=) ******************************************************************************************************************************************************************************************************************************************************************************************************************** (IC) | 3029: 8D 1A D0 L 3029 STA COLBK    61: 111 A=(X=) *********************************************************************************************************************************************************************************************************************************************************************************************************** (Y=) ******************************************************************************************************************************************************************************************************************************************************************************************************************** (IC) | 302 C: 38 SEC    61: 113 | A=(X=)  Y=(IC) |  (D: E9)  SBC # $ 01    62: 1 | A=(X=) *********************************************************************************************************************************************************************************************************************************************************************************************************** (Y=) ******************************************************************************************************************************************************************************************************************************************************************************************************************** (IC) | 302 F: CA DEX    62: 3 | A=(X=)  Y=(IC) | 3030: 8D 0A D4 STA WSYNC    62: 7 | A=(X=)  Y=(IC) | 3033: 8D 0A D4 STA WSYNC    62: 108 A=(X=)  Y=(IC) | 3036: D0 F1 BNE $ 3029    63: 107 A=(X=)  Y=(IC) | 3029: 8D 1A D0 L 3029 STA COLBK - NMI interrupt (DLI)    64: 5 | A=(X=)  Y=(IC) | E 791: 2C 0F D4 LE 791 BIT NMIST    64: 11 A=(X=)  Y=(NIC) E 794: 10  (BPL $ E)     64: 13 A=(X=)  Y=(NIC) E 796: 6C 00 02 JMP (VDSLST)    64: 19 A=(X=)  Y=(NIC)  (F:)  PHA    64: 102 A=(X=)  Y=(NIC) 3020: 8A TXA    64: 104 A=08 X=08 Y=00 (IC) | 3021: 48 PHA    64: 107 A=08 X=08 Y=00 (IC) | 3022: A2 10 LDX # $ 10    64: 109 A=08 X=10 Y=00 (IC) | 3024: A9 5F LDA # $ 5F    64: 111 | A=5F X=10 Y=00 (IC) | 3026: 8D 0A D4 STA WSYNC    65: 1 | A=5F X=10 Y=00 (IC) | 3029: 8D 1A D0 L 3029 STA COLBK    65: 108 A=5F X=10 Y=00 (IC) | 302 C: 38 SEC    65: 110 A=5F X=10 Y=00 (IC) |  (D: E9)  SBC # $ 01    65: 112 | A=5E X=10 Y=00 (IC) | 302 F: CA DEX    66: 0 | A=5E X=0F Y=00 (IC) | 3030: 8D 0A D4 STA WSYNC    66: 4 | A=5E X=0F Y=00 (IC) | 3033: 8D 0A D4 STA WSYNC    66: 108 | A=5E X=0F Y=00 (IC) | 3036: D0 F1 BNE $ 3029    67: 107 | A=5E X=0F Y=00 (IC) | 3029: 8D 1A D0 L 3029 STA COLBK

The atari 800 emulator hits the DLI two instructions earlier than Altirra, immediately after the two(STA) (WSYNC) (commands) and therefore before the(STA) (COLBK)that causes Altirra to have a new color on scan line 64). In the atari 800 / Omnivore instruction history below:

the DLI starts late on scan line 63 as (naively) expected and gets to the(STA) (WSYNC)early in scan line 64 while there is still time to hit the(STA)COLBKwhile still on scan line 64. This changes scan line 65 to be the correct background color for the second DLI.

I think the takeaway from this section is: don’t let your DLI get interrupted by anything else, or it is likely that you will encounter emulation Differences.

VBI Interrupting A DLI ¶

For completeness, here is an example of the vertical blank interrupting a DLI.

• Source Code:vbi_interrupting_dli.s
• Executable:vbi_interrupting_dli.xex

The DLI is started at the bottom of the screen, gets interrupted by the VBI, and picks up again when VBI ends. Even though the electron beam is turned off,WSYNCis still called and performs its delay function when the scan line is off screen. The resulting image resumes its color cycling background on the top of the screen, stopping after 128 scan lines even though only a fraction of those are actually visible on screen.

DLI on the JVB Instruction***

A DLI on the JVB instruction at the end of the display list is possible, but has an interesting property: it triggers DLIs on every scan line until the vertical blank. *******

If your DLI is not short enough, it will keep getting interrupted by the DLI on triggered by the next scan line, stacking up interrupts until mercifully the triggering process is stopped by the vertical blank after 248 scan lines have been generated.

After the vertical blank routine exits, the stacked-up DLI calls will have to unwind themselves so the most recently interrupted DLI (from scan line 247, the scan line just before the vertical blank) will resume and execute code until its(RTI). This will pop data off the stack and return control to the DLI that was interrupted on scan line 246, and so-forth until all the interrupted DLIs have issued theirRTIInstructions.

On a standard length display list that generates 24 blank lines followed by 192 output lines, the JVB instruction will be on scan line 224. Since the JVB technically generates a single blank line in the display list, the DLI will also be triggered on scan line 224. This case would produce 24 DLIs before the vertical blank. *******

Here are the requirements for successful use of DLIs:

• your DLI routine must save any registers it clobbers

• restore any registers you save before exiting

• exit with an(RTI)

• use(WSYNC)if necessary

• be aware of cycles stolen by ANTIC: you could have only 60 cycles per scan line in higher resolution graphics modes, and as few as 10 (!) on the first line of text modes

• store the address of your routine in(VDSLST)before enabling DLIs withNMIEN

• guard against the DLI itself being interrupted

Note

the wordspritein this sense wasn’t in use when the Atari was designed, andSeveral(sources)claimthat it was coined by the designers of the Texas Instruments TI 9918 graphics chip at about the same timeframe.