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>";
        }
    }

}