wag

README

wag is a WebAssembly compiler implemented as a Go package.

• License: 3-clause BSD
• Author: Timo Savola timo.savola@iki.fi

Features

• The input is a wasm32 binary module.

• The output is executable x86-64 or ARM64 machine code. (ARM64 support is incomplete. Support for 32-bit or big-endian CPU architectures isn't planned.)

• It is only a compiler. A runtime environment for the compiled program, including all import functions, needs to be implemented separately. (But see wasys for a combined compiler and runtime.)

• Single-pass, fast ahead-of-time compilation. Early functions can be executed while the latter functions are still being compiled, even while the source is still being downloaded.

• The generated code requires minimal runtime support; it's designed to be executed in an isolated environment. Calling standard library ABIs is not supported, but see wasys for an example program which exposes syscalls as WebAssembly import functions.

• Supports snapshot-and-restore across compiler versions and CPU architectures. Could also support limited form of code swapping during snapshot and restore.

• Cross-compilaton is supported via Go build tags. If wagamd64 is specified, the x86-64 code generator is used regardless of host architecture, and CPU feature detection is disabled with pessimistic assumptions. Likewise for wagarm64, but feature detection is never used for ARM64.

Status

• Supports WebAssembly version 1 (MVP).

• Generated x86-64 code requires SSE4.1 ROUNDSS/ROUNDSD instructions.

• ARM64 backend supports "hello, world" but not much else.

• The Go package API hasn't been finalized (but it's getting there).

Security

Spectre variant 1: Memory indexes are limited to 32 bits and static offsets to 31 bits. To prevent conditional branch exploitation, a secure runtime environment must ensure that nothing else is mapped within 6 GB following the address of WebAssembly linear memory. It's therefore not safe for an oblivious host program using default memory allocation APIs to run arbitrary user programs.

Spectre variant 2: On x86, Retpoline is used to protect the runtime environment (although user programs shouldn't be able to inject arbitrary addresses into the branch target buffer).

Testing

Requires Linux, Go, make, clang and libcapstone. About 75% of the WebAssembly spec testsuite is run, by first converting the tests to binary format:

1. go get -t github.com/tsavola/wag
2. make -C $GOPATH/src/github.com/tsavola/wag/testdata/wabt
3. go test -v -bench=. github.com/tsavola/wag/...

Screenshot #1

$ go get github.com/tsavola/wag/cmd/wasys
$ wasys -v $GOPATH/src/github.com/tsavola/wag/testdata/hello.wasm
import write(i32, i32, i32) i32
import openat(i32, i32, i32, i32) i32
import read(i32, i32, i32) i32
import close(i32) i32
import pipe2(i32, i32) i32
import _exit(i32)
hello, world

Screenshot #2

=== RUN   TestSnapshot
--- PASS: TestSnapshot (0.00s)
    snapshot_test.go:80: print output:
        10
        --- snapshotting ---
        current memory limit: 0x6a96051ca000
        current stack ptr:    0x6a960533ffc0
        globals+memory addr:  0x6a96051ba000
        stack addr:           0x6a960533f000
        globals+memory size:  65536
        memory size:          65536
        stack offset:         4032
        stacktrace:
        #1  func-3
        #2  func-2
        --- shot snapped ---
        20
    snapshot_test.go:88: resuming
    snapshot_test.go:100: print output:
        20
        30
        330
        40
        440

Documentation

Overview

Package wag provides a high-level WebAssembly compiler API.

See the Compile function's source code for an example of how to use the low-level compiler APIs (implemented in subpackages).

Errors

Some errors returned by wag implement the following interface:

interface {
    ModuleError() string
}

Presence of the ModuleError method indicates that the error is caused by unsupported or malformed WebAssembly module. Other errors returned by compilation functions are either read errors or internal compiler errors. Read errors (such as EOF) are passed though as is.

Errors implementing the following interface indicate that generated code or data doesn't fit in a target buffer:

interface {
    BufferSizeLimit() string
}

(Buffer size limit errors implement also the ModuleError method.)

Index

• type Config
• type EntryPolicy
• type Object
  • func Compile(objectConfig *Config, r compile.Reader, imports binding.ImportResolver) (object *Object, err error)

Types

type Config

type Config struct {
	Text            compile.CodeBuffer // Defaults to dynamically sized buffer.
	GlobalsMemory   compile.DataBuffer // Defaults to dynamically sized buffer.
	MemoryAlignment int                // Defaults to minimal valid alignment.
	Entry           string             // No entry function by default.
	EntryPolicy     EntryPolicy        // Defaults to binding.GetMainFunc.
	EntryArgs       []uint64           // Defaults to zeros (subject to policy).
}

Config for a single compiler invocation. Zero values are replaced with effective defaults during compilation.

type EntryPolicy

type EntryPolicy func(m *compile.Module, symbol string) (globalIndex uint32, sig wa.FuncType, err error)

EntryPolicy validates an entry function's signature while looking it up from a module's exported functions.

type Object

type Object struct {
	FuncTypes         []wa.FuncType       // Signatures for debug output.
	InitialMemorySize int                 // Current memory allocation.
	MemorySizeLimit   int                 // Maximum valid value if not limited.
	Text              []byte              // Machine code and read-only data.
	debug.InsnMap                         // Stack unwinding and debug metadata.
	MemoryOffset      int                 // Threshold between globals and memory.
	GlobalsMemory     []byte              // Global values and memory contents.
	StackFrame        []byte              // Entry function address and arguments.
	Names             section.NameSection // Symbols for debug output.
}

Object code with debug information. The fields are roughly in order of appearance during compilation.

Executing the code requires a platform-specific mechanism; it's not supported by this package.

func Compile

func Compile(objectConfig *Config, r compile.Reader, imports binding.ImportResolver) (object *Object, err error)

Compile a WebAssembly binary module into machine code. The Object is constructed incrementally so that populated fields may be inspected on error.

See the source code for examples of how to use the lower-level APIs.