@specy/risc-v 3.6.2 → 3.7.0

package/README.md

@@ -13,6 +13,16 @@ First, create an instance of the simulator with `makeRiscVFromFiles`. Supply a v
 
 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.
 
+The optional third factory argument selects the assembly profile:
+
+```typescript
+const core = makeRiscVFromFiles(files, 'main.s', { assemblerProfile: 'gnu-compiler-v1' });
+```
+
+Omission selects `rars`. `RISCV.assemblerProfiles` lists supported profiles; every present invalid profile throws. GNU compiler v1 provides independent named sections, explicit data alignment, exact eight-byte data, byte-valued string escapes, bounded expressions/aliases, numeric labels, and absolute/PC-relative address fixups. It uses fixed instruction expansions and rejects unsupported directives, ISA attributes, relocations and unresolved runtime helpers. Units link with ld semantics: global and weak symbols (an undefined weak reference is zero), COMDAT groups (the first copy is kept), and `.init_array`/`.fini_array` with ld-provided `__init_array_start`/`__init_array_end` bounds. Global labels enter the global symbol table, so the start label finds them. It does not load or link ELF, compressed/vector instructions, TLS or a standard library. RARS retains its existing educational syntax and macros.
+
+`getAddressOfLabel(name)` returns a defined label/alias address after successful assembly, or `-1` when absent. Profile state is per program; width, memory and execution state retain the existing single-instance constraint.
+
 ⚠️**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

package/dist/index.d.mts

