wasm #

Description

The wasm module is a pure V implementation of the WebAssembly bytecode module format, available in the form of a builder.

It allows users to generate WebAssembly modules in memory.

With the V wasm module, users can create functions, opcodes, and utilize the entire wasm specification without the need for a large dependency like binaryen. All of this functionality is available within V itself, making the module a valuable resource for V developers seeking to build high-performance web applications.

The module is designed to generate a []u8, which can be written to a .wasm file or executed in memory.

Examples are present in examples/wasm_codegen.

import wasm
import os

fn main() {
    mut m := wasm.Module{}
    mut func := m.new_function('add', [.i32_t, .i32_t], [.i32_t])
    {
        func.local_get(0) // | local.get 0
        func.local_get(1) // | local.get 1
        func.add(.i32_t) // | i32.add
    }
    m.commit(func, true) // `export: true`

    mod := m.compile() // []u8

    os.write_file_array('add.wasm', mod)!
}

This module does not perform verification of the WebAssembly output. Use a tool like wasm-validate to validate, and wasm-dis to show a decompiled form.

fn constexpr_ref_null(rt RefType) ConstExpression

constexpr_ref_null returns a constant expression that evaluates to a null reference.

fn constexpr_value[T](v T) ConstExpression

constexpr_value returns a constant expression that evaluates to a single value.

fn constexpr_value_zero(v ValType) ConstExpression

constexpr_value_zero returns a constant expression that evaluates to zero.

fn ElementMode.from[W](input W) !ElementMode

fn NumType.from[W](input W) !NumType

fn RefType.from[W](input W) !RefType

fn Section.from[W](input W) !Section

fn Subsection.from[W](input W) !Subsection

fn ValType.from[W](input W) !ValType

type DataSegmentIndex = int

type ElementIndex = int

type GlobalImportIndex = int

type GlobalIndex = int

type LabelIndex = int

type LocalIndex = int

type PatchPos = int

type TableIndex = int

type TypeIndex = int

enum NumType as u8 {
	i32_t = 0x7f
	i64_t = 0x7e
	f32_t = 0x7d
	f64_t = 0x7c
}

enum RefType as u8 {
	funcref_t   = 0x70
	externref_t = 0x6f
}

enum ValType as u8 {
	i32_t       = 0x7f
	i64_t       = 0x7e
	f32_t       = 0x7d
	f64_t       = 0x7c
	v128_t      = 0x7b
	funcref_t   = 0x70
	externref_t = 0x6f
}

struct ConstExpression {
mut:
	call_patches []CallPatch
	code         []u8
}

WebAssembly constant expressions are permitted to use a subset of valid instructions.

fn (mut expr ConstExpression) i32_const(v i32)

i32_const places a constant i32 value on the stack. WebAssembly instruction: i32.const.

fn (mut expr ConstExpression) i64_const(v i64)

i64_const places a constant i64 value on the stack. WebAssembly instruction: i64.const.

fn (mut expr ConstExpression) f32_const(v f32)

f32_const places a constant f32 value on the stack. WebAssembly instruction: f32.const.

fn (mut expr ConstExpression) f64_const(v f64)

f64_const places a constant f64 value on the stack. WebAssembly instruction: f64.const.

fn (mut expr ConstExpression) add(typ NumType)

add adds two values on the stack with type typ. WebAssembly instructions: i32|i64.add.

fn (mut expr ConstExpression) sub(typ NumType)

sub subtracts two values on the stack with type typ. WebAssembly instructions: i32|i64.sub.

fn (mut expr ConstExpression) mul(typ NumType)

mul multiplies two values on the stack with type typ. WebAssembly instructions: i32|i64.mul.

fn (mut expr ConstExpression) global_get(global GlobalImportIndex)

global_get places the value of the global at the index global on the stack. Constant expressions are only allowed to refer to imported globals. WebAssembly instruction: global.get.

fn (mut expr ConstExpression) ref_null(rt RefType)

ref_null places a null reference on the stack. WebAssembly instruction: ref.null.

fn (mut expr ConstExpression) ref_func(name string)

