Expert.java

package libsidplay.components.cart.supported;

import libsidplay.common.Event;
import libsidplay.common.Event.Phase;
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;

/**
 * CRT 6, preloaded Expert Cartridge in ON mode. Its 8 KiB RAM appears at
 * $8000 and, read-only, at $E000. The rest of the C64 and both VIC phases
 * keep their ordinary memory decoding (selective Ultimax).
 * Reference: VICE vice/src/c64/cart/expert.c and c64cartsystem.h.
 */
public class Expert extends Cartridge {
    protected final byte[] ram = new byte[0x2000];
    private boolean mapped;
    private boolean writable;
    private boolean detached;
    private boolean busAvailable = true;
    private boolean freezeRequested;

    public Expert(final DataInputStream input, final PLA pla) throws IOException {
        super(pla);
        byte[] header = new byte[16];
        int count = readChipHeader(input, header);
        if (count == 0) throw new IOException("Expert Cartridge requires one CHIP record");
        validateHeader(header, count);
        long length = (long) u16(header, 4) << 16 | u16(header, 6);
        int type = u16(header, 8);
        if (length < 0x2010 || type > 2 || u16(header, 10) != 0
                || u16(header, 12) != 0x8000 || u16(header, 14) != ram.length) {
            throw new IOException("Invalid Expert Cartridge CHIP record");
        }
        try {
            input.readFully(ram);
        } catch (EOFException e) {
            throw new EOFException("Truncated Expert Cartridge CHIP payload");
        }
        if (length == 0x4010) {
            // Historical Expert images (also shown in the VICE CRT manual)
            // declare 16 KiB but contain one complete 8 KiB RAM image, then EOF.
            count = readChipHeader(input, header);
            if (count == 0) return;
            skipFully(input, length - 0x2010 - count, "Truncated Expert Cartridge CHIP padding");
        } else {
            skipFully(input, length - 0x2010, "Truncated Expert Cartridge CHIP padding");
        }
        count = readChipHeader(input, header);
        if (count != 0) {
            validateHeader(header, count);
            throw new IOException("Too many Expert Cartridge CHIP records");
        }
    }

    private static void validateHeader(byte[] header, int count) throws IOException {
        if (count != header.length) throw new EOFException("Truncated Expert Cartridge CHIP header");
        if (header[0] != 'C' || header[1] != 'H' || header[2] != 'I' || header[3] != 'P') {
            throw new IOException("Invalid Expert Cartridge CHIP signature");
        }
    }

    private static int u16(byte[] bytes, int offset) {
        return (bytes[offset] & 255) << 8 | bytes[offset + 1] & 255;
    }

    private void enableRam() {
        if (detached) return;
        mapped = writable = true;
        pla.setGameExrom(true, true);
        setNMI(false);
    }

    private void accessIO1(int address) {
        if (detached || (address & 0xff) > 1) return;
        mapped = !mapped;
        writable = false;
        pla.setGameExrom(true, true);
        setNMI(false);
    }

    private final Bank io1Bank = new Bank() {
        @Override public byte read(int address) {
            accessIO1(address);
            return pla.getDisconnectedBusBank().read(address);
        }
        @Override public void write(int address, byte value) { accessIO1(address); }
    };

    private final Bank romlBank = new Bank() {
        @Override public byte read(int address) { return ram[address & 0x1fff]; }
        @Override public void write(int address, byte value) {
            if (!detached && writable && mapped) ram[address & 0x1fff] = value;
        }
    };

    private final Bank romhBank = new Bank() {
        @Override public byte read(int address) { return ram[address & 0x1fff]; }
        @Override public void write(int address, byte value) { }
    };

    @Override public void installBankHooks(Bank[] cpuReadMap, Bank[] cpuWriteMap) {
        if (detached || !mapped) return;
        cpuReadMap[0x8] = cpuReadMap[0x9] = romlBank;
        if (writable) cpuWriteMap[0x8] = cpuWriteMap[0x9] = romlBank;
        cpuReadMap[0xe] = cpuReadMap[0xf] = cpuWriteMap[0xe] = cpuWriteMap[0xf] = romhBank;
    }

    @Override public void nmiAcknowledged() { enableRam(); }

    private final Event freezeMapping = Event.of("Expert Cartridge freeze", event -> enableRam());

    @Override protected void doFreeze() {
        var scheduler = pla.getCPU().getEventScheduler();
        if (detached || freezeRequested || scheduler.isPending(freezeMapping)) return;
        // As in VICE, start the button pulse after stolen bus cycles finish.
        if (!busAvailable) {
            freezeRequested = true;
            return;
        }
        setNMI(true);
        scheduler.schedule(freezeMapping, 3, Phase.PHI1);
    }

    @Override public void changedBA(boolean state) {
        busAvailable = state;
        if (state && freezeRequested) {
            freezeRequested = false;
            doFreeze();
        }
    }

    @Override public void reset() {
        pla.getCPU().getEventScheduler().cancel(freezeMapping);
        super.reset();
        detached = false;
        busAvailable = true;
        freezeRequested = false;
        enableRam();
    }

    @Override public void onDetach() {
        detached = true;
        freezeRequested = false;
        mapped = writable = false;
        pla.getCPU().getEventScheduler().cancel(freezeMapping);
        setNMI(false);
        pla.setGameExrom(true, true);
    }

    @Override public Bank getRoml() { return romlBank; }
    @Override public Bank getRomh() { return romhBank; }
    @Override public Bank getIO1() { return io1Bank; }
    @Override public String toString() { return "Expert Cartridge"; }
}