ac6502 1.2.0 → 1.3.0

package/dist/components/IO/GPIOCard.d.ts

@@ -0,0 +1,105 @@
+import { IO } from '../IO';
+import { GPIOAttachment } from './GPIOAttachments/GPIOAttachment';
+/**
+ * GPIOCard - Emulates the 65C22 VIA (Versatile Interface Adapter)
+ *
+ * The 65C22 VIA provides:
+ * - Two 8-bit bidirectional I/O ports (Port A and Port B)
+ * - Two 16-bit timers with interrupt generation
+ * - Shift register for serial I/O
+ * - Handshaking lines for data transfer
+ */
+export declare class GPIOCard implements IO {
+    private static readonly VIA_ORB;
+    private static readonly VIA_ORA;
+    private static readonly VIA_DDRB;
+    private static readonly VIA_DDRA;
+    private static readonly VIA_T1CL;
+    private static readonly VIA_T1CH;
+    private static readonly VIA_T1LL;
+    private static readonly VIA_T1LH;
+    private static readonly VIA_T2CL;
+    private static readonly VIA_T2CH;
+    private static readonly VIA_SR;
+    private static readonly VIA_ACR;
+    private static readonly VIA_PCR;
+    private static readonly VIA_IFR;
+    private static readonly VIA_IER;
+    private static readonly VIA_ORA_NH;
+    private static readonly IRQ_CA2;
+    private static readonly IRQ_CA1;
+    private static readonly IRQ_SR;
+    private static readonly IRQ_CB2;
+    private static readonly IRQ_CB1;
+    private static readonly IRQ_T2;
+    private static readonly IRQ_T1;
+    private static readonly IRQ_IRQ;
+    private static readonly MAX_ATTACHMENTS_PER_PORT;
+    private regORB;
+    private regORA;
+    private regDDRB;
+    private regDDRA;
+    private regT1C;
+    private regT1L;
+    private regT2C;
+    private regT2L;
+    private regSR;
+    private regACR;
+    private regPCR;
+    private regIFR;
+    private regIER;
+    private CA1;
+    private CA2;
+    private CB1;
+    private CB2;
+    private T1_running;
+    private T2_running;
+    private T1_IRQ_enabled;
+    private T2_IRQ_enabled;
+    private tickCounter;
+    private ticksPerMicrosecond;
+    private portA_attachments;
+    private portB_attachments;
+    private portA_attachmentCount;
+    private portB_attachmentCount;
+    raiseIRQ: () => void;
+    raiseNMI: () => void;
+    constructor();
+    reset(coldStart: boolean): void;
+    read(address: number): number;
+    write(address: number, data: number): void;
+    tick(frequency: number): void;
+    private updateIRQ;
+    private setIRQFlag;
+    private clearIRQFlag;
+    private readPortA;
+    private readPortB;
+    private writePortA;
+    private writePortB;
+    private updateCA2;
+    private updateCB2;
+    private notifyAttachmentsControlLines;
+    private sortAttachmentsByPriority;
+    /**
+     * Attach a GPIO device to Port A
+     * @param attachment - The attachment to add
+     */
+    attachToPortA(attachment: GPIOAttachment): void;
+    /**
+     * Attach a GPIO device to Port B
+     * @param attachment - The attachment to add
+     */
+    attachToPortB(attachment: GPIOAttachment): void;
+    /**
+     * Get a Port A attachment by index
+     * @param index - The attachment index
+     * @returns The attachment or null if not found
+     */
+    getPortAAttachment(index: number): GPIOAttachment | null;
+    /**
+     * Get a Port B attachment by index
+     * @param index - The attachment index
+     * @returns The attachment or null if not found
+     */
+    getPortBAttachment(index: number): GPIOAttachment | null;
+}

package/dist/components/IO/RAMCard.d.ts