ref_func places a reference to a function with name on the stack. If this function does not exist when calling compile on the module, it will panic. WebAssembly instruction: ref.func.

fn (mut expr ConstExpression) ref_func_import(mod string, name string)

ref_func places a reference to an imported function with name on the stack. If the imported function does not exist when calling compile on the module, it will panic. WebAssembly instruction: ref.func.

struct FuncType {
pub:
	parameters []ValType
	results    []ValType
	name       ?string
}

struct Function {
	tidx int
	idx  int
mut:
	patches []FunctionPatch // sorted
	label   int
	export  bool
	mod     &Module = unsafe { nil }
	code    []u8
	locals  []FunctionLocal
pub:
	name string
pub mut:
	export_name ?string
}

fn (mut func Function) abs(typ NumType)

abs gets the absolute value of a float with type typ. WebAssembly instruction: f32|f64.abs.

fn (mut func Function) add(typ NumType)

add adds two values on the stack with type typ. WebAssembly instructions: i32|i64|f32|f64.add.

fn (mut func Function) b_and(typ NumType)

and takes the bitwise and of two values on the stack with type typ. WebAssembly instruction: i32|i64.and.

fn (mut func Function) b_or(typ NumType)

or takes the bitwise or of two values on the stack with type typ. WebAssembly instruction: i32|i64.or.

fn (mut func Function) b_shl(typ NumType)

shl performs bitwise left-shift on a value with type typ. WebAssembly instruction: i32|i64.shl.

fn (mut func Function) b_shr(typ NumType, is_signed bool)

shr performs bitwise right-shift on a value with type typ, with respect to is_signed. WebAssembly instructions: i32|i64.shr_s, i32|i64.shr_u.

fn (mut func Function) b_xor(typ NumType)

xor takes the bitwise xor of two values on the stack with type typ. WebAssembly instruction: i32|i64.xor.

fn (mut func Function) c_block(parameters []ValType, results []ValType) LabelIndex

c_block creates a label that can later be branched out of with c_br and c_br_if. Blocks are strongly typed, you must supply a list of types for parameters and results. All blocks must be ended, see the c_end function.

fn (mut func Function) c_br(label LabelIndex)

c_br branches to a loop or block with the label passed in at label. WebAssembly instruction: br.

fn (mut func Function) c_br_if(label LabelIndex)

c_br_if branches to a loop or block with the label passed in at label, based on an i32 condition. WebAssembly instruction: br_if.

fn (mut func Function) c_else(label LabelIndex)

c_else opens the else case of an if expression, it must be closed by calling c_end.

fn (mut func Function) c_end(label LabelIndex)

c_end ends the block, loop or if expression with the label passed in at label.

fn (mut func Function) c_if(parameters []ValType, results []ValType) LabelIndex

c_if opens an if expression. It executes a statement if the last item on the stack is true. It creates a label that can later be branched out of with c_br and c_br_if. If expressions are strongly typed, you must supply a list of types for parameters and results. Call c_else to open the else case of an if expression, or close it by calling c_end_if. All if expressions must be ended, see the c_end function.

fn (mut func Function) c_loop(parameters []ValType, results []ValType) LabelIndex

c_loop creates a label that can later be branched to with c_br and c_br_if. Loops are strongly typed, you must supply a list of types for parameters and results. All loops must be ended, see the c_end function.

fn (mut func Function) c_return()

c_return returns from a function. WebAssembly instruction: return.

fn (mut func Function) c_select()

c_select selects one of its first two operands based on an i32 condition. WebAssembly instruction: select.

fn (mut func Function) call(name string)

call calls a locally defined function. If this function does not exist when calling compile on the module, it will panic. WebAssembly instruction: call.

fn (mut func Function) call_import(mod string, name string)

call calls an imported function. If the imported function does not exist when calling compile on the module, it will panic. WebAssembly instruction: call.

fn (mut func Function) call_indirect(typeidx TypeIndex, tableidx TableIndex)

call_indirect calls a function from table tableidx whose type is typeidx. The function index to call is popped from the stack as an i32. Obtain typeidx from Module.new_functype. WebAssembly instruction: call_indirect.

