memory.js

/**
 * @fileoverview Simulates different types of memory (eg, NONE, ROM, RAM)
 * @author <a href="mailto:Jeff@pcjs.org">Jeff Parsons</a>
 * @copyright © 2012-2020 Jeff Parsons
 * @license MIT
 *
 * This file is part of PCjs, a computer emulation software project at <https://www.pcjs.org>.
 */

"use strict";

/**
 * @typedef {Config} MemoryConfig
 * @property {number} [addr]
 * @property {number} size
 * @property {number} [type]
 * @property {boolean} [littleEndian]
 * @property {Array.<number>|string} [values]
 */

/**
 * @class {Memory}
 * @unrestricted
 * @property {number} [addr]
 * @property {number} size
 * @property {number} type
 * @property {Bus} bus
 * @property {number} dataWidth
 * @property {number} dataLimit
 * @property {number} pairLimit
 * @property {boolean} littleEndian
 * @property {ArrayBuffer|null} buffer
 * @property {DataView|null} dataView
 * @property {Array.<number>|null} values
 * @property {Array.<Uint16>|null} valuePairs
 * @property {Array.<Int32>|null} valueQuads
 * @property {boolean} fDirty
 * @property {number} nReadTraps
 * @property {number} nWriteTraps
 * @property {function(number)|null} readDataOrig
 * @property {function(number,number)|null} writeDataOrig
 * @property {function(number)|null} readPairOrig
 * @property {function(number,number)|null} writePairOrig
 * @property {function((number|undefined),number,number)|null} readTrap
 * @property {function((number|undefined),number,number)|null} writeTrap
 */
class Memory extends Device {
    /**
     * Memory(idMachine, idDevice, config)
     *
     * @this {Memory}
     * @param {string} idMachine
     * @param {string} idDevice
     * @param {MemoryConfig} [config]
     */
    constructor(idMachine, idDevice, config)
    {
        super(idMachine, idDevice, config);

        this.addr = this.config['addr'];
        this.size = this.config['size'];
        this.type = this.config['type'] || Memory.TYPE.NONE;

        /*
         * If no Bus ID was provided, then we fallback to the default Bus.
         */
        let idBus = this.config['bus'];
        this.bus = /** @type {Bus} */ (idBus? this.findDevice(idBus) : this.findDeviceByClass(idBus = "Bus"));
        if (!this.bus) throw new Error(this.sprintf("unable to find bus '%s'", idBus));

        this.dataWidth = this.bus.dataWidth;
        this.dataLimit = Math.pow(2, this.dataWidth) - 1;
        this.pairLimit = Math.pow(2, this.dataWidth * 2) - 1;

        this.fDirty = this.fUseArrayBuffer = false;
        this.littleEndian = this.bus.littleEndian !== false;
        this.buffer = this.dataView = null
        this.values = this.valuePairs = this.valueQuads = null;

        let readValue = this.readValue;
        let writeValue = this.writeValue;
        let readPair = this.littleEndian? this.readDynamicPairLE : this.readDynamicPairBE;
        let writePair = this.littleEndian? this.writeDynamicPairLE : this.writeDynamicPairBE;

        if (this.bus.type == Bus.TYPE.STATIC) {
            writeValue = this.writeValueDirty;
            readPair = this.littleEndian? this.readValuePairLE : this.readValuePairBE;
            writePair = this.writeValuePairDirty;
            if (this.dataWidth == 8 && this.getMachineConfig('ArrayBuffer') !== false) {
                this.fUseArrayBuffer = true;
                readPair = this.littleEndian == LITTLE_ENDIAN? this.readValuePair16 : this.readValuePair16SE;
            }
        }

        switch(this.type) {
        case Memory.TYPE.NONE:
            this.readData = this.readNone;
            this.writeData = this.writeNone;
            this.readPair = this.readNonePair;
            this.writePair = this.writeNonePair;
            break;
        case Memory.TYPE.READONLY:
            this.readData = readValue;
            this.writeData = this.writeNone;
            this.readPair = readPair;
            this.writePair = this.writeNone;
            break;
        case Memory.TYPE.READWRITE:
            this.readData = readValue;
            this.writeData = writeValue;
            this.readPair = readPair;
            this.writePair = writePair;
            break;
        default:
            this.assert(false, "unsupported memory type: %d", this.type);
            break;
        }

        /*
         * Additional block properties used for trapping reads/writes
         */
        this.nReadTraps = this.nWriteTraps = 0;
        this.readTrap = this.writeTrap = null;
        this.readDataOrig = this.writeDataOrig = null;
        this.readPairOrig = this.writePairOrig = null;

        this.getValues(this.config['values']);
        this.initValues();
    }

