@specy/risc-v 2.1.0 → 3.1.0

package/README.md

@@ -9,22 +9,33 @@ It is part of a family of javascript assembly interpreters/simulators:
 
 ## Usage 
 
-First, create an instance of the simulator with the `RISCV.makeRiscvFromSource` function.
+First, create an instance of the simulator with `makeRiscVFromFiles`. Supply a virtual source tree and the path of its entry file. Relative `.include` paths resolve from the file containing the directive, while paths beginning with `/` resolve from the virtual root.
 
 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
-`;
+import {RISCV, makeRiscVFromFiles, JsRiscV, RegisterName, BackStepAction} from '@specy/risc-v';
+
+const files = {
+  'src/main.asm': `
+    .include "lib/math.asm"
+    .text
+    .globl main
+  main:
+    add_values(t2, 5, 7)
+  `,
+  'src/lib/math.asm': `
+    .macro add_values(%result, %left, %right)
+      li %result, %left
+      addi %result, %result, %right
+    .end_macro
+  `,
+} as const;
 
 // RISCV.setIs64Bit(true); // Set to 64-bit mode if needed
-const riscvSimulator: JsRiscV = RISCV.makeRiscVFromSource(sourceCode);
+const riscvSimulator: JsRiscV = makeRiscVFromFiles(files, 'src/main.asm');
 
 riscvSimulator.assemble();
 riscvSimulator.initialize(true); // Start at 'main'
@@ -154,10 +165,10 @@ riscvSimulator.removeMemoryObservers()
 
 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.
+* `makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): JsRiscV`
+  Creates a simulator from a snapshot of a virtual source tree and its entry file. Source paths are canonical, root-relative POSIX paths. The factory is also available as `RISCV.makeRiscVFromFiles` and initializes the simulation environment when needed.
 * `RISCV.initializeRISCV(): void`
-  Initializes the core RISC-V simulation environment. Called internally by `makeRiscvFromSource`, but can be called explicitly if needed.
+  Initializes the core RISC-V simulation environment. Called internally by `makeRiscVFromFiles`, 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`
@@ -199,13 +210,12 @@ This interface provides methods to control and interact with a RISC-V simulator
 * `removeMemoryObserver(handle: number): void`: Removes one registration.
 * `removeMemoryObservers(): void`: Removes every registration.
 * `countMemoryObservers(): number`: The number of live registrations.
-* `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.
+* `getStatementsAtSourceLocation(sourcePath: string, sourceLine: number): JsProgramStatement[]`: Returns every machine statement generated from an original one-based source location, in address order. Pseudo-instructions and macro calls can produce multiple results.
+* `getCompiledStatements(): JsProgramStatement[]`: Returns all machine statements after a successful assembly.
+* `getParsedStatements(): JsProgramStatement[]`: Returns the parsed statements before pseudo-instruction expansion.
+* `getTokenizedLines(): RiscvTokenizedLine[]`: Returns the expanded source stream with each line's path, one-based line number, original source, processed source, and tokens. It is available after tokenization succeeds, including when a later assembly stage fails.
 * `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.
 
@@ -217,6 +227,8 @@ This interface provides methods to control and interact with a RISC-V simulator
 #### Types
 
 * `RegisterName`: Union type for RISC-V register names (e.g., `'ra'`, `'sp'`, `'a0'`, `'t0'`, etc.).
+* `RISCVSourceSet`: A read-only mapping from canonical virtual source paths to source strings.
+* `RISCVSourceLocation`: A source path and one-based source line.
 * `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.
@@ -224,10 +236,10 @@ This interface provides methods to control and interact with a RISC-V simulator
 * `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).
+* `JsProgramStatement`: Interface representing an assembled instruction, including its source path, source line, address, binary/machine/assembly representations, and full original source line.
+* `JsInstructionToken`: Interface representing a token from the assembly source (value, type, and one-based source column).
 * `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.).
+* `RiscvTokenizedLine`: An object containing source identity, original and processed line strings, and parsed `JsInstructionToken`s.
+* `RISCVAssembleError`: Interface describing an assembly diagnostic with its source path, one-based line and column, warning status, and structured macro expansion trace.
 * `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).
+* `JsRiscvStackFrame`: Interface describing a frame on the call stack (PC, target address, SP, FP, register snapshot).

package/dist/index.d.mts

@@ -1,7 +1,6 @@
 type JsInstructionToken = {
-    sourceLine: number;
+    /** One-based column in the processed source line. */
     sourceColumn: number;
-    originalSourceLine: number;
     value: string;
     type: string;
 };
@@ -178,16 +177,30 @@ type JsInstruction = {
     getIsRv64Only: () => boolean;
 };
 type RiscvTokenizedLine = {
-    line: string;
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+    /** Exact line supplied in the source set. */
+    source: string;
+    /** Line after assembler substitutions such as `.eqv`. */
+    processedSource: string;
     tokens: JsInstructionToken[];
 };
