Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

30.6 KB
Raw Blame

Tiers of Support in Wasmtime

Wasmtime's support for platforms and features can be distinguished with three different tiers of support. The description of these tiers are intended to be inspired by the Rust compiler's support tiers for targets but are additionally tailored for Wasmtime. Wasmtime's tiered support additionally applies not only to platforms/targets themselves but additionally features implemented within Wasmtime itself.

The purpose of this document is to provide a means by which to evaluate the inclusion of new features and support for existing features within Wasmtime. This should not be used to "lawyer" a change into Wasmtime on a precise technical detail or similar since this document is itself not 100% precise and will change over time.

Current Tier Status

For explanations of what each tier means see below.

Tier 1

Category Description
Target x86_64-apple-darwin
Target x86_64-pc-windows-msvc
Target x86_64-unknown-linux-gnu
Compiler Cranelift [^support]
Compiler Winch [^support]
WebAssembly Proposal mutable-globals
WebAssembly Proposal sign-extension-ops
WebAssembly Proposal nontrapping-float-to-int-conversion
WebAssembly Proposal multi-value
WebAssembly Proposal bulk-memory
WebAssembly Proposal reference-types
WebAssembly Proposal simd
WebAssembly Proposal component-model
WebAssembly Proposal component-model-async
WebAssembly Proposal relaxed-simd
WebAssembly Proposal multi-memory
WebAssembly Proposal tail-call
WebAssembly Proposal extended-const
WebAssembly Proposal memory64
WebAssembly Proposal function-references
WebAssembly Proposal gc
WebAssembly Proposal exception-handling
WebAssembly Proposal wide-arithmetic
WASI Proposal wasi-io
WASI Proposal wasi-clocks
WASI Proposal wasi-filesystem
WASI Proposal wasi-random
WASI Proposal wasi-sockets
WASI Proposal wasi-http
WASI Proposal wasi_snapshot_preview1
WASI Proposal wasi_unstable
Embedding API Rust
Embedding API C

[^support]: Compiler support is further broken down below into finer-grained target/wasm proposal combinations. Compilers are not required to support the full matrix of all tier 1 targets/proposals, and not all wasm proposals which have support in a compiler are mature enough to be enabled by default and therefore supported as tier 1.

Tier 2

Category Description Missing Tier 1 Requirements
Target aarch64-unknown-linux-gnu Continuous fuzzing
Target aarch64-apple-darwin Continuous fuzzing
Target s390x-unknown-linux-gnu Continuous fuzzing
Target x86_64-pc-windows-gnu Clear owner of the target
Target Support for #![no_std] Support beyond CI checks
WebAssembly Proposal custom-page-sizes Unstable wasm proposal
WebAssembly Proposal threads fuzzing, API quality
Execution Backend Pulley More time fuzzing/baking
Embedding API C++ Full-time maintainer

Tier 3

Category Description Missing Tier 2 Requirements
Target aarch64-apple-ios CI testing, full-time maintainer
Target aarch64-linux-android CI testing, full-time maintainer
Target aarch64-pc-windows-msvc CI testing, full-time maintainer
Target aarch64-unknown-linux-musl [^4] CI testing, full-time maintainer
Target armv7-unknown-linux-gnueabihf full-time maintainer
Target i686-pc-windows-msvc CI testing, full-time maintainer
Target i686-unknown-linux-gnu full-time maintainer
Target powerpc64le-unknown-linux-gnu CI testing, full-time maintainer
Target riscv32imac-unknown-none-elf[^5] CI testing, full-time maintainer
Target riscv64gc-unknown-linux-gnu full-time maintainer
Target wasm32-wasip1 [^3] Supported but not tested
Target x86_64-linux-android CI testing, full-time maintainer
Target x86_64-unknown-freebsd CI testing, full-time maintainer
Target x86_64-unknown-illumos CI testing, full-time maintainer
Target x86_64-unknown-linux-musl [^4] CI testing, full-time maintainer
Target x86_64-unknown-none [^5] CI testing, full-time maintainer
WASI Proposal wasi-nn More expansive CI testing
WASI Proposal wasi-threads More CI, unstable proposal
WASI Proposal wasi-config unstable proposal
WASI Proposal wasi-keyvalue unstable proposal
WASI Proposal wasi-tls unstable proposal
misc Non-Wasmtime Cranelift usage [^1] CI testing, full-time maintainer
misc DWARF debugging [^2] CI testing, full-time maintainer, improved quality

