@specy/risc-v 4.1.0 → 4.2.1

package/README.md

@@ -382,7 +382,7 @@ This interface provides methods to control and interact with a RISC-V simulator
 * `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'] | Promise<HandlerMap[T]['out']>): void`: Registers a handler function for a specific event (e.g., syscalls). See `HandlerName`, `HandlerMap` and [IO handlers](#io-handlers) 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. Notifies no memory observer: inspecting memory from the host is not the program reading it.
+* `readMemoryBytes(address: number, length: number): number[]`: Reads `length` bytes from memory starting at `address`. Returns an array of byte values. Notifies no memory observer: inspecting memory from the host is not the program reading it. Text reads as the encodings of the statements it holds, little endian, and as zero where no statement is; the program's own loads from text still fault unless self-modifying code is enabled.
 * `setMemoryBytes(address: number, bytes: number[]): void`: Writes an array of `bytes` to memory starting at `address`, the way the program does: write observers are notified and, while undo is enabled, an undo step is recorded per byte.
 * `setPeripheralWord(address: number, value: number): void`: Writes one word-aligned word as a peripheral would, notifying no observer and recording no undo step. See [memory observers](#memory-observers).
 * `addMemoryWriteObserver(startAddress: number, endAddress: number, handler): number`: Observes every write in an address range. See [memory observers](#memory-observers).
@@ -446,3 +446,28 @@ instructions still expose a serial inside handlers. Match and retain host frames
 `getUndoGroups`/`getUndoGroupsRange`, never by PC; drop frames whose groups are no longer retained.
 
 `initialize` is rejected while an instruction or Poke is active.
+
+### Memory layout and bounds
+
+After a successful `assemble()`, `getLayoutItems()` returns an `Int32Array` of
+five-field tuples: address, byte length, kind (`0` code, `1` data, `2` reserved),
+index into `getSectionNames()`, and byte alignment. Convert addresses to unsigned
+32-bit values in JavaScript (`address >>> 0`). Items describe the assembled program,
+including the kept sections of loaded library members; zero-length items are omitted.
+
+`getSymbolNames()` and `getSymbolFiles()` are parallel string arrays.
+`getSymbolValues()` has three integers per name: address, data flag, library flag.
+A library flag of `1` includes locals of data-only library members. The source file
+identifies an included file, rather than only its enclosing compilation unit.
+
+After `initialize()`, `getHeapStart()` and `getHeapBreak()` bound the current heap.
+An allocation's previous break is recorded with its instruction, so Undo restores
+it and executing that instruction again makes the same allocation.
+
+`getStackTop()` reports the initialized `sp`, fixed until the next initialization.
+The current `sp` is still available in the register file. Tracking a changing top
+inside RARS's instruction loop measured about 6% slower, so this Core retains the
+initial-stack convention.
+
+`getTextSegments()` returns half-open start and end pairs for the text segment, which hold
+statements rather than bytes: `readMemoryBytes` reads them, `setMemoryBytes` cannot write them.

package/dist/index.d.mts

@@ -460,7 +460,9 @@ declare enum BackStepAction {
      * generator back, so that stepping the service again draws the same number. The generator's
      * state is the simulator's own, so `param2`, `oldValue` and `newValue` are 0.
      */
-    RANDOM_STREAM_RESTORE = 15
+    RANDOM_STREAM_RESTORE = 15,
+    /** Internal heap and stack extent restores; no displayed mutation. */
+    HEAP_RESTORE = 16
 }
 /**
  * Represents a back step in the simulation undo stack.
@@ -745,6 +747,20 @@ interface JsRiscV {
     getLabelAtAddress(address: number): string | null;
     /** Address of a defined label/alias, or -1 if absent. Requires successful assembly. */
     getAddressOfLabel(label: string): number;
+    /** Tuples of address, length, kind (code=0/data=1/reserved=2), section index, alignment. */
+    getLayoutItems(): Int32Array;
+    getSectionNames(): string[];
+    getSymbolFiles(): string[];
+    getSymbolNames(): string[];
+    /** Tuples of address, data flag, library owner flag. */
+    getSymbolValues(): Int32Array;
+    getHeapBreak(): number;
+    getStackTop(): number;
+    /**
+     * Half-open start and end pairs of the text segment, which hold statements rather than bytes:
+     * `readMemoryBytes` reads them as encodings, `setMemoryBytes` cannot write them.
+     */
+    getTextSegments(): Int32Array;
     /**
      * Where the program's heap, and so the first block sbrk (9) hands out, starts. RARS's heap base,
      * 0x10040000, unless the program is a `gnu-compiler-v1` Build whose static data (`.data`,
@@ -941,6 +957,9 @@ interface JsRiscV {
      *
      * Reading through this method notifies no memory observer: inspecting memory from the host is
      * not the program reading it, so a memory viewer never drives a memory-mapped register.
+     * The text segment reads as the encodings of the statements it holds, little endian, with
+     * zero where no statement is; the program's own loads from text still fault unless
+     * self-modifying code is enabled.
      * @param address The starting memory address.
      * @param length The number of bytes to read.
      * @returns An array of bytes read from memory.

package/dist/index.d.ts

@@ -460,7 +460,9 @@ declare enum BackStepAction {
      * generator back, so that stepping the service again draws the same number. The generator's
      * state is the simulator's own, so `param2`, `oldValue` and `newValue` are 0.
      */
-    RANDOM_STREAM_RESTORE = 15
+    RANDOM_STREAM_RESTORE = 15,
+    /** Internal heap and stack extent restores; no displayed mutation. */
+    HEAP_RESTORE = 16
 }
 /**
  * Represents a back step in the simulation undo stack.
@@ -745,6 +747,20 @@ interface JsRiscV {
     getLabelAtAddress(address: number): string | null;
     /** Address of a defined label/alias, or -1 if absent. Requires successful assembly. */
     getAddressOfLabel(label: string): number;
+    /** Tuples of address, length, kind (code=0/data=1/reserved=2), section index, alignment. */
+    getLayoutItems(): Int32Array;
+    getSectionNames(): string[];
+    getSymbolFiles(): string[];
+    getSymbolNames(): string[];
+    /** Tuples of address, data flag, library owner flag. */
+    getSymbolValues(): Int32Array;
+    getHeapBreak(): number;
+    getStackTop(): number;
+    /**
+     * Half-open start and end pairs of the text segment, which hold statements rather than bytes:
+     * `readMemoryBytes` reads them as encodings, `setMemoryBytes` cannot write them.
+     */
+    getTextSegments(): Int32Array;
     /**
      * Where the program's heap, and so the first block sbrk (9) hands out, starts. RARS's heap base,
      * 0x10040000, unless the program is a `gnu-compiler-v1` Build whose static data (`.data`,
@@ -941,6 +957,9 @@ interface JsRiscV {
      *
      * Reading through this method notifies no memory observer: inspecting memory from the host is
      * not the program reading it, so a memory viewer never drives a memory-mapped register.
+     * The text segment reads as the encodings of the statements it holds, little endian, with
+     * zero where no statement is; the program's own loads from text still fault unless
+     * self-modifying code is enabled.
      * @param address The starting memory address.
      * @param length The number of bytes to read.
      * @returns An array of bytes read from memory.