Next: REPL commands, Previous: Printer, Up: Toolchain reference [Contents][Index]
The (wasm vm) module provides a virtual machine for
interpreting Wasm functions. To use the interpreter, a Wasm module is
first validated for type safety (among other things) and then
instantiated, at which point exported functions become callable from
Scheme.
The interpreter only accepts validated Wasm. The validate-wasm
procedure validates and wraps a Wasm module to indicate successful
validation:
(use-modules (wasm vm) (wasm resolve)) (define validated-wasm (validate-wasm (wat->wasm '(module (func (export "main") (result i32) (i32.const 42))))))
When starting with a Wasm binary, the convenient
load-and-validate-wasm procedure parses the binary and then
performs validation:
(call-with-input-file "hello.wasm" load-and-validate-wasm)
Once the Wasm module has been validated, the runtime data needed for interpretation can be created by instantiating the module:
(define instance (instantiate-wasm validated-wasm))
Exported Wasm functions then become usable as Scheme procedures:
(define wasm-main (wasm-instance-export-ref instance "main")) (wasm-main) ;; => 42
Wasm functions are statically typed, which means that calls from Scheme to Wasm require runtime type checking for each call.
Validate the Wasm module wasm and return a validated Wasm object.
Load and validate the Wasm module within obj then return a
validated Wasm object. obj may be a <wasm> record as
produced by resolve-wasm (see Resolver), a bytevector
containing a Wasm binary, or an input port from which to read a Wasm
binary.
Return #t if obj is a validated Wasm object.
Unbox and return the Wasm module within validated-wasm.
Return a new Wasm instance for the validated Wasm module wasm.
imports is a nested association list of imported functions, globals, memories, and tables. Wasm imports are identified by a module name and an object name. Consider the following Wasm module that computes 2D polar coordinates and prints them to a log:
(use-modules (wasm resolve) (wasm vm) (wasm wat)) (define the-module (resolve-wasm (wat->wasm '(module (func $logf64 (import "debug" "logf64") (param f64)) (func $cos (import "math" "cos") (param f64) (result f64)) (func $sin (import "math" "sin") (param f64) (result f64)) (func (export "polar") (param $r f64) (param $theta f64) (call $logf64 (f64.mul (local.get $r) (call $cos (local.get $theta)))) (call $logf64 (f64.mul (local.get $r) (call $sin (local.get $theta)))))))))
This module requires three imported functions from two modules. Thus the module instantiation code would look like this:
(define (logf64 x) (format #t "f64: ~a\n" x)) (define the-instance (instantiate-wasm (validate-wasm the-module) #:imports `(("debug" . (("logf64" . ,logf64))) ("math" . (("cos" . ,cos) ("sin" . ,sin))))))
Return a new Wasm global containing value. When mutable?
is #f, the value cannot be modified later.
Return #t if obj is a Wasm global.
Return the current value within global.
Set the value within global to val. An exception is raised if global is immutable.
Return #t if global is mutable.
Return a new Wasm linear memory containing size 64KiB pages. limits determines the lower and upper bounds of how many pages this memory can store. The default limits are a minimum of 1 page and no maximum page limit. See Data types for more information on limit objects.
Return #t if obj is a Wasm memory.
Return the current bytevector representing the pages of memory.
Return the size of memory in 64KiB pages.
Return the limits of memory
Increase the size of memory by n pages. An exception is raised if growing by n exceeds the limits of memory.
Return a new Wasm reference table containing size element slots. limits determines the lower and upper bounds of how many elements this table can store. The default limits are a minimum of 1 element and no maximum element limit. See Data types for more information on limit objects.
Return #t if obj is a Wasm table.
Return the size of table.
Return the reference at the ith index in table.
Set the ith element of table to x, a Wasm reference type.
Fill the elements of table from start to start + length, exclusive, with the value fill.
Copy the block of elements from vector elems, from start to start + length, exclusive, to table, starting at at.
Increase the size of table by n elements. An exception is raised if growing by n exceeds the limits of table.
Every Wasm instruction evaluated by interpreter can be observed via
the current-instruction-listener parameter. Use this hook to
instrument Wasm modules.
The following instruction listener would print every instruction’s name on a separate line:
(define (log-instr instr path instance stack blocks locals) (display (car instr)) (newline)) (parameterize ((current-instruction-listener log-instr)) ...)
The current instruction observation hook which is invoked before each instruction evaluation. Must be a procedure that accepts the following arguments:
The Wasm value stack is a special data type with the following API:
Return #t if obj is a Wasm value stack.
Return the values on stack as a list.
Next: REPL commands, Previous: Printer, Up: Toolchain reference [Contents][Index]