docs(runtime) Add some better runtime docs

CHANGELOG.md

@@ -6,6 +6,7 @@ Blocks of changes will separated by version increments.
 
 ## **[Unreleased]**
 
+- [#269](https://github.com/wasmerio/wasmer/pull/269) Add better runtime docs
 - [#432](https://github.com/wasmerio/wasmer/pull/432) Fix returned value of `wasmer_last_error_message` in the runtime C API
 - [#429](https://github.com/wasmerio/wasmer/pull/429) Get wasi::path_filestat_get working for some programs; misc. minor WASI FS improvements
 - [#413](https://github.com/wasmerio/wasmer/pull/413) Update LLVM backend to use new parser codegen traits

lib/clif-backend/src/signal/unix.rs

@@ -1,5 +1,5 @@
 //! Installing signal handlers allows us to handle traps and out-of-bounds memory
-//! accesses that occur when runniing webassembly.
+//! accesses that occur when running WebAssembly.
 //!
 //! This code is inspired by: https://github.com/pepyakin/wasmtime/commit/625a2b6c0815b21996e111da51b9664feb174622
 //!

lib/runtime-core/src/backing.rs

@@ -17,30 +17,31 @@ use crate::{
 };
 use std::slice;
 
+/// The `LocalBacking` "owns" the memory used by all the local resources of an Instance.
+/// That is, local memories, tables, and globals (as well as some additional
+/// data for the virtual call machinery).
 #[derive(Debug)]
 pub struct LocalBacking {
+    /// This is a map from the local resource index to actual memory,
+    /// table, and globals.
     pub(crate) memories: BoxedMap<LocalMemoryIndex, Memory>,
     pub(crate) tables: BoxedMap<LocalTableIndex, Table>,
     pub(crate) globals: BoxedMap<LocalGlobalIndex, Global>,
 
+    /// This own the memory containing the pointers to the local memories.
+    /// While simplifying implementation, this adds indirection and may hurt
+    /// performance, especially on cache-starved systems.
     pub(crate) vm_memories: BoxedMap<LocalMemoryIndex, *mut vm::LocalMemory>,
     pub(crate) vm_tables: BoxedMap<LocalTableIndex, *mut vm::LocalTable>,
     pub(crate) vm_globals: BoxedMap<LocalGlobalIndex, *mut vm::LocalGlobal>,
 
+    /// The dynamic sigindices are used to efficiently support caching and
+    /// the `call_indirect` wasm instruction. This field (and local_functions
+    /// as well) are subject to change.
     pub(crate) dynamic_sigindices: BoxedMap<SigIndex, vm::SigId>,
     pub(crate) local_functions: BoxedMap<LocalFuncIndex, *const vm::Func>,
 }
 
-// impl LocalBacking {
-//     pub fn memory(&mut self, local_memory_index: LocalMemoryIndex) -> &mut Memory {
-//         &mut self.memories[local_memory_index]
-//     }
-
-//     pub fn table(&mut self, local_table_index: LocalTableIndex) -> &mut TableBacking {
-//         &mut self.tables[local_table_index]
-//     }
-// }
-
 impl LocalBacking {
     pub(crate) fn new(module: &ModuleInner, imports: &ImportBacking, vmctx: *mut vm::Ctx) -> Self {
         let mut memories = Self::generate_memories(module);
@@ -102,6 +103,9 @@ impl LocalBacking {
         memories.into_boxed_map()
     }
 
+    /// Initialize each locally-defined memory in the Module.
+    ///
+    /// This involves copying in the data initializers.
     fn finalize_memories(
         module: &ModuleInner,
         imports: &ImportBacking,
@@ -174,6 +178,9 @@ impl LocalBacking {
         tables.into_boxed_map()
     }
 
+    /// This initializes all of the locally-defined tables in the Module, e.g.
+    /// putting all the table elements (function pointers)
+    /// in the right places.
     #[allow(clippy::cast_ptr_alignment)]
     fn finalize_tables(
         module: &ModuleInner,

lib/runtime-core/src/error.rs

@@ -11,7 +11,7 @@ pub type ResolveResult<T> = std::result::Result<T, ResolveError>;
 pub type ParseResult<T> = std::result::Result<T, ParseError>;
 
 /// This is returned when the chosen compiler is unable to
-/// successfully compile the provided webassembly module into
+/// successfully compile the provided WebAssembly module into
 /// a `Module`.
 ///
 /// Comparing two `CompileError`s always evaluates to false.
@@ -114,7 +114,7 @@ impl std::fmt::Display for LinkError {
 impl std::error::Error for LinkError {}
 
 /// This is the error type returned when calling
-/// a webassembly function.
+/// a WebAssembly function.
 ///
 /// The main way to do this is `Instance.call`.
 ///
@@ -270,7 +270,7 @@ impl std::error::Error for CreationError {}
 
 /// The amalgamation of all errors that can occur
 /// during the compilation, instantiation, or execution
-/// of a webassembly module.
+/// of a WebAssembly module.
 ///
 /// Comparing two `Error`s always evaluates to false.
 #[derive(Debug)]

lib/runtime-core/src/instance.rs

@@ -262,15 +262,15 @@ impl Instance {
         }
     }
 
-    /// Call an exported webassembly function given the export name.
+    /// Call an exported WebAssembly function given the export name.
     /// Pass arguments by wrapping each one in the [`Value`] enum.
     /// The returned values are also each wrapped in a [`Value`].
     ///
     /// [`Value`]: enum.Value.html
     ///
     /// # Note:
     /// This returns `CallResult<Vec<Value>>` in order to support
-    /// the future multi-value returns webassembly feature.
+    /// the future multi-value returns WebAssembly feature.
     ///
     /// # Usage:
     /// ```
@@ -601,7 +601,7 @@ pub struct DynFunc<'a> {
 }
 
 impl<'a> DynFunc<'a> {
-    /// Call an exported webassembly function safely.
+    /// Call an exported WebAssembly function safely.
     ///
     /// Pass arguments by wrapping each one in the [`Value`] enum.
     /// The returned values are also each wrapped in a [`Value`].
@@ -610,7 +610,7 @@ impl<'a> DynFunc<'a> {
     ///
     /// # Note:
     /// This returns `CallResult<Vec<Value>>` in order to support
-    /// the future multi-value returns webassembly feature.
+    /// the future multi-value returns WebAssembly feature.
     ///
     /// # Usage:
     /// ```

lib/runtime-core/src/memory/static_/unshared.rs

@@ -11,7 +11,7 @@ use crate::{
 /// This is an internal-only api.
 ///
 /// A static memory allocates 6GB of *virtual* memory when created
-/// in order to allow the webassembly module to contain no bounds-checks.
+/// in order to allow the WebAssembly module to contain no bounds-checks.
 ///
 /// Additionally, static memories stay at a single virtual address, so there is no need
 /// to reload its address on each use.

lib/runtime-core/src/sig_registry.rs

@@ -23,10 +23,18 @@ struct GlobalSigRegistry {
     sig_assoc: Map<SigIndex, Arc<FuncSig>>,
 }
 
+/// The `SigRegistry` represents a process-global map of function signatures
+/// to signature indexes and vice versa (the map goes both ways).
+///
+/// This exists for two reasons:
+/// 1. The `call_indirect` wasm instruction can compare two signature indices
+///     to do signature validation very quickly.
+/// 2. To intern function signatures, which may be expensive to create.
 #[derive(Debug)]
 pub struct SigRegistry;
 
 impl SigRegistry {
+    /// Map a `FuncSig` to a global `SigIndex`.
     pub fn lookup_sig_index<Sig>(&self, func_sig: Sig) -> SigIndex
     where
         Sig: Into<Arc<FuncSig>>,
@@ -45,11 +53,15 @@ impl SigRegistry {
         sig_index
     }
 
+    /// Map a global `SigIndex` to an interned `FuncSig`.
     pub fn lookup_signature(&self, sig_index: SigIndex) -> Arc<FuncSig> {
         let global = (*GLOBAL_SIG_REGISTRY).read();
         Arc::clone(&global.sig_assoc[sig_index])
     }
 
+    /// Register a function signature with the global signature registry.
+    ///
+    /// This will return an interned `FuncSig`.
     pub fn lookup_signature_ref(&self, func_sig: &FuncSig) -> Arc<FuncSig> {
         let mut global = (*GLOBAL_SIG_REGISTRY).write();
         let global = &mut *global;

lib/runtime-core/src/vm.rs

@@ -11,7 +11,16 @@ use hashbrown::HashMap;
 
 /// The context of the currently running WebAssembly instance.
 ///
+/// This is implicitly passed to every WebAssembly function.
+/// Since this is per-instance, each field has a statically
+/// (as in after compiling the wasm) known size, so no
+/// runtime checks are necessary.
 ///
+/// While the runtime currently just passes this around
+/// as the first, implicit parameter of every function,
+/// it may someday be pinned to a register (especially
+/// on arm, which has a ton of registers) to reduce
+/// register shuffling.
 #[derive(Debug)]
 #[repr(C)]
 pub struct Ctx {
@@ -20,11 +29,25 @@ pub struct Ctx {
 
     pub(crate) local_functions: *const *const Func,
 
+    /// These are pointers to things that are known to be owned
+    /// by the owning `Instance`.
     local_backing: *mut LocalBacking,
     import_backing: *mut ImportBacking,
     pub module: *const ModuleInner,
 
+    //// This is intended to be user-supplied, per-instance
+    /// contextual data. There are currently some issue with it,
+    /// notably that it cannot be set before running the `start`
+    /// function in a WebAssembly module.
+    ///
+    /// [#219](https://github.com/wasmerio/wasmer/pull/219) fixes that
+    /// issue, as well as allowing the user to have *per-function*
+    /// context, instead of just per-instance.
     pub data: *mut c_void,
+
+    /// If there's a function set in this field, it gets called
+    /// when the context is destructed, e.g. when an `Instance`
+    /// is dropped.
     pub data_finalizer: Option<fn(data: *mut c_void)>,
 }
 

lib/singlepass-backend/src/protect_unix.rs

@@ -1,5 +1,5 @@
 //! Installing signal handlers allows us to handle traps and out-of-bounds memory
-//! accesses that occur when runniing webassembly.
+//! accesses that occur when runniing WebAssembly.
 //!
 //! This code is inspired by: https://github.com/pepyakin/wasmtime/commit/625a2b6c0815b21996e111da51b9664feb174622
 //!