compile

Documentation

Overview

Package compile is used internally by wagon to convert standard structured WebAssembly bytecode into an unstructured form suitable for execution by it's VM. The conversion process consists of translating block instruction sequences and branch operators (br, br_if, br_table) to absolute jumps to PC values. For instance, an instruction sequence like:

loop
  i32.const 1
  get_local 0
  i32.add
  set_local 0
  get_local 1
  i32.const 1
  i32.add
  tee_local 1
  get_local 2
  i32.eq
  br_if 0
end

Is "compiled" to:

i32.const 1
i32.add
set_local 0
get_local 1
i32.const 1
i32.add
tee_local 1
get_local 2
i32.eq
jmpnz <addr> <preserve> <discard>

Where jmpnz is a jump-if-not-zero operator that takes certain arguments plus the jump address as immediates. This is in contrast with original WebAssembly bytecode, where the target of branch operators are relative block depths instead.

Index

• Variables
• type BranchTable
  • func Compile(disassembly []disasm.Instr) ([]byte, []*BranchTable)
• type Target

Variables

var (
	// OpJmp unconditionally jumps to the provided address.
	OpJmp byte = 0x0c
	// OpJmpZ jumps to the given address if the value at the top of the stack is zero.
	OpJmpZ byte = 0x03
	// OpJmpNz jumps to the given address if the value at the top of the
	// stack is not zero. It also discards elements and optionally preserves
	// the topmost value on the stack
	OpJmpNz byte = 0x0d
	// OpDiscard discards a given number of elements from the execution stack.
	OpDiscard byte = 0x0b
	// OpDiscardPreserveTop discards a given number of elements from the
	// execution stack, while preserving the value on the top of the stack.
	OpDiscardPreserveTop byte = 0x05
)

Types

type BranchTable

type BranchTable struct {
	Targets       []Target // A list of targets, br_table pops an int value, and jumps to Targets[val]
	DefaultTarget Target   // If val > len(Targets), the VM will jump here
	// contains filtered or unexported fields
}

BranchTable is the structure pointed to by a rewritten br_table instruction. A rewritten br_table instruction is of the format:

br_table <table_index>

where <table_index> is the index to an array of BranchTable objects stored by the VM.

func Compile

func Compile(disassembly []disasm.Instr) ([]byte, []*BranchTable)

Compile rewrites WebAssembly bytecode from its disassembly. TODO(vibhavp): Add options for optimizing code. Operators like i32.reinterpret/f32 are no-ops, and can be safely removed.

type Target

type Target struct {
	Addr        int64 // The absolute address of the target
	Discard     int64 // The number of elements to discard
	PreserveTop bool  // Whether the top of the stack is to be preserved
	Return      bool  // Whether to return in order to take this branch/target
}

Target is the "target" of a br_table instruction. Unlike other control instructions, br_table does jumps and discarding all by itself.