Cartridge.java
package libsidplay.components.cart;
import libsidplay.common.Event;
import libsidplay.components.cart.supported.*;
import libsidplay.components.pla.Bank;
import libsidplay.components.pla.PLA;
import java.io.DataInputStream;
import java.io.EOFException;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
/**
* Cartridge base class.
*
* @author Antti Lankila
*/
public class Cartridge {
private static final Charset ISO88591 = StandardCharsets.ISO_8859_1;
/**
* CCS64 cartridge type map
*/
public enum CRTType {
NORMAL(0), ACTION_REPLAY(1), KCS_POWER_CARTRIDGE(2), FINAL_CARTRIDGE_III(3), SIMONS_BASIC(4), OCEAN_TYPE_1(5),
EXPERT_CARTRIDGE(6), FUN_PLAY__POWER_PLAY(7),
SUPER_GAMES(8), ATOMIC_POWER(9), EPYX_FASTLOAD(10), WESTERMANN_LEARNING(11), REX_UTILITY(12),
FINAL_CARTRIDGE_I(13), MAGIC_FORMEL(14), C64_GAME_SYSTEM__SYSTEM_3(15),
WARPSPEED(16), DINAMIC(17), ZAXXON__SUPER_ZAXXON(18), MAGIC_DESK__DOMARK__HES_AUSTRALIA(19),
SUPER_SNAPSHOT_5(20), COMAL_80(21), STRUCTURED_BASIC(22), ROSS(23),
DELA_EP64(24), DELA_EP7X8(25), DELA_EP256(26), REX_EP256(27), MIKRO_ASSEMBLER(28), FINAL_PLUS(29),
ACTION_REPLAY_4(30), STARDOS(31),
EASYFLASH(32), RETRO_REPLAY(36), PAGEFOX(53), RGCD(57), GMOD2(60);
private final int magic;
CRTType(int magic) {
this.magic = magic;
}
public static CRTType getType(byte[] header) {
if (!new String(header, 0, 0x10, ISO88591).equals("C64 CARTRIDGE ")) {
throw new RuntimeException("File is not a .CRT file");
}
CRTType cart = getType((header[0x16] & 0xff) << 8 | header[0x17] & 0xff);
if (cart == null) {
throw new RuntimeException("Cartridge magic value: "
+ ((header[0x16] & 0xff) << 8 | header[0x17] & 0xff) + " unsupported!");
}
return cart;
}
private static CRTType getType(int magic) {
return Arrays.stream(values()).filter(crt -> crt.magic == magic).findFirst().orElse(null);
}
}
protected Cartridge(final PLA pla) {
this.pla = pla;
}
/**
* Instance of the system's PLA chip.
*/
public final PLA pla;
/**
* Current state of cartridge-asserted NMI
*/
private boolean nmiState;
/**
* Current state of cartridge-asserted IRQ
*/
private boolean irqState;
/**
* Get currently active ROML bank.
*
* @return ROML bank
*/
public Bank getRoml() {
return pla.getDisconnectedBusBank();
}
/**
* Get currently active ROMH bank.
*
* @return ROMH bank
*/
public Bank getRomh() {
return pla.getDisconnectedBusBank();
}
/**
* In Ultimax mode, the main memory between 0x1000-0xffff is disconnected. This
* allows carts to export their own memory for those regions, excluding the
* areas that will be mapped to ROML, IO, and ROMH, though.
*
* @return Memory bank for Ultimax mode
*/
public Bank getUltimaxMemory() {
return pla.getDisconnectedBusBank();
}
/**
* Acquire the IO1 bank
*
* @return The bank responding to IO1 line.
*/
public Bank getIO1() {
return pla.getDisconnectedBusBank();
}
/**
* Acquire the IO2 bank.
*
* @return The bank responding to IO2 line.
*/
public Bank getIO2() {
return pla.getDisconnectedBusBank();
}
/** Whether an IO2 read drives data, independently of read-triggered side effects. */
public boolean isIO2ReadDriven(int address) {
return getIO2() != pla.getDisconnectedBusBank();
}
/**
* Create a cartridge.
*
* @param pla Instance of the system's PLA chip
* @param cartType cartridge type
* @param sizeKB size in KB
* @return a cartridge instance
*/
public static Cartridge create(final PLA pla, final CartridgeType cartType, final int sizeKB)
throws IOException {
switch (cartType) {
case GEORAM:
return new GeoRAM(null, pla, sizeKB);
case REU:
return new REU(null, pla, sizeKB);
case SOUNDEXPANDER:
return new SFXSoundExpander(null, pla, sizeKB);
default:
throw new RuntimeException("Cartridge is unsupported");
}
}
/**
* Load a cartridge.
*
* @param pla Instance of the system's PLA chip
* @param cartType cartridge type
* @param file file to load from
* @return a cartridge instance
*/
public static Cartridge read(final PLA pla, final CartridgeType cartType, final File file) throws IOException {
try (final DataInputStream dis = new DataInputStream(new FileInputStream(file))) {
switch (cartType) {
case GEORAM:
return new GeoRAM(dis, pla, GeoRAM.imageSizeKB(file.length()));
case REU:
return new REU(dis, pla, (int) (file.length() >> 10));
case CRT:
return readCRT(pla, dis);
default:
throw new RuntimeException("Cartridge unsupported");
}
}
}
/**
* Read a CHIP header, returning 0 at clean EOF or the actual number of bytes
* read (up to 16).
*/
protected static int readChipHeader(DataInputStream input, byte[] header) throws IOException {
int length = 0;
while (length < header.length) {
int value = input.read();
if (value == -1) break;
header[length++] = (byte) value;
}
return length;
}
/** Read and discard: FileInputStream.skip can advance beyond EOF without reporting truncation. */
protected static void skipFully(DataInputStream input, long length, String eofMessage) throws IOException {
if (length == 0) return;
byte[] buffer = new byte[(int) Math.min(length, 4096)];
try {
while (length > 0) {
int count = (int) Math.min(length, buffer.length);
input.readFully(buffer, 0, count);
length -= count;
}
} catch (EOFException e) {
throw new EOFException(eofMessage);
}
}
/**
* Load a cartridge of type CRT.
*
* @param pla Instance of the system's PLA chip
* @param is input stream to load from
* @return a cartridge instance
*/
public static Cartridge readCRT(final PLA pla, final DataInputStream is) throws IOException {
final byte[] header = new byte[0x40];
is.readFully(header);
long headerLength = 0;
for (int i = 0x10; i < 0x14; i++) headerLength = headerLength << 8 | header[i] & 0xff;
// Some legacy CRTs declare $20 but still contain the complete 64-byte header.
if (headerLength == 0x20) headerLength = header.length;
if (headerLength < header.length) throw new IOException("Invalid CRT header length");
skipFully(is, headerLength - header.length, "Truncated CRT header extension");
final CRTType type = CRTType.getType(header);
switch (type) {
case ACTION_REPLAY:
return new ActionReplay(is, pla);
case NORMAL:
if ((header[0x18] & 0xfe) != 0 || (header[0x19] & 0xfe) != 0) {
throw new IOException("Invalid Normal CRT GAME/EXROM flags");
}
return new Normal(is, pla, header[0x19] != 0, header[0x18] != 0);
case FINAL_CARTRIDGE_III:
return new FinalV3(is, pla);
case EXPERT_CARTRIDGE:
return new Expert(is, pla);
case ATOMIC_POWER:
return new AtomicPower(is, pla);
case EPYX_FASTLOAD:
return new EpyxFastLoad(is, pla);
case REX_UTILITY:
return new Rex(is, pla);
case FINAL_CARTRIDGE_I:
return new FinalV1(is, pla);
case ZAXXON__SUPER_ZAXXON:
return new Zaxxon(is, pla);
case COMAL_80:
if ((header[0x1a] & 0xff) > 1) {
throw new IOException("Unsupported COMAL-80 CRT subtype: " + (header[0x1a] & 0xff));
}
return new Comal80(is, pla, header[0x1a] == 1);
case MIKRO_ASSEMBLER:
return new MikroAss(is, pla);
case EASYFLASH:
return new EasyFlash(is, pla);
case MAGIC_DESK__DOMARK__HES_AUSTRALIA:
return new MagicDesk(is, pla);
case OCEAN_TYPE_1:
return new OceanType1(is, pla);
case PAGEFOX:
return new Pagefox(is, pla);
case SUPER_GAMES:
return new SuperGames(is, pla);
case RGCD:
if (header[0x1a] != 0) {
throw new IOException("Unsupported RGCD CRT subtype: " + (header[0x1a] & 0xff));
}
return new RGCD(is, pla);
case RETRO_REPLAY:
if ((header[0x1a] & 0xff) > 1) {
throw new IOException("Unsupported Retro Replay CRT subtype: " + (header[0x1a] & 0xff));
}
return new RetroReplay(is, pla, header[0x1a] == 1);
case GMOD2:
return new GMod2(is, pla);
default:
throw new RuntimeException("Cartridges of format: " + type + " unsupported");
}
}
/**
* If the cartridge needs to listen to write activity on specific banks, it can
* install the requisite hooks into the bank here.
*
* @param cpuReadMap CPU read map
* @param cpuWriteMap CPU write map
*/
public void installBankHooks(Bank[] cpuReadMap, Bank[] cpuWriteMap) {
}
/**
* Return an instance of a cartridge when no real cartridge is connected.
*
* @return the null cartridge
*/
public static Cartridge nullCartridge(final PLA pla) {
return new Cartridge(pla) {
@Override
public String toString() {
return "";
}
};
}
/**
* Bring the cart to power-on state. If overridden, remember to call the
* superclass method.
*/
public void reset() {
nmiState = false;
irqState = false;
}
/**
* Push the cartridge's "freeze" button.
* <p>
* Because this is a UI-method, we use thread-safe scheduling to delay the
* freezing to occur at some safe later time.
* <p>
* Subclasses need to override doFreeze().
*/
public final void freeze() {
pla.getCPU().getEventScheduler().scheduleThreadSafe(Event.of("Freeze TS", event -> Cartridge.this.doFreeze()));
}
/**
* Handle pressing of the freeze button.
*/
protected void doFreeze() {
}
/**
* Callback to notify cartridge of the current state of NMI signal on the system
* Bus. The boolean value is active high.
*
* @param state 0 = low, 1 = high
*/
public void changedNMI(boolean state) {
}
/** The CPU has selected the NMI vector; cartridge vector memory must now be visible. */
public void nmiAcknowledged() {
}
/**
* Callback to notify cartridge of the current state of IRQ signal on the system
* Bus. The boolean value is active high.
*
* @param state 0 = low, 1 = high
*/
public void changedIRQ(boolean state) {
}
/**
* Callback to notify cartridge of the current state of BA signal on the system bus.
* The boolean value is active high.
*
* @param state 0 = low, 1 = high
*/
public void changedBA(boolean state) {
}
/**
* The REC samples BA earlier than the CPU. A newly activated sprite 0 can
* therefore leave one additional cycle available to a DMA cartridge.
* Other cartridges continue to receive the ordinary BA notification.
*/
public void changedBA(boolean state, boolean lateSpriteDma) {
changedBA(state);
}
/**
* Assert NMI (= electrically pull NMI low) on the system bus. The boolean value
* is active high. Method is meant for subclasses only.
*
* @param state 0 = low, 1 = high
*/
public void setNMI(boolean state) {
if (state ^ nmiState) {
pla.setNMI(state);
nmiState = state;
}
}
/**
* Assert IRQ (= electrically pull IRQ low) on the system bus. The boolean value
* is active high. Method is meant for subclasses only.
*
* @param state 0 = low, 1 = high
*/
public void setIRQ(boolean state) {
if (state ^ irqState) {
pla.setIRQ(state);
irqState = state;
}
}
/** Release cartridge-owned events and bus lines before replacement. */
public void onDetach() {
}
/** Retained devices must keep their events and bus lines when a REU bundle changes. */
public void onDetach(Cartridge replacement) {
if (!replacement.contains(this)) onDetach();
}
public boolean contains(Cartridge device) {
return this == device;
}
/** Clock cartridge chips. */
public void clock() {
}
@Override
public String toString() {
return getClass().getSimpleName();
}
}