fn (mut func Function) cast(a NumType, is_signed bool, b NumType)

cast casts a value of type a with respect to is_signed, to type b. A generic utility function over a large amount of WebAssembly instructions.

Note: This function uses non-trapping float conversion operators, see cast_trapping to use opcodes that cause a runtime exception. WebAssembly instructions:- i32|i64.trunc_sat_f32_s, i32|i64.trunc_sat_f64_s.

• f32.demote_f64, f64.promote_f32.
• i32.wrap_i64, i64.extend_i32_s, i64.extend_i32_u.
• f32|f64.convert_i32_s, f32|f64.convert_i32_u.
• f32|f64.convert_i64_s, f32|f64.convert_i64_u.

fn (mut func Function) cast_trapping(a NumType, is_signed bool, b NumType)

cast_trapping casts a value of type a with respect to is_signed, to type b. A generic utility function over a large amount of WebAssembly instructions.

Note: This function uses trapping float conversion operators, see cast to use opcodes that do NOT cause a runtime exception. WebAssembly instructions:- i32|i64.trunc_f32_s, i32|i64.trunc_f64_s.

• See function cast for the rest.

fn (mut func Function) ceil(typ NumType)

ceil rounds up the value of a float with type typ to the nearest integer. WebAssembly instruction: f32|f64.ceil.

fn (mut func Function) clz(typ NumType)

clz counts the amount of leading zeros in the numbers binary representation. WebAssembly instruction: i32|i64.clz.

fn (mut func Function) copysign(typ NumType)

copysign copies the sign bit of one float value to another float, both with type typ. WebAssembly instruction: f32|f64.copysign.

fn (mut func Function) ctz(typ NumType)

ctz counts the amount of trailing zeros in the numbers binary representation. WebAssembly instruction: i32|i64.ctz.

fn (mut func Function) data_drop(idx DataSegmentIndex)

data_drop prevents further use of a passive memory segment. WebAssembly instruction: data.drop.

fn (mut func Function) div(typ NumType, is_signed bool)

div divides two values on the stack with type typ, with respect to is_signed. WebAssembly instructions: i32|i64.div_s, i32|i64.div_u, f32|f64.div.

fn (mut func Function) drop()

drop drops the value on the stack WebAssembly instruction: drop.

fn (mut func Function) eq(typ NumType)

eq checks if two values with type typ are equal, places an i32 boolean value on the stack. WebAssembly instruction: i32|i64|f32|f64.eq.

fn (mut func Function) eqz(typ NumType)

eqz checks if the value with type typ is equal to zero, places an i32 boolean value on the stack. WebAssembly instruction: i32|i64.eqz.

fn (mut func Function) export_name(name string)

export_name sets the export name of the function to name

fn (mut func Function) f32_const(v f32)

f32_const places a constant f32 value on the stack. WebAssembly instruction: f32.const.

fn (mut func Function) f64_const(v f64)

f64_const places a constant f64 value on the stack. WebAssembly instruction: f64.const.

fn (mut func Function) floor(typ NumType)

floor rounds down the value of a float with type typ to the nearest integer. WebAssembly instruction: f32|f64.floor.

fn (mut func Function) ge(typ NumType, is_signed bool)

ge checks if two values with type typ with respect to is_signed are greater than or equal to another, places an i32 boolean value on the stack. WebAssembly instructions: i32|i64.ge_s, i32|i64.ge_u, f32|f64.ge.

fn (mut func Function) global_get(global GlobalIndices)

global_get places the value of the global at the index global on the stack. WebAssembly instruction: global.get.

fn (mut func Function) global_set(global GlobalIndices)

global_set sets the global at the index global to the value on the stack. WebAssembly instruction: global.set.

fn (mut func Function) gt(typ NumType, is_signed bool)

gt checks if two values with type typ with respect to is_signed are greater than another, places an i32 boolean value on the stack. WebAssembly instructions: i32|i64.gt_s, i32|i64.gt_u, f32|f64.gt.

fn (mut func Function) i32_const(v i32)

i32_const places a constant i32 value on the stack. WebAssembly instruction: i32.const.

fn (mut func Function) i64_const(v i64)

