Add "GC Zeal" infrastructure for additional, aggressive GC assertions (#12921)

* Add "GC Zeal" infrastructure for additional, aggressive GC assertions

This initial commit just sets up the initial GC Zeal infrastructure, it doesn't
actually start using it anywhere yet.

* Adds support for `cfg(gc_zeal)` to `crates/wasmtime/build.rs` and
  `crates/cranelift/build.rs`
* Defines `gc_assert!` macro
* Defines `wasmtime_environ::gc::POISON` constant for GC heap poisoning
* Adds debug assert that `POISON` doesn't overlap any valid `VMGcKind`
  discriminant
* Adds CI job to run GC-related tests with `cfg(gc_zeal)`

* Review feedback

Author: fitzgen

.github/workflows/main.yml

@@ -231,6 +231,9 @@ jobs:
           if grep -q pulley names.log; then
             echo test-nightly=true >> $GITHUB_OUTPUT
           fi
+          if grep -q gc names.log; then
+            echo test-gc-zeal=true >> $GITHUB_OUTPUT
+          fi
         fi
         matrix="$(node ./ci/build-test-matrix.js ./commits.log ./names.log $run_full)"
         echo "test-matrix={\"include\":$(echo $matrix)}" >> $GITHUB_OUTPUT
@@ -244,6 +247,7 @@ jobs:
             echo test-capi=true >> $GITHUB_OUTPUT
             echo test-nightly=true >> $GITHUB_OUTPUT
             echo test-miri=true >> $GITHUB_OUTPUT
+            echo test-gc-zeal=true >> $GITHUB_OUTPUT
             echo audit=true >> $GITHUB_OUTPUT
             echo preview1-adapter=true >> $GITHUB_OUTPUT
             echo run-dwarf=true >> $GITHUB_OUTPUT
@@ -663,6 +667,29 @@ jobs:
     - run: cargo fuzz check --dev --fuzz-dir ./cranelift/assembler-x64/fuzz
     - run: cargo fuzz check --dev --fuzz-dir ./crates/wizer/fuzz
 
+  # Run GC-related tests with `cfg(gc_zeal)` set
+  gc_zeal:
+    needs: determine
+    if: needs.determine.outputs.test-gc-zeal
+    name: GC Zeal Tests
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        submodules: true
+    - uses: ./.github/actions/install-rust
+    - name: Run GC tests with cfg(gc_zeal) enabled
+      env:
+        WASMTIME_TEST_GC_KEYWORDS: "gc drc any eq struct array i31 extern exn ref rec"
+        RUSTFLAGS: "--cfg gc_zeal"
+      run: |
+        set -e
+
+        cargo test --test all -- $WASMTIME_TEST_GC_KEYWORDS
+
+        # The wast test runner will read `WASMTIME_TEST_GC_KEYWORDS` on its own.
+        cargo test --test wast
+
   # Perform all tests of the c-api
   test_capi:
     needs: determine
@@ -1336,6 +1363,7 @@ jobs:
       - build-preview1-component-adapter-provider
       - test-min-platform-example
       - check_js
+      - gc_zeal
     if: always()
     steps:
     # Calculate the exit status of the whole CI workflow.

Cargo.toml

@@ -205,13 +205,17 @@ unused_import_braces = 'warn'
 unused-lifetimes = 'warn'
 unused-macro-rules = 'warn'
 
-# Don't warn about unknown cfgs for pulley
+# Don't warn about unknown cfgs for our custom cfgs.
 [workspace.lints.rust.unexpected_cfgs]
 level = "warn"
 check-cfg = [
   'cfg(pulley_tail_calls)',
   'cfg(pulley_assume_llvm_makes_tail_calls)',
   'cfg(pulley_disable_interp_simd)',
+  'cfg(arc_try_new)',
+
+  # When enabled, `cfg(gc_zeal)` activates aggressive GC debugging assertions.
+  'cfg(gc_zeal)',
 ]
 
 [workspace.lints.clippy]

crates/environ/src/gc.rs

@@ -22,6 +22,20 @@ use crate::{
 use alloc::sync::Arc;
 use core::alloc::Layout;
 
+/// Poison byte written over unallocated GC heap memory when `cfg(gc_zeal)` is
+/// enabled.
+pub const POISON: u8 = 0b00001111;
+
+/// Assert a condition, but only when `gc_zeal` is enabled.
+#[macro_export]
+macro_rules! gc_assert {
+    ($($arg:tt)*) => {
+        if cfg!(gc_zeal) {
+            assert!($($arg)*);
+        }
+    };
+}
+
 /// Discriminant to check whether GC reference is an `i31ref` or not.
 pub const I31_DISCRIMINANT: u32 = 1;
 
@@ -485,15 +499,23 @@ impl VMGcKind {
     #[inline]
     pub fn from_high_bits_of_u32(val: u32) -> VMGcKind {
         let masked = val & Self::MASK;
-        match masked {
+        let result = match masked {
             x if x == Self::ExternRef.as_u32() => Self::ExternRef,
             x if x == Self::AnyRef.as_u32() => Self::AnyRef,
             x if x == Self::EqRef.as_u32() => Self::EqRef,
             x if x == Self::ArrayRef.as_u32() => Self::ArrayRef,
             x if x == Self::StructRef.as_u32() => Self::StructRef,
             x if x == Self::ExnRef.as_u32() => Self::ExnRef,
             _ => panic!("invalid `VMGcKind`: {masked:#032b}"),
-        }
+        };
+
+        let poison_kind = u32::from_le_bytes([POISON, POISON, POISON, POISON]) & VMGcKind::MASK;
+        debug_assert_ne!(
+            masked, poison_kind,
+            "No valid `VMGcKind` should overlap with the poison pattern"
+        );
+
+        result
     }
 
     /// Does this kind match the other kind?

tests/wast.rs

@@ -18,25 +18,37 @@ fn main() {
 
     let mut trials = Vec::new();
 
+    // Check for if we are only running GC-related tests.
+    let gc_keywords = std::env::var("WASMTIME_TEST_GC_KEYWORDS")
+        .ok()
+        .map(|s| s.split(" ").map(|s| s.to_string()).collect::<Vec<_>>());
+
     let mut add_trial = |test: &WastTest, config: WastConfig| {
-        let trial = Trial::test(
-            format!(
-                "{:?}/{}{}{}",
-                config.compiler,
-                if config.pooling { "pooling/" } else { "" },
-                if config.collector != Collector::Auto {
-                    format!("{:?}/", config.collector)
-                } else {
-                    String::new()
-                },
-                test.path.to_str().unwrap()
-            ),
-            {
-                let test = test.clone();
-                move || run_wast(&test, config).map_err(|e| format!("{e:?}").into())
+        let name = format!(
+            "{:?}/{}{}{}",
+            config.compiler,
+            if config.pooling { "pooling/" } else { "" },
+            if config.collector != Collector::Auto {
+                format!("{:?}/", config.collector)
+            } else {
+                String::new()
             },
+            test.path.to_str().unwrap()
         );
 
+        // Don't add this trial if we are only running GC-related tests and it
+        // doesn't look like a GC-related test.
+        if let Some(ks) = &gc_keywords {
+            if config.collector == Collector::Auto && !ks.iter().any(|kw| name.contains(kw)) {
+                return;
+            }
+        }
+
+        let trial = Trial::test(name, {
+            let test = test.clone();
+            move || run_wast(&test, config).map_err(|e| format!("{e:?}").into())
+        });
+
         trials.push(trial);
     };