Documentation

Overview

Package compile implements a WebAssembly compiler.

Text

Module sections (wasm v1) which affect the immutable text (machine code):

Type
Import
Function
Table
Memory (*)
Global (*)
Element
Code

(*) Memory sizes and global values do not affect text, only their counts and types do.

Sections which have no effect on text:

Export
Start
Data
Custom sections

Vector-based import function indexes also affect text, but their addresses are configured at run-time by mapping the vector immediately before text.

Globals and memory

The memory, global and data sections comprise a single mutable buffer.

Stack

Any effect the export and start sections have happens via the run-time stack buffer, which must be initialized with optional start and entry function addresses.

Stack regions from low to high address:

1. Space for runtime-specific variables.
2. Space for signal stacks and red zones.
3. 240 bytes for use by trap handlers and vector-based import functions.
4. 8 bytes for trap handler return address (included in call stack).
5. 8 bytes for an extra function call (included in call stack).
6. The rest of the call stack (size must be a multiple of 8).
7. Start function address (4 bytes padded to 8).
8. Entry function address (4 bytes padded to 8).

Address of region 3 must be aligned so that the threshold between regions 5 and 6 (the stack limit) is a multiple of 256.

Function addresses are relative to the start of text. Zero address causes the function to be skipped.

Stack pointer is initially positioned between regions 6 and 7. Function prologue compares the stack pointer against the threshold between regions 5 and 6 (the stack limit).

Index

Constants

View Source
const (
	MaxTextSize   = 512 * 1024 * 1024
	MaxMemorySize = maxMemoryPages * wa.PageSize
)
View Source
const ObjectVersion = 0

    ABI version of generated machine code.

    Variables

    This section is empty.

    Functions

    func LoadCodeSection

    func LoadCodeSection(config *CodeConfig, r Reader, mod Module, lib Library) (err error)

      LoadCodeSection reads a WebAssembly module's code section and generates machine code.

      If CodeBuffer panicks with an error, it will be returned by this function.

      func LoadCustomSections

      func LoadCustomSections(config *Config, r Reader) (err error)

        LoadCustomSections reads WebAssembly module's extension sections.

        func LoadDataSection

        func LoadDataSection(config *DataConfig, r Reader, mod Module) (err error)

          LoadDataSection reads a WebAssembly module's data section and generates initial contents of mutable program state (globals and linear memory).

          If DataBuffer panicks with an error, it will be returned by this function.

          func ValidateDataSection

          func ValidateDataSection(config *Config, r Reader, mod Module) (err error)

            ValidateDataSection reads a WebAssembly module's data section.

            Types

            type Breakpoint

            type Breakpoint = gen.Breakpoint

            type CodeBuffer

            type CodeBuffer = code.Buffer

            type CodeConfig

            type CodeConfig struct {
            	MaxTextSize  int        // Set to MaxTextSize if unspecified or too large.
            	Text         CodeBuffer // Initialized with default implementation if nil.
            	Mapper       ObjectMapper
            	EventHandler func(event.Event)
            	LastInitFunc uint32
            	Breakpoints  map[uint32]Breakpoint
            	Config
            }

              CodeConfig for a single compiler invocation.

              MaxTextSize field limits memory allocations only when Text field is not specified. To limit memory allocations when providing a custom CodeBuffer implementation, the implementation must take care of it.

              type Config

              type Config struct {
              	// SectionMapper is invoked for every section (standard or custom), just
              	// after the section id byte.  It must read and return the payload length
              	// (varuint32), but not the payload itself.
              	SectionMapper func(sectionID byte, r Reader) (payloadLen uint32, err error)
              
              	// CustomSectionLoader is invoked for every custom section.  It must read
              	// exactly payloadLen bytes, or return an error.  SectionMapper (if
              	// configured) has been invoked just before it.
              	CustomSectionLoader func(r Reader, payloadLen uint32) error
              }

                Config for loading WebAssembly module sections.

                type DataBuffer

                type DataBuffer = data.Buffer

                type DataConfig

                type DataConfig struct {
                	GlobalsMemory   DataBuffer // Initialized with default implementation if nil.
                	MemoryAlignment int        // Initialized with minimal value if zero.
                	Config
                }

                  DataConfig for a single compiler invocation.

                  type DebugObjectMapper

                  type DebugObjectMapper = obj.DebugObjectMapper

                  type Library

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

                  func (Library) ExportFunc

                  func (l Library) ExportFunc(field string) (funcIndex uint32, sig wa.FuncType, found bool)

                  func (Library) ImportFunc

                  func (l Library) ImportFunc(i int) (module, field string, sig wa.FuncType)

                  func (*Library) LoadSections

                  func (lib *Library) LoadSections(r Reader) (err error)

                  func (Library) NumImportFuncs

                  func (l Library) NumImportFuncs() int

                  func (*Library) SetImportFunc

                  func (l *Library) SetImportFunc(i int, vectorIndex int)

                  func (*Library) XXX_Internal

                  func (l *Library) XXX_Internal() interface{}

                  type Module

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

                    Module contains a WebAssembly module specification without code or data.

                    func LoadInitialSections

                    func LoadInitialSections(config *ModuleConfig, r Reader) (m Module, err error)

                      LoadInitialSections reads module header and all sections preceding code and data.

                      func (Module) AsLibrary

                      func (mod Module) AsLibrary() (lib Library, err error)

                      func (Module) ExportFunc

                      func (m Module) ExportFunc(field string) (funcIndex uint32, sig wa.FuncType, found bool)

                      func (Module) ExportFuncs

                      func (m Module) ExportFuncs() map[string]uint32

                      func (Module) FuncTypeIndexes

                      func (m Module) FuncTypeIndexes() []uint32

                      func (Module) FuncTypes

                      func (m Module) FuncTypes() []wa.FuncType

                      func (Module) GlobalTypes

                      func (m Module) GlobalTypes() []wa.GlobalType

                      func (Module) GlobalsSize

                      func (m Module) GlobalsSize() int

                      func (Module) ImportFunc

                      func (m Module) ImportFunc(i int) (module, field string, sig wa.FuncType)

                      func (Module) ImportGlobal

                      func (m Module) ImportGlobal(i int) (module, field string, t wa.Type)

                      func (Module) InitialMemorySize

                      func (m Module) InitialMemorySize() int

                      func (Module) MemorySizeLimit

                      func (m Module) MemorySizeLimit() int

                      func (Module) NumImportFuncs

                      func (m Module) NumImportFuncs() int

                      func (Module) NumImportGlobals

                      func (m Module) NumImportGlobals() int

                      func (*Module) SetImportFunc

                      func (m *Module) SetImportFunc(i int, libFunc uint32)

                      func (*Module) SetImportGlobal

                      func (m *Module) SetImportGlobal(i int, init uint64)

                      func (Module) StartFunc

                      func (m Module) StartFunc() (funcIndex uint32, defined bool)

                      func (Module) Types

                      func (m Module) Types() []wa.FuncType

                      type ModuleConfig

                      type ModuleConfig struct {
                      	Config
                      }

                        ModuleConfig for a single compiler invocation.

                        type ObjectMapper

                        type ObjectMapper = obj.ObjectMapper

                        type Reader

                        type Reader = binary.Reader

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

                          Directories

                          Path Synopsis