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 wasm binary module.

• The output is machine code.

• It is only a compiler. A runtime environment for the compiled program, including all import functions, needs to be implemented separately. Wag has been developed for the Gate 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 directly supported.

• Supports snapshot-and-restore across compiler versions and CPU architectures.

• Supports breakpoint debugging via recompilation.

• Cross-compilation 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 not currently used for ARM64 in any case).

Status

• Supports WebAssembly version 1 (wasm32). No wasm extensions are supported.

• Supports x86-64 and ARM64 code generation.

• Generated x86-64 code requires SSE4.1 floating-point instructions (available since 2007).

Security

Spectre variant 1: Out-of-bounds linear memory access detection requires that addressable but unallocated memory is inaccessible. It naturally prevents conditional branch exploitation.

Spectre variant 2: On x86-64, 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, Make, Go, Python, Capstone, and a recent version of WABT. The applicable parts of the WebAssembly spec testsuite are run. Code execution tests are implemented in a separate Go module in the testsuite subdirectory (to work around circular dependencies). All tests can be run by checking out Git submodules and running make check.

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

ModuleError and ResourceLimit error types are accessible via errors subpackage. Such errors may be returned by compilation and other parsing functions. Other types of errors indicate either a read error or an internal compiler error. (Unexpected EOF is a ModuleError which wraps io.ErrUnexpectedEOF.)

Index

• func CompileLibrary(r compile.Reader, imports binding.LibraryImportResolver) (lib compile.Library, err error)
• type Config
• type Object
  • func Compile(objectConfig *Config, r compile.Reader, lib compile.Library) (object *Object, err error)

Functions

func CompileLibrary

func CompileLibrary(r compile.Reader, imports binding.LibraryImportResolver) (lib compile.Library, err error)

Types

type Config

type Config struct {
	ImportResolver  binding.ImportResolver // Imports are mapped to the library by default.
	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.
}

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

type Object

type Object struct {
	FuncTypes         []wa.FuncType       // Signatures for debug output.
	InitialMemorySize int                 // Current memory allocation.
	MemorySizeLimit   int                 // -1 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              // Start and entry function addresses.
	Names             section.NameSection // Symbols for debug output.
	Debug             *dwarf.Data         // More detailed debug information.
}

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

Executing the code requires a platform-specific mechanism. It is not supported by this package, but see the compile subpackage for information.

func Compile

func Compile(objectConfig *Config, r compile.Reader, lib compile.Library) (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.