@specy/risc-v 2.0.1 → 2.1.0

package/README.md

@@ -102,6 +102,52 @@ Synchronous handlers never yield to the event loop: the simulation runs straight
 returned promise settles on a microtask. Overlapping calls are queued and run one after another,
 never concurrently.
 
+Program time is a handler too, so a run can be given a clock of its own: `sleep` answers syscall 32
+and `time` answers syscall 30. A live run resolves `sleep` on a timer and returns `Date.now()` from
+`time`; a scripted run can settle `sleep` immediately, advance a virtual clock by the requested
+milliseconds and return that clock instead, which keeps elapsed-time output reproducible.
+
+## Memory observers
+
+A memory-mapped device - a framebuffer, a keyboard register - is modelled by observing the memory
+the program reads and writes:
+
+```ts
+// Every write in a framebuffer: (address, length, value), with the width of the store in bytes.
+const frame = riscvSimulator.addMemoryWriteObserver(0x10010000, 0x10012ffc, (address, length, value) => {
+    screen.markDirty(address)
+})
+
+// One memory-mapped register: reads and writes, either of which may be null.
+const receiver = riscvSimulator.addMemoryAccessObserver(
+    0xffff0004,
+    () => keyboard.consumeCharacter(),
+    null
+)
+
+riscvSimulator.removeMemoryObserver(frame)
+riscvSimulator.removeMemoryObservers()
+```
+
+*   Addresses must be word-aligned, `endAddress` is inclusive and covers its whole word, and a range
+    may not cross `0x80000000`; a registration that breaks any of these throws. Either form of a
+    high address is accepted: `0xffff0000` and `0xffff0000 | 0` name the same word.
+*   Handlers are given signed 32 bit integers, as the guest holds them: the register at
+    `0xffff000c` arrives as `-65524`, and a pixel word with its high bit set arrives negative.
+    Apply `>>> 0` wherever the unsigned form is wanted.
+*   Handlers run synchronously inside the instruction that caused the access, so they must be cheap
+    and must not write back into their own range. A returned promise is ignored, unlike an IO
+    handler's.
+*   An observer is notified *after* the access, with the value the program read or stored. A
+    register whose value is consumed by reading it must therefore be reloaded from the handler,
+    with `setPeripheralWord`, for the next read.
+*   Observers live on the simulator's memory, which assembling and initializing only clear the
+    contents of, so a registration survives `assemble()` and `initialize()` and - like a registered
+    IO handler - is shared by every `JsRiscV` instance. Notifications start once a program has been
+    assembled.
+*   `undo()` restores memory through the same stores, so an observed range reports the restored
+    values as ordinary writes and a device that follows notifications alone stays in step.
+
 ## API
 
 ### `RISCV` Static Class