[^1]: This is intended to encompass features that Cranelift supports as a general-purpose code generator such as integer value types other than i32 and i64, non-Wasmtime calling conventions, code model settings, relocation restrictions, etc. These features aren't covered by Wasmtime's usage of Cranelift because the WebAssembly instruction set doesn't leverage them. This means that they receive far less testing and fuzzing than the parts of Cranelift exercised by Wasmtime.

[^2]: Currently there is no active maintainer of DWARF debugging support and support is currently best-effort. Additionally there are known shortcomings and bugs. At this time there's no developer time to improve the situation here as well.

[^3]: Wasmtime's cranelift and winch features can be compiled to WebAssembly but not the runtime feature at this time. This means that Wasmtime-compiled-to-wasm can itself compile wasm but cannot execute wasm.

[^4]: Binary artifacts for MUSL are dynamically linked, not statically linked, meaning that they are not suitable for "run on any linux distribution" style use cases. Wasmtime does not have static binary artifacts at this time and that will require building from source.

[^5]: Rust targets that are #![no_std] don't support the entire feature set of Wasmtime. For example the threads Cargo feature requires the standard library. For more information see the no_std documentation. Additionally these targets are sound in the presence of multiple threads but will panic on contention of data structures. If you're doing multithreaded things in no_std please file an issue so we can help solve your use case.

Unsupported features and platforms

While this is not an exhaustive list, Wasmtime does not currently have support for the following features. Note that this is intended to document Wasmtime's current state and does not mean Wasmtime does not want to ever support these features; rather design discussion and PRs are welcome for many of the below features to figure out how best to implement them and at least move them to Tier 3 above.

Compiler Support

Compiler backends of Wasmtime, at this time Cranelift and Winch, are further refined in the below table in their support for various architectures and WebAssembly features. Tier 1 WebAssembly feature are required to be supported by at least one compiler on all Tier 1 targets, and similarly for Tier 2 features and so on. Note that architecture here is independent of OS, meaning that support is uniform across Wasmtime's supported target for each tier. Not all wasm proposals which have support in a compiler are mature enough to be enabled by default and therefore supported as tier 1. The legend here is:

  • βœ… - fully supported
  • 🚧 - work-in-progress
  • ❌ - not supported yet
x86_64
Feature Cranelift Winch
mutable-globals βœ… βœ…
sign-extension-ops βœ… βœ…
nontrapping-float-to-int-conversion βœ… βœ…
multi-value βœ… βœ…
bulk-memory βœ… βœ…
reference-types βœ… ❌[^a]
simd βœ… βœ…
component-model βœ… βœ…
component-model-async βœ… βœ…
relaxed-simd βœ… ❌
multi-memory βœ… βœ…
threads βœ… βœ…
tail-call βœ… βœ…
extended-const βœ… βœ…
memory64 βœ… βœ…
function-references βœ… ❌
gc βœ… ❌
wide-arithmetic βœ… βœ…
custom-page-sizes βœ… βœ…
exception-handling βœ… βœ…
stack-switching 🚧 ❌
aarch64
Feature Cranelift Winch[^c]
mutable-globals βœ… βœ…
sign-extension-ops βœ… βœ…
nontrapping-float-to-int-conversion βœ… βœ…
multi-value βœ… βœ…
bulk-memory βœ… βœ…
reference-types βœ… ❌[^a]
simd βœ… βœ…
component-model βœ… βœ…
component-model-async βœ… βœ…
relaxed-simd βœ… ❌
multi-memory βœ… βœ…
threads βœ… ❌
tail-call βœ… βœ…
extended-const βœ… βœ…
memory64 βœ… βœ…
function-references βœ… ❌
gc βœ… ❌
wide-arithmetic βœ… ❌
custom-page-sizes βœ… βœ…
exception-handling βœ… βœ…
stack-switching ❌ ❌
s390x
Feature Cranelift Winch
mutable-globals βœ… ❌
sign-extension-ops βœ… ❌
nontrapping-float-to-int-conversion βœ… ❌
multi-value βœ… ❌
bulk-memory βœ… ❌
reference-types βœ… ❌[^a]
simd βœ… ❌
component-model βœ… ❌
component-model-async βœ… ❌
relaxed-simd βœ… ❌
multi-memory βœ… ❌
threads βœ… ❌
tail-call βœ… ❌
extended-const βœ… ❌
memory64 βœ… ❌
function-references βœ… ❌
gc βœ… ❌
wide-arithmetic βœ… ❌
custom-page-sizes βœ… ❌
exception-handling βœ… ❌
stack-switching ❌ ❌
riscv64
Feature Cranelift Winch
mutable-globals βœ… ❌
sign-extension-ops βœ… ❌
nontrapping-float-to-int-conversion βœ… ❌
multi-value βœ… ❌
bulk-memory βœ… ❌
reference-types βœ… ❌[^a]
simd βœ…[^d] ❌
component-model βœ… ❌
component-model-async βœ… ❌
relaxed-simd βœ…[^d] ❌
multi-memory βœ… ❌
threads βœ… ❌
tail-call βœ… ❌
extended-const βœ… ❌
memory64 βœ… ❌
function-references βœ… ❌
gc βœ… ❌
wide-arithmetic βœ… ❌
custom-page-sizes βœ… ❌
exception-handling βœ… ❌
stack-switching ❌ ❌
Pulley