    /**
     * getValues(values)
     *
     * @this {Memory}
     * @param {Array.<number>|string|undefined} values
     */
    getValues(values)
    {
        if (typeof values == "string") {
            let memory = this;
            this.setReady(false);
            this.getResource(values, function onLoadValues(sURL, sResource, readyState, nErrorCode) {
                if (readyState == 4) {
                    if (!nErrorCode && sResource) {
                        try {
                            let json = JSON.parse(sResource);
                            memory.getValues(json.values);
                        } catch(err) {
                            memory.printf("error (%s) parsing resource: %s\n", err.message, sURL);
                        }
                        memory.setReady(true);
                    }
                    else {
                        memory.printf("error (%d) loading resource: %s\n", nErrorCode, sURL);
                    }
                }
            });
            return;
        }
        this.config['values'] = values;
    }

    /**
     * initValues(values)
     *
     * @this {Memory}
     * @param {Array.<number>} [values]
     */
    initValues(values)
    {
        if (this.type > Memory.TYPE.NONE) {
            if (this.fUseArrayBuffer) {
                this.buffer = new ArrayBuffer(this.size);
                this.dataView = new DataView(this.buffer, 0, this.size);
                /*
                 * If littleEndian is true, we can use valuePairs[] and valueQuads[] directly; well, we can use
                 * them whenever the offset is a multiple of 1, 2 or 4, respectively.  Otherwise, we must fallback
                 * to dv.getUint8()/dv.setUint8(), dv.getUint16()/dv.setUint16() and dv.getInt32()/dv.setInt32().
                 */
                this.values = new Uint8Array(this.buffer, 0, this.size);
                this.valuePairs = new Uint16Array(this.buffer, 0, this.size >> 1);
                this.valueQuads = new Int32Array(this.buffer, 0, this.size >> 2);
            }
            else {
                /*
                 * TODO: I used to call fill(this.dataLimit), but is there really any reason to do that?
                 */
                this.values = new Array(this.size).fill(0);
            }
            if (values) {
                this.assert(this.values.length == values.length);
                for (let i = 0; i < values.length; i++) {
                    this.values[i] = values[i];
                }
            }
        }
    }

    /**
     * onReset()
     *
     * Called by the Bus device to provide notification of a reset event.
     *
     * Originally called by the CPU (eg, TMS1500) onReset() handler.  There was no need for this handler
     * until we added the mini-debugger's ability to edit ROM locations via setData().  So this gives the
     * user the ability to revert back to the original ROM if they want to undo any modifications.
     *
     * NOTE: Machines probably don't (and shouldn't) depend on the initial memory contents being zero,
     * but zeroing doesn't hurt, and when saving memory blocks in a compressed format (eg, RLE), this will
     * help them compress.
     *
     * @this {Memory}
     */
    onReset()
    {
        if (this.config['values']) {
            this.bus.initBlocks(this.addr, this.size, this.config['values']);
        } else {
            if (this.type & Memory.TYPE.READWRITE) {
                if (this.values) this.values.fill(0);
            }
        }
    }

    /**
     * isDirty()
     *
     * Returns true if the block is dirty; the block is marked clean in the process, and the write
     * handlers are switched to those responsible for marking the block dirty.
     *
     * @this {Memory}
     * @returns {boolean}
     */
    isDirty()
    {
        if (this.fDirty) {
            this.fDirty = false;
            if (this.bus.type == Bus.TYPE.STATIC) {
                if (!this.nWriteTraps) {
                    this.writeData = this.writeValueDirty;
                    this.writePair = this.writeValuePairDirty;
                } else {
                    this.writeDataOrig = this.writeValueDirty;
                    this.writePairOrig = this.writeValuePairDirty;
                }
            }
            return true;
        }
        return false;
    }

    /**
     * readNone(offset)
     *
     * @this {Memory}
     * @param {number} offset
     * @returns {number}
     */
    readNone(offset)
    {
        return this.dataLimit;
    }

    /**
     * readNonePair(offset)
     *
     * @this {Memory}
     * @param {number} offset
     * @returns {number}
     */
    readNonePair(offset)
    {
        if (this.littleEndian) {
            return this.readNone(offset) | (this.readNone(offset + 1) << this.dataWidth);
        } else {
            return this.readNone(offset + 1) | (this.readNone(offset) << this.dataWidth);
        }
    }

