Enable System Emulation in Web Browsers

User-space emulation has been supported and deployable in WebAssembly
since #389, but system emulation was not yet available. With #508,
system emulation was introduced, and later #551 added support for
trap-and-emulate of guest Linux SDL syscalls, enabling offloading to the
host’s SDL backend. This commit bridges these components together to
enable full system emulation in the browser.

xterm.js is leveraged as the frontend terminal, bridged with the backend
VM shell through a custom buffer management mechanism. This mechanism
handles both standard ASCII input and escape sequences (such as arrow
keys), providing a shell experience in the browser that closely
resembles a real terminal.

To handle terminal input without blocking the browser’s cooperative
multitasking model, the original approach of mapping the read()
system call to window.prompt() is avoided. Blocking behavior would
freeze the browser’s event loop and degrade responsiveness. Instead,
input from xterm.js is stored in a shared input buffer. The rv32emu
periodically checks this buffer when handling external interrupts, and
if input is available, it is read and consumed by the guest OS shell.

The SDL graphic and sound backend are also supported. After booting the
guest Linux system, users can run graphical applications such as
doom-riscv, quake, or smolnes. These programs can be exited using
Ctrl+C or their built-in exit funtionality.

To reduce the size of the WebAssembly build and for the sake of the
modularity, the project is now separated into user and system targets.
As a result, two dedicated HTML files and corresponding preload
JavaScript files are introduced:
- user.html with user-pre.js
- system.html with system-pre.js

Navigation buttons are added to the index pages of both user and system
demos, allowing users to switch easily between the two modes.
Note that these navigation buttons are only functional when both user
and system demos are deployed together, otherwise, the target pages may
not be reachable.
To improve usability, logic is implemented to disable and enable the
"Run" button at appropriate times, preventing accidental re-execution
when the process is already running.

Additional improvements:
- Ensure xterm.js uses \r\n instead of \n when logging to correctly move
the cursor to the beginning of the line.
- Add a new src/emsc.h header to store Emscripten-related variables and
function declarations for better management.

This implementation has been tested on the latest versions of Chrome,
Firefox, and Safari.

To serve user space emulation index page:
$ make start-web CC=emcc ENABLE_SDL=1 -j8

To serve system emulation index page:
$ make start-web CC=emcc ENABLE_SYSTEM=1 ENABLE_SDL=1 INITRD_SIZE=32 -j8

Author: ChinYikMing

Makefile

@@ -286,8 +286,8 @@ $(OUT)/emulate.o: CFLAGS += -foptimize-sibling-calls -fomit-frame-pointer -fno-s
 
 include mk/external.mk
 include mk/artifact.mk
-include mk/wasm.mk
 include mk/system.mk
+include mk/wasm.mk
 
 all: config $(BUILD_DTB) $(BUILD_DTB2C) $(BIN)
 

assets/wasm/html/system.html

@@ -121,6 +121,10 @@
     </select>
     <button id="runButton">Run</button>
 
+    <button id="toSysEmuButton">
+      🚀 Navigate to System Emulation
+    </button>
+
     <div class="emscripten">
       <progress value="0" max="100" id="progress" hidden=1></progress>
     </div>
@@ -137,6 +141,13 @@
       var spinnerElement = document.getElementById('spinner');
       var runButton = document.getElementById("runButton");
       runButton.addEventListener("click", runButtonClickHandler);
+      var toSysEmuButton = document.getElementById("toSysEmuButton");
+      toSysEmuButton.addEventListener("click", toSysEmuButtonClickHandler);
+
+      function toSysEmuButtonClickHandler() {
+        console.log("Navigate to system emulation");
+	window.location.href = "/system"
+      }
 
       var elfDropdown = document.getElementById("elfDropdown");
       for (var i = 0; i < elfFiles.length; i++) {
@@ -163,11 +174,7 @@
           element.scrollTop = element.scrollHeight;
         }
         Module._indirect_rv_halt();