@@ -0,0 +1,37 @@
+import { IO } from '../IO';
+/**
+ * RAMCard - Emulates banked RAM with 256KB total capacity
+ *
+ * Provides 256KB of banked RAM divided into 256 banks of 1KB each.
+ * A bank control register at address 0x3FF selects which bank is currently visible.
+ *
+ * Address Map:
+ * $000-$3FE: Bank data (1K window into selected bank)
+ * $3FF: Bank control register (read/write)
+ */
+export declare class RAMCard implements IO {
+    static TOTAL_SIZE: number;
+    static BANK_SIZE: number;
+    static NUM_BANKS: number;
+    static BANK_CONTROL_REGISTER: number;
+    data: number[];
+    currentBank: number;
+    raiseIRQ: () => void;
+    raiseNMI: () => void;
+    /**
+     * Read from RAM or bank control register
+     */
+    read(address: number): number;
+    /**
+     * Write to RAM or bank control register
+     */
+    write(address: number, data: number): void;
+    /**
+     * Tick - no timing behavior for RAM
+     */
+    tick(frequency: number): void;
+    /**
+     * Reset the RAM card
+     */
+    reset(coldStart: boolean): void;
+}

package/dist/components/IO/RTCCard.d.ts

@@ -0,0 +1,107 @@
+import { IO } from '../IO';
+/**
+ * DS1511Y Real-Time Clock IC Emulation
+ *
+ * Register Map (0x00-0x1F):
+ * 0x00: Seconds (BCD, 00-59)
+ * 0x01: Minutes (BCD, 00-59)
+ * 0x02: Hours (BCD, 00-23)
+ * 0x03: Day of Week (1-7, 1=Sunday)
+ * 0x04: Date (BCD, 01-31)
+ * 0x05: Month (BCD, 01-12) + Control bits (EOSC, E32K)
+ * 0x06: Year (BCD, 00-99)
+ * 0x07: Century (BCD, 00-39)
+ * 0x08: Alarm Seconds (BCD, 00-59) + AM1 bit
+ * 0x09: Alarm Minutes (BCD, 00-59) + AM2 bit
+ * 0x0A: Alarm Hours (BCD, 00-23) + AM3 bit
+ * 0x0B: Alarm Day/Date + AM4, DY/DT bits
+ * 0x0C: Watchdog (0.1 Second and 0.01 Second)
+ * 0x0D: Watchdog (0.1 Second and Second)
+ * 0x0E: Control A (BLF1, BLF2, PBS, PAB, TDF, KSF, WDF, IRQF)
+ * 0x0F: Control B (TE, CS, BME, TPE, TIE, KIE, WDE, WDS)
+ * 0x10: RAM Address (Extended RAM Address pointer)
+ * 0x11: Reserved
+ * 0x12: Reserved
+ * 0x13: RAM Data (Extended RAM Data at address pointed to by 0x10)
+ */
+export declare class RTCCard implements IO {
+    raiseIRQ: () => void;
+    raiseNMI: () => void;
+    private userSeconds;
+    private userMinutes;
+    private userHours;
+    private userDayOfWeek;
+    private userDate;
+    private userMonth;
+    private monthControl;
+    private userYear;
+    private userCentury;
+    private internalSeconds;
+    private internalMinutes;
+    private internalHours;
+    private internalDayOfWeek;
+    private internalDate;
+    private internalMonth;
+    private internalYear;
+    private internalCentury;
+    private alarmSeconds;
+    private alarmMinutes;
+    private alarmHours;
+    private alarmDayDate;
+    private watchdog1;
+    private watchdog2;
+    private watchdogCounterCentis;
+    private watchdogCycleCounter;
+    private controlA;
+    private controlB;
+    private ramAddress;
+    private ramData;
+    private cycleCounter;
+    private cpuFrequency;
+    private transferCycleCounter;
+    private pendingUserToInternal;
+    private userSyncNeeded;
+    private lastTEEnabled;
+    constructor();
+    /**
+     * Initialize RTC with current system time
+     */
+    private initializeWithCurrentTime;
+    /**
+     * Convert decimal to BCD (Binary Coded Decimal)
+     */
+    private decimalToBCD;
+    /**
+     * Convert BCD to decimal
+     */
+    private bcdToDecimal;
+    /**
+     * Get the number of days in a month
+     */
+    private getDaysInMonth;
+    /**
+     * Get next day of week
+     */
+    private getNextDayOfWeek;
+    private copyInternalToUser;
+    private copyUserToInternal;
+    private getTransferCyclesRequired;
+    private markUserTimeWrite;
+    /**
+     * Increment time by one second
+     */
+    private incrementTime;
+    /**
+     * Check if alarm should trigger
+     */
+    private checkAlarm;
+    private raiseInterruptIfEnabled;
+    private setKickstartFlag;
+    private decodeWatchdogCentis;
+    private reloadWatchdog;
+    private stepWatchdog;
+    read(address: number): number;
+    write(address: number, data: number): void;
+    tick(frequency: number): void;
+    reset(coldStart: boolean): void;
+}

