FloppyDrive.java

package libsidplay.components.c1541;

import libsidplay.common.EventScheduler;
import libsidplay.components.mos6510.MOS6510;
import libsidplay.components.mos6526.MOS6526;

/**
 * An independently clocked, ROM-executing IEC disk drive.
 * <p>
 * Register, memory and media operations belong to the emulation thread, or must be performed while emulation is
 * stopped.
 */
public interface FloppyDrive {
    /**
     * Get the IEC device number.
     *
     * @return floppy device number (8-11)
     */
    int getID();

    /**
     * Get the scheduler for this drive's CPU and peripherals.
     *
     * @return drive event scheduler
     */
    EventScheduler getEventScheduler();

    /**
     * Get the drive CPU.
     *
     * @return drive CPU
     */
    MOS6510 getCPU();

    /**
     * Get the CIA used for fast serial transfers, if present.
     *
     * @return drive CIA, or null for drives without a CIA
     */
    default MOS6526 getCIA() {
        return null;
    }

    /**
     * Get the live drive RAM.
     *
     * @return RAM contents
     */
    byte[] getRAM();

    /**
     * Get the live drive ROM, including any installed custom ROM.
     *
     * @return ROM contents
     */
    byte[] getROM();

    /**
     * Get the controller responsible for the mounted disk and head mechanics.
     *
     * @return disk controller
     */
    DriveController getDiskController();

    /**
     * Reset the drive electronics while retaining the mounted disk.
     */
    void reset();

    /**
     * Set whether the drive participates in emulation.
     *
     * @param on drive power on/off
     */
    void setPowerOn(boolean on);

    /**
     * Is the drive powered on?
     *
     * @return true if the drive is on
     */
    boolean isPowerOn();

    /**
     * Get the emulated drive model.
     *
     * @return floppy type
     */
    FloppyType getFloppyType();

    /**
     * Get the mounted disk's file name.
     *
     * @return disk file name, or null when no disk is mounted
     */
    String getDiskName();

    /**
     * Notify the drive of the IEC attention line state.
     *
     * @param asserted true while the active-low ATN line is asserted
     */
    void attention(boolean asserted);

    /**
     * Connect a parallel cable, if the drive supports one.
     *
     * @param cable parallel cable
     */
    default void setParallelCable(IParallelCable cable) {
    }

    /**
     * Signal a parallel cable handshake, if supported by the drive.
     */
    default void parallelPulse() {
    }

    /**
     * Enable or disable a 1541 RAM expansion bank, if supported by the drive.
     *
     * @param bank    expansion bank (0-4)
     * @param enabled true to enable the bank
     */
    default void setRamExpansion(int bank, boolean enabled) {
    }

    /**
     * Install a custom drive ROM, if supported by the drive.
     *
     * @param rom custom ROM, or null to restore the stock ROM
     */
    default void setCustomKernalRom(byte[] rom) {
    }

    /**
     * Get the current drive CPU frequency, including the 1571's clock selection.
     *
     * @return CPU frequency in Hz
     */
    default double getClockFrequency() {
        return 1_000_000;
    }

    /**
     * Get the drive status displayed by the user interface.
     *
     * @return power and activity status
     */
    default C1541.FloppyStatus getStatus() {
        return !isPowerOn() ? C1541.FloppyStatus.OFF
                : getDiskController().isLEDOn() ? C1541.FloppyStatus.LOAD : C1541.FloppyStatus.ON;
    }
}