i64_const places a constant i64 value on the stack. WebAssembly instruction: i64.const.

fn (mut func Function) le(typ NumType, is_signed bool)

le checks if two values with type typ with respect to is_signed are less than or equal to another, places an i32 boolean value on the stack. WebAssembly instructions: i32|i64.le_s, i32|i64.le_u, f32|f64.le.

fn (mut func Function) load(typ NumType, align int, offset int)

load loads a value with type typ from memory. WebAssembly instruction: i32|i64|f32|f64.load.

fn (mut func Function) load16(typ NumType, is_signed bool, align int, offset int)

load16 loads a 16-bit value with type typ with respect to is_signed from memory. WebAssembly instructions: i32|i64.load16_s, i32|i64.load16_u.

fn (mut func Function) load32_i64(is_signed bool, align int, offset int)

load32_i64 loads a 32-bit value of type i64 with respect to is_signed from memory. WebAssembly instructions: i64.load32_s, i64.load32_u.

fn (mut func Function) load8(typ NumType, is_signed bool, align int, offset int)

load8 loads a 8-bit value with type typ with respect to is_signed from memory. WebAssembly instructions: i32|i64.load8_s, i32|i64.load8_u.

fn (mut func Function) local_get(local LocalIndex)

local_get places the value of the local at the index local on the stack. WebAssembly instruction: local.get.

fn (mut func Function) local_set(local LocalIndex)

local_get sets the local at the index local to the value on the stack. WebAssembly instruction: local.set.

fn (mut func Function) local_tee(local LocalIndex)

local_tee sets the local at the index local to the value on the stack, then places it's value on the stack. WebAssembly instruction: local.tee.

fn (mut func Function) lt(typ NumType, is_signed bool)

lt checks if two values with type typ with respect to is_signed are less than another, places an i32 boolean value on the stack. WebAssembly instructions: i32|i64.lt_s, i32|i64.lt_u, f32|f64.lt.

fn (mut func Function) max(typ NumType)

max gets the higher value of two floats with type typ. WebAssembly instruction: f32|f64.max.

fn (mut func Function) memory_copy()

memory_copy copies one region of memory to another. Similar to memcpy and memmove, memory regions can overlap. WebAssembly instruction: memory.copy.

fn (mut func Function) memory_fill()

memory_fill sets a memory region to a byte value. Similar to memset. WebAssembly instruction: memory.copy.

fn (mut func Function) memory_grow()

memory_grow increases the size of the memory instance. WebAssembly instruction: memory.grow.

fn (mut func Function) memory_init(idx DataSegmentIndex)

memory_init copies from a passive memory segment to the memory instance. WebAssembly instruction: memory.init.

fn (mut func Function) memory_size()

memory_size gets the size of the memory instance. WebAssembly instruction: memory.size.

fn (mut func Function) min(typ NumType)

min gets the smaller value of two floats with type typ. WebAssembly instruction: f32|f64.min.

fn (mut func Function) mul(typ NumType)

mul multiplies two values on the stack with type typ. WebAssembly instructions: i32|i64|f32|f64.mul.

fn (mut func Function) ne(typ NumType)

ne checks if two values with type typ are not equal, places an i32 boolean value on the stack. WebAssembly instruction: i32|i64|f32|f64.ne.

fn (mut func Function) nearest(typ NumType)

nearest rounds the value of a float with type typ to the nearest integer. WebAssembly instruction: f32|f64.nearest.

fn (mut func Function) neg(typ NumType)

neg negates the value of a float with type typ. WebAssembly instruction: f32|f64.neg.

fn (mut func Function) new_local(v ValType) LocalIndex

new_local creates a function local and returns it's index. See local_get, local_set, local_tee.

fn (mut func Function) new_local_named(v ValType, name string) LocalIndex

new_local_named creates a function local with a name and returns it's index. The name is used in debug information, where applicable. See local_get, local_set, local_tee.

fn (mut func Function) nop()

nop instruction, does nothing. WebAssembly instruction: nop.

fn (mut func Function) patch(loc PatchPos, begin PatchPos)

