virtual-machine 0.0.31 → 0.0.35

package/build/index.d.ts

@@ -1,5 +1,3 @@
-export { WorkerErrorMessage, WorkerHaltedMessage, WorkerInitMessage, WorkerOutboundMessage, WorkerReadyMessage } from './worker.js';
-
 /* tslint:disable */
 /* eslint-disable */
 
@@ -18,6 +16,9 @@ declare class WasmVm {
   [Symbol.dispose](): void;
   /**
    * Get a byte from the UART output buffer, if available.
+   * 
+   * In SMP mode, this checks both the shared UART output buffer (for worker output)
+   * and the local UART buffer (for hart 0 output).
    */
   get_output(): number | undefined;
   /**
@@ -29,15 +30,42 @@ declare class WasmVm {
    * Print a status message to UART output (visible in browser).
    */
   print_status(message: string): void;
+  /**
+   * Start worker threads for secondary harts (1..num_harts).
+   *
+   * Workers run in parallel with the main thread, sharing DRAM and CLINT
+   * via SharedArrayBuffer.
+   *
+   * # Arguments
+   * * `worker_url` - URL to the worker script (e.g., "/worker.js")
+   */
+  start_workers(worker_url: string): void;
   /**
    * Get the current network connection status.
    * This checks the actual connection state by seeing if an IP was assigned.
    */
   network_status(): NetworkStatus;
+  /**
+   * Create a new VM instance with a specified number of harts.
+   *
+   * # Arguments
+   * * `kernel` - ELF kernel binary
+   * * `num_harts` - Number of harts (0 = auto-detect)
+   */
+  static new_with_harts(kernel: Uint8Array, num_harts: number): WasmVm;
   /**
    * Get current memory usage (DRAM size) in bytes.
    */
   get_memory_usage(): bigint;
+  /**
+   * Get the SharedArrayBuffer for external worker management.
+   * Returns None if not in SMP mode.
+   */
+  get_shared_buffer(): SharedArrayBuffer | undefined;
+  /**
+   * Terminate all workers.
+   */
+  terminate_workers(): void;
   /**
    * Disconnect from the network.
    */
@@ -52,19 +80,74 @@ declare class WasmVm {
    * Note: Connection is asynchronous. Check network_status() to monitor connection state.
    */
   connect_webtransport(url: string, cert_hash?: string | null): void;
+  /**
+   * Inject a network packet to be received by the guest.
+   * Called from JavaScript when the native WebTransport addon receives a packet.
+   */
+  inject_network_packet(packet: Uint8Array): boolean;
+  /**
+   * Extract a network packet sent by the guest.
+   * Returns the packet data or null if no packet is pending.
+   */
+  extract_network_packet(): Uint8Array | undefined;
+  /**
+   * Set up an external network backend for packet bridging.
+   * This is used by the Node.js CLI to bridge packets between the native
+   * WebTransport addon and the WASM VM.
+   * 
+   * @param mac_bytes - MAC address as 6 bytes [0x52, 0x54, 0x00, 0x12, 0x34, 0x56]
+   */
+  setup_external_network(mac_bytes: Uint8Array): void;
+  /**
+   * Set the assigned IP address for the external network.
+   * Called when the native WebTransport addon receives an IP assignment.
+   */
+  set_external_network_ip(ip_bytes: Uint8Array): boolean;
+  /**
+   * Get the number of pending RX packets.
+   */
+  external_network_rx_pending(): number;
+  /**
+   * Get the number of pending TX packets.
+   */
+  external_network_tx_pending(): number;
+  /**
+   * Extract all pending network packets sent by the guest.
+   * Returns an array of packet data.
+   */
+  extract_all_network_packets(): Array<any>;
+  /**
+   * Check if external network is connected (has IP assigned).
+   */
+  is_external_network_connected(): boolean;
   /**
    * Create a new VM instance and load a kernel (ELF or raw binary).
+   *
+   * If SharedArrayBuffer is available, the VM will use true parallel
+   * execution with Web Workers. Otherwise, falls back to single-threaded mode.
+   *
+   * Hart count is auto-detected as half of hardware_concurrency.
+   * Use `new_with_harts()` to specify a custom hart count.
    */
   constructor(kernel: Uint8Array);
   /**
-   * Execute one instruction on each CPU (round-robin).
+   * Execute one instruction on hart 0 (primary hart).
+   *
+   * In SMP mode, secondary harts run in Web Workers and execute in parallel.
+   * This method only steps hart 0, which handles I/O coordination.
+   *
    * Returns true if the VM is still running, false if halted.
    */
   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.
    */
   input(byte: number): void;
+  /**
+   * Check if running in SMP mode (with workers).
+   */
+  is_smp(): boolean;
   /**
    * Execute up to N instructions in a batch.
    * Returns the number of instructions actually executed.
@@ -86,15 +169,75 @@ declare class WasmVm {
    * This should be called before starting execution if the kernel needs a filesystem.
    */
   load_disk(disk_image: Uint8Array): void;
+  /**
+   * Get the number of harts configured.
+   */
+  num_harts(): number;
+}
+
+declare class WorkerState {
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Execute a batch of instructions and return.
+   * 
+   * This is designed to be called repeatedly from JavaScript, allowing
+   * the event loop to yield between batches. This prevents the worker
+   * from blocking indefinitely and allows it to respond to messages.
+   *
+   * Returns a WorkerStepResult indicating whether to continue, halt, etc.
+   */
+  step_batch(batch_size: number): WorkerStepResult;
+  /**
+   * Get the total step count.
+   */
+  step_count(): bigint;
+  /**
+   * Create a new worker state for a secondary hart.
+   */
+  constructor(hart_id: number, shared_mem: any, entry_pc: bigint);
+  /**
+   * Get the hart ID.
+   */
+  hart_id(): number;
+}
+
+/**
+ * Result of executing a batch of instructions.
+ */
+declare enum WorkerStepResult {
+  /**
+   * Continue executing - call step_batch again
+   */
+  Continue = 0,
+  /**
+   * Halt requested via control region
+   */
+  Halted = 1,
+  /**
+   * Shutdown requested by guest (RequestedTrap)
+   */
+  Shutdown = 2,
+  /**
+   * Fatal error occurred
+   */
+  Error = 3,
 }
 
 /**
- * Worker entry point, called from JavaScript.
+ * Check interrupts for this hart using the shared CLINT.
  *
- * # Arguments
- * * `hart_id` - This worker's hart ID (1, 2, 3, ...)
- * * `shared_mem` - SharedArrayBuffer containing DRAM
- * * `entry_pc` - Kernel entry point address
+ * This is called periodically by the worker to check for:
+ * - Software interrupts (IPI via MSIP)
+ * - Timer interrupts (MTIP)
+ */
+declare function worker_check_interrupts(hart_id: number, shared_mem: any): bigint;
+
+/**
+ * Legacy worker entry point - DEPRECATED.
+ * 
+ * This function runs a blocking infinite loop. Use WorkerState + step_batch instead
+ * for cooperative scheduling that doesn't block the worker's event loop.
  */
 declare function worker_entry(hart_id: number, shared_mem: any, entry_pc: bigint): void;
 
@@ -103,27 +246,48 @@ type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Modul
 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 wasmvm_connect_webtransport: (a: number, b: number, c: number, d: number, e: number) => [number, number];
   readonly wasmvm_disconnect_network: (a: number) => void;
+  readonly wasmvm_external_network_rx_pending: (a: number) => number;
+  readonly wasmvm_external_network_tx_pending: (a: number) => number;
+  readonly wasmvm_extract_all_network_packets: (a: number) => any;
+  readonly wasmvm_extract_network_packet: (a: number) => any;
   readonly wasmvm_get_memory_usage: (a: number) => bigint;
   readonly wasmvm_get_output: (a: number) => number;
+  readonly wasmvm_get_shared_buffer: (a: number) => any;
   readonly wasmvm_halt_code: (a: number) => bigint;
+  readonly wasmvm_inject_network_packet: (a: number, b: any) => number;
   readonly wasmvm_input: (a: number, b: number) => void;
+  readonly wasmvm_is_external_network_connected: (a: number) => number;
   readonly wasmvm_is_halted: (a: number) => number;
+  readonly wasmvm_is_smp: (a: number) => number;
   readonly wasmvm_load_disk: (a: number, b: number, c: number) => void;
   readonly wasmvm_network_status: (a: number) => number;
   readonly wasmvm_new: (a: number, b: number) => [number, number, number];
+  readonly wasmvm_new_with_harts: (a: number, b: number, c: number) => [number, number, number];
+  readonly wasmvm_num_harts: (a: number) => number;
   readonly wasmvm_print_banner: (a: number) => void;
   readonly wasmvm_print_status: (a: number, b: number, c: number) => void;
+  readonly wasmvm_set_external_network_ip: (a: number, b: any) => number;
+  readonly wasmvm_setup_external_network: (a: number, b: any) => [number, number];
+  readonly wasmvm_start_workers: (a: number, b: number, c: number) => [number, number];
   readonly wasmvm_step: (a: number) => number;
   readonly wasmvm_step_n: (a: number, b: number) => number;
+  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 wasm_bindgen__convert__closures_____invoke__h5a9b831ab69bf07a: (a: number, b: number) => void;
-  readonly wasm_bindgen__closure__destroy__h101a38767d457860: (a: number, b: number) => void;
-  readonly wasm_bindgen__convert__closures_____invoke__hc493fd296d4613a9: (a: number, b: number) => void;
+  readonly workerstate_hart_id: (a: number) => number;
+  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 wasm_bindgen__convert__closures_____invoke__hbde9876d0cea708c: (a: number, b: number, c: any) => void;
+  readonly wasm_bindgen__closure__destroy__h1a8abd1a91785820: (a: number, b: number) => void;
   readonly wasm_bindgen__convert__closures_____invoke__h39d3e89751b07765: (a: number, b: number, c: any) => void;
   readonly wasm_bindgen__closure__destroy__hf225e18fc5ab9bc1: (a: number, b: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__he7a35327fb096d07: (a: number, b: number) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__h749506e285e0c000: (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;
@@ -163,11 +327,64 @@ declare const __pkg_riscv_vm_NetworkStatus: typeof NetworkStatus;
 type __pkg_riscv_vm_SyncInitInput = SyncInitInput;
 type __pkg_riscv_vm_WasmVm = WasmVm;
 declare const __pkg_riscv_vm_WasmVm: typeof WasmVm;
+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_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, __wbg_init as default, __pkg_riscv_vm_initSync as initSync, __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, __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 };
+}
+
+/**
+ * Worker utility types and functions.
+ *
+ * This module contains only types and side-effect-free utility functions
+ * that can be safely imported in Node.js or browser environments.
+ *
+ * The actual worker entry point is in worker.ts (browser-only).
+ */
+/** Message sent from main thread to initialize the worker */
+interface WorkerInitMessage {
+    hartId: number;
+    /** SharedArrayBuffer containing control + CLINT + DRAM */
+    sharedMem: SharedArrayBuffer;
+    entryPc: number;
 }
+/** Message sent when worker is ready to execute */
+interface WorkerReadyMessage {
+    type: "ready";
+    hartId: number;
+}
+/** Message sent when worker has halted */
+interface WorkerHaltedMessage {
+    type: "halted";
+    hartId: number;
+    stepCount?: number;
+}
+/** Message sent when an error occurs */
+interface WorkerErrorMessage {
+    type: "error";
+    hartId?: number;
+    error: string;
+}
+type WorkerOutboundMessage = WorkerReadyMessage | WorkerHaltedMessage | WorkerErrorMessage;
+/**
+ * Check if halt has been requested in the shared control region.
+ * This can be used for JS-side polling if needed.
+ */
+declare function isHaltRequested(sharedMem: SharedArrayBuffer): boolean;
+/**
+ * Request halt by setting the flag in shared memory.
+ * This can be called from any thread.
+ */
+declare function requestHalt(sharedMem: SharedArrayBuffer): void;
+/**
+ * Check if VM has halted.
+ */
+declare function isHalted(sharedMem: SharedArrayBuffer): boolean;
 
 declare function WasmInternal(): Promise<typeof __pkg_riscv_vm>;
 
@@ -178,7 +395,10 @@ interface VmOptions {
     workerScript?: string;
 }
 /**
- * Create a VM instance and optionally start workers for multi-hart execution.
+ * Create a VM instance with optional SMP support.
+ *
+ * If SharedArrayBuffer is available (requires COOP/COEP headers), the VM
+ * will run in true parallel mode with Web Workers for secondary harts.
  *
  * @param kernelData - ELF kernel binary
  * @param options - VM configuration options
@@ -188,6 +408,9 @@ declare function createVM(kernelData: Uint8Array, options?: VmOptions): Promise<
 /**
  * Run the VM with an output callback for UART data.
  *
+ * This function manages the main execution loop, stepping hart 0 on the
+ * main thread. Secondary harts (if any) run in Web Workers.
+ *
  * @param vm - WasmVm instance
  * @param onOutput - Callback for each character output
  * @param options - Run options
@@ -198,6 +421,7 @@ declare function runVM(vm: WasmVm, onOutput: (char: string) => void, options?: {
 }): () => void;
 interface SharedMemorySupport {
     supported: boolean;
+    crossOriginIsolated: boolean;
     message: string;
 }
 /**
@@ -211,5 +435,41 @@ declare function checkSharedMemorySupport(): SharedMemorySupport;
  * Check if the page is cross-origin isolated (required for SharedArrayBuffer).
  */
 declare function isCrossOriginIsolated(): boolean;
+/**
+ * Headers required for SharedArrayBuffer support.
+ *
+ * For Vite dev server, add to vite.config.ts:
+ * ```ts
+ * server: {
+ *   headers: {
+ *     "Cross-Origin-Opener-Policy": "same-origin",
+ *     "Cross-Origin-Embedder-Policy": "require-corp",
+ *   },
+ * },
+ * ```
+ *
+ * For production, configure your web server to add these headers.
+ */
+declare const REQUIRED_HEADERS: {
+    readonly "Cross-Origin-Opener-Policy": "same-origin";
+    readonly "Cross-Origin-Embedder-Policy": "require-corp";
+};
+/**
+ * Manually create and manage workers for advanced use cases.
+ *
+ * Most users should use createVM() which handles workers automatically.
+ */
+interface WorkerManager {
+    /** Start a worker for a specific hart */
+    startWorker(hartId: number, sharedMem: SharedArrayBuffer, entryPc: number, workerScript?: string): Worker;
+    /** Terminate all workers */
+    terminateAll(): void;
+    /** Get number of active workers */
+    count(): number;
+}
+/**
+ * Create a worker manager for manual worker control.
+ */
+declare function createWorkerManager(): WorkerManager;
 
-export { NetworkStatus, type SharedMemorySupport, type VmOptions, WasmInternal, WasmVm, checkSharedMemorySupport, createVM, isCrossOriginIsolated, runVM };
+export { NetworkStatus, REQUIRED_HEADERS, type SharedMemorySupport, type VmOptions, WasmInternal, WasmVm, type WorkerErrorMessage, type WorkerHaltedMessage, type WorkerInitMessage, type WorkerManager, type WorkerOutboundMessage, type WorkerReadyMessage, checkSharedMemorySupport, createVM, createWorkerManager, isCrossOriginIsolated, isHaltRequested, isHalted, requestHalt, runVM };