Reorganising the repository - external renames and moves (#4074)

* Adding first rough ouline of the repository structure * Remove old CI stuff * add title * formatting fixes * move node-exits job's script to scripts dir * Move docs into subdir * move to bin * move maintainence scripts, configs and helpers into its own dir * add .local to ignore * move core->client * start up 'test' area * move test client * move test runtime * make test move compile * Add dependencies rule enforcement. * Fix indexing. * Update docs to reflect latest changes * Moving /srml->/paint * update docs * move client/sr-* -> primitives/ * clean old readme * remove old broken code in rhd * update lock * Step 1. * starting to untangle client * Fix after merge. * start splitting out client interfaces * move children and blockchain interfaces * Move trie and state-machine to primitives. * Fix WASM builds. * fixing broken imports * more interface moves * move backend and light to interfaces * move CallExecutor * move cli off client * moving around more interfaces * re-add consensus crates into the mix * fix subkey path * relieve client from executor * starting to pull out client from grandpa * move is_decendent_of out of client * grandpa still depends on client directly * lemme tests pass * rename srml->paint * Make it compile. * rename interfaces->client-api * Move keyring to primitives. * fixup libp2p dep * fix broken use * allow dependency enforcement to fail * move fork-tree * Moving wasm-builder * make env * move build-script-utils * fixup broken crate depdencies and names * fix imports for authority discovery * fix typo * update cargo.lock * fixing imports * Fix paths and add missing crates * re-add missing crates
2026-04-28 14:27:57 +00:00 · 2019-11-14 21:51:17 +01:00
parent becc3b0a4f
commit 60e5011c72
809 changed files with 7801 additions and 6464 deletions
@@ -0,0 +1,271 @@
+// Copyright 2019 Parity Technologies (UK) Ltd.
+// This file is part of Substrate.
+
+// Substrate is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Substrate is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
+
+//! Traits and accessor functions for calling into the Substrate Wasm runtime.
+//!
+//! The primary means of accessing the runtimes is through a cache which saves the reusable
+//! components of the runtime that are expensive to initialize.
+
+use crate::{wasmi_execution, error::{Error, WasmError}};
+#[cfg(feature = "wasmtime")]
+use crate::wasmtime;
+use log::{trace, warn};
+
+use codec::Decode;
+
+use primitives::{storage::well_known_keys, traits::Externalities, H256};
+
+use runtime_version::RuntimeVersion;
+use std::{collections::hash_map::{Entry, HashMap}, panic::AssertUnwindSafe};
+
+use wasm_interface::Function;
+
+/// The Substrate Wasm runtime.
+pub trait WasmRuntime {
+	/// Attempt to update the number of heap pages available during execution.
+	///
+	/// Returns false if the update cannot be applied. The function is guaranteed to return true if
+	/// the heap pages would not change from its current value.
+	fn update_heap_pages(&mut self, heap_pages: u64) -> bool;
+
+	/// Return the host functions that are registered for this Wasm runtime.
+	fn host_functions(&self) -> &[&'static dyn Function];
+
+	/// Call a method in the Substrate runtime by name. Returns the encoded result on success.
+	fn call(&mut self, ext: &mut dyn Externalities, method: &str, data: &[u8])
+		-> Result<Vec<u8>, Error>;
+}
+
+/// Specification of different methods of executing the runtime Wasm code.
+#[derive(Debug, PartialEq, Eq, Hash, Copy, Clone)]
+pub enum WasmExecutionMethod {
+	/// Uses the Wasmi interpreter.
+	Interpreted,
+	/// Uses the Wasmtime compiled runtime.
+	#[cfg(feature = "wasmtime")]
+	Compiled,
+}
+
+/// A Wasm runtime object along with its cached runtime version.
+struct VersionedRuntime {
+	runtime: Box<dyn WasmRuntime>,
+	/// Runtime version according to `Core_version`.
+	version: RuntimeVersion,
+}
+
+/// Cache for the runtimes.
+///
+/// When an instance is requested for the first time it is added to this cache. Metadata is kept
+/// with the instance so that it can be efficiently reinitialized.
+///
+/// When using the Wasmi interpreter execution method, the metadata includes the initial memory and
+/// values of mutable globals. Follow-up requests to fetch a runtime return this one instance with
+/// the memory reset to the initial memory. So, one runtime instance is reused for every fetch
+/// request.
+///
+/// For now the cache grows indefinitely, but that should be fine for now since runtimes can only be
+/// upgraded rarely and there are no other ways to make the node to execute some other runtime.
+pub struct RuntimesCache {
+	/// A cache of runtime instances along with metadata, ready to be reused.
+	///
+	/// Instances are keyed by the Wasm execution method and the hash of their code.
+	instances: HashMap<(WasmExecutionMethod, [u8; 32]), Result<VersionedRuntime, WasmError>>,
+}
+
+impl RuntimesCache {
+	/// Creates a new instance of a runtimes cache.
+	pub fn new() -> RuntimesCache {
+		RuntimesCache {
+			instances: HashMap::new(),
+		}
+	}
+
+	/// Fetches an instance of the runtime.
+	///
+	/// On first use we create a new runtime instance, save it to the cache
+	/// and persist its initial memory.
+	///
+	/// Each subsequent request will return this instance, with its memory restored
+	/// to the persisted initial memory. Thus, we reuse one single runtime instance
+	/// for every `fetch_runtime` invocation.
+	///
+	/// # Parameters
+	///
+	/// `ext` - Externalities to use for the runtime. This is used for setting
+	/// up an initial runtime instance.
+	///
+	/// `default_heap_pages` - Number of 64KB pages to allocate for Wasm execution.
+	///
+	/// `host_functions` - The host functions that should be registered for the Wasm runtime.
+	///
+	/// # Return value
+	///
+	/// If no error occurred a tuple `(&mut WasmRuntime, H256)` is
+	/// returned. `H256` is the hash of the runtime code.
+	///
+	/// In case of failure one of two errors can be returned:
+	///
+	/// `Err::InvalidCode` is returned for runtime code issues.
+	///
+	/// `Error::InvalidMemoryReference` is returned if no memory export with the
+	/// identifier `memory` can be found in the runtime.
+	pub fn fetch_runtime<E: Externalities>(
+		&mut self,
+		ext: &mut E,
+		wasm_method: WasmExecutionMethod,
+		default_heap_pages: u64,
+		host_functions: &[&'static dyn Function],
+	) -> Result<(&mut (dyn WasmRuntime + 'static), &RuntimeVersion, H256), Error> {
+		let code_hash = ext
+			.original_storage_hash(well_known_keys::CODE)
+			.ok_or(Error::InvalidCode("`CODE` not found in storage.".into()))?;
+
+		let heap_pages = ext
+			.storage(well_known_keys::HEAP_PAGES)
+			.and_then(|pages| u64::decode(&mut &pages[..]).ok())
+			.unwrap_or(default_heap_pages);
+
+		let result = match self.instances.entry((wasm_method, code_hash.into())) {
+			Entry::Occupied(o) => {
+				let result = o.into_mut();
+				if let Ok(ref mut cached_runtime) = result {
+					let heap_pages_changed = !cached_runtime.runtime.update_heap_pages(heap_pages);
+					let host_functions_changed = cached_runtime.runtime.host_functions()
+						!= host_functions;
+					if heap_pages_changed || host_functions_changed {
+						let changed = if heap_pages_changed {
+							"heap_pages"
+						} else {
+							"host functions"
+						};
+
+						trace!(
+							target: "runtimes_cache",
+							"{} were changed. Reinstantiating the instance",
+							changed,
+						);
+						*result = create_versioned_wasm_runtime(
+							ext,
+							wasm_method,
+							heap_pages,
+							host_functions.into(),
+						);
+						if let Err(ref err) = result {
+							warn!(target: "runtimes_cache", "cannot create a runtime: {:?}", err);
+						}
+					}
+				}
+				result
+			},
+			Entry::Vacant(v) => {
+				trace!(target: "runtimes_cache", "no instance found in cache, creating now.");
+				let result = create_versioned_wasm_runtime(
+					ext,
+					wasm_method,
+					heap_pages,
+					host_functions.into(),
+				);
+				if let Err(ref err) = result {
+					warn!(target: "runtimes_cache", "cannot create a runtime: {:?}", err);
+				}
+				v.insert(result)
+			}
+		};
+
+		result.as_mut()
+			.map(|entry| (entry.runtime.as_mut(), &entry.version, code_hash))
+			.map_err(|ref e| Error::InvalidCode(format!("{:?}", e)))
+	}
+
+	/// Invalidate the runtime for the given `wasm_method` and `code_hash`.
+	///
+	/// Invalidation of a runtime is useful when there was a `panic!` in native while executing it.
+	/// The `panic!` maybe have brought the runtime into a poisoned state and so, it is better to
+	/// invalidate this runtime instance.
+	pub fn invalidate_runtime(
+		&mut self,
+		wasm_method: WasmExecutionMethod,
+		code_hash: H256,
+	) {
+		// Just remove the instance, it will be re-created the next time it is requested.
+		self.instances.remove(&(wasm_method, code_hash.into()));
+	}
+}
+
+/// Create a wasm runtime with the given `code`.
+pub fn create_wasm_runtime_with_code(
+	wasm_method: WasmExecutionMethod,
+	heap_pages: u64,
+	code: &[u8],
+	host_functions: Vec<&'static dyn Function>,
+) -> Result<Box<dyn WasmRuntime>, WasmError> {
+	match wasm_method {
+		WasmExecutionMethod::Interpreted =>
+			wasmi_execution::create_instance(code, heap_pages, host_functions)
+				.map(|runtime| -> Box<dyn WasmRuntime> { Box::new(runtime) }),
+		#[cfg(feature = "wasmtime")]
+		WasmExecutionMethod::Compiled =>
+			wasmtime::create_instance(code, heap_pages, host_functions)
+				.map(|runtime| -> Box<dyn WasmRuntime> { Box::new(runtime) }),
+	}
+}
+
+fn create_versioned_wasm_runtime<E: Externalities>(
+	ext: &mut E,
+	wasm_method: WasmExecutionMethod,
+	heap_pages: u64,
+	host_functions: Vec<&'static dyn Function>,
+) -> Result<VersionedRuntime, WasmError> {
+	let code = ext
+		.original_storage(well_known_keys::CODE)
+		.ok_or(WasmError::CodeNotFound)?;
+	let mut runtime = create_wasm_runtime_with_code(wasm_method, heap_pages, &code, host_functions)?;
+
+	// Call to determine runtime version.
+	let version_result = {
+		// `ext` is already implicitly handled as unwind safe, as we store it in a global variable.
+		let mut ext = AssertUnwindSafe(ext);
+
+		// The following unwind safety assertion is OK because if the method call panics, the
+		// runtime will be dropped.
+		let mut runtime = AssertUnwindSafe(runtime.as_mut());
+		crate::native_executor::safe_call(
+			move || runtime.call(&mut **ext, "Core_version", &[])
+		).map_err(|_| WasmError::Instantiation("panic in call to get runtime version".into()))?
+	};
+	let encoded_version = version_result
+		.map_err(|e| WasmError::Instantiation(format!("failed to call \"Core_version\": {}", e)))?;
+	let version = RuntimeVersion::decode(&mut encoded_version.as_slice())
+		.map_err(|_| WasmError::Instantiation("failed to decode \"Core_version\" result".into()))?;
+
+	Ok(VersionedRuntime {
+		runtime,
+		version,
+	})
+}
+
+#[cfg(test)]
+mod tests {
+	use wasm_interface::HostFunctions;
+
+	#[test]
+	fn host_functions_are_equal() {
+		let host_functions = runtime_io::SubstrateHostFunctions::host_functions();
+
+		let equal = &host_functions[..] == &host_functions[..];
+		assert!(equal, "Host functions are not equal");
+	}
+}