    /**
     * readDirect(offset)
     *
     * Some Memory devices (eg, ROM) may override readValue() but never readDirect().
     *
     * @this {Memory}
     * @param {number} offset
     * @returns {number}
     */
    readDirect(offset)
    {
        if (this.values) {
            return this.values[offset];
        }
        return 0;
    }

    /**
     * readValue(offset)
     *
     * @this {Memory}
     * @param {number} offset
     * @returns {number}
     */
    readValue(offset)
    {
        return this.values[offset];
    }

    /**
     * readValuePairBE(offset)
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset)
     * @returns {number}
     */
    readValuePairBE(offset)
    {
        return this.values[offset + 1] | (this.values[offset] << this.dataWidth);
    }

    /**
     * readValuePairLE(offset)
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset)
     * @returns {number}
     */
    readValuePairLE(offset)
    {
        return this.values[offset] | (this.values[offset + 1] << this.dataWidth);
    }

    /**
     * readValuePair16(offset)
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset)
     * @returns {number}
     */
    readValuePair16(offset)
    {
        return this.valuePairs[offset >>> 1];
    }

    /**
     * readValuePair16SE(offset)
     *
     * This function is neither big-endian (BE) or little-endian (LE), but rather "swap-endian" (SE), which
     * means there's a mismatch between our emulated machine and the host machine, so we call the appropriate
     * DataView function with the desired littleEndian setting.
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset)
     * @returns {number}
     */
    readValuePair16SE(offset)
    {
        return this.dataView.getUint16(offset, this.littleEndian);
    }

    /**
     * readDynamicPairBE(offset)
     *
     * This slow version is used with a dynamic (eg, I/O) bus only, and it must also accomodate odd offsets.
     *
     * @this {Memory}
     * @param {number} offset
     * @returns {number}
     */
    readDynamicPairBE(offset)
    {
        this.assert((offset < this.size - 1), "readDynamicPairBE(%#0x) exceeds block size", this.addr + offset);
        return this.readValue(offset + 1) | (this.readValue(offset) << this.dataWidth);
    }

    /**
     * readDynamicPairLE(offset)
     *
     * This slow version is used with a dynamic (eg, I/O) bus only, and it must also accomodate odd offsets.
     *
     * @this {Memory}
     * @param {number} offset
     * @returns {number}
     */
    readDynamicPairLE(offset)
    {
        this.assert((offset < this.size - 1), "readDynamicPairLE(%#0x) exceeds block size", this.addr + offset);
        return this.readValue(offset) | (this.readValue(offset + 1) << this.dataWidth);
    }

    /**
     * writeNone(offset, value)
     *
     * @this {Memory}
     * @param {number} offset
     * @param {number} value
     */
    writeNone(offset, value)
    {
    }

    /**
     * writeNonePair(offset, value)
     *
     * @this {Memory}
     * @param {number} offset
     * @param {number} value
     */
    writeNonePair(offset, value)
    {
        if (this.littleEndian) {
            this.writeNone(offset, value & this.dataLimit);
            this.writeNone(offset + 1, value >> this.dataWidth);
        } else {
            this.writeNone(offset, value >> this.dataWidth);
            this.writeNone(offset + 1, value & this.dataLimit);
        }
    }

    /**
     * writeDirect(offset, value)
     *
     * Some Memory devices (eg, ROM) may override writeValue() but never writeDirect().
     *
     * @this {Memory}
     * @param {number} offset
     * @param {number} value
     */
    writeDirect(offset, value)
    {
        this.assert(!(value & ~this.dataLimit), "writeDirect(%#0x,%#0x) exceeds data width", this.addr + offset, value);
        if (this.values) this.values[offset] = value;
    }

    /**
     * writeValue(offset, value)
     *
     * @this {Memory}
     * @param {number} offset
     * @param {number} value
     */
    writeValue(offset, value)
    {
        this.assert(!(value & ~this.dataLimit), "writeValue(%#0x,%#0x) exceeds data width", this.addr + offset, value);
        this.values[offset] = value;
    }

    /**
     * writeValueDirty(offset, value)
     *
     * @this {Memory}
     * @param {number} offset
     * @param {number} value
     */
    writeValueDirty(offset, value)
    {
        this.assert(!(value & ~this.dataLimit), "writeValueDirty(%#0x,%#0x) exceeds data width", this.addr + offset, value);
        this.values[offset] = value;
        this.fDirty = true;
        if (!this.nWriteTraps) {
            this.writeData = this.writeValue;
        } else {
            this.writeDataOrig = this.writeValue;
        }
    }

