wag

README

wag is a WebAssembly compiler (or assembler?) 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 embedders of the compiler decide what kind of import functions they choose to implement and make available for the WebAssembly programs.

• The output is executable x86-64 machine code. Support for 64-bit ARM is planned. (Support for non-64-bit or non-little-endian CPU architectures isn't planned.)

• 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.

Status

• Implements WebAssembly binary encoding version 1.

• The Go package API hasn't been finalized.

• The snapshot-and-restore functionality is beta quality.

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 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 open(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:73: 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:81: resuming
	snapshot_test.go:93: print output:
		20
		30
		330
		40
		440

Documentation

Index

• Constants
• type CallSite
• type DataBuffer
• type Env
• type FixedBuffer
  • func NewFixedBuffer(b []byte) *FixedBuffer
  • func (f *FixedBuffer) Bytes() []byte
  • func (f *FixedBuffer) Extend(n int) []byte
  • func (f *FixedBuffer) Pos() int32
  • func (f *FixedBuffer) PutByte(b byte)
  • func (f *FixedBuffer) PutBytes(b []byte)
  • func (f *FixedBuffer) ResizeBytes(n int) []byte
• type InsnMap
• type Module
  • func (m *Module) CallMap() []CallSite
  • func (m *Module) Data() (data []byte, memoryOffset int)
  • func (m *Module) FunctionMap() []int32
  • func (m *Module) FunctionSignatures() (funcSigs []function.Type)
  • func (m *Module) GlobalsSize() int
  • func (m *Module) Load(r Reader, env Env, text TextBuffer, roData DataBuffer, roDataAddr int32, ...) (err error)
  • func (m *Module) LoadCodeSection(r Reader, text TextBuffer, roData DataBuffer, roDataAddr int32, ...) (err error)
  • func (m *Module) LoadDataSection(r Reader, data DataBuffer) (err error)
  • func (m *Module) LoadPreliminarySections(r Reader, env Env) (err error)
  • func (m *Module) MemoryLimits() (initial, maximum wasm.MemorySize)
  • func (m *Module) ROData() (b []byte)
  • func (m *Module) Signatures() []function.Type
  • func (m *Module) Text() (b []byte)
• type Reader
• type TextBuffer

Constants

const (
	DefaultMemoryAlignment = 16 // see Module.MemoryAlignment
)

Types

type CallSite

type CallSite = module.CallSite

type DataBuffer

type DataBuffer = module.DataBuffer

type Env

type Env interface {
	ImportFunction(module, field string, sig function.Type) (variadic bool, absAddr uint64, err error)
	ImportGlobal(module, field string, t wasm.Type) (valueBits uint64, err error)
}

type FixedBuffer

type FixedBuffer struct {
	// contains filtered or unexported fields
}

FixedBuffer is a fixed-capacity implementation of TextBuffer and DataBuffer.

func NewFixedBuffer

func NewFixedBuffer(b []byte) *FixedBuffer

func (*FixedBuffer) Bytes

func (f *FixedBuffer) Bytes() []byte

func (*FixedBuffer) Extend

func (f *FixedBuffer) Extend(n int) []byte

func (*FixedBuffer) Pos

func (f *FixedBuffer) Pos() int32

func (*FixedBuffer) PutByte

func (f *FixedBuffer) PutByte(b byte)

func (*FixedBuffer) PutBytes

func (f *FixedBuffer) PutBytes(b []byte)

func (*FixedBuffer) ResizeBytes

func (f *FixedBuffer) ResizeBytes(n int) []byte

type InsnMap

type InsnMap = codegen.InsnMap

type Module

type Module struct {
	EntrySymbol          string
	EntryArgs            []uint64
	MemoryAlignment      int // see Data()
	UnknownSectionLoader func(r Reader, payloadLen uint32) error
	InsnMap              InsnMap

	module.Module
}

func (*Module) CallMap

func (m *Module) CallMap() []CallSite

CallMap is available after code section has been loaded.

func (*Module) Data

func (m *Module) Data() (data []byte, memoryOffset int)

Data is available after data section has been loaded. memoryOffset is an offset into data. It will be a multiple of MemoryAlignment.

func (*Module) FunctionMap

func (m *Module) FunctionMap() []int32

FunctionMap is available after code section has been loaded.

func (*Module) FunctionSignatures

func (m *Module) FunctionSignatures() (funcSigs []function.Type)

FunctionSignatures are available after preliminary sections have been loaded.

func (*Module) GlobalsSize

func (m *Module) GlobalsSize() int

GlobalsSize is available after preliminary sections have been loaded.

func (*Module) Load

func (m *Module) Load(r Reader, env Env, text TextBuffer, roData DataBuffer, roDataAddr int32, data DataBuffer) (err error)

Load all (remaining) sections.

func (*Module) LoadCodeSection

func (m *Module) LoadCodeSection(r Reader, text TextBuffer, roData DataBuffer, roDataAddr int32, startTrigger chan<- struct{}) (err error)

LoadCodeSection, after loading the preliminary sections.

func (*Module) LoadDataSection

func (m *Module) LoadDataSection(r Reader, data DataBuffer) (err error)

LoadDataSection, after loading the preliminary sections.

func (*Module) LoadPreliminarySections

func (m *Module) LoadPreliminarySections(r Reader, env Env) (err error)

LoadPreliminarySections, excluding the code and data sections.

func (*Module) MemoryLimits

func (m *Module) MemoryLimits() (initial, maximum wasm.MemorySize)

MemoryLimits are available after preliminary sections have been loaded.

func (*Module) ROData

func (m *Module) ROData() (b []byte)

ROData is available after code section has been loaded.

func (*Module) Signatures

func (m *Module) Signatures() []function.Type

Signatures are available after preliminary sections have been loaded.

func (*Module) Text

func (m *Module) Text() (b []byte)

Text is available after code section has been loaded.

type Reader

type Reader = module.Reader

Reader is a subset of bufio.Reader, bytes.Buffer and bytes.Reader.

type TextBuffer

type TextBuffer = module.TextBuffer