Add back DummyVM as a part of the porting guide. Minor changes to M…

…MTk initialization in the porting guide. (#1142)

Following the discussion here:
https://mmtk.zulipchat.com/#narrow/stream/315620-Porting/topic/Porting.20MMTK.20to.20Clasp.20Common.20Lisp/near/442123897.
It is useful for the language implementers to have a Rust binding crate
that implements all the boilerplate code and can compile to start with.
This PR adds back `DummyVM` to the porting guide, and includes some
minor changes to the porting guide.

---------

Co-authored-by: Kunal Sareen <[email protected]>
Co-authored-by: Kunshan Wang <[email protected]>

.github/scripts/ci-common.sh

@@ -7,6 +7,8 @@ project_root=$(dirname "$0")/../..
 
 cargo_toml=$project_root/Cargo.toml
 
+dummyvm_toml=$project_root/docs/dummyvm/Cargo.toml
+
 # Repeat a command for all the features. Requires the command as one argument (with double quotes)
 for_all_features() {
     # without mutually exclusive features

.github/scripts/ci-doc.sh

@@ -22,6 +22,9 @@ if ! cat $project_root/src/plan/mod.rs | grep -q "pub mod mygc;"; then
 fi
 cargo build
 
+# Check dummyvm in portingguide
+cargo build --manifest-path $dummyvm_toml
+
 # Install mdbook using the stable toolchain and the default target
 unset CARGO_BUILD_TARGET
 cargo +stable install mdbook mdbook-admonish mdbook-hide

.github/scripts/ci-style.sh

@@ -51,3 +51,4 @@ style_check_auxiliary_crate() {
 }
 
 style_check_auxiliary_crate macros
+style_check_auxiliary_crate docs/dummyvm

.github/scripts/ci-test.sh

@@ -37,3 +37,6 @@ find ./src ./tests -type f -name "mock_test_*" | while read -r file; do
         env MMTK_PLAN=$MMTK_PLAN cargo test --features mock_test,"$FEATURES" -- $t;
     done
 done
+
+# Test the dummy VM
+cargo test --manifest-path $dummyvm_toml

docs/dummyvm/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "mmtk_dummyvm"
+version = "0.0.1"
+authors = [" <>"]
+edition = "2021"
+
+[lib]
+name = "mmtk_dummyvm"
+# be careful - LTO is only allowed for certain crate types
+# We know that cdylib should work for LTO.
+crate-type = ["cdylib"]
+
+[profile.release]
+lto = true
+
+[dependencies]
+# We use a local path as the MMTk dependency here, as we want to test the code with the current version.
+# Generally for a binding, you would like to use a specific version, or a git commit.
+# mmtk = "0.25.0"
+# mmtk = { git = "https://github.com/mmtk/mmtk-core.git", branch = "master" }
+mmtk = { path = "../../." }
+libc = "0.2"
+atomic = "0.6"
+
+[features]
+default = []
+is_mmtk_object = ["mmtk/is_mmtk_object"]
+malloc_counted_size = ["mmtk/malloc_counted_size"]

docs/dummyvm/README.md

@@ -0,0 +1,7 @@
+An example of MMTk/Rust-side Binding Implementation
+===
+
+A binding needs to implement certain Rust traits and may need to expose MMTk's Rust API to native code.
+This Rust crate illustrates a minimal example of what needs to be implemented on the binding side in Rust.
+When starting a new port of MMTk, developers can use this crate as a starting point by directly copying
+it to their port. For more details, see [the porting guide](https://docs.mmtk.io/portingguide/howto/nogc.html#set-up).

docs/header/mmtk.h → docs/dummyvm/include/mmtk.h

@@ -17,84 +17,62 @@ extern "C" {
 
 typedef void* MMTk_Mutator;
 typedef void* MMTk_Builder;
-typedef void* MMTk;
 
 // Initialize an MMTk instance
-extern MMTk mmtk_init(MMTk_Builder builder);
+extern void mmtk_init(MMTk_Builder builder);
 
 // Request MMTk to create a new mutator for the given `tls` thread
 extern MMTk_Mutator mmtk_bind_mutator(void* tls);
 
 // Reclaim mutator that is no longer needed
 extern void mmtk_destroy_mutator(MMTk_Mutator mutator);
 
-// Flush mutator local state
-extern void mmtk_flush_mutator(MMTk_Mutator mutator);
-
-// Initialize MMTk scheduler and GC workers
-extern void mmtk_initialize_collection(void* tls);
-
 // Allocate memory for an object
 extern void* mmtk_alloc(MMTk_Mutator mutator,
                         size_t size,
                         size_t align,
                         size_t offset,
                         int allocator);
 
-// Slowpath allocation for an object
-extern void* mmtk_alloc_slow(MMTk_Mutator mutator,
-                             size_t size,
-                             size_t align,
-                             size_t offset,
-                             int allocator);
-
 // Perform post-allocation hooks or actions such as initializing object metadata
 extern void mmtk_post_alloc(MMTk_Mutator mutator,
                             void* refer,
                             int bytes,
                             int allocator);
 
-// Return if the object pointed to by `ref` is live
-extern bool mmtk_is_live_object(void* ref);
-
-// Return if the object pointed to by `ref` is in mapped memory
-extern bool mmtk_is_mapped_object(void* ref);
-
-// Return if the address pointed to by `addr` is in mapped memory
-extern bool mmtk_is_mapped_address(void* addr);
-
-// Return if object pointed to by `object` will never move
-extern bool mmtk_will_never_move(void* object);
-
-// Process an MMTk option. Return true if option was processed successfully
-extern bool mmtk_process(MMTk_Builder builder, char* name, char* value);
-
-// Process MMTk options. Return true if all options were processed successfully
-extern bool mmtk_process_bulk(MMTk_Builder builder, char* options);
-
-// Sanity only. Scan heap for discrepancies and errors
-extern void mmtk_scan_region();
-
-// Request MMTk to trigger a GC. Note that this may not actually trigger a GC
-extern void mmtk_handle_user_collection_request(void* tls);
-
 // Run the main loop for a GC worker. Does not return
 extern void mmtk_start_worker(void* tls, void* worker);
 
-// Return the current amount of free memory in bytes
-extern size_t mmtk_free_bytes();
+// Initialize MMTk scheduler and GC workers
+extern void mmtk_initialize_collection(void* tls);
 
 // Return the current amount of used memory in bytes
 extern size_t mmtk_used_bytes();
 
+// Return the current amount of free memory in bytes
+extern size_t mmtk_free_bytes();
+
 // Return the current amount of total memory in bytes
 extern size_t mmtk_total_bytes();
 
-// Return the starting address of MMTk's heap
-extern void* mmtk_starting_heap_address();
+// Return if the object pointed to by `object` is live
+extern bool mmtk_is_live_object(void* object);
 
-// Return the ending address of MMTk's heap
-extern void* mmtk_last_heap_address();
+// Return if object pointed to by `object` will never move
+extern bool mmtk_will_never_move(void* object);
+
+// Return if the address is an object in MMTk heap.
+// Only available when the feature is_mmtk_object is enabled.
+extern bool mmtk_is_mmtk_object(void* addr);
+
+// Return if the object is in any MMTk space.
+extern bool mmtk_is_in_mmtk_spaces(void* object);
+
+// Return if the address pointed to by `addr` is in memory that is mapped by MMTk
+extern bool mmtk_is_mapped_address(void* addr);
+
+// Request MMTk to trigger a GC. Note that this may not actually trigger a GC
+extern void mmtk_handle_user_collection_request(void* tls);
 
 // Add a reference to the list of weak references
 extern void mmtk_add_weak_candidate(void* ref);
@@ -111,6 +89,33 @@ extern void mmtk_harness_begin(void* tls);
 // Generic hook to allow benchmarks to be harnessed
 extern void mmtk_harness_end();
 
+// Create an MMTKBuilder
+extern MMTk_Builder mmtk_create_builder();
+
+// Process an MMTk option. Return true if option was processed successfully
+extern bool mmtk_process(MMTk_Builder builder, char* name, char* value);
+
+// Return the starting address of MMTk's heap
+extern void* mmtk_starting_heap_address();
+
+// Return the ending address of MMTk's heap
+extern void* mmtk_last_heap_address();
+
+// Standard malloc functions
+extern void* mmtk_malloc(size_t size);
+extern void* mmtk_calloc(size_t num, size_t size);
+extern void* mmtk_realloc(void* addr, size_t size);
+extern void* mmtk_free(void* addr);
+
+// Counted versions of the malloc functions. The allocation size will be ounted into the MMTk heap.
+// Only available when the feature malloc_counted_size is enabled.
+extern void* mmtk_counted_malloc(size_t size);
+extern void* mmtk_counted_calloc(size_t num, size_t size);
+extern void* mmtk_realloc_with_old_size(void* addr, size_t size, size_t old_size);
+extern void* mmtk_free_with_size(void* addr, size_t old_size);
+// Get the number of active bytes in malloc.
+extern size_t mmtk_get_malloc_bytes();
+
 #ifdef __cplusplus
 }
 #endif

docs/dummyvm/src/active_plan.rs

@@ -0,0 +1,26 @@
+use crate::DummyVM;
+use mmtk::util::opaque_pointer::*;
+use mmtk::vm::ActivePlan;
+use mmtk::Mutator;
+
+pub struct VMActivePlan {}
+
+// Documentation: https://docs.mmtk.io/api/mmtk/vm/active_plan/trait.ActivePlan.html
+impl ActivePlan<DummyVM> for VMActivePlan {
+    fn number_of_mutators() -> usize {
+        unimplemented!()
+    }
+
+    fn is_mutator(_tls: VMThread) -> bool {
+        // FIXME: Properly check if the thread is a mutator
+        true
+    }
+
+    fn mutator(_tls: VMMutatorThread) -> &'static mut Mutator<DummyVM> {
+        unimplemented!()
+    }
+
+    fn mutators<'a>() -> Box<dyn Iterator<Item = &'a mut Mutator<DummyVM>> + 'a> {
+        unimplemented!()
+    }
+}