virtual-machine 0.7.2 → 0.7.5

package/build/index.d.ts

@@ -259,6 +259,14 @@ declare class WasmVm {
    * This allows the browser to do partial texture uploads for better performance.
    */
   get_gpu_dirty_rect(): Uint32Array | undefined;
+  /**
+   * Reset hart 0 to bare machine mode at the entry point.
+   *
+   * Benchmark workloads (see `bench_workload`) are M-mode programs; this
+   * undoes the S-mode boot setup that `new_with_harts` applies so they
+   * run exactly like under the native bench runner.
+   */
+  reset_machine_mode(): void;
   /**
    * Check if cancellation has been requested.
    */
@@ -277,10 +285,14 @@ declare class WasmVm {
    * Get a direct zero-copy view into the framebuffer in SharedArrayBuffer.
    * 
    * This eliminates all memory copies by creating a Uint8Array view directly
-   * into the SharedArrayBuffer at the framebuffer offset. The browser can
-   * pass this directly to WebGPU's writeTexture for zero-copy rendering.
-   * 
-   * Returns None if SharedArrayBuffer is not available (single-threaded mode).
+   * into guest memory at the framebuffer offset. The browser can pass this
+   * directly to WebGPU's writeTexture for zero-copy rendering.
+   *
+   * Works in both memory modes:
+   * - SMP (SharedArrayBuffer): stable view into the SAB.
+   * - Single-hart (linear memory): view into WASM linear memory. This view
+   *   is invalidated whenever WASM memory grows, so consume it immediately
+   *   and call this again each frame (do not cache it JS-side).
    */
   get_framebuffer_view(): Uint8Array | undefined;
   /**
@@ -369,7 +381,11 @@ declare class WasmVm {
   step(): boolean;
   /**
    * Push an input byte to the UART.
-   * In SMP mode, this also writes to the shared input buffer so workers can receive it.
+   *
+   * In SMP mode there is a single shared input ring consumed by whichever
+   * hart runs the shell (the bus routes RBR/LSR reads of every hart,
+   * including hart 0, to the ring). Pushing to the local FIFO as well
+   * would duplicate the stream and leave stale bytes behind.
    */
   input(byte: number): void;
   /**
@@ -377,12 +393,22 @@ declare class WasmVm {
    */
   is_smp(): boolean;
   /**
-   * Execute up to N instructions in a batch.
-   * Returns the number of instructions actually executed.
-   * This is more efficient than calling step() N times due to reduced
-   * JS-WASM boundary crossings.
+   * Execute up to N instructions by looping `step()`.
+   *
+   * DEPRECATED for hot paths: prefer `run_batch`, which hoists device
+   * polling and CLINT sync out of the instruction loop and returns early
+   * on WFI. `step_n` keeps the historical contract that a return value
+   * less than `count` means the VM halted (it never stops early on WFI),
+   * which existing consumers rely on for halt detection.
    */
   step_n(count: number): number;
+  /**
+   * Total retired guest instructions on hart 0.
+   *
+   * Unlike step counts, this reflects real instructions (superblock
+   * execution retires many instructions per step). Use for MIPS metrics.
+   */
+  instret(): number;
   /**
    * Get the entry PC address for workers.
    * This is the address where secondary harts should start executing.
@@ -423,6 +449,20 @@ declare class WasmVm {
    * Get the number of harts configured.
    */
   num_harts(): number;
+  /**
+   * Execute up to N instructions in a batch with device polling, CLINT
+   * sync, and RTC updates hoisted to chunk boundaries.
+   *
+   * This is the fast path for hart 0: the inner loop is a tight
+   * `cpu.step()` with no per-instruction bookkeeping. Interrupt latency
+   * is bounded by IRQ_SYNC_INTERVAL (shared-CLINT sync) and the CPU's own
+   * internal 256-instruction interrupt poll.
+   *
+   * Returns the number of dispatcher steps executed (superblocks count as
+   * one step; use `instret()` for true instruction counts). Returns early
+   * on halt or WFI so the JS caller can pace execution.
+   */
+  run_batch(max_steps: number): number;
 }
 
 declare class WorkerState {
@@ -496,6 +536,15 @@ declare enum WorkerStepResult {
   Wfi = 4,
 }
 
+/**
+ * Build a synthetic benchmark workload binary (see `bench` module).
+ *
+ * Load the returned bytes as a raw "kernel" via `WasmVm::new_with_harts`
+ * and drive it with `step_n`; read `instret()` for MIPS accounting.
+ * Available workloads: nop, prime, memcpy, spinlock, ecall.
+ */
+declare function bench_workload(name: string): Uint8Array;
+
 /**
  * Check interrupts for this hart using the shared CLINT.
  *
@@ -519,6 +568,7 @@ interface InitOutput {
   readonly memory: WebAssembly.Memory;
   readonly __wbg_wasmvm_free: (a: number, b: number) => void;
   readonly __wbg_workerstate_free: (a: number, b: number) => void;
+  readonly bench_workload: (a: number, b: number) => [number, number, number, number];
   readonly wasmvm_allow_workers_to_start: (a: number) => void;
   readonly wasmvm_clear_cancel: (a: number) => void;
   readonly wasmvm_connect_webtransport: (a: number, b: number, c: number, d: number, e: number) => [number, number];
@@ -553,6 +603,7 @@ interface InitOutput {
   readonly wasmvm_has_gpu_frame: (a: number) => number;
   readonly wasmvm_inject_network_packet: (a: number, b: any) => number;
   readonly wasmvm_input: (a: number, b: number) => void;
+  readonly wasmvm_instret: (a: number) => number;
   readonly wasmvm_is_cancel_requested: (a: number) => number;
   readonly wasmvm_is_external_network_connected: (a: number) => number;
   readonly wasmvm_is_halted: (a: number) => number;
@@ -565,6 +616,8 @@ interface InitOutput {
   readonly wasmvm_print_banner: (a: number) => void;
   readonly wasmvm_print_status: (a: number, b: number, c: number) => void;
   readonly wasmvm_request_cancel: (a: number) => void;
+  readonly wasmvm_reset_machine_mode: (a: number) => void;
+  readonly wasmvm_run_batch: (a: number, b: number) => number;
   readonly wasmvm_send_d1_char: (a: number, b: number) => number;
   readonly wasmvm_send_d1_key_event: (a: number, b: number, c: number) => number;
   readonly wasmvm_send_key_event: (a: number, b: number, c: number) => number;
@@ -579,6 +632,7 @@ interface InitOutput {
   readonly wasmvm_terminate_workers: (a: number) => void;
   readonly wasmvm_uart_output_pending: (a: number) => number;
   readonly worker_check_interrupts: (a: number, b: any) => bigint;
+  readonly worker_entry: (a: number, b: any, c: bigint) => void;
   readonly workerstate_get_a0: (a: number) => bigint;
   readonly workerstate_hart_id: (a: number) => number;
   readonly workerstate_is_msip_pending: (a: number) => number;
@@ -586,13 +640,12 @@ interface InitOutput {
   readonly workerstate_new: (a: number, b: any, c: bigint) => number;
   readonly workerstate_step_batch: (a: number, b: number) => number;
   readonly workerstate_step_count: (a: number) => bigint;
-  readonly worker_entry: (a: number, b: any, c: bigint) => void;
-  readonly wasm_bindgen__convert__closures_____invoke__h4e3f98878f091896: (a: number, b: number) => void;
-  readonly wasm_bindgen__closure__destroy__h16ea2e7332e3f0d8: (a: number, b: number) => void;
-  readonly wasm_bindgen__convert__closures_____invoke__h260170fb96639bcf: (a: number, b: number, c: any) => void;
-  readonly wasm_bindgen__closure__destroy__h612f8e24953b61d5: (a: number, b: number) => void;
-  readonly wasm_bindgen__convert__closures_____invoke__h658bde57dcf0e58b: (a: number, b: number) => void;
-  readonly wasm_bindgen__convert__closures_____invoke__h5006ec25729b138d: (a: number, b: number, c: any) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h10fd13f77519f00f: (a: number, b: number, c: any) => void;
+  readonly wasm_bindgen__closure__destroy__h98fb6f0c0578da12: (a: number, b: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h3c19a701e2fb4946: (a: number, b: number, c: any) => void;
+  readonly wasm_bindgen__closure__destroy__h1e8cf243a981f4cd: (a: number, b: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h6ce8d92453d66e1b: (a: number, b: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h1f45221b43ca80d0: (a: number, b: number) => void;
   readonly __wbindgen_malloc: (a: number, b: number) => number;
   readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
   readonly __wbindgen_exn_store: (a: number) => void;
@@ -636,11 +689,12 @@ type __pkg_riscv_vm_WorkerState = WorkerState;
 declare const __pkg_riscv_vm_WorkerState: typeof WorkerState;
 type __pkg_riscv_vm_WorkerStepResult = WorkerStepResult;
 declare const __pkg_riscv_vm_WorkerStepResult: typeof WorkerStepResult;
+declare const __pkg_riscv_vm_bench_workload: typeof bench_workload;
 declare const __pkg_riscv_vm_initSync: typeof initSync;
 declare const __pkg_riscv_vm_worker_check_interrupts: typeof worker_check_interrupts;
 declare const __pkg_riscv_vm_worker_entry: typeof worker_entry;
 declare namespace __pkg_riscv_vm {
-  export { type __pkg_riscv_vm_InitInput as InitInput, type __pkg_riscv_vm_InitOutput as InitOutput, __pkg_riscv_vm_NetworkStatus as NetworkStatus, type __pkg_riscv_vm_SyncInitInput as SyncInitInput, __pkg_riscv_vm_WasmVm as WasmVm, __pkg_riscv_vm_WorkerState as WorkerState, __pkg_riscv_vm_WorkerStepResult as WorkerStepResult, __wbg_init as default, __pkg_riscv_vm_initSync as initSync, __pkg_riscv_vm_worker_check_interrupts as worker_check_interrupts, __pkg_riscv_vm_worker_entry as worker_entry };
+  export { type __pkg_riscv_vm_InitInput as InitInput, type __pkg_riscv_vm_InitOutput as InitOutput, __pkg_riscv_vm_NetworkStatus as NetworkStatus, type __pkg_riscv_vm_SyncInitInput as SyncInitInput, __pkg_riscv_vm_WasmVm as WasmVm, __pkg_riscv_vm_WorkerState as WorkerState, __pkg_riscv_vm_WorkerStepResult as WorkerStepResult, __pkg_riscv_vm_bench_workload as bench_workload, __wbg_init as default, __pkg_riscv_vm_initSync as initSync, __pkg_riscv_vm_worker_check_interrupts as worker_check_interrupts, __pkg_riscv_vm_worker_entry as worker_entry };
 }
 
 /**