    /**
     * writeValuePairBE(offset, value)
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset)
     * @param {number} value
     */
    writeValuePairBE(offset, value)
    {
        this.assert(!(value & ~this.pairLimit), "writeValuePairBE(%#0x,%#0x) exceeds data width", this.addr + offset, value);
        this.values[offset] = value >> this.dataWidth;
        this.values[offset + 1] = value & this.dataLimit;
    }

    /**
     * writeValuePairLE(offset, value)
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset)
     * @param {number} value
     */
    writeValuePairLE(offset, value)
    {
        this.assert(!(value & ~this.pairLimit), "writeValuePairLE(%#0x,%#0x) exceeds data width", this.addr + offset, value);
        this.values[offset] = value & this.dataLimit;
        this.values[offset + 1] = value >> this.dataWidth;
    }

    /**
     * writeValuePair16(offset, value)
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset)
     * @param {number} value
     */
    writeValuePair16(offset, value)
    {
        let off = offset >>> 1;
        this.assert(!(value & ~this.pairLimit), "writeValuePair16(%#0x,%#0x) exceeds data width", this.addr + offset, value);
        this.valuePairs[off] = value;
    }

    /**
     * writeValuePair16SE(offset, value)
     *
     * This function is neither big-endian (BE) or little-endian (LE), but rather "swap-endian" (SE), which
     * means there's a mismatch between our emulated machine and the host machine, so we call the appropriate
     * DataView function with the desired littleEndian setting.
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset)
     * @param {number} value
     */
    writeValuePair16SE(offset, value)
    {
        this.assert(!(value & ~this.pairLimit), "writeValuePair16SE(%#0x,%#0x) exceeds data width", this.addr + offset, value);
        this.dataView.setUint16(offset, value, this.littleEndian);
    }

    /**
     * writeDynamicPairBE(offset, value)
     *
     * This slow version is used with a dynamic (eg, I/O) bus only, and it must also accomodate odd offsets.
     *
     * @this {Memory}
     * @param {number} offset
     * @param {number} value
     */
    writeDynamicPairBE(offset, value)
    {
        this.assert((offset < this.size - 1), "writeDynamicPairBE(%#0x,%#0x) exceeds block size", this.addr + offset, value);
        this.writeValue(offset, value >> this.dataWidth);
        this.writeValue(offset + 1, value & this.dataLimit);
    }

    /**
     * writeDynamicPairLE(offset, value)
     *
     * This slow version is used with a dynamic (eg, I/O) bus only, and it must also accomodate odd offsets.
     *
     * @this {Memory}
     * @param {number} offset
     * @param {number} value
     */
    writeDynamicPairLE(offset, value)
    {
        this.assert((offset < this.size - 1), "writeDynamicPairLE(%#0x,%#0x) exceeds block size", this.addr + offset, value);
        this.writeValue(offset, value & this.dataLimit);
        this.writeValue(offset + 1, value >> this.dataWidth);
    }

    /**
     * writeValuePairDirty(offset, value)
     *
     * @this {Memory}
     * @param {number} offset (must be an even block offset, because we will halve it to obtain a pair offset)
     * @param {number} value
     */
    writeValuePairDirty(offset, value)
    {
        if (!this.buffer) {
            if (this.littleEndian) {
                this.writeValuePairLE(offset, value);
                if (!this.nWriteTraps) {
                    this.writePair = this.writeValuePairLE;
                } else {
                    this.writePairOrig = this.writeValuePairLE;
                }
            } else {
                this.writeValuePairBE(offset, value);
                if (!this.nWriteTraps) {
                    this.writePair = this.writeValuePairBE;
                } else {
                    this.writePairOrig = this.writeValuePairBE;
                }
            }
        } else {
            if (this.littleEndian == LITTLE_ENDIAN) {
                this.writeValuePair16(offset, value);
                if (!this.nWriteTraps) {
                    this.writePair = this.writeValuePair16;
                } else {
                    this.writePairOrig = this.writeValuePair16;
                }
            } else {
                this.writeValuePair16SE(offset, value);
                if (!this.nWriteTraps) {
                    this.writePair = this.writeValuePair16SE;
                } else {
                    this.writePairOrig = this.writeValuePair16SE;
                }
            }
        }
    }