package/dist/components/IO/SerialCard.d.ts

@@ -0,0 +1,76 @@
+import { IO } from '../IO';
+/**
+ * SerialCard - Emulates a 6551 ACIA (Asynchronous Communications Interface Adapter)
+ *
+ * Register Map:
+ * $00: Data Register (read/write)
+ * $01: Status Register (read) / Programmed Reset (write)
+ * $02: Command Register (write)
+ * $03: Control Register (write)
+ */
+export declare class SerialCard implements IO {
+    raiseIRQ: () => void;
+    raiseNMI: () => void;
+    transmit?: (data: number) => void;
+    private dataRegister;
+    private statusRegister;
+    private commandRegister;
+    private controlRegister;
+    private transmitBuffer;
+    private receiveBuffer;
+    private parityError;
+    private framingError;
+    private overrun;
+    private irqFlag;
+    private echoMode;
+    private cycleCounter;
+    private baudRate;
+    /**
+     * Read from ACIA register
+     */
+    read(address: number): number;
+    /**
+     * Write to ACIA register
+     */
+    write(address: number, data: number): void;
+    /**
+     * Read data from receive buffer
+     */
+    private readData;
+    /**
+     * Write data to transmit buffer
+     */
+    private writeData;
+    /**
+     * Read status register
+     */
+    private readStatus;
+    /**
+     * Write to command register
+     */
+    private writeCommand;
+    /**
+     * Write to control register
+     */
+    private writeControl;
+    /**
+     * Get baud rate from control register code
+     */
+    private getBaudRate;
+    /**
+     * Programmed reset
+     */
+    private programmedReset;
+    /**
+     * Tick - emulate ACIA timing
+     */
+    tick(frequency: number): void;
+    /**
+     * Reset the ACIA
+     */
+    reset(coldStart: boolean): void;
+    /**
+     * Receive data from external source
+     */
+    onData(data: number): void;
+}

package/dist/components/IO/SoundCard.d.ts

