DOCSEARCHbyAlgolia
Submit Docs

Wasmtime

repository·main·Indexed 12 days ago

https://github.com/bytecodealliance/wasmtime

A high-performance WebAssembly runtime. This documentation covers the Wasmtime CLI and the Cranelift compiler infrastructure, including the cranelift-codegen core, cranelift-entity for array-based data structures, the cranelift-assembler-x64 for machine code generation, and the VeriISLE verification tool for ISA and optimization rules.

Tokens
192.1K
Snippets
560
Records
861
Agent score
94%

What's inside Wasmtime

  1. What is Winch?

    main
    Winch is a WebAssembly 'baseline' or single-pass compiler designed for Wasmtime. Unlike optimizing compilers (like Cranelift), Winch prioritizes compilation performance over runtime performance. It achieves this by performing a single pass over Wasm bytecode and generating machine code directly without an intermediate representation (IR).

  3. What is Wasmtime?

    main

    Wasmtime is a standalone runtime for WebAssembly (Wasm), the WebAssembly System Interface (WASI), and the WebAssembly Component Model. It is designed to run WebAssembly code outside of a web browser and can be used in two primary ways:

    1. As a command-line utility: For executing .wasm (binary) or .wat (textual) files directly from the terminal.
    2. As an embedded library: For integrating Wasm execution capabilities into larger applications via various language bindings.

    Key characteristics include:

    • Fast: Built on the optimizing Cranelift code generator.
    • Secure: Focused on correctness and security.
    • Configurable: Allows fine-grained control over CPU and memory consumption.
    • Standards Compliant: Passes the official WebAssembly test suite.

  4. What is Cranelift?

    main

    Cranelift is a low-level, retargetable code generator developed by the Bytecode Alliance. It functions by translating a target-independent intermediate representation (IR) into executable machine code.

    While it is primarily designed as a code generator for WebAssembly (supporting MVP and extensions like SIMD), it is general-purpose enough to be used as a backend for other compilers, such as a debug build backend for the Rust compiler (rustc_codegen_cranelift).

    Key characteristics:

    • Performance: Offers compilation speeds approximately an order of magnitude faster than LLVM-based engines, with generated code performance competitive with browser JIT engines.
    • Security: Designed to handle malicious or arbitrary compiler input by avoiding callstack recursion. It includes mitigations for Spectre attacks on heap, table, and indirect branch bounds checks.
    • Backends: Supports x86-64, aarch64 (ARM64), s390x (IBM Z), and riscv64.
    • ABI Support: On x86-64, it supports both System V AMD64 and Windows x64 calling conventions. On aarch64, it supports standard Linux and macOS (Apple Silicon) calling conventions.

  5. Overview of wasmtime-unwinder

    main

    The wasmtime-unwinder crate provides the core mechanisms for stack walking and exception handling within Wasmtime. It is responsible for navigating the Wasm stack and managing control flow during unwinding events.

    Key capabilities include:

    • Stack Walking: Walking the Wasm stack and visiting individual frames.
    • Exception Handler Discovery: Locating exception handlers using an efficient format serialized from Cranelift compilation metadata. This metadata can be mapped and used in-place from disk.
    • Control Flow Management: Providing a throw helper for host code (invoked from Wasmcode) to find handlers, and a resume stub to transfer control to the identified handler.

  6. Introduction to ISLE (Instruction Selection/Lowering Expressions DSL)

    main
    ISLE is a domain-specific language (DSL) designed for defining instruction selection and lowering passes. It allows developers to define rules for translating high-level intermediate representations (IR) into low-level machine instructions. The language is based on matching patterns (Left-Hand Side) and evaluating expressions (Right-Hand Side) to perform translations. ISLE compiles these rules into efficient Rust code, typically resulting in a single match expression that performs the lowering logic.

  7. Overview of Wasmtime features

    main

    Wasmtime is a standalone, cross-platform engine for running WebAssembly programs. Key capabilities include:

    • High Performance: Built on the Cranelift optimizing code generator for fast runtime or ahead-of-time machine code generation. It is optimized for efficient instantiation and low-overhead transitions between the host and Wasm.
    • Security: Focused on correctness with continuous fuzzing (via Google's OSS Fuzz), leveraging Rust's safety, and following an RFC process for feature design. It includes mitigations for Spectre and follows defense-in-depth practices.
    • Configurability: Provides APIs to restrict WebAssembly resource consumption (CPU and Memory) and scales from tiny environments to large servers.
    • WASI Support: Implements the WebAssembly System Interface (WASI) for interacting with the host environment.
    • Standards Compliance: Passes the official WebAssembly test suite and implements the official WebAssembly C API and various WebAssembly proposals.

  8. Read .clif files with the cranelift-reader crate

    main
    The cranelift-reader crate provides functionality to parse and read .clif (Cranelift Intermediate Format) files. While not strictly required for building a JIT compiler, this crate is essential for testing Cranelift-based workflows by allowing you to load intermediate representation files.

  10. Understand the Cranelift crate structure

    main

    Cranelift is organized into several specialized crates. For most users, the cranelift umbrella crate is the easiest entry point as it re-exports the core codegen and frontend crates.

    Key components include:

    • cranelift-codegen: The core code generator. It accepts Cranelift IR and outputs encoded machine instructions and symbolic relocations.
    • cranelift-frontend: Provides utilities to translate source code into Cranelift IR.
    • cranelift-module: Manages the compilation of multiple functions and data objects as a single unit.
    • cranelift-jit: A JIT backend for cranelift-module that emits code and data directly into memory.
    • cranelift-object: An object-based backend for cranelift-module that emits native object files using the object library.

  11. Pre-initialize WebAssembly modules with Wizer

    main

    Wizer is a WebAssembly pre-initializer that improves startup latency by executing a module's initialization function and snapshotting the resulting state into a new WebAssembly module. This allows the module to 'hit the ground running' without repeating expensive setup code during every instantiation.

    Key Benefits:

    • Significant speedup in instantiation and initialization (benchmarks show 1.35x to 6.00x faster depending on workload).
    • Can be further optimized by running wasm-opt on the resulting module to remove initialization-only code.

    Trade-offs:

    • May increase the size of the Wasm module's Data section, potentially impacting network transfer times.
    • Does not support Reference types (externref) yet.

  12. Debugging WebAssembly in Wasmtime

    main

    Wasmtime provides three primary methods for debugging WebAssembly execution:

    1. Guest-only Live Debugging: Step through the guest WebAssembly code independently of the host.
    2. Native Debugging: Use standard native debuggers like gdb or lldb to step through both the guest WebAssembly and the host environment simultaneously.
    3. Post-mortem Analysis: Generate Wasm core dumps when a Wasm guest traps, which can be analyzed using external tools.