FinalV3.java

package libsidplay.components.cart.supported;

import java.io.DataInputStream;
import java.io.EOFException;
import java.io.IOException;
import java.util.Arrays;

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 static java.nio.charset.StandardCharsets.US_ASCII;

/**
 * CRT 3: Final Cartridge III (64 KiB) / Final Cartridge III+ (256 KiB).
 * IO1/IO2 always mirror the selected ROML bank; only writes to $DFFF latch
 * banking, GAME/EXROM, NMI and the register lock. Freeze unlocks the register
 * without changing banks, with disconnected PHI1 and Ultimax PHI2 mapping.
 * Reference: VICE vice/src/c64/cart/final3.c.
 */
public class FinalV3 extends Cartridge {
    protected int currentRomBank;
    protected final byte[][] romLBanks = new byte[16][0x2000];
    protected final byte[][] romHBanks = new byte[16][0x2000];
    protected boolean controlRegAvailable;
    private final int bankMask;
    private boolean detached;

    public FinalV3(final DataInputStream input, final PLA pla) throws IOException {
        super(pla);
        for (byte[] bank : romLBanks) Arrays.fill(bank, (byte) 0xff);
        for (byte[] bank : romHBanks) Arrays.fill(bank, (byte) 0xff);
        byte[] header = new byte[16];
        int records = 0, highestBank = 0;
        for (;;) {
            int count = readChipHeader(input, header);
            if (count == 0) break;
            if (count != header.length) throw new EOFException("Truncated Final Cartridge III CHIP header");
            if (!"CHIP".equals(new String(header, 0, 4, US_ASCII))) {
                throw new IOException("Invalid Final Cartridge III CHIP signature");
            }
            if (++records > 16) throw new IOException("Too many Final Cartridge III CHIP records");
            long length = (long) u16(header, 4) << 16 | u16(header, 6);
            int type = u16(header, 8), bank = u16(header, 10), size = u16(header, 14);
            // As with other banked CRTs, the load address is metadata, not a decoder.
            if (length < header.length + (long) size || (type != 0 && type != 2)
                    || bank >= 16 || size != 0x4000) {
                throw new IOException("Invalid Final Cartridge III CHIP record");
            }
            try {
                input.readFully(romLBanks[bank]);
                input.readFully(romHBanks[bank]);
            } catch (EOFException e) {
                throw new EOFException("Truncated Final Cartridge III CHIP payload");
            }
            skipFully(input, length - header.length - size, "Truncated Final Cartridge III CHIP padding");
            highestBank = Math.max(highestBank, bank);
        }
        if (records != 4 && records != 16) {
            throw new IOException("Final Cartridge III requires 4 or 16 CHIP records");
        }
        if (highestBank >= records) throw new IOException("Final Cartridge III bank exceeds ROM capacity");
        bankMask = records - 1;
    }

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

    private final Bank ioBank = new Bank() {
        @Override public byte read(int address) {
            return romLBanks[currentRomBank][address & 0x1fff];
        }
        @Override public void write(int address, byte value) {
            if (!controlRegAvailable || address != 0xdfff) return;
            currentRomBank = value & bankMask;
            controlRegAvailable = (value & 0x80) == 0;
            pla.setGameExrom((value & 0x20) != 0, (value & 0x10) != 0);
            setNMI((value & 0x40) == 0);
        }
    };

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

    private final Event freezeMapping = Event.of("Final Cartridge III freeze", event -> {
        controlRegAvailable = true;
        pla.setGameExrom(true, true, false, true);
    });

    @Override protected void doFreeze() {
        var scheduler = pla.getCPU().getEventScheduler();
        if (detached || scheduler.isPending(freezeMapping)) return;
        setNMI(true);
        scheduler.schedule(freezeMapping, 3, Phase.PHI1);
    }

    @Override public void reset() {
        pla.getCPU().getEventScheduler().cancel(freezeMapping);
        super.reset();
        detached = false;
        currentRomBank = 0;
        controlRegAvailable = true;
        pla.setGameExrom(false, false);
    }

    @Override public void onDetach() {
        detached = true;
        controlRegAvailable = 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 ioBank; }
    @Override public Bank getIO2() { return ioBank; }
    @Override public String toString() { return bankMask == 15 ? "Final Cartridge III+" : "Final Cartridge III"; }
}