@@ -0,0 +1,120 @@
+import { IO } from '../IO';
+/**
+ * MOS 6581 SID (Sound Interface Device) Emulation
+ *
+ * Register Map ($00-$1C):
+ *   Voice 1: $00-$06
+ *   Voice 2: $07-$0D
+ *   Voice 3: $0E-$14
+ *   Filter:  $15-$17
+ *   Volume:  $18
+ *   Paddle:  $19-$1A (read-only)
+ *   OSC 3:   $1B (read-only)
+ *   ENV 3:   $1C (read-only)
+ *
+ * Each voice has:
+ *   Frequency  (16-bit, lo/hi)
+ *   Pulse Width (12-bit, lo/hi)
+ *   Control Register (waveform select, gate, sync, ring mod, test)
+ *   Attack/Decay (4-bit each)
+ *   Sustain/Release (4-bit each)
+ *
+ * Waveforms: Triangle, Sawtooth, Pulse, Noise
+ * Filter: 12-bit cutoff, resonance, low/band/high-pass, voice routing
+ *
+ * Clock rate: ~1 MHz (NTSC: 1,022,727 Hz, PAL: 985,248 Hz)
+ * Output: mono audio samples passed via callback to the host emulator
+ *
+ * Reference: MOS 6581 SID datasheet, reSID by Dag Lem
+ */
+/** Default SID clock rate (NTSC) */
+export declare const SID_CLOCK_NTSC = 1022727;
+export declare const SID_CLOCK_PAL = 985248;
+export declare const enum EnvelopeState {
+    ATTACK = 0,
+    DECAY = 1,
+    SUSTAIN = 2,
+    RELEASE = 3
+}
+export declare class SIDVoice {
+    accumulator: number;
+    frequency: number;
+    pulseWidth: number;
+    control: number;
+    prevGate: boolean;
+    noiseShift: number;
+    waveformOutput: number;
+    envelopeState: EnvelopeState;
+    envelopeLevel: number;
+    envelopeCounter: number;
+    attackRate: number;
+    decayRate: number;
+    sustainLevel: number;
+    releaseRate: number;
+    exponentialCounter: number;
+    exponentialCounterPeriod: number;
+    reset(): void;
+}
+export declare class SoundCard implements IO {
+    raiseIRQ: () => void;
+    raiseNMI: () => void;
+    /** Callback to push audio samples to the host emulator */
+    pushSamples?: (samples: Float32Array) => void;
+    /** Raw register file (write-only from CPU perspective, except reads at $19-$1C) */
+    private registers;
+    /** Three oscillator voices */
+    private voices;
+    /** Filter state */
+    private filterCutoff;
+    private filterResonance;
+    private filterRouting;
+    private filterMode;
+    private masterVolume;
+    /** Filter integrator state (continuous) */
+    private filterLP;
+    private filterBP;
+    private filterHP;
+    /** Cycle accumulator for sample rate conversion */
+    private cycleAccumulator;
+    /** Target audio sample rate */
+    sampleRate: number;
+    /** SID clock rate */
+    sidClock: number;
+    /** Internal sample buffer for pushing to host */
+    private sampleBuffer;
+    private sampleBufferIndex;
+    read(address: number): number;
+    write(address: number, data: number): void;
+    tick(frequency: number): void;
+    reset(coldStart: boolean): void;
+    private updateVoiceRegister;
+    private updateGlobalRegister;
+    private clockOneCycle;
+    private clockOscillator;
+    private generateWaveform;
+    private clockEnvelope;
+    /**
+     * Update the exponential counter period based on current envelope level.
+     * The real SID uses an exponential curve for decay/release by varying
+     * the counter period at specific envelope level thresholds.
+     */
+    private updateExponentialPeriod;
+    private generateSample;
+    /**
+     * Convert the 11-bit filter cutoff register value to a frequency in Hz.
+     * The SID's cutoff mapping is complex and varies between chips.
+     * This approximation covers the usable range (~30 Hz to ~12 kHz).
+     */
+    private computeFilterCutoff;
+    private flushSampleBuffer;
+    /** Get a voice for inspection */
+    getVoice(index: number): SIDVoice;
+    /** Get current register value */
+    getRegister(reg: number): number;
+    /** Get current filter cutoff frequency in Hz */
+    getFilterCutoffHz(): number;
+    /** Get master volume (0-15) */
+    getMasterVolume(): number;
+    /** Get filter routing bitmask */
+    getFilterRouting(): number;
+}

package/dist/components/IO/StorageCard.d.ts

