GeoRAM.java

/**
 * georam.c - GEORAM emulation.
 * <p>
 * Written by
 * Marco van den Heuvel <blackystardust68@yahoo.com>
 * <p>
 * This file is part of VICE, the Versatile Commodore Emulator.
 * See README for a copyright notice.
 * <p>
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License or
 * (at your option) any later version.
 * <p>
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * <p>
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 * 02111-1307  USA.
 * <p>
 * The GeoRAM is a banked memory system. It uses the registers at
 * $dffe and $dfff to determine what part of the GeoRAM memory should
 * be mapped to $de00-$deff.
 * <p>
 * XXX The BBG (Battery Backed GeoRAM) is a version that retains the
 * RAM contents after power-off. This is not emulated, yet.
 *
 * @author Ken Händel
 */
package libsidplay.components.cart.supported;

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;

public class GeoRAM extends Cartridge {

    /**
     * GEORAM register selects a page within a 16KB bank.
     *
     * <PRE>
     * Register | bits
     * -------------------
     * $dffe    | xx543210
     *
     * x = unused, not connected.
     * </PRE>
     */
    protected int dffe;
    /**
     * GEORAM register selects a 16KB bank. The number of 16k blocks that is
     * available depends on the size of the GeoRAM/BBG:
     *
     * <PRE>
     * RAM size | $dfff
     * ------------------
     *   64k | $00-$03
     *  128k | $00-$07
     *  256k | $00-$0f
     *  512k | $00-$1f
     * 1024k | $00-$3f
     * 2048k | $00-$7f
     * 4096k | $00-$ff
     * </PRE>
     */
    protected int dfff;
    /**
     * GEORAM memory.
     */
    protected final byte[] ram;
    private boolean detached;

    public GeoRAM(DataInputStream dis, PLA pla, int sizeKB) throws IOException {
        super(pla);
        if (sizeKB != 0 && !validSize(sizeKB)) throw new IOException("Unsupported GeoRAM size: " + sizeKB + " KiB");
        // Retain the historical default for an empty image or a zero-sized request.
        ram = new byte[(sizeKB == 0 ? 2048 : sizeKB) << 10];
        if (dis != null) {
            int offset = 0;
            while (offset < ram.length) {
                int count = dis.read(ram, offset, ram.length - offset);
                if (count < 0) {
                    if (offset == 0 && sizeKB == 0) break;
                    throw new EOFException("Truncated GeoRAM image");
                }
                if (count == 0) throw new IOException("Stalled GeoRAM image stream");
                offset += count;
            }
            if (offset == ram.length && dis.read() != -1) {
                throw new IOException("Oversized GeoRAM image");
            }
        }
        reset();
    }

    private static boolean validSize(int sizeKB) {
        return sizeKB >= 64 && sizeKB <= 4096 && (sizeKB & (sizeKB - 1)) == 0;
    }

    /** Validate the byte length before a raw image can replace an attached device. */
    public static int imageSizeKB(long bytes) throws IOException {
        if (bytes == 0) return 0;
        if (bytes < 65536 || bytes > 4194304 || (bytes & (bytes - 1)) != 0)
            throw new IOException("Invalid GeoRAM image size: " + bytes + " bytes");
        return (int) (bytes >> 10);
    }

    public int getSizeKB() { return ram.length >> 10; }

    /** A snapshot owns its bytes; callers cannot modify the live cartridge RAM. */
    public byte[] copyRAM() { return ram.clone(); }

    @Override
    public void reset() {
        if (detached) return;
        super.reset();
        pla.setGameExrom(true, true);
        dffe = 0;
        dfff = 0;
    }

    protected final Bank io1Bank = new Bank() {
        @Override
        public byte read(final int address) {
            return detached ? pla.getDisconnectedBusBank().read(address) : ram[dfff << 14 | dffe << 8 | address & 0xff];
        }

        @Override
        public void write(final int address, final byte value) {
            if (!detached) ram[dfff << 14 | dffe << 8 | address & 0xff] = value;
        }
    };

    protected final Bank io2Bank = new Bank() {
        @Override
        public byte read(final int address) {
            return pla.getDisconnectedBusBank().read(address);
        }

        @Override
        public void write(final int address, final byte value) {
            // A0 selects the register; only IO2's upper half is decoded.
            if (detached || (address & 0x80) == 0) return;
            if ((address & 1) == 0) dffe = value & 0x3f;
            else dfff = (value & 0xff) & ((ram.length >> 14) - 1);
        }
    };

    @Override
    public void onDetach() { detached = true; }

    @Override
    public Bank getIO1() {
        return io1Bank;
    }

    @Override
    public Bank getIO2() {
        return io2Bank;
    }

    @Override
    public String toString() {
        return getClass().getSimpleName() + " (" + getPhysicalSize(ram.length) + ")";
    }

}