Using the RAM Under the OS ROM on XL/XE Machines

Atari text screen where every capital letter is drawn mirror-reversed while lower-case letters look normal, with the typed words HELLO and HI below

An 800XL or 130XE has 64K of RAM, but with the operating system ROM switched in you can only reach about 48K of it. The OS covers $C000–$CFFF and $D800–$FFFF, 14K in all, and the RAM underneath is still there. One bit in the PIA's port B switches the ROM out and the RAM in. Software uses it in two ways: for a patched or replacement copy of the OS, or as extra space for code and data. This guide shows both approaches with tested programs, and the two traps that crash most first attempts: interrupts and the character set.

What you'll learn: what PORTB bit 0 maps, why the machine crashes 1/60 second after you clear it, how to copy the OS into RAM and patch it, how to keep the ROM off with interrupt trampolines, and what ANTIC sees while the ROM is out.

What you need: an XL or XE machine (or an emulator set to one), MADS, and some 6502 assembly. The 400 and 800 don't have this feature: their PORTB reads joystick ports 3 and 4. Both examples were assembled with MADS and run in atari800 on the genuine XL/XE OS Rev. 2 ROM.

1. The switch

On XL/XE machines, PORTB ($D301, 54017) controls the memory map:

Bit Function
0 OS ROM at $C000–$CFFF and $D800–$FFFF: 1 = ROM, 0 = RAM
1 BASIC ROM at $A000–$BFFF: 0 = BASIC, 1 = RAM
7 Self-test ROM at $5000–$57FF: 0 = self-test (only while the OS ROM is on), 1 = RAM
2–6 Extended memory banks on the 130XE and upgraded machines (see Using the 130XE's Extra 64K: PORTB Bank Switching)

Three things about this switch matter for everything that follows:

  • $D000–$D7FF never changes. The chip registers (GTIA, POKEY, PIA, ANTIC) stay visible whatever bit 0 says, so the RAM you gain is $C000–$CFFF (4K) plus $D800–$FFFF (10K).
  • Writes to ROM go nowhere. The memory logic decides by address alone, so a write to an address currently occupied by ROM is simply ignored. You can't "write through" the ROM into the RAM below. To copy the OS into RAM, you have to read with the ROM on and write with it off.
  • RESET puts the ROM back. The PIA is reset with the CPU on XL/XE machines, and pull-up resistors hold bit 0 high, so the OS ROM is always enabled after RESET.

2. Why the naive POKE crashes

Try POKE 54017,PEEK(54017)-1 in BASIC on an XL. When we did, the text on screen vanished at once, because ANTIC now fetches its font from the empty RAM under $E000. The worse problem is the top six bytes of memory. The CPU fetches its interrupt addresses from $FFFA (NMI) and $FFFE (IRQ). With the ROM out, those come from whatever happens to be in RAM, so unless another OS has been put there, the next vertical blank (at most 1/60 second away) jumps into garbage and the machine crashes.

So there are two workable strategies:

  1. Put a complete OS in the RAM (a copy of the ROM, possibly patched), then switch. The interrupt vectors and handlers are all there, so everything keeps working, including CIO, SIO and the screen editor.
  2. Keep the ROM, but switch it out only when needed, with interrupts either disabled or redirected to small handlers in RAM that switch the ROM back in for the duration of the interrupt.

3. Strategy 1: a patched OS in RAM

The program below copies the OS into the RAM beneath it, one byte at a time: read the byte with the ROM on, switch the ROM off, write it, switch the ROM back on. It then runs on the copy and patches it. To make the patch visible, it reverses the bits of every capital letter in the OS character set at $E000, so they appear mirrored. Finally, it prints a message through CIO and keeps reading lines from the keyboard, to show that the copied OS works normally.

; Copy the XL/XE OS ROM into the RAM underneath it, switch to the copy,
; then patch the RAM copy: mirror the letters of the built-in font.
NMIEN   = $D40E
PORTB   = $D301
CIOV    = $E456
ICCOM   = $0342
ICBAL   = $0344
ICBLL   = $0348
PTR     = $CB

        org $3000
start   sei                 ; no IRQs...
        lda #0
        sta NMIEN           ; ...and no NMIs while the ROM comes and goes
        lda #$C0            ; copy $C000-$CFFF, skip $D000-$D7FF (I/O),
        sta PTR+1           ; then $D800-$FFFF
        ldy #0
        sty PTR
copy    lda (PTR),y         ; read the ROM byte (ROM on)
        tax
        lda PORTB
        and #$FE            ; bit 0 = 0: RAM appears at $C000-$FFFF
        sta PORTB
        txa
        sta (PTR),y         ; write it into the RAM underneath
        lda PORTB
        ora #$01            ; ROM back on for the next read
        sta PORTB
        iny
        bne copy
        inc PTR+1
        lda PTR+1
        cmp #$D0
        bne notio
        lda #$D8            ; jump over the hardware registers
        sta PTR+1
notio   cmp #0              ; wrapped past $FFFF?
        bne copy

        lda PORTB
        and #$FE            ; run on the RAM copy from now on
        sta PORTB
        lda #$40
        sta NMIEN           ; VBI back on
        cli

; patch: mirror every glyph of the capital letters (internal codes $21-$3A)
        lda #<[$E000+$21*8]
        sta PTR
        lda #>[$E000+$21*8]
        sta PTR+1
        ldy #0
mir     lda (PTR),y
        ldx #8
mbit    lsr                 ; reverse the 8 bits of the row
        rol tmp
        dex
        bne mbit
        lda tmp
        sta (PTR),y
        iny
        cpy #26*8
        bne mir

        ldx #0              ; print a message through CIO (OS in RAM)
        lda #11             ; PUT CHARACTERS
        sta ICCOM,x
        lda #<msg
        sta ICBAL,x
        lda #>msg
        sta ICBAL+1,x
        lda #msglen
        sta ICBLL,x
        lda #0
        sta ICBLL+1,x
        jsr CIOV
input   ldx #0              ; now read lines from the keyboard (E:)
        lda #5              ; GET RECORD: keyboard IRQs, screen editor
        sta ICCOM,x
        lda #<buf
        sta ICBAL,x
        lda #>buf
        sta ICBAL+1,x
        lda #120
        sta ICBLL,x
        jsr CIOV
        jmp input

tmp     dta 0
buf     .ds 120
msg     dta $7D,c'THIS OS IS RUNNING FROM RAM.',$9B
        dta c'ITS FONT IS PATCHED: CAPITALS ARE',$9B
        dta c'MIRRORED, lower case is not.',$9B
        dta c'TYPE SOMETHING:',$9B
msglen  = *-msg
        run start

Notes on the copy:

  • Both interrupt types are off during the copy. SEI stops IRQs, and storing 0 in NMIEN stops the vertical blank NMI. An NMI that arrived in the middle, at a moment when the ROM was out and the RAM vectors were still half-copied, would crash. At least one commercial game, Atomix Plus!, has a copy loop that re-enables NMIs before the ROM is back on and relies on luck.
  • The loop skips $D000–$D7FF. Copying the hardware registers would read and write live chip registers.
  • PORTB is changed by read-modify-write, so the BASIC, self-test and bank bits keep whatever value they had.

The copy takes a moment, because it toggles PORTB twice per byte. Joe Miller's classic "RAMROM" routine, printed in Mapping the Atari, is faster: it copies the ROM to a buffer in low RAM in bulk, switches once, and copies back. Either way, once the copy is running you can change anything in it. The font patch is a harmless demonstration. The best-known real use was compatibility: the Atari Translator disk loads the 400/800 OS into this RAM, so older programs that fail on the XL OS can run.

In the screenshot, the capital letters of the message, and the HELLO typed afterwards, are mirrored while the lower-case letters are not. The keyboard handler, screen editor and CIO all ran from the patched RAM copy.

4. Strategy 2: ROM off, interrupts through trampolines

Sometimes you want the RAM under the ROM for your own code or data and still want the real OS to service interrupts. The standard trick is a pair of small trampolines: handlers in RAM, pointed to by the RAM vectors at $FFFA and $FFFE. Each one switches the ROM on, calls the ROM's own handler as if the interrupt had happened normally, then switches the ROM back off on the way out.

The program below copies the font (more on that in a moment), installs both trampolines, and then runs its main loop with the ROM switched off. To prove the loop is really in RAM mode, it stores the frame counter at $D800, which is RAM under the floating-point ROM, and reads it back. That only works if RAM is mapped there. It also shows the last key code from CH and the live PORTB value, and it copies the frame counter to the border colour, COLOR4.

; Run with the OS ROM switched OFF most of the time, while the ROM OS
; still services every interrupt through two small RAM trampolines.
RTCLOK  = $12
SAVMSC  = $58
CH      = $02FC
COLOR4  = $02C8
NMIEN   = $D40E
PORTB   = $D301
PTR     = $CB
DATA    = $D800             ; RAM under the floating-point ROM: our data area
FONT    = $E000             ; the OS font: ANTIC reads it from RAM too

        org $3000
start   sei
        lda #0
        sta NMIEN           ; no NMIs while the vectors change
        lda #<FONT          ; copy the 1K font into the RAM beneath it
        sta PTR             ; (ANTIC reads RAM there once the ROM is off)
        lda #>FONT
        sta PTR+1
        ldy #0
fcopy   lda (PTR),y         ; read from ROM...
        tax
        lda PORTB
        and #$FE
        sta PORTB
        txa
        sta (PTR),y         ; ...write to RAM (ROM writes are ignored)
        lda PORTB
        ora #$01
        sta PORTB
        iny
        bne fcopy
        inc PTR+1
        lda PTR+1
        cmp #>[FONT+$400]
        bne fcopy
        lda PORTB
        and #$FE
        sta PORTB           ; ROM off: $FFFA-$FFFF are RAM now
        lda #<nmi
        sta $FFFA
        lda #>nmi
        sta $FFFB
        lda #<irq
        sta $FFFE
        lda #>irq
        sta $FFFF
        lda #$40
        sta NMIEN           ; VBI on again; ROM stays OFF
        cli

        ldy #0              ; caption (screen memory is in low RAM)
cap     lda text,y
        sta (SAVMSC),y
        iny
        cpy #textlen
        bne cap

main    lda RTCLOK+2        ; the OS VBI is still counting frames
        sta COLOR4          ; border: only stage 2 of the VBI copies this
        sta DATA            ; store it under the ROM area...
        lda DATA            ; ...and read it back: only works as RAM
        ldy #40+12
        jsr hex2
        lda CH              ; the OS keyboard IRQ still runs
        ldy #80+12
        jsr hex2
        lda PORTB
        ldy #120+12
        jsr hex2
        jmp main

; NMI arriving while the ROM is off: switch it on, run the ROM's own
; NMI handler as if the NMI had happened there, then switch back.
nmi     pha
        lda PORTB
        pha                 ; remember the ROM state we interrupted
        ora #$01
        sta PORTB           ; OS ROM on
        lda #>nmiret        ; fake an interrupt frame so the OS
        pha                 ; handler's RTI comes back here
        lda #<nmiret
        pha
        tsx                 ; copy the flags the CPU pushed (S+5):
        lda $0105,x         ; the OS checks their I and B bits
        pha
        jmp ($FFFA)         ; the ROM's NMI vector
nmiret  pla
        sta PORTB           ; ROM off again (if it was off)
        pla
        rti

irq     pha                 ; same idea for IRQs
        lda PORTB
        pha
        ora #$01
        sta PORTB
        lda #>irqret
        pha
        lda #<irqret
        pha
        tsx
        lda $0105,x
        pha
        jmp ($FFFE)         ; the ROM's IRQ vector
irqret  pla
        sta PORTB
        pla
        rti

hex2    pha                 ; A as two hex digits at screen offset Y
        lda SAVMSC
        sta PTR
        lda SAVMSC+1
        sta PTR+1
        pla
        pha
        lsr
        lsr
        lsr
        lsr
        tax
        lda hexd,x
        sta (PTR),y
        iny
        pla
        and #$0F
        tax
        lda hexd,x
        sta (PTR),y
        rts

text    dta d'OS ROM OFF - INTERRUPTS VIA TRAMPOLINES '
        dta d'FRAME:                                  '
        dta d'LAST KEY:                               '
        dta d'PORTB:                                  '
textlen = *-text
hexd    dta d'0123456789ABCDEF'
        run start

How the trampoline works: the CPU has pushed the return address and flags. The trampoline saves A and the current PORTB, switches the ROM in, then builds a second, fake interrupt frame on the stack: the address nmiret and a copy of the flags. When JMP ($FFFA) now reads the ROM's vector, the OS handler runs exactly as usual and finishes with RTI, which "returns" to nmiret. There the trampoline restores PORTB to what it was, which switches the ROM back off if it was off, and executes the real RTI. Because PORTB is restored rather than forced off, the trampoline also works when an interrupt arrives while the main program has the ROM switched on.

On screen, the frame counter ran, the typed key codes appeared ($3E for S, $0C for RETURN), PORTB read $FE (bit 0 clear), and the value written to $D800 read back correctly.

Two lessons from testing

ANTIC sees the RAM too. Our first version used $E000 as its data area and didn't copy the font. The moment the ROM went out, the screen turned into rows of dots and dashes. The display was fine, but ANTIC was fetching character shapes from $E000, and with the ROM off that is RAM. The memory switch applies to ANTIC's reads as well as the CPU's. If the ROM is out while a text screen is displayed, there must be a font in the RAM under $E000 (or point CHBAS at your own font elsewhere). Display lists and screen memory under the ROM are seen as RAM in the same way.

The flags byte matters. Our first trampoline pushed a fixed flags value of $04 (I set). Everything seemed to work, but the border colour never changed. The OS vertical blank checks the I bit of the flags on the stack to decide whether it interrupted a "critical section". With I apparently set, it skipped stage 2 every frame: no shadow-register copies, no joystick reads, no timers 2–5. Copying the CPU's real flags byte from the stack (LDA $0105,X) fixed it, and the border then cycled through colours with the frame counter. For the IRQ trampoline, the real flags carry the B bit, so a BRK is still recognised.

5. Practical rules

  • Calling the OS while the ROM is off: with trampolines, interrupts are safe, but a direct JSR CIOV jumps into RAM, where there is no OS. Switch the ROM on around OS calls (and keep the buffers you pass to CIO or SIO below $C000), or use strategy 1.
  • The floating-point package lives at $D800–$DFFF. Any program that uses it, including Atari BASIC, needs the ROM in when it calls those routines.
  • Interrupt handlers stored under the ROM must only run while the ROM is out. Point the OS vectors at them only while the RAM is mapped, or keep handlers below $C000.
  • RESET: the PIA reset turns the ROM back on and the OS warm start reinitialises its vectors in page 2. A RAM OS or trampolines must be reinstalled from your DOSINI routine (see The RESET Key: Warm Start, Cold Start and Writing RESET-Proof Programs).
  • Other software may own PORTB too: a DOS RAMdisk, a BASIC that lives under the ROM, or a bank-switching driver. Save and restore PORTB rather than writing fixed values.
  • The 1200XL uses PORTB bits 2 and 3 for its LEDs. Read-modify-write keeps them as they were.

Troubleshooting

  • Crash within a frame of clearing bit 0: no valid NMI/IRQ vectors in RAM. Copy the OS, or install trampolines with NMIs disabled first.
  • Text turns to dots and dashes: ANTIC is reading an empty font under $E000. Copy the font or move CHBAS.
  • Joysticks, colours and timers 2–5 freeze, but the clock runs: the VBI thinks it interrupted a critical section. Pass the original flags in the fake interrupt frame.
  • Copy loop crashes occasionally: an interrupt arrived while the ROM was out. Disable NMIs (NMIEN = 0) as well as IRQs.
  • The copy doesn't take: writes made while the ROM is on are discarded. Switch the ROM off before storing.
  • Works until RESET: reinstall from DOSINI.

Further reading

  • Ian Chadwick, Mapping the Atari (revised edition): PORTB 54017 on the XL/XE, with Joe Miller's RAMROM program and source.
  • Avery Lee, Altirra Hardware Reference Manual, section 2.6 (ROM control, writes to ROM) and 4.16 (the Atomix Plus! example).
  • On this site: Using the 130XE's Extra 64K: PORTB Bank Switching, Memory Expansions Beyond the 130XE, Inside the OS Interrupt Handlers, XL/XE Compatibility: Why Old 800 Software Fails, and How the Translator Fixes It.

Credits