+type RISCVSourceLocation = {
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+};
+type RISCVSourceSet = Readonly<Record<string, string>>;
 type RISCVAssembleError = {
     isWarning: boolean;
     message: string;
-    macroExpansionHistory: string;
-    filename: string;
-    lineNumber: number;
-    columnNumber: number;
+    macroExpansionTrace: RISCVSourceLocation[];
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+    /** One-based column in `sourcePath`. Zero only for diagnostics without a source location. */
+    sourceColumn: number;
 };
 type RISCVAssembleResult = {
     report: string;
@@ -198,7 +211,7 @@ type RISCVAssembleResult = {
     hasWarnings: boolean;
 };
 declare class RISCV {
-    static makeRiscVFromSource: typeof makeRiscVfromSource;
+    static makeRiscVFromFiles: typeof makeRiscVFromFiles;
     static initializeRISCV: typeof initializeRISCV;
     static getInstructionSet(): JsInstruction[];
     static setIs64Bit(is64Bit: boolean): void;
@@ -230,9 +243,9 @@ type JsRiscVStackFrame = {
  * Represents a statement in the assembled program.
  */
 interface JsProgramStatement {
-    /**
-     * The line number in the original source code.
-     */
+    /** Canonical path of the original source file. */
+    readonly sourcePath: string;
+    /** The one-based line number in the original source file. */
     readonly sourceLine: number;
     /**
      * The memory address of the instruction.
@@ -269,7 +282,16 @@ declare enum BackStepAction {
     CONTROL_AND_STATUS_REGISTER_RESTORE = 7,
     CONTROL_AND_STATUS_REGISTER_BACKDOOR = 8,
     FLOATING_POINT_REGISTER_RESTORE = 9,
-    DO_NOTHING = 10
+    DO_NOTHING = 10,
+    /**
+     * Undoes one instruction's worth of the `cycle` and `instret` counters. The simulator adds one
+     * to each of them per instruction and nothing else writes them, so a single entry without
+     * parameters covers both.
+     *
+     * Members mirror the core's `BackStepper.Action` by position, because the core reports an
+     * action as that enum's ordinal. Append here; never insert.
+     */
+    CONTROL_AND_STATUS_COUNTERS_DECREMENT = 11
 }
 /**
  * Represents a back step in the simulation undo stack.
@@ -382,11 +404,8 @@ interface JsRiscV {
      * @param address
      */
     getStatementAtAddress(address: number): JsProgramStatement;
-    /**
-     * Gets the statement at the given source line.
-     * @param line
-     */
-    getStatementAtSourceLine(line: number): JsProgramStatement;
+    /** Gets every machine statement generated from an original source location. */
+    getStatementsAtSourceLocation(sourcePath: string, sourceLine: number): JsProgramStatement[];
     getTokenizedLines(): RiscvTokenizedLine[];
     /**
      * Checks if the simulation can be undone.
@@ -403,7 +422,7 @@ interface JsRiscV {
      * @returns An array of `JsProgramStatement` objects representing the compiled program.
      */
     getCompiledStatements(): JsProgramStatement[];
-    getParsedStatements(): JsInstructionToken[];
+    getParsedStatements(): JsProgramStatement[];
     /**
      * Gets the label at the given address.
      * @param address The memory address.
@@ -560,11 +579,6 @@ interface JsRiscV {
      * The number of live registrations, across every `JsRiscV` instance.
      */
     countMemoryObservers(): number;
-    /**
-     * 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`.
@@ -583,15 +597,19 @@ interface JsRiscV {
     terminated: boolean;
 }
 /**
- * Creates a new RISCV simulator from the given source code.
- * @param source The source code to assemble.
+ * Creates a RISC-V simulator from a virtual source tree and its entry file.
+ *
+ * Source paths are canonical, root-relative, case-sensitive POSIX paths. The source set is
+ * snapshotted by this call; only the entry file and files reached through `.include` are assembled.
+ * @param files Source text keyed by canonical source path.
+ * @param entryFile Canonical path of the file from which include expansion starts.
  * @returns A new `JsRiscV` object.
  */
-declare function makeRiscVfromSource(source: string): JsRiscV;
+declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): JsRiscV;
 /**
  * Initializes the RISCV simulator.
  */
 declare function initializeRISCV(): void;
 declare function bigintToHighLow(value: bigint): [high: number, low: number];
 
-export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, registerHandlers, unimplementedHandler };
+export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, makeRiscVFromFiles, registerHandlers, unimplementedHandler };

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 type JsInstructionToken = {
-    sourceLine: number;
+    /** One-based column in the processed source line. */
     sourceColumn: number;
-    originalSourceLine: number;
     value: string;
     type: string;
 };
