wasm

package module
Version: v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 25, 2018 License: MIT Imports: 5 Imported by: 0

README

CircleCI godoc

go-wasm

A WebAssembly binary file parser in go.

The parser takes an io.Reader and parses a WebAssembly module from it, which allows the user to see into the binary file. All data is read, future version may allow to write it out too, which would allow modifying the binary.

For example:

package main

import (
	"flag"
	"fmt"
	"os"
	"text/tabwriter"

	wasm "github.com/akupila/go-wasm"
)

func main() {
	file := flag.String("file", "", "file to parse (.wasm)")
	flag.Parse()

	if *file == "" {
		flag.Usage()
		os.Exit(2)
	}

	f, err := os.Open(*file)
	if err != nil {
		fmt.Fprintf(os.Stderr, "open file: %v", err)
		os.Exit(1)
	}
	defer f.Close()

	mod, err := wasm.Parse(f)
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}

	w := tabwriter.NewWriter(os.Stdout, 0, 0, 4, ' ', 0)
	fmt.Fprintf(w, "Index\tName\tSize (bytes)\n")
	for i, s := range mod.Sections {
		fmt.Fprintf(w, "%d\t%s\t%d\n", i, s.Name(), s.Size())
	}
	w.Flush()
}

when passed in a .wasm file compiled with go1.11:

Index    Name        Size (bytes)
0        Custom      103
1        Type        58
2        Import      363
3        Function    1588
4        Table       5
5        Memory      5
6        Global      51
7        Export      14
8        Element     3066
9        Code        1174891
10       Data        1169054
11       Custom      45428

Much more information is available by type asserting on the items in .Sections, for example:

for i, s := range mod.Sections {
    switch section := s.(type) {
        case *wasm.SectionCode:
            // can now read function bytecode from section.
    }
}

Installation

go get github.com/akupila/go-wasm/...

Notes

This is a experimental, early and definitely not properly tested. There are probably bugs. If you find one, please open an issue!

Documentation

Overview

Package wasm provides a binary parser for WebAssembly (.wasm) files.

https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md

Example (ParseFile)
f, err := os.Open(filename)
if err != nil {
	log.Fatal(err)
}
defer f.Close()

mod, err := Parse(f)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("The file has %d sections\n", len(mod.Sections))
Output:

The file has 12 sections

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DataSegment

type DataSegment struct {
	// Index is the linear memory index.
	//
	// https://github.com/WebAssembly/design/blob/master/Modules.md#linear-memory-index-space
	Index uint32

	// Offset is an init expression (wasm bytecode) that computes the offset to
	// place the data.
	Offset []byte

	// Data is the raw data to be placed in memory.
	Data []byte
}

A DataSegment is a segment of data in the Data section that is loaded into linear memory.

type ElemSegment

type ElemSegment struct {
	// Index is the table index.
	Index uint32

	// Offset is an init expression (wasm bytecode) to compute the offset at
	// which to place the elements.
	Offset []byte

	// Elems contains the sequence of function indicies.
	Elems []uint32
}

An ElemSegment is an element segment. It initializes a table with initial values.

type ExportEntry

type ExportEntry struct {
	// Field is the name of the field being exported.
	Field string

	// Kind is the kind of export.
	Kind ExternalKind

	// Index is the index into the corresponding index space.
	//
	// https://github.com/WebAssembly/design/blob/master/Modules.md#function-index-space
	Index uint32
}

ExportEntry specifies an individual export from the module.

type ExternalKind

type ExternalKind uint8

ExternalKind is set as the Kind for an import entry. The value specifies what type of import it is.

const (
	// ExtKindFunction is an imported function.
	ExtKindFunction ExternalKind = iota

	// ExtKindTable is an imported table.
	ExtKindTable

	// ExtKindMemory is imported memory.
	ExtKindMemory

	// ExtKindGlobal is an imported global.
	ExtKindGlobal
)

type FuncType

type FuncType struct {
	// Form is the value for a func type constructor (always 0x60, the op code
	// for a function).
	Form int8

	// Params contains the parameter types of the function.
	Params []int8

	// ReturnCount returns the number of results from the function.
	// The value will be 0 or 1.
	//
	// Future version may allow more: https://github.com/WebAssembly/design/issues/1146
	ReturnCount uint8

	// ReturnType is the result type if ReturnCount > 0.
	ReturnTypes []int8
}

A FuncType is the description of a function signature.

type FunctionBody

type FunctionBody struct {
	// Locals define the local variables of the function.
	Locals []LocalEntry

	// Code is the wasm bytecode of the function.
	Code []byte
}

A FunctionBody is the body of a function.

type FunctionType

type FunctionType struct {
	// Index is the index of the function signature.
	Index uint32
}

FunctionType the type for a function import.

type GlobalType

