virtual-machine 0.2.2 → 0.3.1

package/build/index.d.ts

@@ -15,17 +15,17 @@ declare class WasmVm {
   free(): void;
   [Symbol.dispose](): void;
   /**
-   * Enable VirtIO GPU device for graphics rendering.
+   * Enable D1 Display device for graphics rendering.
    *
-   * The GPU device allows the kernel to render to a framebuffer which can
+   * The display device allows the kernel to render to a framebuffer which can
    * then be displayed in a Canvas element. Use `get_gpu_frame()` to retrieve
    * the rendered frame pixels.
    *
    * # Arguments
-   * * `width` - Display width in pixels (default 800 if 0)
-   * * `height` - Display height in pixels (default 600 if 0)
+   * * `width` - Display width in pixels (ignored, uses 1024x768)
+   * * `height` - Display height in pixels (ignored, uses 1024x768)
    */
-  enable_gpu(width: number, height: number): void;
+  enable_gpu(_width: number, _height: number): void;
   /**
    * Get a byte from the UART output buffer, if available.
    *
@@ -62,7 +62,7 @@ declare class WasmVm {
    * Get GPU frame data as RGBA pixels.
    * Returns a Uint8Array of pixel data, or null if no frame is available.
    *
-   * The frame data is in RGBA format with 4 bytes per pixel (800x600 = 1,920,000 bytes).
+   * The frame data is in RGBA format with 4 bytes per pixel (1024×768 = 3,145,728 bytes).
    * 
    * This reads from a fixed framebuffer address in guest memory (0x8100_0000).
    * The kernel GPU driver writes pixels there, and we read them here.
@@ -101,7 +101,7 @@ declare class WasmVm {
   get_heap_usage(): Array<any>;
   /**
    * Get the current network connection status.
-   * This checks the actual connection state by seeing if an IP was assigned.
+   * This checks the actual connection state by seeing if D1 EMAC is enabled.
    */
   network_status(): NetworkStatus;
   /**
@@ -126,6 +126,29 @@ declare class WasmVm {
    * Get current memory usage (DRAM size) in bytes.
    */
   get_memory_usage(): bigint;
+  /**
+   * Send a mouse event to the guest.
+   *
+   * # Arguments
+   * * `x` - X position (0-799)
+   * * `y` - Y position (0-599)
+   * * `buttons` - Button state bitmask (bit 0 = left, bit 1 = right, bit 2 = middle)
+   * * `prev_buttons` - Previous button state to detect changes
+   *
+   * Returns true if the event was sent successfully.
+   */
+  send_mouse_event(x: number, y: number, buttons: number): boolean;
+  /**
+   * Send a touch event to the D1 GT911 touchscreen controller.
+   *
+   * # Arguments
+   * * `x` - X position (0 to display width)
+   * * `y` - Y position (0 to display height)
+   * * `pressed` - true for touch down/move, false for touch up
+   *
+   * Returns true if the event was sent successfully.
+   */
+  send_touch_event(x: number, y: number, pressed: boolean): boolean;
   /**
    * Get the total disk capacity from attached VirtIO block devices.
    * Returns total bytes across all block devices.
@@ -136,6 +159,14 @@ declare class WasmVm {
    * Returns None if not in SMP mode.
    */
   get_shared_buffer(): SharedArrayBuffer | undefined;
+  /**
+   * Send a mouse button event to the guest.
+   *
+   * # Arguments
+   * * `button` - Button number (0 = left, 1 = right, 2 = middle)
+   * * `pressed` - true for press, false for release
+   */
+  send_mouse_button(button: number, pressed: boolean): boolean;
   /**
    * Terminate all workers.
    */
@@ -154,6 +185,22 @@ declare class WasmVm {
    * Note: Connection is asynchronous. Check network_status() to monitor connection state.
    */
   connect_webtransport(url: string, cert_hash?: string | null): void;
+  /**
+   * 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).
+   */
+  get_framebuffer_view(): Uint8Array | undefined;
+  /**
+   * Get the current frame version from kernel memory.
+   * Returns a u32 that increments each time the kernel flushes dirty pixels.
+   * Browser can compare this to skip fetching unchanged frames.
+   */
+  get_gpu_frame_version(): number;
   /**
    * Inject a network packet to be received by the guest.
    * Called from JavaScript when the native WebTransport addon receives a packet.
@@ -250,7 +297,7 @@ declare class WasmVm {
    */
   is_halted(): boolean;
   /**
-   * Load a disk image and attach it as a VirtIO block device.
+   * Load a disk image and attach it as a D1 MMC device.
    * This should be called before starting execution if the kernel needs a filesystem.
    */
   load_disk(disk_image: Uint8Array): void;
@@ -282,10 +329,22 @@ declare class WorkerState {
    * Get the total step count.
    */
   step_count(): bigint;
+  /**
+   * Check if MSIP is pending for this hart (for debugging).
+   */
+  is_msip_pending(): boolean;
+  /**
+   * Check if timer is pending for this hart (for debugging).
+   */
+  is_timer_pending(): boolean;
   /**
    * Create a new worker state for a secondary hart.
    */
   constructor(hart_id: number, shared_mem: any, entry_pc: bigint);
+  /**
+   * Get the a0 register value (for debugging hart ID passing).
+   */
+  get_a0(): bigint;
   /**
    * Get the hart ID.
    */
@@ -312,6 +371,11 @@ declare enum WorkerStepResult {
    * Fatal error occurred
    */
   Error = 3,
+  /**
+   * WFI executed - worker should yield to prevent busy loop
+   * TypeScript should add a small delay before calling step_batch again
+   */
+  Wfi = 4,
 }
 
 /**
@@ -350,7 +414,9 @@ interface InitOutput {
   readonly wasmvm_get_cpu_count: (a: number) => number;
   readonly wasmvm_get_disk_capacity: (a: number) => bigint;
   readonly wasmvm_get_disk_usage: (a: number) => any;
+  readonly wasmvm_get_framebuffer_view: (a: number) => any;
   readonly wasmvm_get_gpu_frame: (a: number) => any;
+  readonly wasmvm_get_gpu_frame_version: (a: number) => number;
   readonly wasmvm_get_gpu_size: (a: number) => any;
   readonly wasmvm_get_heap_usage: (a: number) => any;
   readonly wasmvm_get_memory_usage: (a: number) => bigint;
@@ -372,6 +438,9 @@ interface InitOutput {
   readonly wasmvm_print_banner: (a: number) => void;
   readonly wasmvm_print_status: (a: number, b: number, c: number) => void;
   readonly wasmvm_send_key_event: (a: number, b: number, c: number) => number;
+  readonly wasmvm_send_mouse_button: (a: number, b: number, c: number) => number;
+  readonly wasmvm_send_mouse_event: (a: number, b: number, c: number, d: number) => number;
+  readonly wasmvm_send_touch_event: (a: number, b: number, c: number, d: number) => number;
   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];
@@ -380,17 +449,16 @@ 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;
+  readonly workerstate_is_timer_pending: (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__h74d7f37f0b0d661d: (a: number, b: number, c: any) => void;
-  readonly wasm_bindgen__closure__destroy__h01c75dc83ec8dfae: (a: number, b: number) => void;
-  readonly wasm_bindgen__convert__closures_____invoke__h9f0ee31d317d33d7: (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__h97b9bec6245a8424: (a: number, b: number) => void;
+  readonly worker_entry: (a: number, b: any, c: bigint) => void;
+  readonly wasm_bindgen__convert__closures_____invoke__hfbd40044a7a1ae85: (a: number, b: number, c: any) => void;
+  readonly wasm_bindgen__closure__destroy__h4b145e497aa7828d: (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;
@@ -513,6 +581,37 @@ interface VmOptions {
  * @returns WasmVm instance
  */
 declare function createVM(kernelData: Uint8Array, options?: VmOptions): Promise<WasmVm>;
+interface SDBootInfo {
+    kernelData: Uint8Array;
+    sdcardData: Uint8Array;
+    fsPartitionStart: number;
+}
+/**
+ * Parse an SD card image to extract kernel from FAT32 boot partition.
+ *
+ * SD Card layout:
+ * - MBR with partition table
+ * - Partition 1 (FAT32): kernel.bin
+ * - Partition 2: SFS filesystem
+ */
+declare function parseSDCard(sdcard: Uint8Array): SDBootInfo;
+/**
+ * Fetch an SD card image from a URL for browser use.
+ *
+ * @param url - URL to fetch SD card image from
+ * @returns Parsed boot info with kernel and disk data
+ */
+declare function loadSDCardFromUrl(url: string): Promise<SDBootInfo>;
+/**
+ * Create a VM from an SD card image (fetched from URL).
+ *
+ * This is the recommended way to boot the VM in browser.
+ *
+ * @param sdcardUrl - URL to SD card image
+ * @param options - VM configuration options
+ * @returns WasmVm instance ready to run
+ */
+declare function createVMFromSDCard(sdcardUrl: string, options?: VmOptions): Promise<WasmVm>;
 /**
  * Run the VM with an output callback for UART data.
  *
@@ -580,4 +679,4 @@ interface WorkerManager {
  */
 declare function createWorkerManager(): WorkerManager;
 
-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 };
+export { NetworkStatus, REQUIRED_HEADERS, type SharedMemorySupport, type VmOptions, WasmInternal, WasmVm, type WorkerErrorMessage, type WorkerHaltedMessage, type WorkerInitMessage, type WorkerManager, type WorkerOutboundMessage, type WorkerReadyMessage, checkSharedMemorySupport, createVM, createVMFromSDCard, createWorkerManager, isCrossOriginIsolated, isHaltRequested, isHalted, loadSDCardFromUrl, parseSDCard, requestHalt, runVM };