wazero

https://wazero.io/docs/
Admin
wazero is a WebAssembly runtime written completely in Go that can safely run code compiled in other...
Tokens:6,054
Snippets:85
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Register Allocation Function Instantiation Example

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Illustrates how the generic register allocation function is instantiated for a specific architecture, like ARM64, by embedding the architecture-specific machine details.

```go
backend.RegAllocFunction[*arm64.instruction, *arm64.machine]
```

--------------------------------

### SSA Block Representation Example

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/frontend

An example of a basic block in SSA form, showing its arguments, local variables, and control flow instructions like BranchZero (Brz) and Jump.

```go
blk0: (exec_ctx:i64, module_ctx:i64, v2:i32)
    v3:i32 = Iconst_32 0x0
    v4:i32 = Icmp lt_s, v2, v3
    Brz v4, blk2
    Jump blk1


```

--------------------------------

### SSA Block Termination Example

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/frontend

Illustrates how subsequent basic blocks (blk1, blk2) terminate with jumps to a final block (blk3), passing arguments that are effectively Phi values.

```go
blk1: ()
    ...
	Jump blk3, v7

blk2: ()
	Jump blk3, v2

blk3: (v5:i32)
    ...


```

--------------------------------

### SSA Basic Block Example

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/frontend

Illustrates a basic block in SSA form, showing instructions, values, and types. Instructions consume and produce values, with types like i32.

```go
blk1: () <-- (blk0)
    v6:i32 = Iconst_32 0x0
    v7:i32 = Isub v6, v2
    Jump blk3, v7

```

--------------------------------

### Example SSA Layout for abs Function

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/frontend

Shows the SSA form of the 'abs' function after the block layout phase, illustrating basic blocks and control flow.

```ssa
blk0: (exec_ctx:i64, module_ctx:i64, v2:i32)
	v3:i32 = Iconst_32 0x0
	v4:i32 = Icmp lt_s, v2, v3
	Brz v4, blk2
	Jump fallthrough

blk1: () <-- (blk0)
	v6:i32 = Iconst_32 0x0
	v7:i32 = Isub v6, v2
	Jump blk3, v7

blk2: () <-- (blk0)
	Jump fallthrough, v2

blk3: (v5:i32) <-- (blk1,blk2)
	Jump blk_ret, v5

```

--------------------------------

### Liveness Analysis Example

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Illustrates liveness of variables within a simple C function. Variables `x` and `y` are live at line 4 because they are used in line 3; `z` is live at line 4 for the return statement.

```c
1| int f(int x) {
2|   int y = 2 + x;
3|   int z = x + y;
4|   return z;
5| }

```

--------------------------------

### Wasm Abs Function Example

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/frontend

This is a sample WebAssembly function that calculates the absolute value of an i32 integer.

```wasm
(module
  (func (;0;) (param i32) (result i32)
     (if (result i32) (i32.lt_s (local.get 0) (i32.const 0))
        (then
            (i32.sub (i32.const 0) (local.get 0)))
        (else
            (local.get 0))
     )
  )
  (export "f" (func 0))
)


```

--------------------------------

### ARM64 Basic Blocks After Register Allocation

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Example of basic blocks for an 'abs' function after register allocation on ARM64. Virtual registers are replaced by real registers, and no spills are required in this simple case.

```assembly
L1 (SSA Block: blk0):
	mov x2, x2
	subs wzr, w2, #0x0
	b.ge L2
L3 (SSA Block: blk1):
	mov x8, xzr
	sub w8, w8, w2
	mov x8, x8
	b L4
L2 (SSA Block: blk2):
	mov x8, x2
L4 (SSA Block: blk3):
	mov x0, x8
	ret

```

--------------------------------

### AMD64 Instruction Selection for Addition

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Shows the AT&T syntax for AMD64 assembly, demonstrating how a memory load can be folded into the operand of an add instruction.

```assembly
;; AT&T syntax
add $4(%r5?), %r4? ;; add the value at memory address [`r5?` + 4] to `r4?`
mov %r4?, %r7?     ;; move the result from `r4?` to `r7?`
```

--------------------------------

### SSA Instructions for Addition

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Illustrates a sequence of SSA instructions for an addition operation, including a constant load and a memory load.

```go
v4:i32 = Const 0x9
v6:i32 = Load v5, 0x4
v7:i32 = Iadd v6, v4
```

--------------------------------

### SSA Basic Block with Constant Propagation

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/frontend

Demonstrates constant propagation within an SSA basic block. A comparison between constants is replaced by a constant value.

```go
blk0: (exec_ctx:i64, module_ctx:i64)
    v2:i32 = Iconst_32 -5
    v3:i32 = Iconst_32  0
    v4:i32 = Icmp lt_s, v2, v3
    Brz v4, blk2
    Jump blk1

```

--------------------------------

### Printing Lowered Arch-Specific Instructions

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Use this flag to print basic blocks with lowered arch-specific instructions during the backend lowering phase.

```go
wazevoapi.PrintSSAToBackendIRLowering
```

--------------------------------

### Wasm Runtime Panic (Go)