@@ -0,0 +1,74 @@
+import { IO } from '../IO';
+/**
+ * StorageCard - Emulates a Compact Flash card in 8-bit IDE mode
+ *
+ * Emulates a 128MB CF card with ATA-style register interface.
+ * Uses LBA (Logical Block Addressing) for sector access.
+ *
+ * Register Map (address & 0x07):
+ * $00: Data Register (read/write)
+ * $01: Error Register (read) / Feature Register (write)
+ * $02: Sector Count Register (read/write)
+ * $03: LBA0 Register (read/write) - bits 0-7 of LBA
+ * $04: LBA1 Register (read/write) - bits 8-15 of LBA
+ * $05: LBA2 Register (read/write) - bits 16-23 of LBA
+ * $06: LBA3 Register (read/write) - bits 24-27 of LBA + mode bits
+ * $07: Status Register (read) / Command Register (write)
+ *
+ * Supported Commands:
+ * 0x20, 0x21: Read Sector(s)
+ * 0x30, 0x31: Write Sector(s)
+ * 0xC0: Erase Sector
+ * 0xEC: Identify Drive
+ * 0xEF: Set Features (accepted but not implemented)
+ */
+export declare class StorageCard implements IO {
+    private static readonly STORAGE_SIZE;
+    private static readonly SECTOR_SIZE;
+    private static readonly SECTOR_COUNT;
+    private static readonly STATUS_ERR;
+    private static readonly STATUS_DRQ;
+    private static readonly STATUS_RDY;
+    private static readonly ERR_AMNF;
+    private static readonly ERR_ABRT;
+    private static readonly ERR_IDNF;
+    private storage;
+    private identity;
+    private buffer;
+    private bufferIndex;
+    private commandDataSize;
+    private sectorOffset;
+    private error;
+    private feature;
+    private sectorCount;
+    private lba0;
+    private lba1;
+    private lba2;
+    private lba3;
+    private status;
+    private command;
+    private isIdentifying;
+    private isTransferring;
+    raiseIRQ: () => void;
+    raiseNMI: () => void;
+    constructor();
+    read(address: number): number;
+    write(address: number, data: number): void;
+    tick(frequency: number): void;
+    reset(coldStart: boolean): void;
+    private executeCommand;
+    private readBuffer;
+    private writeBuffer;
+    private sectorIndex;
+    private sectorValid;
+    private generateIdentity;
+    /**
+     * Load storage data from a file
+     * If the file doesn't exist, storage remains empty (initialized to 0x00)
+     */
+    loadFromFile(filePath: string): Promise<void>;
+    /**
+     * Save storage data to a file
+     */
+    saveToFile(filePath: string): Promise<void>;
+}

package/dist/components/IO/VideoCard.d.ts