-        /* important to add some delay for waiting cancellation of main loop before next run */
-        /* Otherwise, get error: only one main loop can be existed */
-        setTimeout(() => {
-          Module['onRuntimeInitialized'](target_elf);
-        }, 1000);
+        Module['run_user'](target_elf);
       }
 
       var Module = {

assets/wasm/html/index.html renamed to assets/wasm/html/user.html

@@ -0,0 +1,65 @@
+Module["noInitialRun"] = true;
+
+Module["run_system"] = function (cli_param) {
+  callMain(cli_param.split(" "));
+};
+
+// index.html's preRun needs to access this, thus declaring as global
+let term;
+
+Module["onRuntimeInitialized"] = function () {
+  const input_buf_ptr = Module._get_input_buf();
+  const input_buf_cap = Module._get_input_buf_cap();
+
+  term = new Terminal({
+    cols: 120,
+    rows: 11,
+  });
+  term.open(document.getElementById("terminal"));
+
+  term.onKey(({ key, domEvent }) => {
+    const code = key.charCodeAt(0);
+    let sequence;
+
+    switch (domEvent.key) {
+      case "ArrowUp":
+        // ESC [ A → "\x1B[A"
+        sequence = "\x1B[A";
+        break;
+      case "ArrowDown":
+        // ESC [ B → "\x1B[B"
+        sequence = "\x1B[B";
+        break;
+      case "ArrowRight":
+        // ESC [ C → "\x1B[C"
+        sequence = "\x1B[C";
+        break;
+      case "ArrowLeft":
+        // ESC [ D → "\x1B[D"
+        sequence = "\x1B[D";
+        break;
+      // TODO: support more escape keys?
+      default:
+        sequence = key;
+        break;
+    }
+
+    let heap = new Uint8Array(
+      Module.HEAPU8.buffer,
+      input_buf_ptr,
+      sequence.length,
+    );
+
+    for (let i = 0; i < sequence.length && i < input_buf_cap; i++) {
+      heap[i] = sequence.charCodeAt(i);
+    }
+    // Fill zero
+    for (let i = sequence.length; i < input_buf_cap; i++) {
+      heap[i] = 0;
+    }
+
+    Module._set_input_buf_size(sequence.length);
+
+    term.scrollToBottom();
+  });
+};

assets/wasm/js/pre.js

@@ -0,0 +1,10 @@
+Module["noInitialRun"] = true;
+
+Module["run_user"] = function (target_elf) {
+  if (target_elf === undefined) {
+    console.warn("target elf executable is undefined");
+    return;
+  }
+
+  callMain([target_elf]);
+};

assets/wasm/js/system-pre.js

@@ -3,7 +3,7 @@ deps_emcc :=
 ASSETS := assets/wasm
 WEB_HTML_RESOURCES := $(ASSETS)/html
 WEB_JS_RESOURCES := $(ASSETS)/js
-EXPORTED_FUNCS := _main,_indirect_rv_halt
+EXPORTED_FUNCS := _main,_indirect_rv_halt,_get_input_buf,_get_input_buf_cap,_set_input_buf_size
 DEMO_DIR := demo
 WEB_FILES := $(BIN).js \
              $(BIN).wasm \
@@ -29,7 +29,19 @@ CFLAGS_emcc += -sINITIAL_MEMORY=2GB \
 	       -s"EXPORTED_FUNCTIONS=$(EXPORTED_FUNCS)" \
 	       -sSTACK_SIZE=4MB \
 	       -sPTHREAD_POOL_SIZE=navigator.hardwareConcurrency \
-	       --embed-file build/jit-bf.elf@/jit-bf.elf \
+	       --embed-file build/timidity@/etc/timidity \
+	       -DMEM_SIZE=0x20000000 \
+	       -DCYCLE_PER_STEP=2000000 \
+	       -O3 \
+	       -w
+
+ifeq ($(call has, SYSTEM), 1)
+CFLAGS_emcc += --embed-file build/linux-image/Image@Image \
+	       --embed-file build/linux-image/[email protected] \
+	       --embed-file build/minimal.dtb@/minimal.dtb \
+	       --pre-js $(WEB_JS_RESOURCES)/system-pre.js
+else
+CFLAGS_emcc += --embed-file build/jit-bf.elf@/jit-bf.elf \
 	       --embed-file build/coro.elf@/coro.elf \
 	       --embed-file build/fibonacci.elf@/fibonacci.elf \
 	       --embed-file build/hello.elf@/hello.elf \
@@ -40,12 +52,9 @@ CFLAGS_emcc += -sINITIAL_MEMORY=2GB \
 	       --embed-file build/riscv32@/riscv32 \
 	       --embed-file build/DOOM1.WAD@/DOOM1.WAD \
 	       --embed-file build/id1/pak0.pak@/id1/pak0.pak \
-	       --embed-file build/timidity@/etc/timidity \
-	       -DMEM_SIZE=0x60000000 \
-	       -DCYCLE_PER_STEP=2000000 \
-	       --pre-js $(WEB_JS_RESOURCES)/pre.js \
-	       -O3 \
-	       -w
+	       --pre-js $(WEB_JS_RESOURCES)/user-pre.js
+endif
+
 
 $(OUT)/elf_list.js: tools/gen-elf-list-js.py
 	$(Q)tools/gen-elf-list-js.py > $@
@@ -132,11 +141,22 @@ define cp-web-file
 endef
 
 # WEB_FILES could be cleaned and recompiled, thus do not mix these two files into WEB_FILES
-STATIC_WEB_FILES := $(WEB_HTML_RESOURCES)/index.html \
-		    $(WEB_JS_RESOURCES)/coi-serviceworker.min.js
+STATIC_WEB_FILES := $(WEB_JS_RESOURCES)/coi-serviceworker.min.js
+ifeq ($(call has, SYSTEM), 1)
+STATIC_WEB_FILES += $(WEB_HTML_RESOURCES)/system.html
+else
+STATIC_WEB_FILES += $(WEB_HTML_RESOURCES)/user.html
+endif
+
+start_web_deps := check-demo-dir-exist $(BIN)
+ifeq ($(call has, SYSTEM), 1)
+start_web_deps += $(BUILD_DTB) $(BUILD_DTB2C)
+endif
 
-start-web: check-demo-dir-exist $(BIN)
+start-web: $(start_web_deps)
+	$(Q)rm -f $(DEMO_DIR)/*.html
 	$(foreach T, $(WEB_FILES), $(call cp-web-file, $(T)))
 	$(foreach T, $(STATIC_WEB_FILES), $(call cp-web-file, $(T)))
+	$(Q)mv $(DEMO_DIR)/*.html $(DEMO_DIR)/index.html
 	$(Q)python3 -m http.server --bind $(DEMO_IP) $(DEMO_PORT) --directory $(DEMO_DIR)
 endif

assets/wasm/js/user-pre.js

@@ -5,12 +5,17 @@
 
 #include <assert.h>
 #include <errno.h>
+#include <fcntl.h>
 #include <poll.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
 
+#if defined(__EMSCRIPTEN__)
+#include "emsc.h"
+#endif
+
 #include "uart.h"
 /* Emulate 8250 (plain, without loopback mode support) */
 
@@ -33,15 +38,42 @@ void u8250_update_interrupts(u8250_state_t *uart)
         uart->current_intr = ilog2(uart->pending_intrs);
 }
 
