Merge #1159

1159: Document runtime-core::vmcalls functions r=MarkMcCaskey a=MarkMcCaskey



Co-authored-by: Mark McCaskey <[email protected]>

lib/runtime-core/src/units.rs

@@ -1,4 +1,4 @@
-//! The units module provides common WebAssembly units like `Pages` and conversion functions into
+//! The units module provides common WebAssembly units like [`Pages`] and conversion functions into
 //! other units.
 use crate::error::PageError;
 use std::{
@@ -8,7 +8,7 @@ use std::{
 
 /// The page size in bytes of a wasm page.
 pub const WASM_PAGE_SIZE: usize = 65_536;
-/// Tbe max number of wasm pages allowed.
+/// The max number of wasm pages allowed.
 pub const WASM_MAX_PAGES: usize = 65_536;
 // From emscripten resize_heap implementation
 /// The minimum number of wasm pages allowed.

lib/runtime-core/src/vmcalls.rs

@@ -1,3 +1,5 @@
+//! Functions called from the generated code.
+
 #![allow(clippy::cast_ptr_alignment)]
 
 use crate::{
@@ -12,6 +14,16 @@ use crate::{
 // |       LOCAL MEMORIES        |
 // +*****************************+
 
+/// Increase the size of the static local memory with offset `memory_index` by
+/// `delta` [`Pages`].
+///
+/// This function returns the number of pages before growing if successful, or
+/// `-1` if the grow failed.
+///
+/// # Safety
+///
+/// The offset given by `memory_index` is not bounds-checked or typed-checked.
+/// Thus, the offset should be in-bounds and point to a [`StaticMemory`].
 pub unsafe extern "C" fn local_static_memory_grow(
     ctx: &mut vm::Ctx,
     memory_index: LocalMemoryIndex,
@@ -31,16 +43,32 @@ pub unsafe extern "C" fn local_static_memory_grow(
     ret
 }
 
+/// Get the size of a local [`StaticMemory`] in [`Pages`].
+///
+/// # Safety
+///
+/// The offset given by `memory_index` is not bounds-checked or typed-checked.
+/// Thus, the offset should be in-bounds and point to a [`StaticMemory`].
 pub unsafe extern "C" fn local_static_memory_size(
     ctx: &vm::Ctx,
     memory_index: LocalMemoryIndex,
 ) -> Pages {
     let local_memory = *ctx.internal.memories.add(memory_index.index());
-    let memory = (*local_memory).memory as *mut StaticMemory;
+    let memory = (*local_memory).memory as *const StaticMemory;
 
     (*memory).size()
 }
 
+/// Increase the size of the dynamic local memory with offset `memory_index` by
+/// `delta` [`Pages`].
+///
+/// This function returns the number of pages before growing if successful, or
+/// `-1` if the grow failed.
+///
+/// # Safety
+///
+/// The offset given by `memory_index` is not bounds-checked or typed-checked.
+/// Thus, the offset should be in-bounds and point to a [`DynamicMemory`].
 pub unsafe extern "C" fn local_dynamic_memory_grow(
     ctx: &mut vm::Ctx,
     memory_index: LocalMemoryIndex,
@@ -60,12 +88,18 @@ pub unsafe extern "C" fn local_dynamic_memory_grow(
     ret
 }
 
+/// Get the size of a local [`DynamicMemory`] in [`Pages`].
+///
+/// # Safety
+///
+/// The offset given by `memory_index` is not bounds-checked or typed-checked.
+/// Thus, the offset should be in-bounds and point to a [`DynamicMemory`].
 pub unsafe extern "C" fn local_dynamic_memory_size(
     ctx: &vm::Ctx,
     memory_index: LocalMemoryIndex,
 ) -> Pages {
     let local_memory = *ctx.internal.memories.add(memory_index.index());
-    let memory = (*local_memory).memory as *mut DynamicMemory;
+    let memory = (*local_memory).memory as *const DynamicMemory;
 
     (*memory).size()
 }
@@ -74,6 +108,16 @@ pub unsafe extern "C" fn local_dynamic_memory_size(
 // |      IMPORTED MEMORIES      |
 // +*****************************+
 
+/// Increase the size of the static imported memory with offset `import_memory_index` by
+/// `delta` [`Pages`].
+///
+/// This function returns the number of pages before growing if successful, or
+/// `-1` if the grow failed.
+///
+/// # Safety
+///
+/// The offset given by `import_memory_index` is not bounds-checked or typed-checked.
+/// Thus, the offset should be in-bounds and point to a [`StaticMemory`].
 pub unsafe extern "C" fn imported_static_memory_grow(
     ctx: &mut vm::Ctx,
     import_memory_index: ImportedMemoryIndex,
@@ -96,6 +140,12 @@ pub unsafe extern "C" fn imported_static_memory_grow(
     ret
 }
 
+/// Get the size of an imported [`StaticMemory`] in [`Pages`].
+///
+/// # Safety
+///
+/// The offset given by `import_memory_index` is not bounds-checked or typed-checked.
+/// Thus, the offset should be in-bounds and point to a [`StaticMemory`].
 pub unsafe extern "C" fn imported_static_memory_size(
     ctx: &vm::Ctx,
     import_memory_index: ImportedMemoryIndex,
@@ -104,11 +154,21 @@ pub unsafe extern "C" fn imported_static_memory_size(
         .internal
         .imported_memories
         .add(import_memory_index.index());
-    let memory = (*local_memory).memory as *mut StaticMemory;
+    let memory = (*local_memory).memory as *const StaticMemory;
 
     (*memory).size()
 }
 
+/// Increase the size of the dynamic imported memory with offset `memory_index` by
+/// `delta` [`Pages`].
+///
+/// This function returns the number of pages before growing if successful, or
+/// `-1` if the grow failed.
+///
+/// # Safety
+///
+/// The offset given by `memory_index` is not bounds-checked or typed-checked.
+/// Thus, the offset should be in-bounds and point to a [`DynamicMemory`].
 pub unsafe extern "C" fn imported_dynamic_memory_grow(
     ctx: &mut vm::Ctx,
     memory_index: ImportedMemoryIndex,
@@ -128,12 +188,18 @@ pub unsafe extern "C" fn imported_dynamic_memory_grow(
     ret
 }
 
+/// Get the size of an imported [`DynamicMemory`] in [`Pages`].
+///
+/// # Safety
+///
+/// The offset given by `memory_index` is not bounds-checked or typed-checked.
+/// Thus, the offset should be in-bounds and point to a [`DynamicMemory`].
 pub unsafe extern "C" fn imported_dynamic_memory_size(
     ctx: &vm::Ctx,
     memory_index: ImportedMemoryIndex,
 ) -> Pages {
     let local_memory = *ctx.internal.imported_memories.add(memory_index.index());
-    let memory = (*local_memory).memory as *mut DynamicMemory;
+    let memory = (*local_memory).memory as *const DynamicMemory;
 
     (*memory).size()
 }