type GlobalType struct {
	// ContentType is the type of the value.
	ContentType int8

	// Mutable is true if the global value can be modified.
	Mutable bool
}

GlobalType is the type for a global import.

type GlobalVariable

type GlobalVariable struct {
	// Type is the type of the global variable.
	Type GlobalType

	// Init is an init expression (wasm bytecode) to set the initial value of
	// the global variable.
	Init []byte
}

A GlobalVariable is a global variable defined by the module.

type ImportEntry

type ImportEntry struct {
	// Module is the name of the module.
	Module string

	// Field is the field name being imported.
	Field string

	// Kind specified the type of import. The import type value will be set
	// depending on the kind, the other ones will be nil.
	Kind ExternalKind

	// FunctionType describes a function import, if Kind == ExtKindFunction.
	FunctionType *FunctionType

	// TableType describes a table import, if Kind == ExtKindTable.
	TableType *TableType

	// MemoryType describes a memory import, if Kind == ExtKindMemory.
	MemoryType *MemoryType

	// GlobalType describes a global import, if Kind == ExtKindGlobal.
	GlobalType *GlobalType
}

ImportEntry describes an individual import to the module.

type LocalEntry

type LocalEntry struct {
	// Count specifies the number of the following type.
	Count uint32

	// Type is the type of the variable.
	Type int8
}

LocalEntry is a local variable in a function.

type LocalName

type LocalName struct {
	// Index is the index of the function whose locals are being named.
	Index uint32

	// LocalMap is the name mapping for the function.
	LocalMap NameMap
}

LocalName a name mapping for a local function name.

type Locals

type Locals struct {
	// Funcs are the functions to be named.
	Funcs []LocalName
}

Locals assigns name maps to a subset of functions in the function index space (imports and module-defined).

type MemoryType

type MemoryType struct {
	// Limits contains memory limits defined by the import.
	Limits ResizableLimits
}

MemoryType is the type for a memory import.

type Module

type Module struct {
	// Sections contains the sections in the parsed file, in the order they
	// appear in the file. A valid  but empty file will have zero sections.
	//
	// The items in the slice will be a mix of the SectionXXX types.
	Sections []Section
}

A Module represents a parsed WASM module.

func Parse

func Parse(r io.Reader) (*Module, error)

Parse parses the input to a WASM module.

type NameMap

type NameMap struct {
	// Names contains a list of mappings in the NameMap.
	Names []Naming
}

A NameMap is a map that maps an index to a name.

type Naming

type Naming struct {
	// Index is the index that is being named.
	Index uint32

	// Name is a UTF-8 name.
	Name string
}

Naming is a single function naming. It maps an index to a human readable function name.

type ResizableLimits

type ResizableLimits struct {
	// Initial is the initial length of the memory.
	Initial uint32

	// Maximum is the maximum length of the memory. May not be set.
	Maximum uint32
}

ResizableLimits describes the limits of a table or memory.

type Section

type Section interface {
	// ID returns the WASM identifier of the section, for example 0x0A for the
	// code section.
	ID() uint8

	// Name returns the name of the section.
	Name() string

	// Size returns the size of the section in bytes.
	Size() uint32
}

A Section contains all the information for a single section in the WASM file. A file is built up of zero or more sections.

type SectionCode

type SectionCode struct {
	// Bodies contains all function bodies.
	Bodies []FunctionBody
	// contains filtered or unexported fields
}

SectionCode contains a function body for every function in the module.

func (SectionCode) ID

func (s SectionCode) ID() uint8

func (SectionCode) Name

func (s SectionCode) Name() string

func (SectionCode) Size

func (s SectionCode) Size() uint32

type SectionCustom

type SectionCustom struct {
	// SectionName is the name of the section as defined in the wasm file.
	SectionName string

	// Payload is the raw payload for the section.
	Payload []byte
	// contains filtered or unexported fields
}

SectionCustom is a custom or name section added by the compiler that generated the WASM file.

func (SectionCustom) ID

func (s SectionCustom) ID() uint8

func (SectionCustom) Name

func (s SectionCustom) Name() string

func (SectionCustom) Size

func (s SectionCustom) Size() uint32

type SectionData

type SectionData struct {
	// Entries contains the data segment entries.
	Entries []DataSegment
	// contains filtered or unexported fields
}

SectionData declares the initialized data that is loaded into the linear memory.

func (SectionData) ID

func (s SectionData) ID() uint8

func (SectionData) Name

func (s SectionData) Name() string

func (SectionData) Size

func (s SectionData) Size() uint32

type SectionElement

type SectionElement struct {
	// Entries contains the elements.
	Entries []ElemSegment
	// contains filtered or unexported fields
}

SectionElement defines element segments that initialize elements of imported or internally-defined tables with any other definition in the module.

https://github.com/WebAssembly/design/blob/master/Modules.md#elements-section

func (SectionElement) ID

func (s SectionElement) ID() uint8

