@specy/risc-v 0.1.0

package/README.md

@@ -0,0 +1,152 @@
+# RiscV-js
+This is a Typescript implementation of a RISC-V simulator made by compiling the [RARS RISC-V simulator](https://github.com/TheThirdOne/rars) to Javascript. 
+It is part of a family of javascript assembly interpreters/simulators: 
+
+- MIPS: [git repo](https://github.com/Specy/mars),  [npm package](https://www.npmjs.com/package/@specy/mips)
+- RISC-V: [git repo](https://github.com/Specy/rars), [npm package](https://www.npmjs.com/package/@specy/risc-v)
+- X86: [git repo](https://github.com/Specy/x86-js), [npm package](https://www.npmjs.com/package/@specy/x86)
+- M68K: [git repo](https://github.com/Specy/s68k), [npm package](https://www.npmjs.com/package/@specy/s68k)
+
+## Usage 
+
+First, create an instance of the simulator with the `RISCV.makeRiscvFromSource` function.
+
+Before running the simulator, you must assemble and initialize it. You can then step through the program, simulate with breakpoints, or simulate with a limit.
+
+⚠️**WARNING**⚠️ You must have only one instance of the simulator at a time. Memory, registers, and other state may be shared or behave unpredictably with multiple instances.
+
+```typescript
+import {RISCV, JsRiscV, RegisterName, BackStepAction} from '@specy/risc-v';
+const sourceCode = `
+    li t0, 5          # Load immediate value 5 into register t0
+    li t1, 7          # Load immediate value 7 into register t1
+    add t2, t0, t1    # Add t0 and t1, store result in t2
+`;
+
+// RISCV.setIs64Bit(true); // Set to 64-bit mode if needed
+const riscvSimulator: JsRiscV = RISCV.makeRiscVFromSource(sourceCode);
+
+riscvSimulator.assemble();
+riscvSimulator.initialize(true); // Start at 'main'
+
+while (!riscvSimulator.terminated) {
+  riscvSimulator.step();
+}
+// or riscvSimulator.simulate()
+
+const pc = riscvSimulator.programCounter;
+const t2 = riscvSimulator.getRegisterValue('t2');
+
+console.log(`Program Counter: ${pc}`);
+console.log(`t2: ${t2}`);
+
+// Accessing memory:
+const data = riscvSimulator.readMemoryBytes(0xffff0000, 4); // Read 4 bytes from address 0xffff0000
+riscvSimulator.setMemoryBytes(0xffff0000, [0x01, 0x02, 0x03, 0x04]); // Write 4 bytes to address 0xffff0000
+
+// Registering Handlers (for syscalls and other events):
+riscvSimulator.registerHandler("printInt", (value: number) => {
+  console.log("printInt syscall called with:", value);
+});
+
+// Accessing the undo stack:
+const undoStack = riscvSimulator.getUndoStack();
+undoStack.forEach(step => {
+  if (step.action === BackStepAction.REGISTER_RESTORE) {
+    console.log(`Register restored at PC ${step.pc}`);
+  }
+});
+
+
+// Simulating with breakpoints:
+const breakpoints = [0x00400004, 0x00400008]; // Example breakpoint addresses
+riscvSimulator.simulateWithBreakpoints(breakpoints);
+
+//Simulating with a limit
+const limit = 100
+riscvSimulator.simulateWithLimit(limit);
+
+//Simulating with breakpoints and a limit
+riscvSimulator.simulateWithBreakpointsAndLimit(breakpoints, limit);
+
+//Setting Register Values:
+riscvSimulator.setRegisterValue("t0", 42);
+```
+
+## API
+
+### `RISCV` Static Class
+
+Provides static methods to initialize and create simulator instances.
+
+* `RISCV.makeRiscvFromSource(source: string): JsRiscv`
+  Creates a new `JsRiscv` instance from RISC-V assembly source code. This also initializes the underlying RISC-V simulation environment if it hasn't been already.
+* `RISCV.initializeRISCV(): void`
+  Initializes the core RISC-V simulation environment. Called internally by `makeRiscvFromSource`, but can be called explicitly if needed.
+* `RISCV.getInstructionSet(): JsInstruction[]`
+  Returns an array of objects, each describing a supported RISC-V instruction (name, example, description, tokens).
+* `RISCV.setIs64Bit(is64Bit: boolean): void`
+  Sets the simulator to operate in 32-bit or 64-bit mode. This affects the instruction set.
+
+### `JsRiscv` Interface
+
+This interface provides methods to control and interact with a RISC-V simulator instance.
+
+#### Properties
+
+* `canUndo: boolean` (Read-only): True if an undo operation can be performed.
+* `programCounter: number` (Read-only): The current value of the program counter (PC).
+* `stackPointer: number` (Read-only): The current value of the stack pointer (`$sp`).
+* `terminated: boolean` (Read-only): True if the simulation has terminated (e.g., via an exit syscall or error).
+
+#### Methods
+
+* `assemble(): RISCVAssembleResult`: Assembles the program. Returns an object containing a report, error list, and an `hasErrors` flag.
+* `initialize(startAtMain: boolean): void`: Initializes the simulator state for execution. If `startAtMain` is true, execution begins at the `main` label; otherwise, it starts at the first instruction.
+* `step(): boolean`: Executes a single instruction. Returns `true` if the execution is complete (program terminated), `false` otherwise.
+* `undo(): void`: Undoes the last instruction executed, if `canUndo` is true and undo is enabled.
+* `setUndoEnabled(enabled: boolean): void`: Enables or disables the undo feature.
+* `setUndoSize(size: number): void`: Sets the maximum number of steps kept in the undo history. Must be called before assembling.
+* `simulateWithLimit(limit: number): boolean`: Simulates the program for a maximum of `limit` instructions. Returns `true` if execution completes/terminates before the limit, `false` otherwise.
+* `simulateWithBreakpoints(breakpoints: number[]): boolean`: Simulates the program until a breakpoint is reached or the program terminates. `breakpoints` is an array of memory addresses. Returns `true` if execution completes/terminates, `false` if a breakpoint is hit.
+* `simulateWithBreakpointsAndLimit(breakpoints: number[], limit: number): boolean`: Simulates until a breakpoint, limit is reached, or termination. Returns `true` if execution completes/terminates, `false` otherwise.
+* `getRegisterValue(register: RegisterName): number`: Returns the value of the specified register.
+* `setRegisterValue(register: RegisterName, value: number): void`: Sets the value of the specified register.
+* `getRegistersValues(): number[]`: Returns an array of all general-purpose register values. The order might be implementation-defined but usually corresponds to register numbers 0-31.
+* `getConditionFlags(): number[]`: Gets the 8 condition flags (if applicable, typically related to floating-point or custom extensions).
+* `registerHandler<T extends HandlerName>(name: T, handler: (...args: HandlerMap[T]['in']) => HandlerMap[T]['out']): void`: Registers a handler function for a specific event (e.g., syscalls). See `HandlerName` and `HandlerMap` for details.
+* `getUndoStack(): JsBackStep[]`: Returns the undo stack, an array of `JsBackStep` objects representing simulation history.
+* `readMemoryBytes(address: number, length: number): number[]`: Reads `length` bytes from memory starting at `address`. Returns an array of byte values.
+* `setMemoryBytes(address: number, bytes: number[]): void`: Writes an array of `bytes` to memory starting at `address`.
+* `getCurrentStatementIndex(): number`: Returns the index of the current instruction in the list of assembled program statements.
+* `getNextStatement(): JsProgramStatement | null`: Returns the next `JsProgramStatement` to be executed, or `null` if at the end.
+* `getStatementAtAddress(address: number): JsProgramStatement | null`: Gets the program statement at the given memory `address`.
+* `getStatementAtSourceLine(line: number): JsProgramStatement | null`: Gets the program statement corresponding to the original source `line` number.
+* `getCompiledStatements(): JsProgramStatement[]`: Returns an array of all assembled program statements.
+* `getParsedStatements(): JsInstructionToken[]`: Returns an array of tokens from the initial parsing stage.
+* `getTokenizedLines(): RiscvTokenizedLine[]`: Returns an array of lines, each with its source string and corresponding tokens.
+* `getCallStack(): JsRiscvStackFrame[]`: Returns the current call stack as an array of stack frame objects.
+* `getLabelAtAddress(address: number): string | null`: Returns the label name at the given memory `address`, or `null` if no label exists there.
+
+#### Helper Functions (for use with `JsRiscv`)
+
+* `registerHandlers(riscv: JsRiscv, handlers: Partial<HandlerMapFns>): void`: A utility to register multiple handlers at once.
+* `unimplementedHandler(name: HandlerName): (...args: any[]) => any`: Returns a function that throws an error indicating the handler `name` is not implemented. Useful for stubbing handlers.
+
+#### Types
+
+* `RegisterName`: Union type for RISC-V register names (e.g., `'ra'`, `'sp'`, `'a0'`, `'t0'`, etc.).
+* `HandlerName`: Union type of all possible handler names (keys of `HandlerMap`).
+* `HandlerMap`: An object type mapping `HandlerName`s to their expected input argument types (`in`) and return type (`out`). This defines the signature for syscall/event handlers.
+* `HandlerMapFns`: An object type where keys are `HandlerName`s and values are the corresponding handler functions.
+* `DialogType`: Enum for message dialog types (`ERROR_MESSAGE`, `INFORMATION_MESSAGE`, `WARNING_MESSAGE`, `QUESTION_MESSAGE`).
+* `ConfirmResult`: Enum for confirm dialog results (`YES`, `NO`, `CANCEL`).
+* `BackStepAction`: Enum representing types of actions that can be undone (e.g., `MEMORY_RESTORE_WORD`, `REGISTER_RESTORE`).
+* `JsBackStep`: Interface representing an entry in the undo stack, detailing the action, parameters, and PC value.
+* `JsProgramStatement`: Interface representing an assembled instruction, including source line, address, binary/machine/assembly representations.
+* `JsInstructionToken`: Interface representing a token from the assembly source (value, type, source position).
+* `JsInstruction`: Interface describing a RISC-V instruction (name, example, description, token patterns).
+* `RiscvTokenizedLine`: An object containing the original line string and its parsed `JsInstructionToken`s.
+* `RISCVAssembleError`: Interface describing an assembly error (message, line/column, warning status, etc.).
+* `RISCVAssembleResult`: Interface for the result of `assemble()`, containing a report string, list of `RISCVAssembleError`s, and a `hasErrors` boolean.
+* `JsRiscvStackFrame`: Interface describing a frame on the call stack (PC, target address, SP, FP, register snapshot).

package/dist/index.d.mts

@@ -0,0 +1,467 @@
+type JsInstructionToken = {
+    sourceLine: number;
+    sourceColumn: number;
+    originalSourceLine: number;
+    value: string;
+    type: string;
+};
+declare enum StopReason {
+    BREAKPOINT = 0,
+    EXCEPTION = 1,
+    MAX_STEPS = 2,// includes step mode (where maxSteps is 1)
+    NORMAL_TERMINATION = 3,
+    CLIFF_TERMINATION = 4,// run off bottom of program
+    PAUSE = 5,
+    STOP = 6
+}
+declare enum DialogType {
+    ERROR_MESSAGE = 0,
+    INFORMATION_MESSAGE = 1,
+    WARNING_MESSAGE = 2,
+    QUESTION_MESSAGE = 3
+}
+declare enum ConfirmResult {
+    YES = 0,
+    NO = 1,
+    CANCEL = 2
+}
+type HandlerMap = {
+    openFile: {
+        in: [filename: string, flags: number, append: boolean];
+        out: number;
+    };
+    closeFile: {
+        in: [fileDescriptor: number];
+        out: void;
+    };
+    writeFile: {
+        in: [fileDescriptor: number, buffer: number[]];
+        out: void;
+    };
+    readFile: {
+        in: [fileDescriptor: number, destination: number[], length: number];
+        out: number;
+    };
+    confirm: {
+        in: [message: string];
+        out: ConfirmResult;
+    };
+    inputDialog: {
+        in: [message: string];
+        out: string;
+    };
+    outputDialog: {
+        in: [message: string, type: DialogType];
+        out: void;
+    };
+    askDouble: {
+        in: [message: string];
+        out: number;
+    };
+    askFloat: {
+        in: [message: string];
+        out: number;
+    };
+    askInt: {
+        in: [message: string];
+        out: number;
+    };
+    askString: {
+        in: [message: string];
+        out: string;
+    };
+    readDouble: {
+        in: [];
+        out: number;
+    };
+    readFloat: {
+        in: [];
+        out: number;
+    };
+    readInt: {
+        in: [];
+        out: number;
+    };
+    readString: {
+        in: [];
+        out: string;
+    };
+    readChar: {
+        in: [];
+        out: string;
+    };
+    logLine: {
+        in: [message: string];
+        out: void;
+    };
+    log: {
+        in: [message: string];
+        out: void;
+    };
+    printChar: {
+        in: [c: string];
+        out: void;
+    };
+    printDouble: {
+        in: [d: number];
+        out: void;
+    };
+    printFloat: {
+        in: [f: number];
+        out: void;
+    };
+    printInt: {
+        in: [i: number];
+        out: void;
+    };
+    printString: {
+        in: [l: string];
+        out: void;
+    };
+    sleep: {
+        in: [milliseconds: number];
+        out: void;
+    };
+    stdIn: {
+        in: [buffer: number[], length: number];
+        out: void;
+    };
+    stdOut: {
+        in: [buffer: number[]];
+        out: void;
+    };
+};
+type JsInstruction = {
+    name: string;
+    example: string;
+    description: string;
+    tokens: JsInstructionToken[];
+};
+type RiscvTokenizedLine = {
+    line: string;
+    tokens: JsInstructionToken[];
+};
+type RISCVAssembleError = {
+    isWarning: boolean;
+    message: string;
+    macroExpansionHistory: string;
+    filename: string;
+    lineNumber: number;
+    columnNumber: number;
+};
+type RISCVAssembleResult = {
+    report: string;
+    errors: RISCVAssembleError[];
+    hasErrors: boolean;
+};
+declare class RISCV {
+    static makeRiscVFromSource: typeof makeRiscVfromSource;
+    static initializeRISCV: typeof initializeRISCV;
+    static getInstructionSet(): JsInstruction[];
+    static setIs64Bit(is64Bit: boolean): void;
+}
+type JsRiscVStackFrame = {
+    /**
+     * The program counter value at the moment the stack frame was created.
+     */
+    pc: number;
+    /**
+     * The address of the target instruction.
+     */
+    toAddress: number;
+    /**
+     * The stack pointer value at the moment the stack frame was created.
+     */
+    sp: number;
+    /**
+     * The frame pointer value at the moment the stack frame was created.
+     */
+    fp: number;
+    /**
+     * The values of all registers at the moment the stack frame was created.
+     */
+    registers: number[];
+};
+/**
+ * Represents a statement in the assembled program.
+ */
+interface JsProgramStatement {
+    /**
+     * The line number in the original source code.
+     */
+    readonly sourceLine: number;
+    /**
+     * The memory address of the instruction.
+     */
+    readonly address: number;
+    /**
+     * The binary representation of the instruction.
+     */
+    readonly binaryStatement: number;
+    /**
+     * The original source code line.
+     */
+    readonly source: string;
+    /**
+     * The machine code representation of the instruction.
+     */
+    readonly machineStatement: string;
+    /**
+     * The assembly representation of the instruction.
+     */
+    readonly assemblyStatement: string;
+}
+/**
+ * Enum representing the types of "undo" actions.
+ */
+declare enum BackStepAction {
+    MEMORY_RESTORE_RAW_WORD = 0,
+    MEMORY_RESTORE_WORD = 1,
+    MEMORY_RESTORE_HALF = 2,
+    MEMORY_RESTORE_BYTE = 3,
+    REGISTER_RESTORE = 4,
+    PC_RESTORE = 5,
+    COPROC0_REGISTER_RESTORE = 6,
+    COPROC1_REGISTER_RESTORE = 7,
+    COPROC1_CONDITION_CLEAR = 8,
+    COPROC1_CONDITION_SET = 9,
+    DO_NOTHING = 10
+}
+/**
+ * Represents a back step in the simulation undo stack.
+ */
+interface JsBackStep {
+    /**
+     * The action performed (e.g., register write, memory write).
+     */
+    readonly action: BackStepAction;
+    /**
+     * Information about the action
+     */
+    readonly param1: number;
+    /**
+     * Information about the action
+     */
+    readonly param2: number;
+    /**
+     * The program counter value before the action.
+     */
+    readonly pc: number;
+}
+declare enum RISCVRegisters {
+    zero = 0,
+    ra = 1,
+    sp = 2,
+    gp = 3,
+    tp = 4,
+    t0 = 5,
+    t1 = 6,
+    t2 = 7,
+    s0 = 8,
+    s1 = 9,
+    a0 = 10,
+    a1 = 11,
+    a2 = 12,
+    a3 = 13,
+    a4 = 14,
+    a5 = 15,
+    a6 = 16,
+    a7 = 17,
+    s2 = 18,
+    s3 = 19,
+    s4 = 20,
+    s5 = 21,
+    s6 = 22,
+    s7 = 23,
+    s8 = 24,
+    s9 = 25,
+    s10 = 26,
+    s11 = 27,
+    t3 = 28,
+    t4 = 29,
+    t5 = 30,
+    t6 = 31
+}
+type RegisterName = keyof typeof RISCVRegisters;
+declare const RISCV_REGISTERS: RegisterName[];
+type HandlerName = keyof HandlerMap;
+type HandlerMapFns = {
+    [K in HandlerName]: (...args: HandlerMap[K]['in']) => HandlerMap[K]['out'];
+};
+declare function registerHandlers(riscv: JsRiscV, handlers: HandlerMapFns): void;
+declare function unimplementedHandler(name: HandlerName): () => never;
+/**
+ * Interface for interacting with a RISCV simulator.
+ */
+interface JsRiscV {
+    /**
+     * Assembles the program.
+     */
+    assemble(): RISCVAssembleResult;
+    /**
+     * Initializes the simulator.
+     * @param startAtMain If true, starts execution at the 'main' label. Otherwise, starts at the first instruction.
+     */
+    initialize(startAtMain: boolean): void;
+    /**
+     * Gets the current stop reason.
+     */
+    getStopReason(): StopReason;
+    /**
+     * Executes a single instruction.
+     * @returns True if the execution is complete, false otherwise.
+     */
+    step(): StopReason;
+    /**
+     * Gets the 8 condition flags.
+     */
+    getConditionFlags(): number[];
+    /**
+     * Sets the size of the undo stack, must be called before assembling the program.
+     * @param size
+     */
+    setUndoSize(size: number): void;
+    /**
+     * Undoes the last instruction executed.
+     */
+    undo(): void;
+    /**
+     * Gets the statement at the given address.
+     * @param address
+     */
+    getStatementAtAddress(address: number): JsProgramStatement;
+    /**
+     * Gets the statement at the given source line.
+     * @param line
+     */
+    getStatementAtSourceLine(line: number): JsProgramStatement;
+    getTokenizedLines(): RiscvTokenizedLine[];
+    /**
+     * Checks if the simulation can be undone.
+     * @returns True if the simulation can be undone, false otherwise.
+     * */
+    canUndo: boolean;
+    /**
+     * Gets the call stack.
+     * @returns An array of memory addresses representing the call stack.
+     */
+    getCallStack(): JsRiscVStackFrame[];
+    /**
+     * Gets the compiled statements.
+     * @returns An array of `JsProgramStatement` objects representing the compiled program.
+     */
+    getCompiledStatements(): JsProgramStatement[];
+    getParsedStatements(): JsInstructionToken[];
+    /**
+     * Gets the label at the given address.
+     * @param address The memory address.
+     * @returns The label at the given address, or null if no label is found.
+     */
+    getLabelAtAddress(address: number): string | null;
+    /**
+     * Sets whether the undo feature is enabled.
+     * @param enabled True to enable the undo feature, false to disable it.
+     */
+    setUndoEnabled(enabled: boolean): void;
+    /**
+     * Simulates until the stop condition is met. it might be a breakpoint, exception, etc...
+     */
+    simulate(): StopReason;
+    /**
+     * Simulates the program for a limited number of instructions.
+     * @param limit The maximum number of instructions to execute.
+     * @returns True if the execution is complete, false otherwise.
+     */
+    simulateWithLimit(limit: number): StopReason;
+    /**
+     * Simulates the program until a breakpoint is reached.
+     * @param breakpoints An array of memory addresses where the simulation should pause.
+     * @returns True if the execution is complete, false otherwise.
+     */
+    simulateWithBreakpoints(breakpoints: number[]): StopReason;
+    /**
+     * Simulates the program with both breakpoints and a limit.
+     * @param breakpoints An array of memory addresses where the simulation should pause.
+     * @param limit The maximum number of instructions to execute.
+     * @returns True if the execution is complete, false otherwise.
+     */
+    simulateWithBreakpointsAndLimit(breakpoints: number[], limit: number): StopReason;
+    /**
+     * Gets the value of a register.
+     * @param register The name of the register.
+     * @returns The value of the register.
+     */
+    getRegisterValue(register: RegisterName): number;
+    /**
+     * Registers a handler function for a specific event or condition.
+     * @param name The name of the event or condition.
+     * @param handler The handler function to be called when the event occurs. The function signature depends on the event name.
+     */
+    registerHandler<T extends HandlerName>(name: T, handler: (...args: HandlerMap[T]['in']) => HandlerMap[T]['out']): void;
+    /**
+     * Gets the current value of the stack pointer.
+     * @returns The value of the stack pointer.
+     */
+    stackPointer: number;
+    /**
+     * Gets the current value of the program counter.
+     * @returns The value of the program counter.
+     */
+    programCounter: number;
+    /**
+     * Gets the values of all registers.
+     * @returns An array containing the register values. The order of the values is implementation defined.
+     */
+    getRegistersValues(): number[];
+    /**
+     * Gets the undo stack.
+     * @returns An array of `JsBackStep` objects representing the history of the simulation.
+     */
+    getUndoStack(): JsBackStep[];
+    /**
+     * Reads a sequence of bytes from memory.
+     * @param address The starting memory address.
+     * @param length The number of bytes to read.
+     * @returns An array of bytes read from memory.
+     */
+    readMemoryBytes(address: number, length: number): number[];
+    /**
+     * Writes a sequence of bytes to memory.
+     * @param address The starting memory address.
+     * @param bytes An array of bytes to write to memory.
+     */
+    setMemoryBytes(address: number, bytes: number[]): void;
+    /**
+     * Gets the index of the current statement in the assembled program.
+     * @returns The index of the current statement.
+     */
+    getCurrentStatementIndex(): number;
+    /**
+     * Gets the next statement to be executed.
+     * @returns The next `JsProgramStatement`.
+     */
+    getNextStatement(): JsProgramStatement;
+    /**
+     * Sets the value of a register.
+     * @param register The name of the register.
+     * @param value The value to set the register to.
+     */
+    setRegisterValue(register: RegisterName, value: number): void;
+    /**
+     * Checks if the simulation has terminated.
+     * @returns True if the simulation has terminated, false otherwise.
+     */
+    terminated: boolean;
+}
+/**
+ * Creates a new RISCV simulator from the given source code.
+ * @param source The source code to assemble.
+ * @returns A new `JsRiscV` object.
+ */
+declare function makeRiscVfromSource(source: string): JsRiscV;
+/**
+ * Initializes the RISCV simulator.
+ */
+declare function initializeRISCV(): void;
+
+export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, registerHandlers, unimplementedHandler };