wag

README

wag is a WebAssembly compiler implemented as a Go package.

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

Features

• Source is a wasm32 binary module. The application embedding the compiler decides what import functions it provides.

• Supports x86-64. Support for 64-bit ARM is planned. (Support for non-64-bit or non-little-endian CPU architectures isn't planned.)

• Single-pass, low-latency 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.

• Generated code requires minimal runtime support. It may be run e.g. in a strict seccomp sandbox. Note: calling standard library ABIs is not supported.

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

Status

• WebAssembly binary encoding version 1.

• Some floating-point instructions haven't been implemented yet.

• The Go package API hasn't been finalized.

• Cross-compilation will be supported once the backend interface stabilizes.

• Multithreading is not supported. (WebAssembly doesn't define it yet.)

• Much debugging remains to be done...

Testing

Requires Linux, Go, make, clang and libcapstone. About 70% 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

The wag-toolchain repository tests input from a C/C++ compiler.

Screenshot

=== 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

• type Buffer
• type Environment
• type InsnMap
• type Module
  • func (m *Module) CallMap() []byte
  • func (m *Module) Data() (data []byte, memoryOffset int)
  • func (m *Module) FunctionMap() []byte
  • func (m *Module) FunctionSignatures() (funcSigs []types.Function)
  • func (m *Module) Load(r Reader, env Environment, textBuffer Buffer, roDataBuf []byte, ...) (err error)
  • func (m *Module) LoadCodeSection(r Reader, textBuffer Buffer, roDataBuf []byte, roDataAbsAddr int32, ...) (err error)
  • func (m *Module) LoadDataSection(r Reader) (err error)
  • func (m *Module) LoadPreliminarySections(r Reader, env Environment) (err error)
  • func (m *Module) MemoryLimits() (initial, maximum wasm.MemorySize)
  • func (m *Module) ROData() []byte
  • func (m *Module) Signatures() []types.Function
  • func (m *Module) Text() (b []byte)
• type Reader

Types

type Buffer

type Buffer = module.Buffer

type Environment

type Environment interface {
	ImportFunction(module, field string, sig types.Function) (variadic bool, absAddr uint64, err error)
	ImportGlobal(module, field string, t types.T) (valueBits uint64, err error)
}

type InsnMap

type InsnMap interface {
	Init(numFuncs int)
	PutFunc(pos int32)
	PutInsn(pos int32)
}

type Module

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

	module.Internal
}

func (*Module) CallMap

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

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.

func (*Module) FunctionMap

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

FunctionMap is available after code section has been loaded.

func (*Module) FunctionSignatures

func (m *Module) FunctionSignatures() (funcSigs []types.Function)

FunctionSignatures are available after preliminary sections have been loaded.

func (*Module) Load

func (m *Module) Load(r Reader, env Environment, textBuffer Buffer, roDataBuf []byte, roDataAbsAddr int32, startTrigger chan<- struct{}) (err error)

Load all (remaining) sections.

func (*Module) LoadCodeSection

func (m *Module) LoadCodeSection(r Reader, textBuffer Buffer, roDataBuf []byte, roDataAbsAddr int32, startTrigger chan<- struct{}) (err error)

LoadCodeSection, after loading the preliminary sections.

func (*Module) LoadDataSection

func (m *Module) LoadDataSection(r Reader) (err error)

LoadDataSection, after loading the preliminary sections.

func (*Module) LoadPreliminarySections

func (m *Module) LoadPreliminarySections(r Reader, env Environment) (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() []byte

ROData is available after code section has been loaded.

func (*Module) Signatures

func (m *Module) Signatures() []types.Function

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.