Note that the pulley "architecture" is a stand-in for Wasmtime's baseline support for all platforms. This is how Wasmtime's interpreter works and this is intended to work on all platforms. The columns here are for compiler support for emitting Pulley bytecode.

Feature Cranelift Winch
mutable-globals βœ… ❌
sign-extension-ops βœ… ❌
nontrapping-float-to-int-conversion βœ… ❌
multi-value βœ… ❌
bulk-memory βœ… ❌
reference-types βœ… ❌[^a]
simd βœ… ❌
component-model βœ… ❌
component-model-async βœ… ❌
relaxed-simd βœ… ❌
multi-memory βœ… ❌
threads ❌[^b] ❌
tail-call βœ… ❌
extended-const βœ… ❌
memory64 βœ… ❌
function-references βœ… ❌
gc βœ… ❌
wide-arithmetic βœ… ❌
custom-page-sizes βœ… ❌
exception-handling βœ… ❌
stack-switching ❌ ❌

[^a]: Winch supports GC reference values such as externref through parameters, results, locals, globals, and calls, including the required stack maps and collector barriers. It also supports multiple tables and LEB-encoded table indices, but does not yet support every table and element-segment case in the reference-types proposal. [^b]: Pulley does not support the threads proposal because there is no known safe way to implement this with Rust's memory model. [^c]: Winch's support for aarch64 is complete for Core Wasm. [^d]: On riscv64 requires the V extension (the has_v Cranelift setting). The proposals are enabled by default, so without it they must be disabled explicitly or creating an engine fails.

Tier Details

Wasmtime's precise definitions of tiers are not guaranteed to be constant over time, so these descriptions are likely to change over time. Tier 1 is classified as the highest level of support, confidence, and correctness for a component. Each tier additionally encompasses all the guarantees of previous tiers.

Features classified under a particular tier may already meet the criteria for later tiers as well. In situations like this it's not intended to use these guidelines to justify removal of a feature at any one point in time. Guidance is provided here for phasing out unmaintained features but it should be clear under what circumstances work "can be avoided" for each tier.

Tier 3 - Not Production Ready

The general idea behind Tier 3 is that this is the baseline for inclusion of code into the Wasmtime project. This is not intended to be a catch-all "if a patch is sent it will be merged" tier. Instead the goal of this tier is to outline what is expected of contributors adding new features to Wasmtime which might be experimental at the time of addition. This is intentionally not a relaxed tier of restrictions but already implies a significant commitment of effort to a feature being included within Wasmtime.

Tier 3 features include:

  • Inclusion of a feature does not impose unnecessary maintenance overhead on other components/features. Some examples of additions to Wasmtime which would not be accepted are:

    • An experimental feature doubles the time of CI for all PRs.
    • A change which makes it significantly more difficult to architecturally change Wasmtime's internal implementation.
    • A change which makes building Wasmtime more difficult for unrelated developers.

    In general Tier 3 features are off-by-default at compile time but still tested-by-default on CI.

  • New features of Wasmtime cannot have major known bugs at the time of inclusion. Landing a feature in Wasmtime requires the feature to be correct and bug-free as best can be evaluated at the time of inclusion. Inevitably bugs will be found and that's ok, but anything identified during review must be addressed.

  • Code included into the Wasmtime project must be of an acceptable level of quality relative to the rest of the code in Wasmtime.

  • There must be a path to a feature being finished at the time of inclusion. Adding a new backend to Cranelift for example is a significant undertaking which may not be able to be done in a single PR. Partial implementations of a feature are acceptable so long as there's a clear path forward and schedule for completing the feature.

  • New components in Wasmtime must have a clearly identified owner who is willing to be "on the hook" for review, updates to the internals of Wasmtime, etc. For example a new backend in Cranelift would need to have a maintainer who is willing to respond to changes in Cranelift's interfaces and the needs of Wasmtime.