    /**
     * trapRead(func)
     *
     * I've decided to call the trap handler AFTER reading the value, so that we can pass the value
     * along with the address; for example, the Debugger might find that useful for its history buffer.
     *
     * Note that for blocks of type NONE, the base will be undefined, so the function will not see the
     * original address, only the block offset.
     *
     * @this {Memory}
     * @param {function((number|undefined), number, number)} func (receives the base address, offset, and value read)
     * @returns {boolean} true if trap successful, false if unsupported or already trapped by another function
     */
    trapRead(func)
    {
        if (!this.nReadTraps) {
            let block = this;
            this.nReadTraps++;
            this.readTrap = func;
            this.readDataOrig = this.readData;
            this.readPairOrig = this.readPair;
            this.readData = function readDataTrap(offset) {
                let value = block.readDataOrig(offset);
                block.readTrap(block.addr, offset, value);
                return value;
            };
            this.readPair = function readPairTrap(offset) {
                let value = block.readPairOrig(offset);
                block.readTrap(block.addr, offset, value);
                block.readTrap(block.addr, offset + 1, value);
                return value;
            };
            return true;
        }
        if (this.readTrap == func) {
            this.nReadTraps++;
            return true;
        }
        return false;
    }

    /**
     * trapWrite(func)
     *
     * Note that for blocks of type NONE, the base will be undefined, so the function will not see the
     * original address, only the block offset.
     *
     * @this {Memory}
     * @param {function((number|undefined), number, number)} func (receives the base address, offset, and value written)
     * @returns {boolean} true if trap successful, false if unsupported or already trapped by another function
     */
    trapWrite(func)
    {
        if (!this.nWriteTraps) {
            let block = this;
            this.nWriteTraps++;
            this.writeTrap = func;
            this.writeDataOrig = this.writeData;
            this.writePairOrig = this.writePair;
            this.writeData = function writeDataTrap(offset, value) {
                block.writeTrap(block.addr, offset, value);
                block.writeDataOrig(offset, value);
            };
            this.writePair = function writePairTrap(offset, value) {
                block.writeTrap(block.addr, offset, value);
                block.writeTrap(block.addr, offset + 1, value);
                block.writePairOrig(offset, value);
            };
            return true;
        }
        if (this.writeTrap == func) {
            this.nWriteTraps++;
            return true
        }
        return false;
    }

    /**
     * untrapRead(func)
     *
     * @this {Memory}
     * @param {function((number|undefined), number, number)} func (receives the base address, offset, and value read)
     * @returns {boolean} true if untrap successful, false if no (or another) trap was in effect
     */
    untrapRead(func)
    {
        if (this.nReadTraps && this.readTrap == func) {
            if (!--this.nReadTraps) {
                this.readData = this.readDataOrig;
                this.readPair = this.readPairOrig;
                this.readDataOrig = this.readPairOrig = this.readTrap = null;
            }
            this.assert(this.nReadTraps >= 0);
            return true;
        }
        return false;
    }

    /**
     * untrapWrite(func)
     *
     * @this {Memory}
     * @param {function((number|undefined), number, number)} func (receives the base address, offset, and value written)
     * @returns {boolean} true if untrap successful, false if no (or another) trap was in effect
     */
    untrapWrite(func)
    {
        if (this.nWriteTraps && this.writeTrap == func) {
            if (!--this.nWriteTraps) {
                this.writeData = this.writeDataOrig;
                this.writePair = this.writePairOrig;
                this.writeDataOrig = this.writePairOrig = this.writeTrap = null;
            }
            this.assert(this.nWriteTraps >= 0);
            return true;
        }
        return false;
    }

    /**
     * loadState(state)
     *
     * Memory and Ports states are loaded by the Bus onLoad() handler, which calls our loadState() handler.
     *
     * @this {Memory}
     * @param {Array} state
     * @returns {boolean}
     */
    loadState(state)
    {
        let idDevice = state.shift();
        if (this.idDevice == idDevice) {
            this.fDirty = state.shift();
            state.shift();      // formerly fDirtyEver, now unused
            let values = state.shift();
            if (values) this.initValues(this.decompress(values, this.size));
            return true;
        }
        return false;
    }

    /**
     * saveState(state)
     *
     * Memory and Ports states are saved by the Bus onSave() handler, which calls our saveState() handler.
     *
     * @this {Memory}
     * @param {Array} state
     */
    saveState(state)
    {
        state.push(this.idDevice);
        state.push(this.fDirty);
        state.push(false);      // formerly fDirtyEver, now unused
        state.push(this.values? this.compress(this.values) : this.values);
    }
}

/*
 * Memory block types use discrete bits so that enumBlocks() can be passed a set of combined types,
 * by OR'ing the desired types together.
 */
Memory.TYPE = {
    NONE:               0x01,
    READONLY:           0x02,
    READWRITE:          0x04,
    /*
     * The rest are not discrete memory types, but rather sets of types that are handy for enumBlocks().
     */
    READABLE:           0x0E,
    WRITABLE:           0x0C
};

Defs.CLASSES["Memory"] = Memory;