diff --git a/manual/wasm_runtime.wiki b/manual/wasm_runtime.wiki new file mode 100644 index 0000000000..5410d67a4c --- /dev/null +++ b/manual/wasm_runtime.wiki @@ -0,0 +1,60 @@ += Writing Wasm primitives + +User-defined primitives can be implemented by writing Wasm modules. +This modules (".wat" extension for text modules and ".wasm" extension +for binary modules) can be passed on the command-line. + +It still makes sense to link JavaScript files to specify the possible +side-effects of some primitives (see <<a_manual chapter="linker" |Link +with JavaScript code>>), or to implement some functionalities in +JavaScript. + +== Data representation == + +The type {{{(ref eq)}}} is used for all OCaml values. +Integers, chars, booleans and constant constructors are mapped to +{{{(ref i31)}}}. + +We use the following types for blocks, strings (and bytes), floats, +float arrays, and Javascript values. The first field of a block is its +tag, of type {{{(ref i31)}}}. +{{{ +(type $block (array (mut (ref eq)))) +(type $string (array (mut i8))) +(type $float (struct (field f64))) +(type $float_array (array (mut f64))) +(type $js (struct (ref null any))) +}}} + +You can import the following functions to access or allocate integers of type int32, int64, and nativeint. +{{{ +(import "env" "Int32_val" + (func $Int32_val (param (ref eq)) (result i32))) +(import "env" "caml_copy_int32" + (func $caml_copy_int32 (param i32) (result (ref eq)))) +(import "env" "Nativeint_val" + (func $Nativeint_val (param (ref eq)) (result i32))) +(import "env" "caml_copy_nativeint" + (func $caml_copy_int32 (param i32) (result (ref eq)))) +(import "env" "Int64_val" + (func $Int64_val (param (ref eq)) (result i64))) +(import "env" "caml_copy_int64" + (func $caml_copy_int64 (param i64) (result (ref eq)))) +}}} + +== Implementing primitives + +{{{ +(func (export "input") (param $channel (ref eq)) (param $buffer (ref eq)) (param $offset (ref eq)) (param $length (ref eq)) (result (ref eq)) + ... +) +}}} + +== Linking with JavaScript == + +You can import JavaScript primitive using the {{{"js"}}} namespace: +{{{ +(import "js" "add" (func $add (param f64) (param f64) (result f64))) +}}} + +You can use functions defined in `runtime/wasm/jslib.wat` for conversions.