This baseline level of support notably does not require any degree of testing, fuzzing, or verification. As a result components classified as Tier 3 are generally not production-ready as they have not been battle-tested much.

Features classified as Tier 3 may be disabled in CI or removed from the repository as well. If a Tier 3 feature is preventing development of other features then the owner will be notified. If no response is heard from within a week then the feature will be disabled in CI. If no further response happens for a month then the feature may be removed from the repository.

Tier 2 - Almost Production Ready

This tier is meant to encompass features and components of Wasmtime which are well-maintained, tested well, but don't necessarily meet the stringent criteria for Tier 1. Features in this category may already be "production ready" and safe to use.

Tier 2 features, organized by category, include:

  • Target

    • Tests are run in CI for this platform with a compiler, either directly or via emulation. This ensures that all changes to Wasmtime are tested against this target, and this additionally means that all applicable Tier 1/2 features are tested on this target in CI.

    • Complete implementations for anything that's part of Tier 1. For example all Tier 2 targets must implement all of the applicable Tier 1 WebAssembly proposals, and all Tier 2 features must be implemented on all Tier 1 targets.

  • WebAssembly Proposal

    • Must be fully tested on CI. This means that it must pass tests on all applicable Tier 1 and Tier 2 target/compiler combos. Note that only one compiler is required to implement the feature at this time, but it must run, via some compiler, on all targets.
    • The upstream WebAssembly proposal is stage 3+.
  • WASI Proposal

    • Similar to WebAssembly proposals this must be fully tested on CI. WASI proposals at Tier 2 must support all Tier 1/2 targets, however.
  • Maintenance

    • All existing developers are expected to handle minor changes which affect Tier 2 components. For example if Cranelift's interfaces change then the developer changing the interface is expected to handle the changes for Tier 2 architectures so long as the affected part is relatively minor. Note that if a more substantial change is required to a Tier 2 component then that falls under the next bullet.

    • Maintainers of a Tier 2 feature are responsive (reply to requests within a week) and are available to accommodate architectural changes that affect their component. For example more expansive work beyond the previous bullet where contributors can't easily handle changes are expected to be guided or otherwise implemented by Tier 2 maintainers.

    • Major changes otherwise requiring an RFC that affect Tier 2 components are required to consult Tier 2 maintainers in the course of the RFC. Major changes to Tier 2 components themselves do not require an RFC, however.

Features at this tier generally are not turned off or disabled for very long. Maintainers are already required to be responsive to changes and will be notified of any unrelated change which affects their component. It's recommended that if a component breaks for one reason or another due to an unrelated change that the maintainer either contributes to the PR-in-progress or otherwise has a schedule for the implementation of the feature.

Tier 1 - Production Ready

This tier is intended to be the highest level of support in Wasmtime for any particular feature, indicating that it is suitable for production environments. This conveys a high level of confidence in the Wasmtime project about the specified features.

Tier 1 features, broken down by category, include:

  • WebAssembly Proposal

    • Continuous fuzzing is required for at least one target. This means that any WebAssembly proposal must have support in the wasm-smith crate and existing fuzz targets must be running and exercising the new code paths. Where possible differential fuzzing should also be implemented to compare results with other implementations.

    • Must meet all stabilization requirements.

  • Target

    • A target's architecture must be continuously fuzzing via at least one Rust target. For example currently there are three x86_64 targets that are considered Tier 1 but only x86_64-unknown-linux-gnu is fuzzed.
  • Compiler

    • A compiler, like a target, must be continuously fuzzed on at least one target to be considered Tier 1 for a particular target.
  • Maintenance

    • CVEs and security releases will be performed as necessary for any bugs found in features and targets.

    • Major changes affecting this component may require help from maintainers with specialized expertise, but otherwise it should be reasonable to expect most Wasmtime developers to be able to maintain Tier 1 features.

    • Major changes affecting Tier 1 features require an RFC and prior agreement on the change before an implementation is committed.

A major inclusion point for this tier is intended to be the continuous fuzzing of Wasmtime. This implies a significant commitment of resources for fixing issues, hardware to execute Wasmtime, etc. Additionally this tier comes with the broadest expectation of "burden on everyone else" in terms of what changes everyone is generally expected to handle.

Features classified as Tier 1 are rarely, if ever, turned off or removed from Wasmtime.