Source: https://wazero.io/docs/how_do_compiler_functions_work

Demonstrates how a `panic` in Go, when compiled to Wasm, results in a call to `runtime._panic` and an `unreachable` instruction.

```go
package main

func main() {
	panic("help")
}

```

--------------------------------

### SSA Basic Block After Constant Propagation

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/frontend

Shows the result of constant propagation, where a comparison is replaced by a constant value, simplifying the block.

```go
blk0: (exec_ctx:i64, module_ctx:i64)
    v4:i32 = Iconst_32 1
    Brz v4, blk2
    Jump blk1

```

--------------------------------

### ARM64 Basic Blocks After Instruction Selection

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Presents the structure of basic blocks for an 'abs' function in ARM64 assembly after instruction selection, including labels for control flow.

```assembly
L1 (SSA Block: blk0):
	mov x130?, x2
	subs wzr, w130?, #0x0
	b.ge L2
L3 (SSA Block: blk1):
	mov x136?, xzr
	sub w134?, w136?, w130?
	mov x135?, w134?
	b L4
L2 (SSA Block: blk2):
	mov x135?, x130?
L4 (SSA Block: blk3):
	mov x0, x135?
	ret
```

--------------------------------

### Host Function Signature

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/appendix

Defines the expected signature for host functions that can be invoked from the generated WebAssembly code. The `stack` parameter carries arguments.

```go
func(ctx context.Context, stack []uint64)
```

--------------------------------

### Register Allocation Procedure

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

The `DoAllocation` method performs register allocation for a given function, involving sub-phases like liveness analysis and register assignment.

```go
regalloc.Allocator.DoAllocation(f)
```

--------------------------------

### Register Allocation Interfaces in Go

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Defines the core interfaces for the register allocation algorithm in Go, allowing it to work with any ISA by implementing these contracts. These interfaces abstract architecture-specific details.

```go
type Function interface {
	Blocks() []Block
}

type Block interface {
	Instrs() []Instr
}

type Instr interface {
	// Returns the set of registers defined by this instruction.
	Def() map[abi.桫]struct{}
	// Returns the set of registers used by this instruction.
	Use() map[abi.桫]struct{}
}

```

--------------------------------

### Wasm Host Function Call (Go)

Source: https://wazero.io/docs/how_do_compiler_functions_work

Defines a host function `random_get` imported by Wasm and a `main` function that calls it. Use this to enable Wasm modules to call Go functions.

```go
package main

import "unsafe"

// random_get is a function defined on the host, specifically, the wazero
// program written in Go.
//
//go:wasmimport wasi_snapshot_preview1 random_get
func random_get(ptr uintptr, size uint32) (errno uint32)

// main is compiled to wasm, so this is the guest. Conventionally, this ends up
// named `_start`.
func main() {
    // Define a buffer to hold random data
	ssize := uint32(8)
    buf := make([]byte, size)

	// Fill the buffer with random data using an imported host function.
    // The host needs to know where in guest memory to place the random data.
	// To communicate this, we have to convert buf to a uintptr.
    errno := random_get(uintptr(unsafe.Pointer(&buf[0])), size)
    if errno != 0 {
        panic(errno)
    }
}

```

--------------------------------

### SSA Basic Block After Dead Code Elimination

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/frontend

Illustrates dead code elimination at the control-flow graph level, where unreachable branches and instructions are removed.

```go
blk0: (exec_ctx:i64, module_ctx:i64)
    Jump blk1

```

--------------------------------

### Register Info Declaration in Go

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

Shows the declaration of the `regalloc.RegisterInfo` struct in Go, used to configure the register allocator. It includes sets for allocatable and callee-saved registers.

```go
type RegisterInfo struct {
	// AllocatableRegisters is the set of registers that are available for allocation.
	AllocatableRegisters map[abi.桫]struct{}
	// CalleeSavedRegisters is the set of registers that might be saved by the callee to the stack.
	CalleeSavedRegisters map[abi.桫]struct{}
}

```

--------------------------------

### Go Entrypoint Trampoline Signature

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/appendix

Defines the signature for the Go-side trampoline function that bridges the Go runtime and the generated Wasm code. It takes pointers to executable code, context structures, and stack information.

```go
func entrypoint(
	preambleExecutable, functionExecutable *byte,
	executionContextPtr uintptr, moduleContextPtr *byte,
	paramResultStackPtr *uint64,
	goAllocatedStackSlicePtr uintptr)
```

--------------------------------

### Lowering SSA Instruction to Machine Code

Source: https://wazero.io/docs/how_the_optimizing_compiler_works/backend

The `LowerInstr` method translates an SSA instruction to machine code. Machine-specific implementations are located in package `backend/isa/<arch>`.

```go
backend.Machine.LowerInstr(*ssa.Instruction)
```

--------------------------------

### Wasm Module Import Requirement

Source: https://wazero.io/docs

This WebAssembly module requires importing the exported function named `foo` from the instantiated module named `env`. This is how a Wasm module interacts with the outside of its own sandbox.

```wasm
(module (import "env" "foo" (func)))
```
Tokens:
Raw