+#if defined(__EMSCRIPTEN__)
+#define INPUT_BUF_MAX_CAP 16
+static char input_buf[INPUT_BUF_MAX_CAP];
+static uint8_t input_buf_start = 0;
+uint8_t input_buf_size = 0;
+
+char *get_input_buf()
+{
+    return input_buf;
+}
+
+uint8_t get_input_buf_cap()
+{
+    return INPUT_BUF_MAX_CAP;
+}
+
+void set_input_buf_size(uint8_t size)
+{
+    input_buf_size = size;
+}
+#endif
+
 void u8250_check_ready(u8250_state_t *uart)
 {
     if (uart->in_ready)
         return;
 
+#if defined(__EMSCRIPTEN__)
+    if (input_buf_size)
+        uart->in_ready = true;
+#else
     struct pollfd pfd = {uart->in_fd, POLLIN, 0};
     poll(&pfd, 1, 0);
     if (pfd.revents & POLLIN)
         uart->in_ready = true;
+#endif
 }
 
 static void u8250_handle_out(u8250_state_t *uart, uint8_t value)
@@ -57,12 +89,19 @@ static uint8_t u8250_handle_in(u8250_state_t *uart)
     if (!uart->in_ready)
         return value;
 
+#if defined(__EMSCRIPTEN__)
+    value = (uint8_t) input_buf[input_buf_start];
+    input_buf_start++;
+    if (--input_buf_size == 0)
+        input_buf_start = 0;
+#else
     if (read(uart->in_fd, &value, 1) < 0)
         rv_log_error("Failed to read UART input: %s", strerror(errno));
