WasmKit Documentation

The stack frame is inspired by the stitch WebAssembly interpreter and consists of four main parts:

1. Frame Header: Contains the saved stack pointer, return address, current instance, and value slots for parameters and return values.
2. Locals: Contains the local variables of the current function.
3. Constant Pool: Contains constant values. Its size is determined during translation based on Wasm-level code size.
4. Dynamic Stack: Contains intermediate values produced by instructions. Its size is fixed at the end of translation based on the maximum stack height.

Slots vs Values

All values are indexed in 64-bit slots (StackSlot == UInt64).

• i32, i64, f32, f64, and ref occupy 1 slot.
• v128 occupies 2 consecutive slots (lo then hi).

Note: Register indices always refer to the first slot of a value. For a v128 value, the register index points to the lo slot, and reg + 1 points to the hi slot.

Lifting and Lowering are the two primary mechanisms for type conversion in the Canonical ABI. They are often split into two stages depending on whether the data fits in function arguments or must be handled via memory.

Lifting (Core $\rightarrow$ WIT)

Used to bring core values into the WIT domain.

1. Flat Lifting: Translates a list of core values directly into a WIT value.
2. Loading: Reads a WIT value from memory. This is used when the value is too large to be passed directly as a function argument or return value.

Lowering (WIT $\rightarrow$ Core)

Used to move WIT values into the core domain.

1. Flat Lowering: Translates a WIT value into a list of core values.
2. Storing: Writes a WIT value to memory. This is used when the value is too large to be passed directly as a function argument or return value.

Note on implementation: To support environments without the multi-value proposal, the number of return values (MAX_FLAT_RESULTS) is currently limited to 1 in the core-level signature.

The StringPassing example demonstrates a common ABI (Application Binary Interface) for passing UTF-8 strings between a WebAssembly host and a guest module. This pattern involves two primary directions of data flow:

Guest to Host (Printing Strings)

To pass a string from the guest to the host:

1. The WebAssembly guest calls an imported host function (e.g., printer.print_str).
2. The guest passes a pair of i32 values: a pointer (ptr) and a length (len).
3. The host reads the UTF-8 bytes from the module's exported memory starting at ptr for len bytes.

Host to Guest (Allocating and Writing Strings)

To pass a string from the host to the guest:

1. The host calls an exported guest function alloc(size: i32) -> i32 to reserve space in the guest's memory.
2. The host writes the UTF-8 bytes into the memory region returned by alloc.
3. The host calls a guest function (e.g., checksum(ptr: i32, len: i32) -> i32) using the allocated pointer and the string length to process the data.

WasmKit uses a register-based interpreter design to achieve high performance and memory efficiency. This design is an evolution from previous generations:

1. First Generation: Interpreted structured WebAssembly instructions directly using a switch-case dispatch. Every block, loop, or if instruction required its own stack frame, making it slow and memory-inefficient.
2. Second Generation: Introduced a translation pass that converted WebAssembly instructions into a stack-based linear intermediate representation. It pre-computed stack-height information and branch offsets to improve branching performance (achieving ~5x speedup).
3. Current (Register-based) Generation: Designed to address performance bottlenecks in non-optimized WebAssembly code (like Swift Standard Library tests). It removes 'provider' instructions (e.g., local.get, i32.const) during translation and embeds register information directly into 'consumer' instructions (e.g., i32.add, call). This reduces the total number of instructions executed.

When using resource types in WIT, the component that exposes an interface containing that resource type is expected to provide the implementation for its methods.

If multiple components (e.g., a service and a middleware) both import and export the same interface containing a resource, both components are responsible for providing implementations for the resource's lifecycle and methods. This includes:

• Constructors (#[constructor])
• Destructors (#[dtor])
• Methods (#[method])

Type Sharing Constraints:

• Plain types (like record or enum) can be shared between export and import interfaces.
• Resource types (and types that transitively use them) cannot be shared in the same way. Even if they have the same raw representation, each resource instance in an import or export has its own unique constructor, destructor, and method implementations. Data passing between these boundaries must call the appropriate imported/exported implementations.

package example:http
interface handler {
  record header-entry {
    key: string,
    value: string,
  }
  resource blob {
    constructor(bytes: list<u8>)
    size: func() -> u32
  }
  record message {
    body: own<blob>,
    headers: list<header-entry>,
  }
  handle: func(request: message) -> message
}
world service {
  export handler
}
world middleware {
  import handler
  export handler
}