From 3eaf5525d11d5d2c9b68fe99aa8589ffaef74cd2 Mon Sep 17 00:00:00 2001 From: Lachlan Sneff Date: Wed, 13 Mar 2019 14:58:44 -0700 Subject: [PATCH 1/3] Add some better docs --- lib/runtime-core/src/backing.rs | 27 +++++++++++++++++---------- lib/runtime-core/src/sig_registry.rs | 12 ++++++++++++ lib/runtime-core/src/vm.rs | 23 +++++++++++++++++++++++ 3 files changed, 52 insertions(+), 10 deletions(-) diff --git a/lib/runtime-core/src/backing.rs b/lib/runtime-core/src/backing.rs index 48f2d225678..6afb7ddb252 100644 --- a/lib/runtime-core/src/backing.rs +++ b/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. +/// 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, pub(crate) tables: BoxedMap, pub(crate) globals: BoxedMap, + /// 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, pub(crate) vm_tables: BoxedMap, pub(crate) vm_globals: BoxedMap, + /// 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, pub(crate) local_functions: BoxedMap, } -// 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 local memory. + /// + /// 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 local tables, e.g. + /// putting all the table elements (function pointers) + /// in the right places. #[allow(clippy::cast_ptr_alignment)] fn finalize_tables( module: &ModuleInner, diff --git a/lib/runtime-core/src/sig_registry.rs b/lib/runtime-core/src/sig_registry.rs index 1f6d87b4f08..653294f324c 100644 --- a/lib/runtime-core/src/sig_registry.rs +++ b/lib/runtime-core/src/sig_registry.rs @@ -23,10 +23,18 @@ struct GlobalSigRegistry { sig_assoc: Map>, } +/// 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(&self, func_sig: Sig) -> SigIndex where Sig: Into>, @@ -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 { 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 { let mut global = (*GLOBAL_SIG_REGISTRY).write(); let global = &mut *global; diff --git a/lib/runtime-core/src/vm.rs b/lib/runtime-core/src/vm.rs index 508ca031b8e..b9b6bbe27a0 100644 --- a/lib/runtime-core/src/vm.rs +++ b/lib/runtime-core/src/vm.rs @@ -9,7 +9,16 @@ use std::{ffi::c_void, mem, ptr}; /// The context of the currently running WebAssembly instance. /// +/// This is implicitly passed to every webassembly function. +/// Since this is per-module, 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 { @@ -42,11 +51,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, 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, } From 8218e550fcabc4b389855e0054e0ac9ffa42804f Mon Sep 17 00:00:00 2001 From: Syrus Date: Mon, 13 May 2019 11:18:57 -0700 Subject: [PATCH 2/3] Improved docs and fixed few typos --- lib/clif-backend/src/signal/unix.rs | 2 +- lib/runtime-core/src/backing.rs | 6 +++--- lib/runtime-core/src/error.rs | 6 +++--- lib/runtime-core/src/instance.rs | 8 ++++---- lib/runtime-core/src/memory/static_/unshared.rs | 2 +- lib/runtime-core/src/vm.rs | 6 +++--- lib/singlepass-backend/src/protect_unix.rs | 2 +- 7 files changed, 16 insertions(+), 16 deletions(-) diff --git a/lib/clif-backend/src/signal/unix.rs b/lib/clif-backend/src/signal/unix.rs index a5661338410..2f12713fa6a 100644 --- a/lib/clif-backend/src/signal/unix.rs +++ b/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 //! diff --git a/lib/runtime-core/src/backing.rs b/lib/runtime-core/src/backing.rs index 14fe41cbf48..b3d529460ef 100644 --- a/lib/runtime-core/src/backing.rs +++ b/lib/runtime-core/src/backing.rs @@ -17,7 +17,7 @@ use crate::{ }; use std::slice; -/// The `LocalBacking` "owns" the memory used by all the local resources. +/// 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)] @@ -103,7 +103,7 @@ impl LocalBacking { memories.into_boxed_map() } - /// Initialize each local memory. + /// Initialize each locally-defined memory in the Module. /// /// This involves copying in the data initializers. fn finalize_memories( @@ -178,7 +178,7 @@ impl LocalBacking { tables.into_boxed_map() } - /// This initializes all of the local tables, e.g. + /// 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)] diff --git a/lib/runtime-core/src/error.rs b/lib/runtime-core/src/error.rs index fb25acdb875..c93115d145f 100644 --- a/lib/runtime-core/src/error.rs +++ b/lib/runtime-core/src/error.rs @@ -11,7 +11,7 @@ pub type ResolveResult = std::result::Result; pub type ParseResult = std::result::Result; /// 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)] diff --git a/lib/runtime-core/src/instance.rs b/lib/runtime-core/src/instance.rs index 14d7a0146c0..d5f84acc2b3 100644 --- a/lib/runtime-core/src/instance.rs +++ b/lib/runtime-core/src/instance.rs @@ -262,7 +262,7 @@ 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`]. /// @@ -270,7 +270,7 @@ impl Instance { /// /// # Note: /// This returns `CallResult>` 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>` in order to support - /// the future multi-value returns webassembly feature. + /// the future multi-value returns WebAssembly feature. /// /// # Usage: /// ``` diff --git a/lib/runtime-core/src/memory/static_/unshared.rs b/lib/runtime-core/src/memory/static_/unshared.rs index b9e66de0a11..602a02bace9 100644 --- a/lib/runtime-core/src/memory/static_/unshared.rs +++ b/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. diff --git a/lib/runtime-core/src/vm.rs b/lib/runtime-core/src/vm.rs index a4dac4ce6c9..6649b6a5919 100644 --- a/lib/runtime-core/src/vm.rs +++ b/lib/runtime-core/src/vm.rs @@ -11,8 +11,8 @@ use hashbrown::HashMap; /// The context of the currently running WebAssembly instance. /// -/// This is implicitly passed to every webassembly function. -/// Since this is per-module, each field has a statically +/// 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. /// @@ -38,7 +38,7 @@ pub struct Ctx { //// 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. + /// 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* diff --git a/lib/singlepass-backend/src/protect_unix.rs b/lib/singlepass-backend/src/protect_unix.rs index 83ba42c797e..6204134a721 100644 --- a/lib/singlepass-backend/src/protect_unix.rs +++ b/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 //! From 02d4affd6dd07a385ff9ecd3c42e9b9ecdcb36b0 Mon Sep 17 00:00:00 2001 From: Syrus Date: Mon, 13 May 2019 11:44:44 -0700 Subject: [PATCH 3/3] Updated changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 92b3c822159..00d7e67e64e 100644 --- a/CHANGELOG.md +++ b/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