+#endif
     uart->in_ready = false;
-    u8250_check_ready(uart);
 
-    if (value == 1) {           /* start of heading (Ctrl-a) */
+    if (value == 1) { /* start of heading (Ctrl-a) */
+        u8250_check_ready(uart);
         if (getchar() == 120) { /* keyboard x */
             rv_log_info("RISC-V emulator is destroyed");
             exit(EXIT_SUCCESS);

mk/wasm.mk

@@ -0,0 +1,18 @@
+/*
+ * rv32emu is freely redistributable under the MIT License. See the file
+ * "LICENSE" for information on usage and redistribution of this file.
+ */
+
+#pragma once
+
+#include <emscripten.h>
+
+void indirect_rv_halt();
+
+#if RV32_HAS(SYSTEM) && !RV32_HAS(ELF_LOADER)
+extern uint8_t input_buf_size;
+
+char *get_input_buf();
+uint8_t get_input_buf_cap();
+void set_input_buf_size(uint8_t size);
+#endif

src/devices/uart.c

@@ -10,10 +10,6 @@
 #include <stdlib.h>
 #include <string.h>
 
-#ifdef __EMSCRIPTEN__
-#include <emscripten.h>
-#endif
-
 #if RV32_HAS(EXT_F)
 #include <math.h>
 #include "softfp.h"
@@ -23,6 +19,19 @@
 extern struct target_ops gdbstub_ops;
 #endif
 
+#if defined(__EMSCRIPTEN__)
+#include "emsc.h"
+#if RV32_HAS(SYSTEM)
+EM_JS(void, enable_run_button, (), {
+    document.getElementById('runSysButton').disabled = false;
+});
+#else
+EM_JS(void, enable_run_button, (), {
+    document.getElementById('runButton').disabled = false;
+});
+#endif
+#endif
+
 #include "decode.h"
 #include "mpool.h"
 #include "riscv.h"
@@ -1009,6 +1018,9 @@ static void rv_check_interrupt(riscv_t *rv)
     if (peripheral_update_ctr-- == 0) {
         peripheral_update_ctr = 64;
 
+#if defined(__EMSCRIPTEN__)
+    escape_seq:
+#endif
         u8250_check_ready(PRIV(rv)->uart);
         if (PRIV(rv)->uart->in_ready)
             emu_update_uart_interrupts(rv);
@@ -1031,6 +1043,11 @@ static void rv_check_interrupt(riscv_t *rv)
             break;
         case (SUPERVISOR_EXTERNAL_INTR & 0xf):
             SET_CAUSE_AND_TVAL_THEN_TRAP(rv, SUPERVISOR_EXTERNAL_INTR, 0);
+#if defined(__EMSCRIPTEN__)
+            /* escape sequence has more than 1 byte */
+            if (input_buf_size)
+                goto escape_seq;
+#endif
             break;
         default:
             break;
@@ -1174,6 +1191,7 @@ void rv_step(void *arg)
         emscripten_cancel_main_loop();
         rv_delete(rv); /* clean up and reuse memory */
         rv_log_info("RISC-V emulator is destroyed");
+        enable_run_button();
     }
 #endif
 }