patch "patches" the code generated starting from the last patch_pos call in begin to loc.

start := func.patch_pos()

...

patch_block := func.patch_pos()
{
    func.i32_const(10)
    func.local_set(idx)
}
func.patch(start, patch_block) // will patch code to the `start`.
// func.code[patch_block..]

fn (func Function) patch_pos() PatchPos

patch_pos returns a PatchPos for use with patch.

fn (mut func Function) popcnt(typ NumType)

popcnt counts the amount of 1s in a numbers binary representation. WebAssembly instruction: i32|i64.popcnt.

fn (mut func Function) ref_func(name string)

ref_func places a reference to a function with name on the stack. If this function does not exist when calling compile on the module, it will panic. WebAssembly instruction: ref.func.

fn (mut func Function) ref_func_import(mod string, name string)

ref_func_import places a reference to an imported function with name on the stack. If the imported function does not exist when calling compile on the module, it will panic. WebAssembly instruction: ref.func.

fn (mut func Function) ref_is_null(rt RefType)

ref_is_null checks if the reference value on the stack is null, places an i32 boolean value on the stack. WebAssembly instruction: ref_is_null.

fn (mut func Function) ref_null(rt RefType)

ref_null places a null reference on the stack. WebAssembly instruction: ref.null.

fn (mut func Function) reinterpret(a NumType)

reinterpret returns a value which has the same bit-pattern as its operand value, in its result type. WebAssembly instruction: f32.reinterpret_i32, i32.reinterpret_f32, f64.reinterpret_i64, i64.reinterpret_f64.

fn (mut func Function) rem(typ NumType, is_signed bool)

rem takes the remainder of two values on the stack with type typ, with respect to is_signed. WebAssembly instructions: i32|i64.rem_s, i32|i64.rem_u.

fn (mut func Function) rotl(typ NumType)

rotl performs bitwise left-rotate on a value with type typ. WebAssembly instruction: i32|i64.rotl.

fn (mut func Function) rotr(typ NumType)

rotr performs bitwise right-rotate on a value with type typ. WebAssembly instruction: i32|i64.rotr.

fn (mut func Function) sign_extend16(typ ValType)

sign_extend16 extends the value of a 16-bit integer of type typ. WebAssembly instruction: i32|i64.extend16_s.

fn (mut func Function) sign_extend32()

sign_extend32_i64 extends the value of a 32-bit integer of type i64. WebAssembly instruction: i64.extend32_s.

fn (mut func Function) sign_extend8(typ ValType)

sign_extend8 extends the value of a 8-bit integer of type typ. WebAssembly instruction: i32|i64.extend8_s.

fn (mut func Function) sqrt(typ NumType)

sqrt performs the square root on the value of a float with type typ. WebAssembly instruction: f32|f64.sqrt.

fn (mut func Function) store(typ NumType, align int, offset int)

store stores a value with type typ into memory. WebAssembly instruction: i32|i64|f32|f64.store.

fn (mut func Function) store16(typ NumType, align int, offset int)

store16 stores a 16-bit value with type typ into memory. WebAssembly instruction: i32|i64.store16.

fn (mut func Function) store32_i64(align int, offset int)

store16 stores a 32-bit value of type i64 into memory. WebAssembly instruction: i64.store32.

fn (mut func Function) store8(typ NumType, align int, offset int)

store8 stores a 8-bit value with type typ into memory. WebAssembly instruction: i32|i64.store8.

fn (mut func Function) sub(typ NumType)

sub subtracts two values on the stack with type typ. WebAssembly instructions: i32|i64|f32|f64.sub.

fn (mut func Function) table_fill(tableidx TableIndex)

table_fill fills a range of table tableidx with a reference. It pops the count, the init reference, and the start index from the stack. WebAssembly instruction: table.fill.

fn (mut func Function) table_get(tableidx TableIndex)

table_get places the reference at the index (popped from the stack) of table tableidx onto the stack. WebAssembly instruction: table.get.

fn (mut func Function) table_grow(tableidx TableIndex)

table_grow grows table tableidx by n entries (popped from the stack), filling them with an init reference (popped from the stack). It places the previous size on the stack as an i32, or -1 on failure. WebAssembly instruction: table.grow.