@@ -1,3 +1,43 @@
+type AssemblerProfile = 'rars' | 'gnu-compiler-v1';
+/**
+ * GNU compiler assembly members and the index naming the member that defines each global. A Build
+ * pulls a member only to resolve a global the program uses and does not define, as ld pulls members
+ * out of an archive, and keeps pulling for the globals those members use in turn. Members are always
+ * assembled with the `gnu-compiler-v1` profile, whatever profile the program uses, and their paths
+ * never meet the program's Files.
+ */
+type RuntimeLibrary = {
+    /** Canonical member path to its source. */
+    members: Record<string, string>;
+    /** Global symbol to the path of the member defining it. */
+    index: Record<string, string>;
+    /**
+     * Globals the library supplies even to a weak reference, which otherwise pulls no member: GCC
+     * refers to `__cxa_pure_virtual` weakly from every abstract class's vtable.
+     */
+    resolveWeak?: string[];
+};
+type AssemblyOptions = {
+    assemblerProfile?: AssemblerProfile;
+    /**
+     * The global execution starts at instead of `main`. The link must define it, and with a library
+     * it pulls its own member, as ld's entry symbol does: `_start` brings in a library's startup code.
+     */
+    entrySymbol?: string;
+    /** Libraries searched in order: the first one whose index names a symbol supplies it. */
+    libraries?: RuntimeLibrary[];
+};
+/** The globals one GNU compiler unit defines and the ones it uses without defining. */
+type GnuUnitSymbols = {
+    /** Globals the unit defines, strong or weak. */
+    defined: string[];
+    /** The defined globals that are weak. */
+    weak: string[];
+    /** Globals the unit uses without defining, other than weak references, which pull nothing. */
+    references: string[];
+    /** Why the unit could not be parsed; empty when it parsed. */
+    errors: string[];
+};
 type JsInstructionToken = {
     /** One-based column in the processed source line. */
     sourceColumn: number;
@@ -135,9 +175,22 @@ type HandlerMap = {
         in: [];
         out: number;
     };
+    /**
+     * A read of standard input (descriptor 0): answer with the bytes left over from the current
+     * line or else one new line, at most `length` of them, as `[count, bytes]`. A count of 0 is end
+     * of input and -1 a failed read. Return a promise to wait for the user.
+     */
     stdIn: {
         in: [buffer: number[], length: number];
-        out: void;
+        out: [count: number, buffer: number[]];
+    };
+    /**
+     * Syscall 62 (lseek): move an open file's position. `whence` is 0 from the start, 1 from the
+     * current position, 2 from the end. Answer with the new position, or -1 when the seek fails.
+     */
+    seekFile: {
+        in: [fileDescriptor: number, offset: number, whence: number];
+        out: number;
     };
     stdOut: {
         in: [buffer: number[]];
@@ -211,8 +264,14 @@ type RISCVAssembleResult = {
     hasWarnings: boolean;
 };
 declare class RISCV {
+    static readonly assemblerProfiles: readonly AssemblerProfile[];
     static makeRiscVFromFiles: typeof makeRiscVFromFiles;
     static initializeRISCV: typeof initializeRISCV;
+    /**
+     * The globals one `gnu-compiler-v1` unit defines and uses, without laying it out or touching
+     * memory, for building a library index. Uses the current width, so call `setIs64Bit` first.
+     */
+    static analyzeGnuUnit(path: string, source: string): GnuUnitSymbols;
     static getInstructionSet(): JsInstruction[];
     static setIs64Bit(is64Bit: boolean): void;
     static is64Bit(): boolean;
@@ -556,6 +615,8 @@ interface JsRiscV {
      * @returns The label at the given address, or null if no label is found.
      */
     getLabelAtAddress(address: number): string | null;
+    /** Address of a defined label/alias, or -1 if absent. Requires successful assembly. */
+    getAddressOfLabel(label: string): number;
     /**
      * Sets whether the undo feature is enabled.
      * @param enabled True to enable the undo feature, false to disable it.
@@ -692,6 +753,15 @@ interface JsRiscV {
      * carries what it changed, with the old and the new value of each write.
      */
     getUndoGroups(): JsUndoGroup[];
+    /**
+     * The newest `max` entries of `getUndoGroups`, read from the top of the history without
+     * grouping the rest of it: what a panel showing the latest steps of a large history wants.
+     */
+    getUndoGroupsUpTo(max: number): JsUndoGroup[];
+    /** `max` entries of `getUndoGroups` after the newest `skip`, which are counted but never built. */
+    getUndoGroupsRange(skip: number, max: number): JsUndoGroup[];
+    /** How many entries `undo()` can still pop, counted the way `getUndoGroups` groups them. */
+    getUndoDepth(): number;
     /**
      * Opens a Poke: a register or memory value changed by the host between two instructions,
      * recorded in this history as a step of its own.
@@ -814,9 +884,10 @@ interface JsRiscV {
  * 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.
+ * @param options The assembler profile, the entry symbol and the libraries to link; see `AssemblyOptions`.
  * @returns A new `JsRiscV` object.
  */
-declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): JsRiscV;
+declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string, options?: AssemblyOptions): JsRiscV;
 /**
  * Initializes the RISCV simulator.
  */
@@ -829,4 +900,4 @@ declare function bigintToHighLow(value: bigint): [high: number, low: number];
  */
 declare function highLowToBigint(high: number, low: number): bigint;
 
-export { BackStepAction, ConfirmResult, type CsrRegisterName, DialogType, type FloatingPointRegisterName, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsInstructionUndoGroup, type JsPokeMemoryWrite, type JsPokeRegisterWrite, type JsPokeUndoGroup, type JsPokeWrite, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type JsUndoGroup, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_CSR_REGISTERS, RISCV_FLOATING_POINT_REGISTERS, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, highLowToBigint, makeRiscVFromFiles, registerHandlers, unimplementedHandler };
+export { type AssemblerProfile, type AssemblyOptions, BackStepAction, ConfirmResult, type CsrRegisterName, DialogType, type FloatingPointRegisterName, type GnuUnitSymbols, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsInstructionUndoGroup, type JsPokeMemoryWrite, type JsPokeRegisterWrite, type JsPokeUndoGroup, type JsPokeWrite, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type JsUndoGroup, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_CSR_REGISTERS, RISCV_FLOATING_POINT_REGISTERS, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, type RuntimeLibrary, StopReason, bigintToHighLow, highLowToBigint, makeRiscVFromFiles, registerHandlers, unimplementedHandler };

package/dist/index.d.ts

@@ -1,3 +1,43 @@
+type AssemblerProfile = 'rars' | 'gnu-compiler-v1';
+/**
+ * GNU compiler assembly members and the index naming the member that defines each global. A Build
+ * pulls a member only to resolve a global the program uses and does not define, as ld pulls members
+ * out of an archive, and keeps pulling for the globals those members use in turn. Members are always
+ * assembled with the `gnu-compiler-v1` profile, whatever profile the program uses, and their paths
+ * never meet the program's Files.
+ */
+type RuntimeLibrary = {
+    /** Canonical member path to its source. */
+    members: Record<string, string>;
+    /** Global symbol to the path of the member defining it. */
+    index: Record<string, string>;
+    /**
+     * Globals the library supplies even to a weak reference, which otherwise pulls no member: GCC
+     * refers to `__cxa_pure_virtual` weakly from every abstract class's vtable.
+     */
+    resolveWeak?: string[];
+};
+type AssemblyOptions = {
+    assemblerProfile?: AssemblerProfile;
+    /**
+     * The global execution starts at instead of `main`. The link must define it, and with a library
+     * it pulls its own member, as ld's entry symbol does: `_start` brings in a library's startup code.
+     */
+    entrySymbol?: string;
+    /** Libraries searched in order: the first one whose index names a symbol supplies it. */
+    libraries?: RuntimeLibrary[];
+};
+/** The globals one GNU compiler unit defines and the ones it uses without defining. */
+type GnuUnitSymbols = {
+    /** Globals the unit defines, strong or weak. */
+    defined: string[];
+    /** The defined globals that are weak. */
+    weak: string[];
+    /** Globals the unit uses without defining, other than weak references, which pull nothing. */
+    references: string[];
+    /** Why the unit could not be parsed; empty when it parsed. */
+    errors: string[];
+};
 type JsInstructionToken = {
     /** One-based column in the processed source line. */
     sourceColumn: number;
@@ -135,9 +175,22 @@ type HandlerMap = {
         in: [];
         out: number;
     };
+    /**
+     * A read of standard input (descriptor 0): answer with the bytes left over from the current
+     * line or else one new line, at most `length` of them, as `[count, bytes]`. A count of 0 is end
+     * of input and -1 a failed read. Return a promise to wait for the user.
+     */
     stdIn: {
         in: [buffer: number[], length: number];
-        out: void;
+        out: [count: number, buffer: number[]];
+    };
+    /**
+     * Syscall 62 (lseek): move an open file's position. `whence` is 0 from the start, 1 from the
+     * current position, 2 from the end. Answer with the new position, or -1 when the seek fails.
+     */
+    seekFile: {
+        in: [fileDescriptor: number, offset: number, whence: number];
+        out: number;
     };
     stdOut: {
         in: [buffer: number[]];
@@ -211,8 +264,14 @@ type RISCVAssembleResult = {
     hasWarnings: boolean;
 };
 declare class RISCV {
+    static readonly assemblerProfiles: readonly AssemblerProfile[];
     static makeRiscVFromFiles: typeof makeRiscVFromFiles;
     static initializeRISCV: typeof initializeRISCV;
+    /**
+     * The globals one `gnu-compiler-v1` unit defines and uses, without laying it out or touching
+     * memory, for building a library index. Uses the current width, so call `setIs64Bit` first.
+     */
+    static analyzeGnuUnit(path: string, source: string): GnuUnitSymbols;
     static getInstructionSet(): JsInstruction[];
     static setIs64Bit(is64Bit: boolean): void;
     static is64Bit(): boolean;
@@ -556,6 +615,8 @@ interface JsRiscV {
      * @returns The label at the given address, or null if no label is found.
      */
     getLabelAtAddress(address: number): string | null;
+    /** Address of a defined label/alias, or -1 if absent. Requires successful assembly. */
+    getAddressOfLabel(label: string): number;
     /**
      * Sets whether the undo feature is enabled.
      * @param enabled True to enable the undo feature, false to disable it.
@@ -692,6 +753,15 @@ interface JsRiscV {
      * carries what it changed, with the old and the new value of each write.
      */
     getUndoGroups(): JsUndoGroup[];
+    /**
+     * The newest `max` entries of `getUndoGroups`, read from the top of the history without
+     * grouping the rest of it: what a panel showing the latest steps of a large history wants.
+     */
+    getUndoGroupsUpTo(max: number): JsUndoGroup[];
+    /** `max` entries of `getUndoGroups` after the newest `skip`, which are counted but never built. */
+    getUndoGroupsRange(skip: number, max: number): JsUndoGroup[];
+    /** How many entries `undo()` can still pop, counted the way `getUndoGroups` groups them. */
+    getUndoDepth(): number;
     /**
      * Opens a Poke: a register or memory value changed by the host between two instructions,
      * recorded in this history as a step of its own.
@@ -814,9 +884,10 @@ interface JsRiscV {
  * 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.
+ * @param options The assembler profile, the entry symbol and the libraries to link; see `AssemblyOptions`.
  * @returns A new `JsRiscV` object.
  */
-declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string): JsRiscV;
+declare function makeRiscVFromFiles(files: RISCVSourceSet, entryFile: string, options?: AssemblyOptions): JsRiscV;
 /**
  * Initializes the RISCV simulator.
  */
@@ -829,4 +900,4 @@ declare function bigintToHighLow(value: bigint): [high: number, low: number];
  */
 declare function highLowToBigint(high: number, low: number): bigint;
 
-export { BackStepAction, ConfirmResult, type CsrRegisterName, DialogType, type FloatingPointRegisterName, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsInstructionUndoGroup, type JsPokeMemoryWrite, type JsPokeRegisterWrite, type JsPokeUndoGroup, type JsPokeWrite, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type JsUndoGroup, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_CSR_REGISTERS, RISCV_FLOATING_POINT_REGISTERS, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, highLowToBigint, makeRiscVFromFiles, registerHandlers, unimplementedHandler };
+export { type AssemblerProfile, type AssemblyOptions, BackStepAction, ConfirmResult, type CsrRegisterName, DialogType, type FloatingPointRegisterName, type GnuUnitSymbols, type HandlerMap, type HandlerMapFns, type JsBackStep, type JsInstruction, type JsInstructionToken, type JsInstructionUndoGroup, type JsPokeMemoryWrite, type JsPokeRegisterWrite, type JsPokeUndoGroup, type JsPokeWrite, type JsProgramStatement, type JsRiscV, type JsRiscVStackFrame, type JsUndoGroup, type MemoryAccessObserver, type MemoryObserverHandle, type MemoryWriteObserver, RISCV, type RISCVAssembleError, type RISCVAssembleResult, RISCVRegisters, type RISCVSourceLocation, type RISCVSourceSet, RISCV_CSR_REGISTERS, RISCV_FLOATING_POINT_REGISTERS, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, type RuntimeLibrary, StopReason, bigintToHighLow, highLowToBigint, makeRiscVFromFiles, registerHandlers, unimplementedHandler };