func (SectionElement) Name

func (s SectionElement) Name() string

func (SectionElement) Size

func (s SectionElement) Size() uint32

type SectionExport

type SectionExport struct {
	Entries []ExportEntry
	// contains filtered or unexported fields
}

SectionExport declares exports from the WASM module.

https://github.com/WebAssembly/design/blob/master/Modules.md#exports

func (SectionExport) ID

func (s SectionExport) ID() uint8

func (SectionExport) Name

func (s SectionExport) Name() string

func (SectionExport) Size

func (s SectionExport) Size() uint32

type SectionFunction

type SectionFunction struct {
	// Types contains a sequence of indices into the type section.
	Types []uint32
	// contains filtered or unexported fields
}

SectionFunction declares the signatures of all functions in the modules. The definitions of the functions will be in the code section.

func (SectionFunction) ID

func (s SectionFunction) ID() uint8

func (SectionFunction) Name

func (s SectionFunction) Name() string

func (SectionFunction) Size

func (s SectionFunction) Size() uint32

type SectionGlobal

type SectionGlobal struct {
	Globals []GlobalVariable
	// contains filtered or unexported fields
}

SectionGlobal provides an internal definition of global variables.

https://github.com/WebAssembly/design/blob/master/Modules.md#global-section

func (SectionGlobal) ID

func (s SectionGlobal) ID() uint8

func (SectionGlobal) Name

func (s SectionGlobal) Name() string

func (SectionGlobal) Size

func (s SectionGlobal) Size() uint32

type SectionImport

type SectionImport struct {
	// Entries contains import entries to the module.
	Entries []ImportEntry
	// contains filtered or unexported fields
}

SectionImport declares all imports defined by the module.

func (SectionImport) ID

func (s SectionImport) ID() uint8

func (SectionImport) Name

func (s SectionImport) Name() string

func (SectionImport) Size

func (s SectionImport) Size() uint32

type SectionMemory

type SectionMemory struct {
	Entries []MemoryType
	// contains filtered or unexported fields
}

SectionMemory declares a memory section. The section provides an internal definition of one linear memory.

https://github.com/WebAssembly/design/blob/master/Modules.md#linear-memory-section

func (SectionMemory) ID

func (s SectionMemory) ID() uint8

func (SectionMemory) Name

func (s SectionMemory) Name() string

func (SectionMemory) Size

func (s SectionMemory) Size() uint32

type SectionName

type SectionName struct {
	// SectionName is the name of the name section. The value is always "name".
	SectionName string

	// Module is the name of the WASM module.
	Module string

	// Functions contains function name mappings.
	Functions *NameMap

	// Locals contains local function name mappings.
	Locals *Locals
	// contains filtered or unexported fields
}

SectionName is a custom section that provides debugging information, by matching indices to human readable names.

func (SectionName) ID

func (s SectionName) ID() uint8

func (SectionName) Name

func (s SectionName) Name() string

func (SectionName) Size

func (s SectionName) Size() uint32

type SectionStart

type SectionStart struct {
	// Index is the index to the start function in the function index space.
	//
	// https://github.com/WebAssembly/design/blob/master/Modules.md#function-index-space
	Index uint32
	// contains filtered or unexported fields
}

SectionStart defines the start node, if the module has a start node defined.

https://github.com/WebAssembly/design/blob/master/Modules.md#module-start-function

func (SectionStart) ID

func (s SectionStart) ID() uint8

func (SectionStart) Name

func (s SectionStart) Name() string

func (SectionStart) Size

func (s SectionStart) Size() uint32

type SectionTable

type SectionTable struct {
	Entries []MemoryType
	// contains filtered or unexported fields
}

SectionTable declares a table section. A table is similar to linear memory, whose elements, instead of being bytes, are opaque values of a particular table element. This allows the table to contain values -- like GC references, raw OS handles, or native pointers -- that are accessed by WebAssembly code indirectly through an integer index.

https://github.com/WebAssembly/design/blob/master/Semantics.md#table

func (SectionTable) ID

func (s SectionTable) ID() uint8

func (SectionTable) Name

func (s SectionTable) Name() string

func (SectionTable) Size

func (s SectionTable) Size() uint32

type SectionType

type SectionType struct {
	// Entries are the entries in a Type section. Each entry declares one type.
	Entries []FuncType
	// contains filtered or unexported fields
}

SectionType declares all function type definitions used in the module.

func (SectionType) ID

func (s SectionType) ID() uint8

func (SectionType) Name

func (s SectionType) Name() string

func (SectionType) Size

func (s SectionType) Size() uint32

type TableType

type TableType struct {
	// ElemType specifies the type of the elements.
	ElemType int8

	// Limits specifies the resizable limits of the table.
	Limits ResizableLimits
}

TableType is the type for a table import.

Directories

Path Synopsis
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL