diff --git a/doc/api/wasi.md b/doc/api/wasi.md index e9c39d868aa90f..95e212e3c2974b 100644 --- a/doc/api/wasi.md +++ b/doc/api/wasi.md @@ -22,15 +22,54 @@ const wasi = new WASI({ const importObject = { wasi_snapshot_preview1: wasi.wasiImport }; (async () => { - const wasm = await WebAssembly.compile(fs.readFileSync('./binary.wasm')); + const wasm = await WebAssembly.compile(fs.readFileSync('./demo.wasm')); const instance = await WebAssembly.instantiate(wasm, importObject); wasi.start(instance); })(); ``` +To run the above example, create a new WebAssembly text format file named +`demo.wat`: + +```text +(module + ;; Import the required fd_write WASI function which will write the given io vectors to stdout + ;; The function signature for fd_write is: + ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written + (import "wasi_snapshot_preview1" "fd_write" (func $fd_write (param i32 i32 i32 i32) (result i32))) + + (memory 1) + (export "memory" (memory 0)) + + ;; Write 'hello world\n' to memory at an offset of 8 bytes + ;; Note the trailing newline which is required for the text to appear + (data (i32.const 8) "hello world\n") + + (func $main (export "_start") + ;; Creating a new io vector within linear memory + (i32.store (i32.const 0) (i32.const 8)) ;; iov.iov_base - This is a pointer to the start of the 'hello world\n' string + (i32.store (i32.const 4) (i32.const 12)) ;; iov.iov_len - The length of the 'hello world\n' string + + (call $fd_write + (i32.const 1) ;; file_descriptor - 1 for stdout + (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0 + (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one. + (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written + ) + drop ;; Discard the number of bytes written from the top of the stack + ) +) +``` + +Use [wabt](https://github.com/WebAssembly/wabt) to compile `.wat` to `.wasm` + +```console +$ wat2wasm demo.wat +``` + The `--experimental-wasi-unstable-preview1` and `--experimental-wasm-bigint` -CLI arguments are needed for the previous example to run. +CLI arguments are needed for this example to run. ## Class: `WASI`