wit

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 28, 2026 License: BSD-3-Clause Imports: 7 Imported by: 0

Documentation

Overview

Package wit reads WIT (the WebAssembly Interface Types language, component-model design/mvp/WIT.md) for the subset the wasi-gfx packages use, and implements the Canonical ABI (design/mvp/CanonicalABI.md) over a core module's linear memory: alignment, sizes, flattening, loads, stores, flat lifting and lowering. A core-module host serves WIT-described imports with it, without a component-model runtime.

Index

Constants

View Source 
const (
	I32  = 'i'
	I64  = 'I'
	F32c = 'f'
	F64c = 'F'
)

Core value types, as the engine's host modules spell them.

View Source 
const (
	MaxFlatParams  = 16
	MaxFlatResults = 1
	// MaxListBytes bounds one list or string a guest passes or receives.
	MaxListBytes = 1 << 28
)

Limits of the ABI (MAX_FLAT_PARAMS, MAX_FLAT_RESULTS).

Variables

View Source 
var ErrTrap = errors.New("canonical ABI trap")

ErrTrap wraps every error that the Canonical ABI defines as a trap.

Functions

func Align 

func Align(t *Type) uint32

Align is the type's alignment.

func Flatten 

func Flatten(t *Type) []byte

Flatten is flatten_type: the core value types of t.

func LiftFlat 

func LiftFlat(t *Type, vals []uint64, m Memory) (any, error)

LiftFlat lifts one value of type t from its core values (a function's flat result, on the caller's side).

func LiftParams 

func LiftParams(f *Func, args []uint64, m Memory) ([]any, error)

LiftParams lifts f's parameters from its core arguments (loading the parameter tuple from memory when they did not fit flat).

func Load 

func Load(m Memory, p uint32, t *Type) (any, error)

Load reads a value of type t at p (aligned).

func LowerFlat 

func LowerFlat(m Memory, a Allocator, t *Type, v any) ([]uint64, error)

LowerFlat is lower_flat: v of type t as core values.

func Parse 

func Parse(src string) (map[string]*Interface, error)

Parse reads WIT source holding one package and its interfaces.

func Size 

func Size(t *Type) uint32

Size is the type's elem_size.

func Store 

func Store(m Memory, a Allocator, p uint32, t *Type, v any) error

Store writes v of type t at p, allocating strings and lists with a.

Types

type AllocReq 

type AllocReq struct{ Align, Size uint32 }

AllocReq is one allocation a lowering needs.

type Allocator 

type Allocator interface {
	Alloc(align, size uint32) (uint32, error)
}

Allocator gives a block of guest memory (the guest's cabi_realloc).

type Case 

type Case struct {
	Name string
	Type *Type
}

Case is a variant case; Type is nil for a case without payload.

type CoreSig 

type CoreSig struct {
	Params, Results []byte
	ParamsInMemory  bool
	RetPtr          bool
}

CoreSig is a function's core signature when lowered synchronously (flatten_functype, 'lower'): params beyond MaxFlatParams go through one pointer; results beyond MaxFlatResults through a return-area pointer appended to the params.

func Sig 

func Sig(f *Func) CoreSig

Sig computes f's core signature.

type Field 

type Field struct {
	Name string
	Type *Type
}

Field is a record field.

type Func 

type Func struct {
	Name   string // as in WIT: "create-buffer", or "" for a constructor
	Kind   FuncKind
	Async  bool
	Params []Param
	Result *Type // nil: no result
}

Func is a WIT function; for a method, Params[0] is "self".

func (*Func) ImportName 

func (f *Func) ImportName(resource string) string

ImportName is a function's core import name.

type FuncKind 

type FuncKind int

FuncKind says where a function is declared. 

const (
	Freestanding FuncKind = iota // "name"
	Method                       // "[method]resource.name"
	Static                       // "[static]resource.name"
	Constructor                  // "[constructor]resource"
)

Function kinds and their core import names (wit-parser's mangling).

type Interface 

type Interface struct {
	Package   string // "wasi:webgpu@0.3.0-rc.2"
	Name      string
	Types     map[string]*Type
	Resources map[string]*Resource
	Funcs     []*Func
	// contains filtered or unexported fields
}

Interface is a WIT interface: its named types, resources and functions.

func (*Interface) ImportModule 

func (i *Interface) ImportModule() string

ImportModule is the core import module name, "ns:pkg/iface@ver".

func (*Interface) ResourceNames 

func (i *Interface) ResourceNames() []string

ResourceNames lists the resources in declaration order.

type Kind 

type Kind int

Kind is a type's constructor. 

const (
	Bool Kind = iota
	U8
	U16
	U32
	U64
	S8
	S16
	S32
	S64
	F32
	F64
	Char
	String
	List
	Record
	Tuple
	Variant
	Enum
	Flags
	Option
	Result
	Own
	Borrow
	Future
	Stream
	Named // an unresolved reference, replaced by Resolve
)

Type kinds (CanonicalABI.md value types).

type Lowering 

type Lowering struct {
	Reqs []AllocReq
	// contains filtered or unexported fields
}

Lowering is a result being lowered: its allocations, then Apply.

func PlanResult 

func PlanResult(f *Func, v any, args []uint64) (*Lowering, error)

PlanResult prepares lowering f's result v. args are the call's core arguments (the last is the return area when Sig(f).RetPtr).

func (*Lowering) Apply 

func (l *Lowering) Apply(m Memory, ptrs []uint32) (uint64, error)

Apply writes the result with the obtained pointers (one per Reqs, in order) and returns the flat result (0 when it went through memory, or when f has no result).

type Memory 

type Memory interface {
	Read(off, n uint32) ([]byte, bool)
	Write(off uint32, b []byte) bool
}

Memory is a guest's linear memory.

type Param 

type Param struct {
	Name string
	Type *Type
}

Param is a function parameter.

type Resource 

type Resource struct {
	Name  string
	Funcs []*Func
}

Resource is a resource type and its functions.

type ResultValue 

type ResultValue struct {
	Err   bool
	Value any
}

ResultValue is a result: Value is the ok or the error payload.

type Some 

type Some struct{ Value any }

Some is a present option value.

type Type 

type Type struct {
	Kind   Kind
	Name   string  // type name for named types, resource name for Own/Borrow
	Elem   *Type   // List, Option, Future, Stream; Result's ok
	Err    *Type   // Result's error
	Fields []Field // Record, Tuple (labels "0", "1", ...)
	Cases  []Case  // Variant
	Labels []string
}

Type is a WIT value type.

func ParamTuple 

func ParamTuple(f *Func) *Type

ParamTuple is the tuple of f's parameter types (what goes to memory when the parameters do not fit flat).

type VariantValue 

type VariantValue struct {
	Case  int
	Value any
}

VariantValue is a variant case and its payload (nil without one).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.