@@ -178,16 +177,30 @@ type JsInstruction = {
     getIsRv64Only: () => boolean;
 };
 type RiscvTokenizedLine = {
-    line: string;
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+    /** Exact line supplied in the source set. */
+    source: string;
+    /** Line after assembler substitutions such as `.eqv`. */
+    processedSource: string;
     tokens: JsInstructionToken[];
 };
+type RISCVSourceLocation = {
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+};
+type RISCVSourceSet = Readonly<Record<string, string>>;
 type RISCVAssembleError = {
     isWarning: boolean;
     message: string;
-    macroExpansionHistory: string;
-    filename: string;
-    lineNumber: number;
-    columnNumber: number;
+    macroExpansionTrace: RISCVSourceLocation[];
+    sourcePath: string;
+    /** One-based line in `sourcePath`. */
+    sourceLine: number;
+    /** One-based column in `sourcePath`. Zero only for diagnostics without a source location. */
+    sourceColumn: number;
 };
 type RISCVAssembleResult = {
     report: string;
@@ -198,7 +211,7 @@ type RISCVAssembleResult = {
     hasWarnings: boolean;
 };
 declare class RISCV {
-    static makeRiscVFromSource: typeof makeRiscVfromSource;
+    static makeRiscVFromFiles: typeof makeRiscVFromFiles;
     static initializeRISCV: typeof initializeRISCV;
     static getInstructionSet(): JsInstruction[];
     static setIs64Bit(is64Bit: boolean): void;
@@ -230,9 +243,9 @@ type JsRiscVStackFrame = {
  * Represents a statement in the assembled program.
  */
 interface JsProgramStatement {
-    /**
-     * The line number in the original source code.
-     */
+    /** Canonical path of the original source file. */
+    readonly sourcePath: string;
+    /** The one-based line number in the original source file. */
     readonly sourceLine: number;
     /**
      * The memory address of the instruction.
@@ -269,7 +282,16 @@ declare enum BackStepAction {
     CONTROL_AND_STATUS_REGISTER_RESTORE = 7,
     CONTROL_AND_STATUS_REGISTER_BACKDOOR = 8,
     FLOATING_POINT_REGISTER_RESTORE = 9,
-    DO_NOTHING = 10
+    DO_NOTHING = 10,
+    /**
+     * Undoes one instruction's worth of the `cycle` and `instret` counters. The simulator adds one
+     * to each of them per instruction and nothing else writes them, so a single entry without
+     * parameters covers both.
+     *
+     * Members mirror the core's `BackStepper.Action` by position, because the core reports an
+     * action as that enum's ordinal. Append here; never insert.
+     */
+    CONTROL_AND_STATUS_COUNTERS_DECREMENT = 11
 }
 /**
  * Represents a back step in the simulation undo stack.
@@ -382,11 +404,8 @@ interface JsRiscV {
      * @param address
      */
     getStatementAtAddress(address: number): JsProgramStatement;
-    /**
-     * Gets the statement at the given source line.
-     * @param line
-     */
-    getStatementAtSourceLine(line: number): JsProgramStatement;
+    /** Gets every machine statement generated from an original source location. */
+    getStatementsAtSourceLocation(sourcePath: string, sourceLine: number): JsProgramStatement[];
     getTokenizedLines(): RiscvTokenizedLine[];
     /**
      * Checks if the simulation can be undone.
@@ -403,7 +422,7 @@ interface JsRiscV {
      * @returns An array of `JsProgramStatement` objects representing the compiled program.
      */
     getCompiledStatements(): JsProgramStatement[];
-    getParsedStatements(): JsInstructionToken[];
+    getParsedStatements(): JsProgramStatement[];
     /**
      * Gets the label at the given address.
      * @param address The memory address.
@@ -560,11 +579,6 @@ interface JsRiscV {
      * The number of live registrations, across every `JsRiscV` instance.
      */
     countMemoryObservers(): number;
-    /**
-     * 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`.
@@ -583,15 +597,19 @@ interface JsRiscV {
     terminated: boolean;
 }
 /**
- * Creates a new RISCV simulator from the given source code.
- * @param source The source code to assemble.
+ * Creates a RISC-V simulator from a virtual source tree and its entry file.
+ *
+ * Source paths are canonical, root-relative, case-sensitive POSIX paths. The source set is
+ * snapshotted by this call; only the entry file and files reached through `.include` are assembled.
+ * @param files Source text keyed by canonical source path.
+ * @param entryFile Canonical path of the file from which include expansion starts.
  * @returns A new `JsRiscV` object.
  */
-declare function makeRiscVfromSource(source: string): JsRiscV;
+declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): JsRiscV;
 /**
  * Initializes the RISCV simulator.
  */
 declare function initializeRISCV(): void;
 declare function bigintToHighLow(value: bigint): [high: number, low: number];
 
-export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, registerHandlers, unimplementedHandler };
+export { BackStepAction, ConfirmResult, DialogType, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, makeRiscVFromFiles, registerHandlers, unimplementedHandler };