Reference

Host API

The RISC-V runner keeps the boundary between guest and host deliberately small: a handful of WASM imports and around thirty exports.

Imports (host → guest)

The module asks the host for very little — shared memory, a way to write console output, and sources of entropy and wall-clock time. Filesystem work is signalled through a status code and a shared-memory request block, not a dedicated import.

Import

Role

memory

shared linear memory (SharedArrayBuffer)

console_write(fd, ptr, len)

write bytes to stdout / stderr

debug_log(val)

diagnostic logging

abort_js()

abort execution (panic handler)

emscripten_random()

entropy for getrandom

emscripten_date_now()

wall-clock time for clocks and timerfds

Exports (guest → host)

Lifecycle — create, reset and step the VM.
Memory — read and write guest memory regions.
Execution — run until the next syscall boundary or trap.
FS protocol — inspect and complete a pending FS request.

The FS_PENDING protocol

Rather than a callback per file operation, the guest writes a request into a shared memory region and raises fs_pending. The host reads the request, performs the I/O against MemFS, writes the result back, and resumes execution. This keeps the hot path free of host round-trips.

javascript

// host side, simplified
while (vm.run() === FS_PENDING) {
  const req = vm.readFsRequest();
  const res = memfs.handle(req);
  vm.writeFsResult(res);
}

← Previous

Syscalls

Networking