REU.java
package libsidplay.components.cart.supported;
import libsidplay.common.Event;
import libsidplay.components.cart.Cartridge;
import libsidplay.components.pla.Bank;
import libsidplay.components.pla.PLA;
import java.io.DataInputStream;
import java.io.EOFException;
import java.io.IOException;
import static libsidutils.IOUtils.getPhysicalSize;
/**
* <p>
* 16 MB RAM Expansion Unit emulation. No REU of this size was ever produced,
* but 1541U and VICE nevertheless can emulate one.
* <p>
* The real REUs that were manufactured had the following sizes:
* <ul>
* <li>1700: 128 kB
* <li>1750: 512 kB
* <li>1764: 256 kB
* <li>1750 XL: 2 MB
* </ul>
* The 1750 REU uses 256 kb chips. The 1750 XL is a mod on 1750, where a custom
* circuit detects the next 2 higher bits of the bank register (bits 3 and 4
* above 0-2) and uses these to do bank-switching between four 512 kB banks.
* Consequently, it was not possible to read those bits from the BANK register,
* and overflow of the REU RAM address can't switch to the next 512 kB bank but
* loops back to the start of each 512 kB window.
* <p>
* We are not emulating the wrap-around features of the REU chips yet. We are
* emulating a fictional REU with a full 8-bit wide BANK register. We do emulate
* the verify-related bugs.
* <p>
* REU images are pure RAM dumps with no internal structure.
*
* @author AL
*/
public class REU extends Cartridge {
private enum Command {
TO_REU, FROM_REU, SWAP, VERIFY
}
private static final int REGISTER_STATUS = 0x0;
private static final int REGISTER_COMMAND = 0x1;
private static final int REGISTER_BASEADDR_LOW = 0x2;
private static final int REGISTER_BASEADDR_HIGH = 0x3;
private static final int REGISTER_RAMADDR_LOW = 0x4;
private static final int REGISTER_RAMADDR_HIGH = 0x5;
private static final int REGISTER_BANK = 0x6;
private static final int REGISTER_BLOCKLEN_LOW = 0x7;
private static final int REGISTER_BLOCKLEN_HIGH = 0x8;
private static final int REGISTER_INTERRUPT = 0x9;
private static final int REGISTER_ADDR_CONTROL = 0xa;
private static final int REGISTER_INTERRUPT_UNUSED = 0x1f;
private static final int REGISTER_ADDR_CONTROL_UNUSED = 0x3f;
/**
* Controller address mask; the 1764 has a 512 KB address space but only 256 KB installed.
*/
protected final int wrapAround;
private byte floatingBusValue = (byte) 0xff;
/**
* REU currently actively performing DMA
*/
protected boolean dmaActive;
/**
* REU RAM region (max. 16 MB)
*/
protected byte[] ram;
/**
* Current state of the bus available signal
*/
protected boolean ba;
/** First PHI2 on which the REC sees BA low (sprite activation can be late). */
private long baLowCycle = Long.MAX_VALUE;
/**
* Is FF00 REU DMA trigger enabled
*/
protected boolean ff00;
/**
* Misc. REU register
*/
protected byte status, command, interrupt, addrControl;
/**
* DMA operation C64 address
*/
protected int baseAddr, shadowBaseAddr;
/**
* DMA operation REU address
*/
protected int ramAddr, shadowRamAddr;
/**
* DMA operation length
*/
protected short dmaLen, shadowDmaLen;
/**
* Currently active command
*/
protected Command reuOperation;
protected final DMAEvent dmaEvent;
protected final Event dmaBeginEvent;
protected final Event dmaEndEvent;
private boolean starTreuWorkaround;
private final Event starTreuResumeEvent;
/**
* REU interrupt enable/disable
*/
protected void interrupt() {
int irq = 0x60 & interrupt & status;
if (irq != 0 && (interrupt & 0x80) != 0) {
status |= 0x80;
}
setIRQ((status & 0x80) != 0);
}
public REU(DataInputStream dis, PLA pla, int sizeKB) throws IOException {
super(pla);
assert dis != null || sizeKB == 0 || sizeKB == 128 || sizeKB == 512 || sizeKB == 256 || sizeKB == 2 << 10
|| sizeKB == 16 << 10;
if (sizeKB == 0) {
// an empty file means maximum size!
sizeKB = 16 << 10;
}
starTreuResumeEvent = Event.of("Restore BA after StarTreu resume read", event -> {
if (!pla.isBusAvailable()) pla.getCPU().setRDY(false);
});
dmaEvent = new DMAEvent();
dmaBeginEvent = Event.of("REU DMA Begin", event -> {
pla.setDMA(true);
dmaActive = true;
dmaEvent.reset();
/* Schedule DMA operation to begin on the next PHI2 */
if (ba || pla.getCPU().getEventScheduler().getTime(Event.Phase.PHI2) < baLowCycle) {
pla.getCPU().getEventScheduler().schedule(dmaEvent, 0, Event.Phase.PHI2);
}
});
dmaEndEvent = Event.of("REU DMA End", event -> {
// BA can rise earlier in this PHI1 and queue a resume. The completed
// transfer must not run another byte after /DMA is released.
pla.getCPU().getEventScheduler().cancel(dmaEvent);
dmaActive = false;
pla.setDMA(false);
var scheduler = pla.getCPU().getEventScheduler();
if (starTreuWorkaround && reuOperation == Command.FROM_REU && baseAddr == 0xd016
&& (addrControl & 0x80) != 0 && !ba
&& baLowCycle == scheduler.getTime(Event.Phase.PHI2)
&& pla.getRAMBank().read(0xfffe) == 0x29 && pla.getRAMBank().read(0xffff) == 0x08) {
// IRQ $0829 identifies the following portrait effect; the earlier
// effect also uses $D016 fillers and needs its original timing.
// VICE finishes the interrupted CPU read before testing the new VIC BA
// edge again. This effect depends on that handoff for its fixed $D016 fills.
// Keep this compatibility behaviour out of the default hardware path.
pla.getCPU().setRDY(true);
scheduler.schedule(starTreuResumeEvent, 1, Event.Phase.PHI1);
}
});
wrapAround = ((sizeKB == 256 ? 512 : sizeKB) << 10) - 1;
ram = new byte[sizeKB << 10];
if (dis != null) {
try {
dis.readFully(ram);
} catch (EOFException e) {
// Short images retain their existing zero-filled tail.
}
} else if (sizeKB == 256) {
initialize1764PowerUpRam();
}
reset();
}
/** One recorded 1764 power-up state, not a universal DRAM power-up guarantee. */
private void initialize1764PowerUpRam() {
// Matches the installed half of REU/raminitpattern/dumpfile-256k-x1541.bin.
for (int address = 0; address < ram.length; address++) {
int value = ((address + 1) & 2) == 0 ? 0xff : 0;
if ((address & 0x100) != 0) value ^= 0xff;
int offset = address & 0xffff;
boolean invertedBand = offset >= 0x2a00 && offset < 0x5400
|| offset >= 0x8000 && offset < 0xac00 || offset >= 0xd600;
if (invertedBand != ((address & 0x20000) != 0)) value ^= 0xff;
ram[address] = (byte) value;
}
}
private final Bank io2Bank = new Bank() {
@Override
public byte read(int address) {
if (dmaActive) {
return pla.getDisconnectedBusBank().read(address);
}
address &= 0x1f;
switch (address) {
case REGISTER_STATUS: {
byte value = status;
status &= 0x1f;
interrupt();
return value;
}
case REGISTER_COMMAND:
return command;
case REGISTER_BASEADDR_HIGH:
return (byte) (baseAddr >> 8);
case REGISTER_BASEADDR_LOW:
return (byte) baseAddr;
case REGISTER_RAMADDR_HIGH:
return (byte) (ramAddr >> 8);
case REGISTER_RAMADDR_LOW:
return (byte) ramAddr;
case REGISTER_BANK:
// Original REC bank bits 3-7 read high, including the 1750 XL.
return (byte) ((ramAddr >> 16) | (ram.length <= (2 << 20) ? 0xf8 : 0));
case REGISTER_BLOCKLEN_HIGH:
return (byte) (dmaLen >> 8);
case REGISTER_BLOCKLEN_LOW:
return (byte) dmaLen;
case REGISTER_INTERRUPT: {
byte value = interrupt;
value |= REGISTER_INTERRUPT_UNUSED;
return value;
}
case REGISTER_ADDR_CONTROL: {
byte value = addrControl;
value |= REGISTER_ADDR_CONTROL_UNUSED;
return value;
}
default:
return (byte) 0xff;
}
}
@Override
public void write(int address, byte value) {
if (dmaActive) {
return;
}
address &= 0x1f;
/*
* How does baseAddress etc. work? The internal register within the REU is 16
* bits wide. Every CPU writing to bank, base and ram addresses is backed by a
* shadow register that holds the reference value that is used during the
* AUTOLOAD mode of command.
*
* Whenever a writing occurs, it goes into the shadow first and is then copied to
* the register used for DMA operations. However, this means that writing low 8
* bits will copy the high 8 bits as well, and vice versa.
*
* The bank is a separate register, and the REU tracks overflows of the ramAddr
* and increments a bank on overflow. I have chosen to store a bank on the ramAddr
* high bits. That is why the bank is modified differently from the other
* modifications.
*/
switch (address) {
case REGISTER_STATUS: {
return;
}
case REGISTER_COMMAND:
command = value;
reuOperation = Command.values()[value & 3];
/* prime ff00 when execute & ff00 */
ff00 = (value & 0x90) == 0x80;
if ((value & 0x90) == 0x90) {
/* execute & no ff00 */
beginDma();
}
return;
case REGISTER_BASEADDR_HIGH:
shadowBaseAddr &= 0x00ff;
shadowBaseAddr |= (value & 0xff) << 8;
baseAddr = shadowBaseAddr;
return;
case REGISTER_BASEADDR_LOW:
shadowBaseAddr &= 0xff00;
shadowBaseAddr |= value & 0xff;
baseAddr = shadowBaseAddr;
return;
case REGISTER_RAMADDR_HIGH:
shadowRamAddr &= 0xff00ff;
shadowRamAddr |= (value & 0xff) << 8;
/* copy bits, keep Bank */
ramAddr &= wrapAround & 0xff0000;
ramAddr |= shadowRamAddr & 0xffff;
ramAddr &= wrapAround;
return;
case REGISTER_RAMADDR_LOW:
shadowRamAddr &= 0xffff00;
shadowRamAddr |= value & 0xff;
/* copy bits, keep Bank */
ramAddr &= wrapAround & 0xff0000;
ramAddr |= shadowRamAddr & 0xffff;
ramAddr &= wrapAround;
return;
case REGISTER_BANK:
/*
* Modify bank and shadow copy of a bank, kept on the high bits of ramAddr, which
* is a deviation from hardware's behavior.
*/
ramAddr &= 0xffff;
ramAddr |= (value & 0xff) << 16;
ramAddr &= wrapAround;
shadowRamAddr &= 0xffff;
shadowRamAddr |= (value & 0xff) << 16;
return;
case REGISTER_BLOCKLEN_HIGH:
shadowDmaLen &= 0x00ff;
shadowDmaLen |= (value & 0xff) << 8;
dmaLen = shadowDmaLen;
return;
case REGISTER_BLOCKLEN_LOW:
shadowDmaLen &= 0xff00;
shadowDmaLen |= value & 0xff;
dmaLen = shadowDmaLen;
return;
case REGISTER_INTERRUPT:
interrupt = value;
interrupt();
return;
case REGISTER_ADDR_CONTROL:
addrControl = value;
}
}
};
@Override
public Bank getIO2() {
return io2Bank;
}
@Override
public boolean isIO2ReadDriven(int address) {
return !dmaActive;
}
@Override
public void reset() {
super.reset();
status = (byte) (ram.length == (128 << 10) ? 0 : 0x10);
command = 0x10;
baseAddr = shadowBaseAddr = 0;
ramAddr = shadowRamAddr = 0;
dmaLen = shadowDmaLen = (short) 0xffff;
interrupt = 0;
addrControl = 0;
stopDma();
ba = pla.isBusAvailable();
baLowCycle = ba ? Long.MAX_VALUE : pla.getCPU().getEventScheduler().getTime(Event.Phase.PHI2);
}
/** Optional VICE handoff compatibility; C64 enables it only for recognised StarTreu ROMs. */
public final void setStarTreuWorkaround(boolean enable) {
starTreuWorkaround = enable;
if (!enable) cancelStarTreuResume();
}
private void cancelStarTreuResume() {
var scheduler = pla.getCPU().getEventScheduler();
if (scheduler.isPending(starTreuResumeEvent)) {
scheduler.cancel(starTreuResumeEvent);
if (!pla.isBusAvailable()) pla.getCPU().setRDY(false);
}
}
private void stopDma() {
cancelStarTreuResume();
var scheduler = pla.getCPU().getEventScheduler();
scheduler.cancel(dmaBeginEvent);
scheduler.cancel(dmaEvent);
scheduler.cancel(dmaEndEvent);
if (dmaActive) pla.setDMA(false);
dmaActive = false;
ff00 = false;
dmaEvent.reset();
}
@Override
public void onDetach() {
stopDma();
setIRQ(false);
}
@Override
public void changedBA(boolean state) {
changedBA(state, false);
}
@Override
public void changedBA(boolean state, boolean lateSpriteDma) {
ba = state;
baLowCycle = state ? Long.MAX_VALUE
: pla.getCPU().getEventScheduler().getTime(Event.Phase.PHI2) + (lateSpriteDma ? 1 : 0);
if (dmaActive && ba) {
// A write may still be queued from the falling edge; never enqueue it twice.
var scheduler = pla.getCPU().getEventScheduler();
scheduler.cancel(dmaEvent);
if (reuOperation == Command.SWAP && dmaEvent.completionPending) {
// Both SWAP accesses have finished. Release in this PHI1 without
// consuming another PHI2 after the VIC gives back the bus.
dmaEvent.complete();
} else {
scheduler.schedule(dmaEvent, 0, Event.Phase.PHI2);
}
}
// Let the queued operation sample the falling edge: non-final writes
// have one cycle of grace; SWAP arbitrates its two-cycle exchange separately.
}
@Override
public void installBankHooks(Bank[] cpuReadMap, Bank[] cpuWriteMap) {
final Bank rom = cpuWriteMap[0xf];
cpuWriteMap[0xf] = new Bank() {
@Override
public void write(int address, byte value) {
rom.write(address, value);
/* when primed, execute DMA on write to 0xff00 */
if (ff00 && address == 0xff00) {
ff00 = false;
beginDma();
}
}
};
}
// Unpopulated 1764 banks return the retained data latch and ignore writes.
private byte readRAM(int address) {
return address < ram.length ? ram[address] : floatingBusValue;
}
private void writeRAM(int address, byte value) {
if (address < ram.length) {
ram[address] = value;
}
}
protected void beginDma() {
pla.getCPU().getEventScheduler().schedule(dmaBeginEvent, 0, Event.Phase.PHI1);
}
protected class DMAEvent extends Event {
/**
* Command.SWAP in the "read c64" phase
*/
private boolean swapReadPhase;
/**
* Command.SWAP read data during the "read c64" phase
*/
private byte swapData;
/** An exchange admitted at BA falling, including a delayed REC sample, can finish its write. */
private boolean swapReadOnBaEdge;
/** Restart cycle after that completed exchange has waited through a VIC steal. */
private boolean swapResumeDelay;
/** Anchor the alternating read/write slots across VIC steals of either length. */
private long swapReadCycle;
/** The saved fixed-I/O byte can be sampled again if BA returns on a read slot. */
private boolean swapIoResumeRefresh;
/** Fixed-address I/O SWAP keeps sampling until the first stalled PHI2. */
private boolean swapIoRefreshPending;
private int swapIoHostAddress;
private int swapIoReuAddress;
private long swapIoRefreshCycle;
/**
* Verify Error exit states
*/
private int verifyError;
private boolean completionPending;
protected DMAEvent() {
super("REU DMA Active");
}
protected void reset() {
swapReadPhase = true;
swapReadOnBaEdge = false;
swapResumeDelay = false;
swapReadCycle = -1;
swapIoResumeRefresh = false;
swapIoRefreshPending = false;
verifyError = 0;
completionPending = false;
}
protected void finish() {
/* Execute off, FF00 off */
command &= 0x7f;
command |= 0x10;
// FROM_REU leaves the next prefetched byte in the data latch.
if (reuOperation == Command.FROM_REU) {
floatingBusValue = readRAM(ramAddr);
}
/* Autoload? */
if ((command & 0x20) != 0) {
baseAddr = shadowBaseAddr;
ramAddr = wrapAround & shadowRamAddr;
dmaLen = shadowDmaLen;
}
pla.getCPU().getEventScheduler().schedule(dmaEndEvent, 0, Event.Phase.PHI1);
}
@Override
public void event() {
long cycle = pla.getCPU().getEventScheduler().getTime(Event.Phase.PHI2);
boolean writeCycle = !completionPending && (reuOperation == Command.FROM_REU
|| reuOperation == Command.SWAP && !swapReadPhase);
if (reuOperation == Command.SWAP && !completionPending) {
if (!swapBusAvailable(cycle)) return;
} else if (!ba && cycle >= baLowCycle + (writeCycle && dmaLen != 1 ? 1 : 0)) {
// The final one-way write waits for a real grant before
// changing memory, mapped I/O or completion state.
return;
}
if (completionPending) {
complete();
return;
}
// A failed comparison consumes one idle cycle, without decrementing
// the remaining length again. Only a final byte is compared here.
if (verifyError != 0) {
if (dmaLen == 1 && pla.dmaRead(baseAddr) == readRAM(ramAddr)) {
status |= 0x40;
interrupt();
}
finish();
return;
}
int oldVerifyError = verifyError;
switch (reuOperation) {
case TO_REU:
floatingBusValue = pla.dmaRead(baseAddr);
writeRAM(ramAddr, floatingBusValue);
break;
case FROM_REU:
floatingBusValue = readRAM(ramAddr);
pla.dmaWrite(baseAddr, floatingBusValue);
break;
case SWAP:
if (swapReadPhase) {
swapReadPhase = false;
swapReadCycle = cycle;
swapIoResumeRefresh = false;
swapData = pla.dmaRead(baseAddr);
pla.getCPU().getEventScheduler().schedule(this, 1, Event.Phase.PHI2);
return;
} else {
swapReadPhase = true;
pla.dmaWrite(baseAddr, readRAM(ramAddr));
writeRAM(ramAddr, swapData);
if (swapReadOnBaEdge && dmaLen != 1 && (addrControl & 0x80) != 0
&& !ba && (cycle == baLowCycle || cycle == baLowCycle + 1)
&& pla.isIoReadAvailable(baseAddr)) {
// Fixed-I/O captures retain a later sample of this byte,
// before AEC falls or on a returned read slot. Neither
// sampling point advances the completed exchange again.
swapIoRefreshPending = true;
swapIoResumeRefresh = true;
swapIoHostAddress = baseAddr;
swapIoReuAddress = ramAddr;
swapIoRefreshCycle = cycle + 1;
}
swapReadOnBaEdge = false;
}
break;
case VERIFY:
if (pla.dmaRead(baseAddr) != readRAM(ramAddr)) {
status |= 0x20;
interrupt();
verifyError++;
}
break;
}
/*
* INC stops on the first verified error, but the last byte does get compared
*/
if (oldVerifyError == 0) {
/* Fixed C64? */
if ((addrControl & 0x80) == 0) {
baseAddr = baseAddr + 1 & 0xffff;
}
/* Fixed REU? */
if ((addrControl & 0x40) == 0) {
ramAddr = ramAddr + 1 & wrapAround;
}
}
/* REU reschedules or exits */
if (dmaLen != 1) {
dmaLen--;
/* If no verified errors yet, continue */
if (oldVerifyError == 0) {
pla.getCPU().getEventScheduler().schedule(this, 1, Event.Phase.PHI2);
} else {
finish();
}
} else {
if (reuOperation == Command.SWAP && writeCycle && !ba && cycle >= baLowCycle) {
// An admitted final SWAP write can overlap BA falling.
// Keep /DMA asserted until the VIC gives the bus back.
completionPending = true;
} else {
complete();
}
}
}
/**
* SWAP has its own BA checkpoints, rather than the independent read/write
* grants of a one-way transfer. f3/g3 cover both edge phases and short
* grants; e4-m2/e6-m2 also require the two-cycle phase to survive a badline
* overlapping sprite DMA, where BA returns on a read slot.
*/
private boolean swapBusAvailable(long cycle) {
if (swapIoRefreshPending) {
swapIoRefreshPending = false;
if (!ba && cycle == swapIoRefreshCycle && pla.isIoReadAvailable(swapIoHostAddress)) {
writeRAM(swapIoReuAddress, pla.dmaRead(swapIoHostAddress));
}
}
// A late sprite activation admits this read before the REC samples BA low.
if (!ba && swapReadPhase && cycle + 1 == baLowCycle) {
swapReadOnBaEdge = true;
}
if (!ba && cycle >= baLowCycle) {
if (swapReadPhase && cycle == baLowCycle) {
swapReadOnBaEdge = true;
return true;
}
if (!swapReadPhase && swapReadOnBaEdge
&& (cycle == baLowCycle || cycle == baLowCycle + 1)) {
return true;
}
// A pending write is retried from the read phase on the next
// grant; its address and remaining length have not advanced.
// A completed edge exchange instead needs one restart cycle.
swapResumeDelay = swapReadPhase;
swapReadPhase = true;
swapReadOnBaEdge = false;
return false;
}
if (swapResumeDelay) {
swapResumeDelay = false;
// Recover the completed byte first when BA returns on a read
// slot, then spend the write slot restarting the next exchange.
boolean readSlot = ((cycle - swapReadCycle) & 1) == 0;
if (readSlot && swapIoResumeRefresh && pla.isIoReadAvailable(swapIoHostAddress)) {
writeRAM(swapIoReuAddress, pla.dmaRead(swapIoHostAddress));
}
swapIoResumeRefresh = false;
pla.getCPU().getEventScheduler().schedule(this, readSlot ? 2 : 1, Event.Phase.PHI2);
return false;
}
// An interrupted write retries on the command's original read slot.
// A new command, including one started with BA low, has no slot yet.
if (swapReadPhase && swapReadCycle >= 0 && ((cycle - swapReadCycle) & 1) != 0) {
pla.getCPU().getEventScheduler().schedule(this, 1, Event.Phase.PHI2);
return false;
}
return true;
}
private void complete() {
/* Set end-of-block unless the final two verify bytes both failed. */
if (verifyError != 2) {
status |= 0x40;
interrupt();
}
completionPending = false;
finish();
}
}
@Override
public String toString() {
return getClass().getSimpleName() + " " + getModelName() + " (" + getPhysicalSize(ram.length) + ")";
}
private String getModelName() {
switch (ram.length >> 10) {
case 128:
return "1700";
case 512:
return "1750";
case 256:
return "1764";
case 2048:
return "1750XL";
case 16384:
default:
return "<noname>";
}
}
}