Detecting the Hardware: One Routine for PAL/NTSC, OS, Memory, Stereo and VBXE

Atari text screen listing GTIA VIDEO: PAL, ANTIC LINES: 312 (PAL), OS: XL/XE, RAM TOP: $C000, XE BANKS: 04, POKEYS: 2 (STEREO), VBXE: NOT FOUND

Modern Atari software often adapts to the machine it finds: music players switch to stereo, games correct their speed for PAL, demos use extended memory or a VBXE when one is present. All of that starts with a short detection routine run at start-up. This guide builds one that checks seven things in one pass and prints a report. Each test is small and explained on its own, so you can lift the ones you need. The modern utility HW-Detect does the same job in much more depth (see HW-Detect: One Program to Identify Your Atari's Hardware). This guide is about how such tests work.

What you'll learn: how to read the video standard from GTIA and from ANTIC (and why both), how to tell the 400/800 OS from the XL/XE OS without crashing either, where the OS records the top of RAM, a safe 130XE bank test, a second-POKEY test, and how a VBXE identifies itself.

What you need: MADS and an emulator. The program was assembled with MADS and run in atari800 as four machines: an NTSC 800XL (genuine XL/XE OS Rev. 2), a PAL 130XE with stereo, a 400/800 with OS-B, and a 320K RAMBO XL with BASIC and stereo. All four reports were correct. We had no VBXE to test with: that test follows the documented register layout, and we only saw its "not found" result.

1. The rules for detection code

  • Read before you write. Some tests have to write to hardware, but a write to the wrong place on the wrong machine does damage. PORTB is the best example: on an XL/XE it controls memory, but on a 400/800 it is the joystick port for sticks 3 and 4. The program only touches it after the OS test has said "XL/XE".
  • Put everything back. Every byte the tests overwrite is saved and restored, and so are interrupt settings.
  • Keep the code out of the way. The bank test switches $4000–$7FFF, so the routine sits at $3000–$330E, below that window.

2. Video standard: ask both chips

GTIA has a read-only register at $D014 (53268), PAL. Bits 1–3 read 111 on an NTSC GTIA and 000 on a PAL or SECAM one. In practice NTSC chips return $0F and PAL chips $01, so testing AND #$0E is safe.

GTIA only tells you about the colour encoding. It is ANTIC that sets the frame timing, 262 lines (about 60 Hz) or 312 lines (about 50 Hz), and the two chips can be mismatched. Machines exist with an NTSC ANTIC and a PAL GTIA (a 60 Hz PAL picture) and the reverse (50 Hz NTSC). In such a machine, ANTIC sets the frame timing and GTIA decides what the PAL register says. For timing music and game speed, ANTIC is what matters, and ANTIC has no ID register. Instead, the program watches VCOUNT ($D40B) for three frames and keeps the highest value seen. VCOUNT is the scan line divided by two, so it peaks at $82 on a 262-line ANTIC and $9B on a 312-line one.

3. Which OS?

The program needs to know whether this is an XL/XE OS before it dares to touch PORTB. It uses a fixed difference between the ROMs. On the XL/XE OS, $E480 is the start of the new jump vector PUPDIV, so it holds a JMP opcode ($4C). On the 400/800 OS, the same address holds the initial value for the DLI vector: we read $90 there on OS-B. For the 400/800 case, the program goes one step further: $E40F reads 56 on OS-A and 0 on OS-B. We could only check the OS-B branch.

These tests identify the OS, not the machine. An XL running the Translator's 400/800 OS from RAM, or a 400/800 fitted with an XL-compatible replacement OS, will report the OS it is running. For most programs, that is exactly the right answer.

4. How much RAM?

At power-up the OS searches for the end of RAM and stores the result, as a number of 256-byte pages, in RAMSIZ ($02E4, 740). A cartridge or the built-in BASIC sits at $A000, so the value is $A0 (40K) when one is present and $C0 (48K) on a machine without. The RAMBO run above was started with BASIC enabled and reported $A000, the others $C000.

Extended memory is a separate question. On an XL/XE, the program does a minimal 130XE-style test with interrupts and NMIs off:

  1. Save byte $4000 of each of the four banks selected by PORTB bits 2–3 (with bit 4 = 0 to open the window), and of main memory.
  2. Write a different tag into each bank, then $FF into main memory.
  3. Count the banks that still hold their own tag.
  4. Restore every saved byte, PORTB, NMIEN and the I flag.

On a 64K XL every write lands in main memory, the final $FF overwrites the tag, and the count is 0. A 130XE gives 4, as does the 320K RAMBO, because this test only looks at the two bank bits a 130XE has. For larger expansions, use the 64-combination counter in Memory Expansions Beyond the 130XE: 192K to 1MB and How to Use Them.

5. A second POKEY

The stereo upgrade puts a second POKEY at the odd 16-byte mirrors of the POKEY page: $D210–$D21F. On a mono machine those addresses are mirrors of the first chip. So the program sets up timer 1 with the shortest period, enables its interrupt and starts it, all through the $D21x addresses, with IRQs masked. Then it reads IRQST on the first chip. If timer 1's bit has gone to 0 (pending), the writes reached the first chip and the machine is mono. If nothing happened there, a second chip took the writes. This is the principle behind the timer-based detector in Stereo POKEY Programming: Detecting and Driving a Second POKEY. Finally the program switches the test timer off and restores IRQEN from POKMSK.

6. A VBXE

The VideoBoard XE has a 32-byte register block at either $D640 or $D740, depending on how it is configured. Its first register, CORE_REVISION, is read-only. Its high nibble holds the major version (1 for current cores), and the low nibble is 0 for the full FX core and 1 for a GTIA-only core. FX core 1.26 reads $11 there, with MINOR_REVISION ($Dx41) reading $26. The program checks both addresses for a value whose high nibble is 1. On our test machines without a VBXE, $D640 and $D740 read as something else and the report said "NOT FOUND".

7. The program

; One-pass hardware report: video standard (GTIA and ANTIC), OS family,
; top of RAM, 130XE-style extended banks, second POKEY, VBXE.
POKMSK  = $10
RTCLOK  = $12
RAMSIZ  = $02E4
ICCOM   = $0342
ICBLL   = $0348
PAL     = $D014
IRQEN   = $D20E
IRQST   = $D20E
PORTB   = $D301
VCOUNT  = $D40B
NMIEN   = $D40E
CIOV    = $E456
SPTR    = $CB

        org $3000
start   jsr say
        dta c'GTIA VIDEO:  ',0
        lda PAL             ; bits 1-3: 111 = NTSC, 000 = PAL
        and #$0E
        bne gnt
        jsr say
        dta c'PAL',$9B,0
        jmp antic
gnt     jsr say
        dta c'NTSC',$9B,0

antic   lda #0              ; ANTIC: highest VCOUNT seen in 3 frames
        sta maxv
        lda RTCLOK+2
        clc
        adc #3
        sta endf
av      lda VCOUNT
        cmp maxv
        bcc av1
        sta maxv
av1     lda RTCLOK+2
        cmp endf
        bne av
        jsr say
        dta c'ANTIC LINES: ',0
        lda maxv
        cmp #$90            ; $82 = 262 lines, $9B = 312 lines
        bcs apal
        jsr say
        dta c'262 (NTSC)',$9B,0
        jmp osid
apal    jsr say
        dta c'312 (PAL)',$9B,0

osid    jsr say
        dta c'OS:          ',0
        lda $E480           ; XL/XE OS: JMP PUPDIV here; 400/800: data
        cmp #$4C
        bne os800
        lda #1
        sta isxl
        jsr say
        dta c'XL/XE',$9B,0
        jmp ram
os800   lda $E40F           ; 400/800: 56 on OS-A, 0 on OS-B
        bne osa
        jsr say
        dta c'400/800 OS-B',$9B,0
        jmp ram
osa     jsr say
        dta c'400/800 OS-A (OR OTHER)',$9B,0

ram     jsr say
        dta c'RAM TOP:     $',0
        lda RAMSIZ          ; pages of RAM found below any cartridge
        jsr hex
        jsr say
        dta c'00',$9B,0

        jsr say
        dta c'XE BANKS:    ',0
        lda isxl            ; PORTB is a joystick port on the 400/800:
        bne banks           ; never write it there
        jsr say
        dta c'N/A ON 400/800',$9B,0
        jmp pokey
banks   jsr xebanks
        txa
        jsr hex
        lda #$9B
        jsr putc

pokey   jsr say
        dta c'POKEYS:      ',0
        jsr stereo
        bcc mono
        jsr say
        dta c'2 (STEREO)',$9B,0
        jmp vbxe
mono    jsr say
        dta c'1',$9B,0

vbxe    jsr say
        dta c'VBXE:        ',0
        ldx #$D6            ; look at $D640, then $D740
vb1     stx vbx+2
vbx     lda $D640           ; CORE_REVISION: high nibble = major version
        and #$F0
        cmp #$10
        beq vbyes
        inx
        cpx #$D8
        bne vb1
        jsr say
        dta c'NOT FOUND',$9B,0
        jmp *
vbyes   jsr say
        dta c'CORE AT $',0
        lda vbx+2
        jsr hex
        jsr say
        dta c'40, REV $',0
        lda vbx+1
        sta vbm+1
        lda vbx+2
        sta vbm+2
        ldx #0
vbm     lda $D640           ; (patched to the found address)
        jsr hex
        lda #$9B
        jsr putc
        jmp *

; ---- 130XE-style banks: bits 2-3 select, bit 4 = 0 opens the window ----
xebanks lda PORTB
        sta oldpb
        sei
        lda #0
        sta NMIEN           ; nothing may run while banks come and go
        ldx #3
xb1     jsr setbank         ; save $4000 of each bank
        lda $4000
        sta save,x
        dex
        bpl xb1
        lda oldpb
        ora #$10            ; main memory
        sta PORTB
        lda $4000
        sta savm
        ldx #3
xb2     jsr setbank         ; tag bank X with $A0+X
        txa
        ora #$A0
        sta $4000
        dex
        bpl xb2
        lda oldpb
        ora #$10
        sta PORTB
        lda #$FF            ; main memory gets a different value
        sta $4000
        ldy #0              ; Y = banks that kept their tag
        ldx #3
xb3     jsr setbank
        txa
        ora #$A0
        cmp $4000
        bne xb4
        iny
xb4     dex
        bpl xb3
        ldx #3              ; put everything back
xb5     jsr setbank
        lda save,x
        sta $4000
        dex
        bpl xb5
        lda oldpb
        ora #$10
        sta PORTB
        lda savm
        sta $4000
        lda oldpb
        sta PORTB
        lda #$40
        sta NMIEN
        cli
        tya
        tax
        rts
setbank txa                 ; PORTB = old value, bit 4 = 0, bits 2-3 = X
        asl
        asl
        sta tmp
        lda oldpb
        and #%11100011
        ora tmp
        sta PORTB
        rts

; ---- second POKEY: start timer 1 "on chip 2" and see if chip 1 notices ----
stereo  sei
        lda #0
        sta IRQEN           ; chip 1: no interrupts
        sta $D21E           ; chip 2 (or chip 1 again on a mono machine)
        sta $D218           ; AUDCTL
        sta $D211           ; AUDC1
        sta $D210           ; AUDF1 = 0: fastest timer
        lda #$01
        sta $D21E           ; enable timer 1 IRQ at the $D21x address
        sta $D219           ; STIMER at the $D21x address
        ldx #0
st1     dex                 ; give the timer time to run out
        bne st1
        lda IRQST           ; chip 1: bit 0 = 0 means its timer fired
        and #$01
        sta tmp
        lda #0
        sta $D21E           ; switch the test timer off again
        lda POKMSK
        sta IRQEN
        cli
        lda tmp
        lsr                 ; carry = 1: chip 1 never saw it -> stereo
        rts

; ---- output helpers ----
say     pla                 ; print the zero-terminated string that
        sta SPTR            ; follows the JSR, then return past it
        pla
        sta SPTR+1
sy1     inc SPTR
        bne sy2
        inc SPTR+1
sy2     ldy #0
        lda (SPTR),y
        beq sy3
        jsr putc
        jmp sy1
sy3     lda SPTR+1
        pha
        lda SPTR
        pha
        rts
putc    ldx #0              ; one character via CIO (length 0 = use A)
        stx ICBLL
        stx ICBLL+1
        pha
        lda #11
        sta ICCOM
        pla
        jmp CIOV
hex     pha
        lsr
        lsr
        lsr
        lsr
        jsr hex1
        pla
        and #$0F
hex1    tax
        lda hexc,x
        jmp putc
hexc    dta c'0123456789ABCDEF'
maxv    dta 0
endf    dta 0
isxl    dta 0
oldpb   dta 0
savm    dta 0
tmp     dta 0
save    .ds 4
        run start

Notes on the code:

  • say prints the string that follows the JSR, then returns past it. The 6502 pushes the address of the last byte of the JSR, so the routine increments before reading, and leaves the pointer on the terminating 0 so the final RTS lands just after it.
  • putc uses CIO's PUT CHARACTERS command with a buffer length of zero, which makes CIO send the byte in A.
  • The VBXE check patches its own operand (vbx+2) to step from $D640 to $D740. On a found core, the second read is patched the same way to print the revision.

Troubleshooting

  • The bank test crashes: the code or its data sits inside $4000–$7FFF, or interrupts were left on while a bank was mapped.
  • Banks reported on a 64K machine: you skipped the final write to main memory, so main RAM kept the last tag and matched.
  • Stereo detected on a mono machine: check that the test writes go to $D21x and the read comes from $D20E, and that IRQs are masked during the test.
  • Wrong video result in an emulator: emulators let you mix PAL and NTSC settings in odd ways. Compare both the GTIA and ANTIC lines of the report.
  • The program hangs on a 400/800: something wrote to PORTB. Only do it after the XL/XE test.

Further reading

  • Avery Lee, Altirra Hardware Reference Manual: GTIA's PAL register (chapter 6), ANTIC display timing and VCOUNT (chapter 4), PORTB bank switching (chapter 2) and the VideoBoard XE register map (chapter 12).
  • Ian Chadwick, Mapping the Atari: PAL (53268), RAMSIZ (740), PORTB (54017) and the OS-A/OS-B test at 58383.
  • On this site: HW-Detect: One Program to Identify Your Atari's Hardware, Stereo POKEY Programming: Detecting and Driving a Second POKEY, CTIA, GTIA and FGTIA: Which Graphics Chip Do You Have?, Using the 130XE's Extra 64K: PORTB Bank Switching, The OS Jump Table: Calling the Atari Operating System the Supported Way.

Credits