From 1b5ab3a5246478b88e2b1971a0b6e8b40a15f30c Mon Sep 17 00:00:00 2001
From: kyegupov <kyegupov4@gmail.com>
Date: Wed, 9 Jan 2019 09:42:49 +0000
Subject: [PATCH] Some documentation for ext_ functions in Substrate Runtime
API (#1369)
* Some documentation for ext_ functions in Substrate Runtime API
This would be useful for using non-Rust language to write Substrate-compatible modules and debugging modules at the WebAssembly level.
* Update without_std.rs
Update comment styles
---
substrate/core/sr-io/without_std.rs | 24 ++++++++++++++++++++++--
1 file changed, 22 insertions(+), 2 deletions(-)
diff --git a/substrate/core/sr-io/without_std.rs b/substrate/core/sr-io/without_std.rs
index d0f112b76e8..6cc5a15d7f2 100644
--- a/substrate/core/sr-io/without_std.rs
+++ b/substrate/core/sr-io/without_std.rs
@@ -53,11 +53,23 @@ pub extern fn oom(_: ::core::alloc::Layout) -> ! {
}
}
+/// Host functions, provided by the executor.
+/// A WebAssembly runtime module would "import" these to access the execution environment
+/// (most importantly, storage) or perform heavy hash calculations.
+/// See also "ext_" functions in sr-sandbox and sr-std
extern "C" {
+ /// Most of the functions below return fixed-size arrays (e.g. hashes) by writing them into
+ /// memory regions that should be preallocated by module.
+ /// Functions that return variable-sized data use host-side allocations. These should be
+ /// manually freed by the module.
fn ext_free(addr: *mut u8);
+
+ /// Printing, useful for debugging
fn ext_print_utf8(utf8_data: *const u8, utf8_len: u32);
fn ext_print_hex(data: *const u8, len: u32);
fn ext_print_num(value: u64);
+
+ /// Host storage access and verification
fn ext_set_storage(key_data: *const u8, key_len: u32, value_data: *const u8, value_len: u32);
fn ext_set_child_storage(storage_key_data: *const u8, storage_key_len: u32, key_data: *const u8, key_len: u32, value_data: *const u8, value_len: u32);
fn ext_clear_storage(key_data: *const u8, key_len: u32);
@@ -66,18 +78,26 @@ extern "C" {
fn ext_exists_child_storage(storage_key_data: *const u8, storage_key_len: u32, key_data: *const u8, key_len: u32) -> u32;
fn ext_clear_prefix(prefix_data: *const u8, prefix_len: u32);
fn ext_kill_child_storage(storage_key_data: *const u8, storage_key_len: u32);
+ /// Host-side result allocation
fn ext_get_allocated_storage(key_data: *const u8, key_len: u32, written_out: *mut u32) -> *mut u8;
+ /// Host-side result allocation
fn ext_get_allocated_child_storage(storage_key_data: *const u8, storage_key_len: u32, key_data: *const u8, key_len: u32, written_out: *mut u32) -> *mut u8;
fn ext_get_storage_into(key_data: *const u8, key_len: u32, value_data: *mut u8, value_len: u32, value_offset: u32) -> u32;
fn ext_get_child_storage_into(storage_key_data: *const u8, storage_key_len: u32, key_data: *const u8, key_len: u32, value_data: *mut u8, value_len: u32, value_offset: u32) -> u32;
fn ext_storage_root(result: *mut u8);
- fn ext_child_storage_root(storage_key_data: *const u8, storage_key_len: u32, written_out: *mut u32) -> *mut u8;
+ /// Host-side result allocation
+ fn ext_child_storage_root(storage_key_data: *const u8, storage_key_len: u32, written_out: *mut u32) -> *mut u8;
fn ext_storage_changes_root(parent_hash_data: *const u8, parent_hash_len: u32, parent_num: u64, result: *mut u8) -> u32;
- fn ext_blake2_256_enumerated_trie_root(values_data: *const u8, lens_data: *const u32, lens_len: u32, result: *mut u8);
+
+ /// The current relay chain identifier.
fn ext_chain_id() -> u64;
+
+ /// Hash calculation and verification
+ fn ext_blake2_256_enumerated_trie_root(values_data: *const u8, lens_data: *const u32, lens_len: u32, result: *mut u8);
fn ext_blake2_256(data: *const u8, len: u32, out: *mut u8);
fn ext_twox_128(data: *const u8, len: u32, out: *mut u8);
fn ext_twox_256(data: *const u8, len: u32, out: *mut u8);
+ /// Note: ext_ed25519_verify returns 0 if the signature is correct, nonzero otherwise.
fn ext_ed25519_verify(msg_data: *const u8, msg_len: u32, sig_data: *const u8, pubkey_data: *const u8) -> u32;
}
--
GitLab