From 0f51179a3d33d3acf2fa1d2d672cc5e8d04c09ec Mon Sep 17 00:00:00 2001 From: Sean McBride Date: Mon, 22 Jun 2026 22:04:30 -0400 Subject: [PATCH] docs: document that modules must be WASI modules (#329) SLEdge assumes every module it loads is a WASI module that uses linear memory, but this assumption was undocumented. The runtime already validates it during dlopen: a non-WASI / no-linear-memory module fails because its aWsm-generated memory symbols (sledge_abi__init_mem, sledge_abi__wasm_memory_starting_pages/_max_pages) don't resolve. Document the requirement in docs/WASI.md: modules must be WASI modules compiled by aWsm and linked against libsledge, linear memory is mandatory, why wasi_snapshot_preview1_* symbol presence is not a useful WASI signal (whole-archive exports), and the --runtime-globals situation. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/WASI.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/WASI.md b/docs/WASI.md index c52ca70c3..fcc050f4b 100644 --- a/docs/WASI.md +++ b/docs/WASI.md @@ -1,5 +1,20 @@ SLEdge only implemented a subset of the WASI syscall interface +## Module Requirements and Assumptions + +SLEdge assumes that every module it loads is a **WASI module** compiled by aWsm and linked against `libsledge`. aWsm can also emit WebAssembly outside the WASI spec (for example, modules that do not use linear memory), but such modules are **not** supported by SLEdge. + +Concretely, a module must satisfy the following to run: + +- **WASI, compiled by aWsm.** A module is produced by running aWsm over a `*.wasm` file to emit `*.bc`, then linking that `*.bc` with `libsledge` into a `*.wasm.so` (see `applications/Makefile`). The runtime `dlopen`s the resulting `*.so` and resolves the aWsm-generated `sledge_abi__*` symbols (see `runtime/include/sledge_abi_symbols.h`). +- **Linear memory is mandatory.** SLEdge's entire I/O model lives in the module's linear memory: the body of an inbound HTTP request is copied into the module's view of stdin, and stdout/stderr are read back out of linear memory to form the response (see "File System" below). A module that does not use linear memory cannot exchange data with the runtime and is rejected at load time, because its aWsm-generated memory symbols (`sledge_abi__init_mem`, `sledge_abi__wasm_memory_starting_pages`, `sledge_abi__wasm_memory_max_pages`) are absent. + +Note that the presence of the `wasi_snapshot_preview1_*` import shims is *not* a useful signal of WASI-ness: those symbols are provided by `libsledge` and are unconditionally exported from every `*.so` via `--whole-archive --export-dynamic`, regardless of which WASI calls the module actually imports. Validation therefore keys off the aWsm-generated module symbols, not the WASI import shims. + +### `--runtime-globals` + +The `sledge_abi__init_globals` symbol is only emitted when aWsm is run with the `--runtime-globals` flag. SLEdge tolerates its absence (globals are then inlined as constants by aWsm), so this symbol is resolved but not required. The "correct" configuration for SLEdge has not been settled; `applications/Makefile` currently builds with `--runtime-globals`. + ## Arguments The WASI calls `args_sizes_get` and `args_get` are supported. HTTP query parameters are captured and passed as arguments.