Wasm GC Implementation Plan

Milestone plan for implementing the Wasm GC specification.

(borrowed from https://docs.wasmtime.dev/contributing-implementing-wasm-proposals.html)

Adding New Support for a Wasm Proposal

The following checkboxes enumerate the steps required to add support for a new WebAssembly proposal to Wasmtime. They can be completed over the course of multiple pull requests.

• Add support to the wat and wast crates: it's already there!
• (in-progress) Add support to the wasmparser crate.
• (in-progress) Add support to the wasmprinter crate.
• (in-progress) Add support to the wasm-encoder crate.
• Add support to the wasm-smith crate (this can be done in parallel with adding code to wasmtime).
• Add a wasmtime::Config::enable_gc method to the wasmtime crate.
• Add a --enable-gc command line flag to the wasmtime binary.
• Enable the spec tests in build.rs but mark them as ignored for now.
• Stop ignoring individual spec tests and get them passing one by one.
• Enable the proposal in the fuzz targets.
  • Add examples from the spec tests to the relevant corpora.

    The wast2json tool from [WABT] is useful for this.

  • Write a custom fuzz target, oracle, and/or test case generator for fuzzing this proposal in particular.

    For example, we wrote a custom generator, oracle, and fuzz target for exercising table.{get,set} instructions and their interaction with GC while implementing the reference types proposal.

• Expose the proposal's new functionality in the wasmtime crate's API.

  For example, the bulk memory operations proposal introduced a table.copy instruction, and we exposed its functionality as the wasmtime::Table::copy method.

• Expose the proposal's new functionality in the C API.

  This may require extensions to the standard C API, and if so, should be defined in wasmtime.h and prefixed with wasmtime_.

• Use the C API to expose the proposal's new functionality in the other language embedding APIs:
  • Python
  • Go
  • .NET
• Document support for the proposal in wasmtime/docs/stability-wasm-proposals-support.md.

Enabling Support By Default

These are the standards that must be met to enable support for a proposal by default in Wasmtime, and can be used as a review checklist.

• The proposal must be in phase 4, or greater, of [the WebAssembly standardization process][phases].
• All spec tests must be passing in Wasmtime.
• No open questions, design concerns, or serious known bugs.
• Has been fuzzed for at least a week minimum.
• We are confident that the fuzzers are fully exercising the proposal's functionality.

  For example, it would not have been enough to simply enable reference types in the compile fuzz target to enable that proposal by default. Compiling a module that uses reference types but not instantiating it nor running any of its functions doesn't exercise any of the GC implementation and does not run the inline fast paths for table operations emitted by the JIT. Exercising these things was the motivation for writing the custom fuzz target for table.{get,set} instructions.

• The proposal's functionality is exposed in the wasmtime crate's API.
• The proposal's functionality is exposed in the C API.
• The proposal's functionality is exposed in at least one of the other languages' APIs.
  [phases]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md
  [WABT]: https://github.com/WebAssembly/wabt/