Using the RAM Under the OS ROM on XL/XE Machines
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:
- 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.
- 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 CIOVjumps 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
- Picture: The first example: the XL OS copied into RAM and its font patched, so capitals appear mirrored. Typed text still goes through the RAM copy's keyboard and screen handlers. — Program authors; screenshot by the site
- Altirra Hardware Reference Manual — 2.6 Bank switching (PORTB bits 0/1/7, $D000-$D7FF always I/O, writes to ROM ignored, pull-ups on reset), 4.16 Examples (Atomix Plus! copy loop) — Avery Lee (Altirra)
- Mapping the Atari (revised) — Appendix 12, PORTB 54017 on XL/XE (crash at next interrupt, Joe Miller's RAMROM program) — AtariArchives.org
- comp.sys.atari.8bit FAQ — 7.1.9 Atari Translator (installs the 400/800 OS in RAM under the XL OS ROM) — Michael Current (comp.sys.atari.8bit FAQ)
