Start a high-level architecture document for Wasmtime (#3019)

* Start a high-level architecture document for Wasmtime

This commit cleands up some existing documentation by removing a number
of "noop README files" and starting a high-level overview of the
architecture of Wasmtime. I've placed this documentation under the
contributing section of the book since it seems most useful for possible
contributors.

I've surely left some things out in this pass, and am happy to add more!

* Review comments

* More rewording

* typos

crates/cranelift/Cargo.toml

@@ -8,7 +8,6 @@ repository = "https://github.com/bytecodealliance/wasmtime"
 documentation = "https://docs.rs/wasmtime-cranelift/"
 categories = ["wasm"]
 keywords = ["webassembly", "wasm"]
-readme = "README.md"
 edition = "2018"
 
 [dependencies]

crates/cranelift/README.md

@@ -1,4 +0,0 @@
-# `wasmtime-cranelift`
-
-This crate provides an implementation of the `Compiler` trait which is
-connected to Cranelift.

crates/debug/Cargo.toml

@@ -8,7 +8,6 @@ repository = "https://github.com/bytecodealliance/wasmtime"
 documentation = "https://docs.rs/wasmtime-debug/"
 categories = ["wasm"]
 keywords = ["webassembly", "wasm", "debuginfo"]
-readme = "README.md"
 edition = "2018"
 
 [dependencies]

crates/debug/README.md

@@ -1,4 +0,0 @@
-This is the `wasmtime-debug` crate, which provides functionality to
-read, transform, and write DWARF section.
-
-[`wasmtime-debug`]: https://crates.io/crates/wasmtime-debug

crates/environ/Cargo.toml

@@ -8,7 +8,6 @@ repository = "https://github.com/bytecodealliance/wasmtime"
 documentation = "https://docs.rs/wasmtime-environ/"
 categories = ["wasm"]
 keywords = ["webassembly", "wasm"]
-readme = "README.md"
 edition = "2018"
 
 [dependencies]

crates/environ/README.md

@@ -1,6 +0,0 @@
-This is the `wasmtime-environ` crate, which contains the implementations
-of the `ModuleEnvironment` and `FuncEnvironment` traits from
-[`cranelift-wasm`](https://crates.io/crates/cranelift-wasm). They effectively
-implement an ABI for basic wasm compilation that defines how linear memories
-are allocated, how indirect calls work, and other details. They can be used
-for JITing, native object files, or other purposes.

crates/jit/Cargo.toml

@@ -8,7 +8,6 @@ license = "Apache-2.0 WITH LLVM-exception"
 categories = ["wasm"]
 keywords = ["webassembly", "wasm"]
 repository = "https://github.com/bytecodealliance/wasmtime"
-readme = "README.md"
 edition = "2018"
 
 [dependencies]

crates/jit/README.md

@@ -1,10 +0,0 @@
-This is the `wasmtime-jit` crate, which contains JIT-based execution
-for wasm, using the wasm ABI defined by [`wasmtime-environ`] and the
-runtime support provided by [`wasmtime-runtime`].
-
-Most users will want to use the main [`wasmtime`] crate instead of using this
-crate directly.
-
-[`wasmtime-environ`]: https://crates.io/crates/wasmtime-environ
-[`wasmtime-runtime`]: https://crates.io/crates/wasmtime-runtime
-[`wasmtime`]: https://crates.io/crates/wasmtime

crates/obj/Cargo.toml

@@ -7,7 +7,6 @@ license = "Apache-2.0 WITH LLVM-exception"
 repository = "https://github.com/bytecodealliance/wasmtime"
 categories = ["wasm"]
 keywords = ["webassembly", "wasm"]
-readme = "README.md"
 edition = "2018"
 
 [dependencies]

crates/obj/README.md

@@ -1,5 +0,0 @@
-This is the `wasmtime-obj` crate, which contains an experimental prototype
-for writing out native object files, using the wasm ABI defined by
-[`wasmtime-environ`].
-
-[`wasmtime-environ`]: https://crates.io/crates/wasmtime-environ

crates/profiling/Cargo.toml

@@ -7,7 +7,6 @@ license = "Apache-2.0 WITH LLVM-exception"
 categories = ["wasm"]
 keywords = ["webassembly", "wasm"]
 repository = "https://github.com/bytecodealliance/wasmtime"
-readme = "README.md"
 edition = "2018"
 
 [dependencies]

crates/profiling/README.md

@@ -1,2 +0,0 @@
-This is the `wasmtime-profiling` crate, which contains runtime performance
-profiling support for Wasmtime.

crates/runtime/Cargo.toml

@@ -8,7 +8,6 @@ license = "Apache-2.0 WITH LLVM-exception"
 categories = ["wasm"]
 keywords = ["webassembly", "wasm"]
 repository = "https://github.com/bytecodealliance/wasmtime"
-readme = "README.md"
 edition = "2018"
 
 [dependencies]

crates/runtime/README.md

@@ -1,14 +0,0 @@
-This is the `wasmtime-runtime` crate, which contains wasm runtime library
-support, supporting the wasm ABI used by [`wasmtime-environ`],
-[`wasmtime-jit`], and [`wasmtime-obj`].
-
-This crate does not make a host vs. target distinction; it is meant to be
-compiled for the target.
-
-Most users will want to use the main [`wasmtime`] crate instead of using this
-crate directly.
-
-[`wasmtime-environ`]: https://crates.io/crates/wasmtime-environ
-[`wasmtime-jit`]: https://crates.io/crates/wasmtime-jit
-[`wasmtime-obj`]: https://crates.io/crates/wasmtime-obj
-[`wasmtime`]: https://crates.io/crates/wasmtime

crates/runtime/src/instance.rs

@@ -98,21 +98,39 @@ pub trait ResourceLimiter {
     }
 }
 
-/// A WebAssembly instance.
+/// A type that roughly corresponds to a WebAssembly instance, but is also used
+/// for host-defined objects.
 ///
-/// This is repr(C) to ensure that the vmctx field is last.
-#[repr(C)]
+/// This structure is is never allocated directly but is instead managed through
+/// an `InstanceHandle`. This structure ends with a `VMContext` which has a
+/// dynamic size corresponding to the `module` configured within. Memory
+/// management of this structure is always externalized.
+///
+/// Instances here can correspond to actual instantiated modules, but it's also
+/// used ubiquitously for host-defined objects. For example creating a
+/// host-defined memory will have a `module` that looks like it exports a single
+/// memory (and similar for other constructs).
+///
+/// This `Instance` type is used as a ubiquitous representation for WebAssembly
+/// values, whether or not they were created on the host or through a module.
+#[repr(C)] // ensure that the vmctx field is last.
 pub(crate) struct Instance {
     /// The `Module` this `Instance` was instantiated from.
     module: Arc<Module>,
 
-    /// Offsets in the `vmctx` region.
+    /// Offsets in the `vmctx` region, precomputed from the `module` above.
     offsets: VMOffsets,
 
     /// WebAssembly linear memory data.
+    ///
+    /// This is where all runtime information about defined linear memories in
+    /// this module lives.
     memories: PrimaryMap<DefinedMemoryIndex, Memory>,
 
     /// WebAssembly table data.
+    ///
+    /// Like memories, this is only for defined tables in the module and
+    /// contains all of their runtime state.
     tables: PrimaryMap<DefinedTableIndex, Table>,
 
     /// Stores the dropped passive element segments in this instantiation by index.
@@ -124,6 +142,9 @@ pub(crate) struct Instance {
     dropped_data: EntitySet<DataIndex>,
 
     /// Hosts can store arbitrary per-instance information here.
+    ///
+    /// Most of the time from Wasmtime this is `Box::new(())`, a noop
+    /// allocation, but some host-defined objects will store their state here.
     host_state: Box<dyn Any + Send + Sync>,
 
     /// Additional context used by compiled wasm code. This field is last, and

crates/wast/Cargo.toml

@@ -7,7 +7,6 @@ license = "Apache-2.0 WITH LLVM-exception"
 categories = ["wasm"]
 keywords = ["webassembly", "wasm"]
 repository = "https://github.com/bytecodealliance/wasmtime"
-readme = "README.md"
 edition = "2018"
 
 [dependencies]

crates/wast/README.md

@@ -1,5 +0,0 @@
-This is the `wasmtime-wast` crate, which contains an implementation of WebAssembly's
-"wast" test scripting language, which is used in the
-[WebAssembly spec testsuite], using wasmtime for execution.
-
-[WebAssembly spec testsuite]: https://github.com/WebAssembly/testsuite