@@ -145,8 +191,14 @@ 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.
-* `setMemoryBytes(address: number, bytes: number[]): void`: Writes an array of `bytes` to memory starting at `address`.
+* `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.
+* `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).
+* `addMemoryAccessObserver(address: number, onRead, onWrite): number`: Observes reads and writes of one word. See [memory observers](#memory-observers).
+* `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`.

package/dist/index.d.mts

@@ -119,10 +119,23 @@ type HandlerMap = {
         in: [l: string];
         out: void;
     };
+    /**
+     * Syscall 32: the program asks to be suspended for this many milliseconds. Return a promise
+     * that settles when the wait is over to suspend the simulation without blocking the host.
+     */
     sleep: {
         in: [milliseconds: number];
         out: void;
     };
+    /**
+     * Syscall 30: the program time in milliseconds, split by the syscall into a0 (low word) and
+     * a1 (high word). Answer with `Date.now()` for a live run, or with a virtual clock for a
+     * scripted one, so that elapsed-time output stays reproducible.
+     */
+    time: {
+        in: [];
+        out: number;
+    };
     stdIn: {
         in: [buffer: number[], length: number];
         out: void;
@@ -136,6 +149,27 @@ type HandlerMap = {
         out: void;
     };
 };
+/**
+ * Notified after a write anywhere in an observed address range.
+ *
+ * `length` is the width of the access in bytes (4, 2 or 1) and `value` is what the program stored,
+ * so a byte or halfword store reports only the bytes it touched; a peripheral that mirrors whole
+ * words should re-read the containing word with `readMemoryBytes` rather than trust `value`.
+ *
+ * Both `address` and `value` are signed 32 bit integers, as the guest holds them: the register at
+ * `0xffff000c` arrives as `-65524`, and a pixel word with its high bit set arrives negative too.
+ * Apply `>>> 0` wherever the unsigned form is wanted.
+ */
+type MemoryWriteObserver = (address: number, length: number, value: number) => void;
+/**
+ * Notified after a read or a write of one observed word, with the same signed 32 bit numbers as
+ * `MemoryWriteObserver`. `value` is the value the program read or stored; on a read it is what
+ * memory held *before* the observer ran, so a register whose value is consumed by reading it must
+ * be reloaded from the handler for the next read.
+ */
+type MemoryAccessObserver = (address: number, value: number) => void;
+/** Identifies one registration, for `removeMemoryObserver`. */
+type MemoryObserverHandle = number;
 type JsInstruction = {
     name: string;
     example: string;
@@ -459,6 +493,9 @@ interface JsRiscV {
     getUndoStack(): JsBackStep[];
     /**
      * Reads a sequence of bytes from memory.
+     *
+     * 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.
      * @param address The starting memory address.
      * @param length The number of bytes to read.
      * @returns An array of bytes read from memory.
@@ -466,10 +503,63 @@ interface JsRiscV {
     readMemoryBytes(address: number, length: number): number[];
     /**
      * Writes a sequence of bytes to memory.
+     *
+     * Unlike `readMemoryBytes`, this writes the way the program does: it notifies write observers
+     * and, while undo is enabled, records an undo step per byte. Use `setPeripheralWord` for a
+     * device keeping its own register up to date.
      * @param address The starting memory address.
      * @param bytes An array of bytes to write to memory.
      */
     setMemoryBytes(address: number, bytes: number[]): void;
+    /**
+     * Writes one word as a peripheral would: no observer is notified and no undo step is recorded,
+     * because the write is not the program acting. This is how a device model refreshes a
+     * memory-mapped register - a ready bit, a pending character - without feeding its own observer
+     * or consuming undo history.
+     * @param address The word address, which must be word-aligned. Either form of a high address
+     * is accepted: `0xffff0000` and `0xffff0000 | 0` name the same word.
+     * @param value The 32 bit value to store, raw, without byte-order adjustment.
+     */
+    setPeripheralWord(address: number, value: number): void;
+    /**
+     * Observes every write in an address range, the shape a framebuffer wants.
+     *
+     * Both addresses must be word-aligned, `endAddress` is inclusive and covers its whole word, and
+     * the range may not cross 0x80000000 (split it in two registrations instead); a range that
+     * breaks any of these throws. Either form of a high address is accepted: `0xffff0000` and
+     * `0xffff0000 | 0` name the same word. The handler runs synchronously inside the storing instruction, so
+     * it must be cheap and must not write back into its own range; a returned promise is ignored.
+     *
+     * Observers live on the simulator's memory, which assembling and initializing only clear the
+     * contents of, so a registration survives `assemble()` and `initialize()`. For the same reason
+     * it is shared by every `JsRiscV` instance: register once per page, or remove the previous
+     * registration before registering again for a newly built program.
+     *
+     * Notifications only start once a program has been assembled, and undo notifies too: restoring
+     * memory during `undo()` goes through the same stores, so an observed range reports the
+     * restored values as ordinary writes.
+     * @returns A handle for `removeMemoryObserver`.
+     */
+    addMemoryWriteObserver(startAddress: number, endAddress: number, handler: MemoryWriteObserver): MemoryObserverHandle;
+    /**
+     * Observes reads and writes of a single word, the shape a memory-mapped register wants. The
+     * address must be word-aligned. Pass `null` for a direction you do not care about. The same
+     * lifetime and synchronous-handler rules as `addMemoryWriteObserver` apply.
+     * @returns A handle for `removeMemoryObserver`.
+     */
+    addMemoryAccessObserver(address: number, onRead: MemoryAccessObserver | null, onWrite: MemoryAccessObserver | null): MemoryObserverHandle;
+    /**
+     * Removes one registration. An unknown handle is ignored.
+     */
+    removeMemoryObserver(handle: MemoryObserverHandle): void;
+    /**
+     * Removes every registration.
+     */
+    removeMemoryObservers(): void;
+    /**
+     * 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.
@@ -504,4 +594,4 @@ declare function makeRiscVfromSource(source: string): JsRiscV;
 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, 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, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, registerHandlers, unimplementedHandler };

package/dist/index.d.ts

@@ -119,10 +119,23 @@ type HandlerMap = {
         in: [l: string];
         out: void;
     };
+    /**
+     * Syscall 32: the program asks to be suspended for this many milliseconds. Return a promise
+     * that settles when the wait is over to suspend the simulation without blocking the host.
+     */
     sleep: {
         in: [milliseconds: number];
         out: void;
     };
+    /**
+     * Syscall 30: the program time in milliseconds, split by the syscall into a0 (low word) and
+     * a1 (high word). Answer with `Date.now()` for a live run, or with a virtual clock for a
+     * scripted one, so that elapsed-time output stays reproducible.
+     */
+    time: {
+        in: [];
+        out: number;
+    };
     stdIn: {
         in: [buffer: number[], length: number];
         out: void;
@@ -136,6 +149,27 @@ type HandlerMap = {
         out: void;
     };
 };
+/**
+ * Notified after a write anywhere in an observed address range.
+ *
+ * `length` is the width of the access in bytes (4, 2 or 1) and `value` is what the program stored,
+ * so a byte or halfword store reports only the bytes it touched; a peripheral that mirrors whole
+ * words should re-read the containing word with `readMemoryBytes` rather than trust `value`.
+ *
+ * Both `address` and `value` are signed 32 bit integers, as the guest holds them: the register at
+ * `0xffff000c` arrives as `-65524`, and a pixel word with its high bit set arrives negative too.
+ * Apply `>>> 0` wherever the unsigned form is wanted.
+ */
+type MemoryWriteObserver = (address: number, length: number, value: number) => void;
+/**
+ * Notified after a read or a write of one observed word, with the same signed 32 bit numbers as
+ * `MemoryWriteObserver`. `value` is the value the program read or stored; on a read it is what
+ * memory held *before* the observer ran, so a register whose value is consumed by reading it must
+ * be reloaded from the handler for the next read.
+ */
+type MemoryAccessObserver = (address: number, value: number) => void;
+/** Identifies one registration, for `removeMemoryObserver`. */
+type MemoryObserverHandle = number;
 type JsInstruction = {
     name: string;
     example: string;
@@ -459,6 +493,9 @@ interface JsRiscV {
     getUndoStack(): JsBackStep[];
     /**
      * Reads a sequence of bytes from memory.
+     *
+     * 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.
      * @param address The starting memory address.
      * @param length The number of bytes to read.
      * @returns An array of bytes read from memory.
@@ -466,10 +503,63 @@ interface JsRiscV {
     readMemoryBytes(address: number, length: number): number[];
     /**
      * Writes a sequence of bytes to memory.
+     *
+     * Unlike `readMemoryBytes`, this writes the way the program does: it notifies write observers
+     * and, while undo is enabled, records an undo step per byte. Use `setPeripheralWord` for a
+     * device keeping its own register up to date.
      * @param address The starting memory address.
      * @param bytes An array of bytes to write to memory.
      */
     setMemoryBytes(address: number, bytes: number[]): void;
+    /**
+     * Writes one word as a peripheral would: no observer is notified and no undo step is recorded,
+     * because the write is not the program acting. This is how a device model refreshes a
+     * memory-mapped register - a ready bit, a pending character - without feeding its own observer
+     * or consuming undo history.
+     * @param address The word address, which must be word-aligned. Either form of a high address
+     * is accepted: `0xffff0000` and `0xffff0000 | 0` name the same word.
+     * @param value The 32 bit value to store, raw, without byte-order adjustment.
+     */
+    setPeripheralWord(address: number, value: number): void;
+    /**
+     * Observes every write in an address range, the shape a framebuffer wants.
+     *
+     * Both addresses must be word-aligned, `endAddress` is inclusive and covers its whole word, and
+     * the range may not cross 0x80000000 (split it in two registrations instead); a range that
+     * breaks any of these throws. Either form of a high address is accepted: `0xffff0000` and
+     * `0xffff0000 | 0` name the same word. The handler runs synchronously inside the storing instruction, so
+     * it must be cheap and must not write back into its own range; a returned promise is ignored.
+     *
+     * Observers live on the simulator's memory, which assembling and initializing only clear the
+     * contents of, so a registration survives `assemble()` and `initialize()`. For the same reason
+     * it is shared by every `JsRiscV` instance: register once per page, or remove the previous
+     * registration before registering again for a newly built program.
+     *
+     * Notifications only start once a program has been assembled, and undo notifies too: restoring
+     * memory during `undo()` goes through the same stores, so an observed range reports the
+     * restored values as ordinary writes.
+     * @returns A handle for `removeMemoryObserver`.
+     */
+    addMemoryWriteObserver(startAddress: number, endAddress: number, handler: MemoryWriteObserver): MemoryObserverHandle;
+    /**
+     * Observes reads and writes of a single word, the shape a memory-mapped register wants. The
+     * address must be word-aligned. Pass `null` for a direction you do not care about. The same
+     * lifetime and synchronous-handler rules as `addMemoryWriteObserver` apply.
+     * @returns A handle for `removeMemoryObserver`.
+     */
+    addMemoryAccessObserver(address: number, onRead: MemoryAccessObserver | null, onWrite: MemoryAccessObserver | null): MemoryObserverHandle;
+    /**
+     * Removes one registration. An unknown handle is ignored.
+     */
+    removeMemoryObserver(handle: MemoryObserverHandle): void;
+    /**
+     * Removes every registration.
+     */
+    removeMemoryObservers(): void;
+    /**
+     * 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.
@@ -504,4 +594,4 @@ declare function makeRiscVfromSource(source: string): JsRiscV;
 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, 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, RISCV_REGISTERS, type RegisterName, type RiscvTokenizedLine, StopReason, bigintToHighLow, registerHandlers, unimplementedHandler };