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. Now, it is time to bridge all these components
together.

Leverage xterm.js as the frontend terminal in the web browser and bridge
it with the backend VM shell through custom buffer management. 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.

The SDL backend is also supported. After booting the guest Linux system,
can run doom-riscv, quake, or smolnes to experience graphical
applications. Can press Ctrl+C to exit SDL-based programs, or use their
built-in exit commands.

To reduce the size of the WASM file, the build is now separated into
user and system targets.
As a result, there are two HTML files:
- user.html
- system.html
and two corresponding preload JavaScript:
- user-pre.js
- system-pre.js

Tested on latest Chrome, Firefox and Safari.

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

@@ -166,7 +166,7 @@
         /* 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);
+          Module['run_user'](target_elf);
         }, 1000);
       }
 

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

@@ -0,0 +1,66 @@
+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 (target_elf) {
+  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);
+    Module._set_input_buf_avail(true);
+
+    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_avail,_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>
 
+#ifdef __EMSCRIPTEN__
+#include <emscripten.h>
+#endif
+
 #include "uart.h"
 /* Emulate 8250 (plain, without loopback mode support) */
 
@@ -33,15 +38,51 @@ void u8250_update_interrupts(u8250_state_t *uart)
         uart->current_intr = ilog2(uart->pending_intrs);
 }
 
+#if defined(__EMSCRIPTEN__)
+
+#define INPUT_BUF_MAX_CAP 128
+
+static char input_buf[INPUT_BUF_MAX_CAP];
+static uint8_t input_buf_size;
+static uint8_t input_buf_start = 0;
+bool is_input_buf_avail = false;
+
+char *get_input_buf()
+{
+    return input_buf;
+}
+
+uint8_t get_input_buf_cap()
+{
+    return INPUT_BUF_MAX_CAP;
+}
+
+void set_input_buf_avail(bool flag)
+{
+    is_input_buf_avail = flag;
+}
+
+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 (is_input_buf_avail)
+        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 +98,22 @@ 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;
+        set_input_buf_avail(false);
+    }
+#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

@@ -1003,12 +1003,19 @@ static bool rv_has_plic_trap(riscv_t *rv)
             (rv->csr_sip & rv->csr_sie));
 }
 
+#if defined(__EMSCRIPTEN__)
+extern bool is_input_buf_avail;
+#endif
+
 static void rv_check_interrupt(riscv_t *rv)
 {
     vm_attr_t *attr = PRIV(rv);
     if (peripheral_update_ctr-- == 0) {
         peripheral_update_ctr = 64;
 
+#if defined(__EMSCRIPTEN__)
+    escape:
+#endif
         u8250_check_ready(PRIV(rv)->uart);
         if (PRIV(rv)->uart->in_ready)
             emu_update_uart_interrupts(rv);
@@ -1031,6 +1038,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 character has more than 1 byte */
+            if (is_input_buf_avail)
+                goto escape;
+#endif
             break;
         default:
             break;

src/devices/uart.c

@@ -234,7 +234,9 @@ static void map_file(char **ram_loc, const char *name)
     struct stat st;
     fstat(fd, &st);
 
-#if HAVE_MMAP
+// EMSCRIPTEN: We don't currently support location hints for the address of the mapping
+// https://github.com/emscripten-core/emscripten/blob/52bc455316b2f44d3a94104776a335a5861ad73b/system/lib/libc/emscripten_mmap.c#L105
+#if HAVE_MMAP && !defined(__EMSCRIPTEN__)
     /* remap to a memory region */
     *ram_loc = mmap(*ram_loc, st.st_size, PROT_READ | PROT_WRITE,
                     MAP_FIXED | MAP_PRIVATE, fd, 0);