@@ -0,0 +1,141 @@
+import { IO } from '../IO';
+/**
+ * TMS9918 Video Display Processor Emulation
+ *
+ * Port mapping (address bit 0):
+ *   Even address (bit 0 = 0): VRAM data read/write
+ *   Odd  address (bit 0 = 1): Register/address write / status read
+ *
+ * Display modes:
+ *   Graphics I   - 32x24 tiles, 8x8 patterns, 1-of-8 color groups
+ *   Graphics II  - 32x24 tiles, 8x8 patterns, per-row color
+ *   Text         - 40x24 tiles, 6x8 patterns, no sprites
+ *   Multicolor   - 32x24 blocks, 4x4 colored cells
+ *
+ * Output: 256x192 active area centered in a 320x240 RGBA buffer
+ *
+ * Reference: vrEmuTms9918 by Troy Schrapel
+ * https://github.com/visrealm/vrEmuTms9918
+ */
+export declare enum TmsMode {
+    GRAPHICS_I = 0,
+    GRAPHICS_II = 1,
+    TEXT = 2,
+    MULTICOLOR = 3
+}
+export declare enum TmsColor {
+    TRANSPARENT = 0,
+    BLACK = 1,
+    MED_GREEN = 2,
+    LT_GREEN = 3,
+    DK_BLUE = 4,
+    LT_BLUE = 5,
+    DK_RED = 6,
+    CYAN = 7,
+    MED_RED = 8,
+    LT_RED = 9,
+    DK_YELLOW = 10,
+    LT_YELLOW = 11,
+    DK_GREEN = 12,
+    MAGENTA = 13,
+    GREY = 14,
+    WHITE = 15
+}
+export declare class VideoCard implements IO {
+    raiseIRQ: () => void;
+    raiseNMI: () => void;
+    /** Eight write-only registers */
+    private registers;
+    /** Status register (read-only from CPU side) */
+    private status;
+    /** Current VRAM address for CPU access (auto-increments) */
+    private currentAddress;
+    /** Address / register write stage (0 or 1) */
+    private regWriteStage;
+    /** Holds first stage byte written to the control port */
+    private regWriteStage0Value;
+    /** Read-ahead buffer for VRAM reads */
+    private readAheadBuffer;
+    /** Current display mode (derived from registers) */
+    private mode;
+    /** 16 KB Video RAM */
+    private vram;
+    /** Per-pixel sprite collision mask for the current scanline */
+    private rowSpriteBits;
+    /** Temporary scanline pixel buffer (color palette indices) */
+    private scanlinePixels;
+    /** 320 × 240 RGBA output buffer for SDL rendering (front buffer – always a complete frame) */
+    buffer: Buffer;
+    /** Back buffer where scanlines are rendered progressively */
+    private backBuffer;
+    /** True when a complete frame has been copied to the front buffer */
+    frameReady: boolean;
+    /** Cycle accumulator for scanline timing */
+    private cycleAccumulator;
+    /** Current scanline being processed (0 – 261) */
+    private currentScanline;
+    read(address: number): number;
+    write(address: number, data: number): void;
+    tick(frequency: number): void;
+    reset(_coldStart: boolean): void;
+    /**
+     * Write to the control (address / register) port.
+     * Two-stage write:
+     *   Stage 0 – latches the low byte (address LSB or register value)
+     *   Stage 1 – interprets the high byte:
+     *     bit 7 set   → register write  (bits 0-2 = register index)
+     *     bit 7 clear → address set      (bit 6: 0 = read, 1 = write)
+     */
+    private writeAddr;
+    /** Write data to VRAM at the current address (auto-increments) */
+    private writeData;
+    /**
+     * Read the status register.
+     * Clears the status flags and resets the write stage.
+     */
+    private readStatus;
+    /** Read data from VRAM via the read-ahead buffer (auto-increments) */
+    private readData;
+    private updateMode;
+    private nameTableAddr;
+    private colorTableAddr;
+    private patternTableAddr;
+    private spriteAttrTableAddr;
+    private spritePatternTableAddr;
+    /** Backdrop / border color (low nibble of register 7) */
+    private mainBgColor;
+    /** Text-mode foreground (high nibble of register 7, transparent → backdrop) */
+    private mainFgColor;
+    /** Foreground from a color byte (high nibble, transparent → backdrop) */
+    private fgColor;
+    /** Background from a color byte (low nibble, transparent → backdrop) */
+    private bgColor;
+    private spriteSize;
+    private spriteMag;
+    private displayEnabled;
+    private processScanline;
+    private renderScanline;
+    private graphicsIScanLine;
+    private graphicsIIScanLine;
+    private textScanLine;
+    private multicolorScanLine;
+    private outputSprites;
+    /** Fill entire back buffer with the current backdrop color */
+    private fillBackground;
+    /** Write a rendered scanline into the back buffer at the correct position */
+    private writeScanlineToBuffer;
+    /** Read a VDP register value */
+    getRegister(reg: number): number;
+    /** Write a VDP register value directly (bypasses control-port staging) */
+    setRegister(reg: number, value: number): void;
+    /** Read a VRAM byte directly (does not affect read-ahead buffer) */
+    getVramByte(addr: number): number;
+    /** Write a VRAM byte directly (does not affect address pointer) */
+    setVramByte(addr: number, value: number): void;
+    /** Peek at the status register without clearing it */
+    getStatus(): number;
+    /** Get the current display mode */
+    getMode(): TmsMode;
+    /** Get the display-enabled state */
+    isDisplayEnabled(): boolean;
+}

package/dist/components/IO.d.ts

@@ -0,0 +1,8 @@
+export interface IO {
+    raiseIRQ: () => void;
+    raiseNMI: () => void;
+    read(address: number): number;
+    write(address: number, data: number): void;
+    tick(frequency: number): void;
+    reset(coldStart: boolean): void;
+}