Ninja Pirate Marksman

    thumbulator.ts
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.1 • Public • Published

    What is it?

    This is a customized version of David Welch's thumbulator, an emulator targetting the thumb subset of the ARM instruction set.

    The thumbulator itself has been transpiled from C using emscripten, the glue code around it is written in Typescript. As such, the module can be directly used with TS, no external typings required (of course, it works in plain JS, too).

    Installation

    The package is available on NPM

    $ npm install thumbulator.ts
    

    How to use it?

    The package has a single default export: the Thumbulator class. In order to instantiate, you need to pass a bus object that implements reading and writing from the bus.

    import Thumbulator from 'thumbulator.ts';
     
    const thumbulator = new Thumbulator({
        read16: (address: number): number => {
            // read a 16 bit word at the given address
        },
        read32: (address: number): number => {
            // optional; read a 32 bit word (will use read16 instead if not defined)
        },
        write16: (address: number, value: number) => {
            // write a 16 bit word to the given address
        },
        write32: (address: number, value: number) => {
            // optional; write a 32 bit word (will use write16 if not defined)
        }
    }, {
        printer: (line: string): void => {
            // optional; override logging (uses console.log and console.error by default)
        },
        stopAddress: number, // optional; the emulation stops with TrapReason.stop when
                             // execution reaches this address
        trapOnInstructionFetch: (address: number): number => {
            // optional; return a nonzero trap code to trap and stop the emulation on
            // instruction fetch. This is evaluated only if stopAddress is not set.
        },
        trapOnBx32: (instructionAddress: number, targetAddress: number): number => {
            // optional; handle BX out of thumb mode.
        }
    });

    The second options object is optional

    After instantiation, call init and wait for the promise to resolve in order to make sure that the emscripten runtime has initialized.

    await thumbulator.init();

    Running the emulation

    const trapReason: Thumbulator.TrapReason = thumbulator.run(cycles);

    Run the emulation for cycles instructions or until a trap occurs. See the source for trap codes.

    Aborting the running emulator (during bus access)

    thumbulator.abort();

    This will cause run to return immediatelly with TrapReason.abort (10).

    Reset the emulation

    thumbulator.reset();

    Read and write registers

    const value = thumbulator.readRegister(r);
    thumbulator.writeRegister(r, value);

    These will read and write registers.

    Verbose debug output

    thumbulator.enableDebug(true);

    This will cause the emulator to enter verbose mode and dump disassembly

    Why?

    This module is used in the 6502.ts VCS emulator for emulating the ARM SOC in the Harmony cartridge.

    License

    Both David Welch's original code and the glue around it are licensed under the MIT license.

    Keywords

    none

    Install

    npm i thumbulator.ts

    DownloadsWeekly Downloads

    1

    Version

    0.3.1

    License

    MIT

    Unpacked Size

    115 kB

    Total Files

    6

    Last publish

    Collaborators

    • dirtyhairy