fn (mut func Function) table_set(tableidx TableIndex)

table_set stores a reference (popped from the stack) at the index (popped from the stack) of table tableidx. WebAssembly instruction: table.set.

fn (mut func Function) table_size(tableidx TableIndex)

table_size places the current size of table tableidx on the stack as an i32. WebAssembly instruction: table.size.

fn (mut func Function) trunc(typ NumType)

trunc discards the fractional part of the value of a float with type typ. WebAssembly instruction: f32|f64.trunc.

fn (mut func Function) unreachable()

unreachable denotes a point in code that should not be reachable, it is an unconditional trap. WebAssembly instruction: unreachable.

struct Module {
mut:
	buf            []u8
	functypes      []FuncType
	functions      map[string]Function
	globals        []Global
	memory         ?Memory
	start          ?string
	fn_imports     []FunctionImport
	global_imports []GlobalImport
	segments       []DataSegment
	tables         []Table
	elements       []Element
	debug          bool
	mod_name       ?string
}

Module contains the WebAssembly module. Use the compile method to compile the module into a pure byte array.

fn (mut mod Module) assign_global_init(global GlobalIndex, init ConstExpression)

assign_global_init assigns a global with the constant expression init. See new_global.

fn (mut mod Module) assign_memory(name string, export bool, min u32, max ?u32)

assign_memory assigns memory to the current module.

fn (mut mod Module) assign_start(name string)

assign_start assigns the start function to the current module.

fn (mut mod Module) assign_table(name string, export bool, reftype RefType, min u32, max ?u32) TableIndex

assign_table declares a table in the current module and returns its index. reftype is the element type (funcref_t or externref_t); pass max as none for a growable table.

fn (mut mod Module) commit(func Function, export bool)

commit commits a function to the module, use export to export the function.

fn (mut mod Module) compile() []u8

compile serialises the WebAssembly module into a byte array. The returned byte array can be written out into a .wasm, or executed in memory.

fn (mut mod Module) enable_debug(mod_name ?string)

enable_debug sets whether to emit debug information for not.

fn (mut mod Module) new_active_element(tableidx TableIndex, offset int, funcs []string) ElementIndex

new_active_element appends an active element segment that initialises table tableidx starting at offset with the given (local) function references, and returns its index. An active segment also declares its functions, so a later ref.func to any of them validates.

fn (mut mod Module) new_data_segment(name ?string, pos int, data []u8) DataSegmentIndex

new_data_segment inserts a new data segment at the memory index pos. name is optional, it is used for debug info.

fn (mut mod Module) new_debug_function(name string, typ FuncType, argument_names []?string) Function

new_debug_function creates a function struct with extra debug information. argument_names must be the same length as the parameters in the function type typ.

fn (mut mod Module) new_declarative_element(funcs []string) ElementIndex

new_declarative_element appends a declarative element segment that declares the given (local) functions, so that ref.func to a non-exported function validates. It allocates no table space. Returns its index.

fn (mut mod Module) new_function(name string, parameters []ValType, results []ValType) Function

new_function creates a function struct.

fn (mut mod Module) new_function_import(modn string, name string, parameters []ValType, results []ValType)

new_function_import imports a new function into the current module.

fn (mut mod Module) new_function_import_debug(modn string, name string, typ FuncType)

new_function_import_debug imports a new function into the current module with extra debug information.

fn (mut mod Module) new_functype(ft FuncType) TypeIndex

new_functype interns a function type and returns its type index. Use it to obtain the type index required by call_indirect.

fn (mut mod Module) new_global(name string, export bool, typ ValType, is_mut bool, init ConstExpression) GlobalIndex

new_global creates a global and returns it's index. See global_get, global_set.

fn (mut mod Module) new_global_import(modn string, name string, typ ValType, is_mut bool) GlobalImportIndex

new_global_import imports a new global into the current module and returns it's index. See global_get, global_set.

fn (mut mod Module) new_passive_data_segment(name ?string, data []u8)

new_passive_data_segment inserts a new passive data segment. name is optional, it is used for debug info.