Add component bindgen macros

.github/workflows/CargoPublish.yml

@@ -71,6 +71,18 @@ jobs:
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_PUBLISH_TOKEN }}
 
+      - name: Publish hyperlight-component-util
+        continue-on-error: ${{ inputs.dry_run }}
+        run: cargo publish --manifest-path ./src/hyperlight_component_util/Cargo.toml ${{ inputs.dry_run && '--dry-run' || '' }}
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_PUBLISH_TOKEN }}
+
+      - name: Publish hyperlight-component-macro
+        continue-on-error: ${{ inputs.dry_run }}
+        run: cargo publish --manifest-path ./src/hyperlight_component_macro/Cargo.toml ${{ inputs.dry_run && '--dry-run' || '' }}
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_PUBLISH_TOKEN }}
+
       # TODO: Do we want to publish hyperlight-guest-capi to crates.io given that it's not for Rust consumption?
       # - name: Publish hyperlight-guest-capi
       #   # `--no-verify` is needed because build.rs writes to "include/hyperlight_guest.h", but since we exclude that directory in Cargo.toml, it should be fine.

Cargo.toml

@@ -11,14 +11,17 @@ members = [
     "src/hyperlight_host",
     "src/hyperlight_guest_capi",
     "src/hyperlight_testing",
-    "fuzz", 
+    "fuzz",
     "src/hyperlight_guest_bin",
+    "src/hyperlight_component_util",
+    "src/hyperlight_component_macro",
 ]
 # Guests have custom linker flags, so we need to exclude them from the workspace
 exclude = [
     "src/tests/rust_guests/callbackguest",
     "src/tests/rust_guests/dummyguest",
     "src/tests/rust_guests/simpleguest",
+    "src/tests/rust_guests/witguest",
 ]
 
 [workspace.package]
@@ -36,6 +39,8 @@ hyperlight-host = { path = "src/hyperlight_host", version = "0.5.1", default-fea
 hyperlight-guest = { path = "src/hyperlight_guest", version = "0.5.1", default-features = false }
 hyperlight-guest-bin = { path = "src/hyperlight_guest_bin", version = "0.5.1", default-features = false }
 hyperlight-testing = { path = "src/hyperlight_testing", default-features = false }
+hyperlight-component-util = { path = "src/hyperlight_component_util" }
+hyperlight-component-macro = { path = "src/hyperlight_component_macro" }
 
 [workspace.lints.rust]
 unsafe_op_in_unsafe_fn = "deny"

Justfile

@@ -12,6 +12,7 @@ default-target := "debug"
 simpleguest_source := "src/tests/rust_guests/simpleguest/target/x86_64-unknown-none"
 dummyguest_source := "src/tests/rust_guests/dummyguest/target/x86_64-unknown-none"
 callbackguest_source := "src/tests/rust_guests/callbackguest/target/x86_64-unknown-none"
+witguest_source := "src/tests/rust_guests/witguest/target/x86_64-unknown-none"
 rust_guests_bin_dir := "src/tests/rust_guests/bin"
 
 ################
@@ -28,15 +29,21 @@ build target=default-target:
 # build testing guest binaries
 guests: build-and-move-rust-guests build-and-move-c-guests
 
-build-rust-guests target=default-target:
+witguest-wit:
+    cargo install --locked wasm-tools
+    cd src/tests/rust_guests/witguest && wasm-tools component wit guest.wit -w -o interface.wasm
+
+build-rust-guests target=default-target: (witguest-wit)
     cd src/tests/rust_guests/callbackguest && cargo build --profile={{ if target == "debug" { "dev" } else { target } }}
     cd src/tests/rust_guests/simpleguest && cargo build --profile={{ if target == "debug" { "dev" } else { target } }} 
     cd src/tests/rust_guests/dummyguest && cargo build --profile={{ if target == "debug" { "dev" } else { target } }} 
+    cd src/tests/rust_guests/witguest && cargo build --profile={{ if target == "debug" { "dev" } else { target } }}
 
 @move-rust-guests target=default-target:
     cp {{ callbackguest_source }}/{{ target }}/callbackguest* {{ rust_guests_bin_dir }}/{{ target }}/
     cp {{ simpleguest_source }}/{{ target }}/simpleguest* {{ rust_guests_bin_dir }}/{{ target }}/
     cp {{ dummyguest_source }}/{{ target }}/dummyguest* {{ rust_guests_bin_dir }}/{{ target }}/
+    cp {{ witguest_source }}/{{ target }}/witguest* {{ rust_guests_bin_dir }}/{{ target }}/
 
 build-and-move-rust-guests: (build-rust-guests "debug") (move-rust-guests "debug") (build-rust-guests "release") (move-rust-guests "release")
 build-and-move-c-guests: (build-c-guests "debug") (move-c-guests "debug") (build-c-guests "release") (move-c-guests "release")
@@ -48,6 +55,8 @@ clean-rust:
     cd src/tests/rust_guests/simpleguest && cargo clean
     cd src/tests/rust_guests/dummyguest && cargo clean
     cd src/tests/rust_guests/callbackguest && cargo clean
+    cd src/tests/rust_guests/witguest && cargo clean
+    cd src/tests/rust_guests/witguest && rm -f interface.wasm
     git clean -fdx src/tests/c_guests/bin src/tests/rust_guests/bin
 
 ################
@@ -127,6 +136,7 @@ fmt-check:
     cargo +nightly fmt --manifest-path src/tests/rust_guests/callbackguest/Cargo.toml -- --check
     cargo +nightly fmt --manifest-path src/tests/rust_guests/simpleguest/Cargo.toml -- --check
     cargo +nightly fmt --manifest-path src/tests/rust_guests/dummyguest/Cargo.toml -- --check
+    cargo +nightly fmt --manifest-path src/tests/rust_guests/witguest/Cargo.toml -- --check
     cargo +nightly fmt --manifest-path src/hyperlight_guest_capi/Cargo.toml -- --check
 
 check-license-headers:
@@ -137,14 +147,16 @@ fmt-apply:
     cargo +nightly fmt --manifest-path src/tests/rust_guests/callbackguest/Cargo.toml
     cargo +nightly fmt --manifest-path src/tests/rust_guests/simpleguest/Cargo.toml
     cargo +nightly fmt --manifest-path src/tests/rust_guests/dummyguest/Cargo.toml
+    cargo +nightly fmt --manifest-path src/tests/rust_guests/witguest/Cargo.toml
     cargo +nightly fmt --manifest-path src/hyperlight_guest_capi/Cargo.toml
 
-clippy target=default-target:
+clippy target=default-target: (witguest-wit)
     cargo clippy --all-targets --all-features --profile={{ if target == "debug" { "dev" } else { target } }} -- -D warnings
 
-clippy-guests target=default-target:
+clippy-guests target=default-target: (witguest-wit)
     cd src/tests/rust_guests/simpleguest && cargo clippy --profile={{ if target == "debug" { "dev" } else { target } }} -- -D warnings
     cd src/tests/rust_guests/callbackguest && cargo clippy --profile={{ if target == "debug" { "dev" } else { target } }} -- -D warnings
+    cd src/tests/rust_guests/witguest && cargo clippy --profile={{ if target == "debug" { "dev" } else { target } }} -- -D warnings
 
 clippy-apply-fix-unix:
     cargo clippy --fix --all 

src/hyperlight_common/Cargo.toml

@@ -20,10 +20,12 @@ anyhow = { version = "1.0.98", default-features = false }
 log = "0.4.27"
 tracing = { version = "0.1.41", optional = true }
 arbitrary = {version = "1.4.1", optional = true, features = ["derive"]}
+spin = "0.10.0"
 
 [features]
 default = ["tracing"]
 fuzzing = ["dep:arbitrary"]
+std = []
 
 [dev-dependencies]
 hyperlight-testing = { workspace = true }

src/hyperlight_common/src/lib.rs

@@ -39,3 +39,6 @@ pub mod mem;
 
 /// cbindgen:ignore
 pub mod outb;
+
+/// cbindgen:ignore
+pub mod resource;

src/hyperlight_common/src/resource.rs

@@ -0,0 +1,172 @@
+/*
+Copyright 2025 The Hyperlight Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+ */
+
+//! Shared operations around resources
+
+// "Needless" lifetimes are useful for clarity
+#![allow(clippy::needless_lifetimes)]
+
+use alloc::sync::Arc;
+
+#[cfg(feature = "std")]
+extern crate std;
+use core::marker::{PhantomData, Send};
+use core::ops::Deref;
+#[cfg(feature = "std")]
+use std::sync::{RwLock, RwLockReadGuard};
+
+#[cfg(not(feature = "std"))]
+use spin::{RwLock, RwLockReadGuard};
+
+/// The semantics of component model resources are, pleasingly,
+/// roughly compatible with those of Rust references, so we would like
+/// to use the more-or-less directly in interfaces generated by
+/// hyperlight_component_macro. Less pleasingly, it's not terribly
+/// easy to show the semantic agreement statically.
+///
+/// In particular, if the host calls into the guest and gives it a
+/// borrow of a resource, reentrant host function calls that use that
+/// borrow need to be able to resolve the original reference and use
+/// it in an appropriately scoped manner, but it is not simple to do
+/// this, because the core Hyperlight machinery doesn't offer an easy
+/// way to augment the host's context for the span of time of a guest
+/// function call.  This may be worth revisiting at some time, but in
+/// the meantime, it's easier to just do it dynamically.
+///
+/// # Safety
+/// Informally: this only creates SharedRead references, so having a
+/// bunch of them going at once is fine.  Safe Rust in the host can't
+/// use any earlier borrows (potentially invalidating these) until
+/// borrow passed into [`ResourceEntry::lend`] has expired.  Because
+/// that borrow outlives the [`LentResourceGuard`], it will not expire
+/// until that destructor is called. That destructor ensures that (a)
+/// there are no outstanding [`BorrowedResourceGuard`]s alive (since
+/// they would be holding the read side of the [`RwLock`] if they
+/// were), and that (b) the shared flag has been set to false, so
+/// [`ResourceEntry::borrow`] will never create another borrow
+pub enum ResourceEntry<T> {
+    Empty,
+    Owned(T),
+    Borrowed(Arc<RwLock<bool>>, *const T),
+}
+unsafe impl<T: Send> Send for ResourceEntry<T> {}
+
+pub struct LentResourceGuard<'a> {
+    flag: Arc<RwLock<bool>>,
+    already_revoked: bool,
+    _phantom: core::marker::PhantomData<&'a mut ()>,
+}
+impl<'a> LentResourceGuard<'a> {
+    pub fn revoke_nonblocking(&mut self) -> bool {
+        #[cfg(feature = "std")]
+        let Ok(mut flag) = self.flag.try_write() else {
+            return false;
+        };
+        #[cfg(not(feature = "std"))]
+        let Some(mut flag) = self.flag.try_write() else {
+            return false;
+        };
+        *flag = false;
+        self.already_revoked = true;
+        true
+    }
+}
+impl<'a> Drop for LentResourceGuard<'a> {
+    fn drop(&mut self) {
+        if !self.already_revoked {
+            #[allow(unused_mut)] // it isn't actually unused
+            let mut guard = self.flag.write();
+            #[cfg(feature = "std")]
+            // If a mutex that is just protecting us from our own
+            // mistakes is poisoned, something is so seriously
+            // wrong that dying is a sensible response.
+            #[allow(clippy::unwrap_used)]
+            {
+                *guard.unwrap() = false;
+            }
+            #[cfg(not(feature = "std"))]
+            {
+                *guard = false;
+            }
+        }
+    }
+}
+pub struct BorrowedResourceGuard<'a, T> {
+    _flag: Option<RwLockReadGuard<'a, bool>>,
+    reference: &'a T,
+}
+impl<'a, T> Deref for BorrowedResourceGuard<'a, T> {
+    type Target = T;
+    fn deref(&self) -> &T {
+        self.reference
+    }
+}
+impl<T> ResourceEntry<T> {
+    pub fn give(x: T) -> ResourceEntry<T> {
+        ResourceEntry::Owned(x)
+    }
+    pub fn lend<'a>(x: &'a T) -> (LentResourceGuard<'a>, ResourceEntry<T>) {
+        let flag = Arc::new(RwLock::new(true));
+        (
+            LentResourceGuard {
+                flag: flag.clone(),
+                already_revoked: false,
+                _phantom: PhantomData {},
+            },
+            ResourceEntry::Borrowed(flag, x as *const T),
+        )
+    }
+    pub fn borrow<'a>(&'a self) -> Option<BorrowedResourceGuard<'a, T>> {
+        match self {
+            ResourceEntry::Empty => None,
+            ResourceEntry::Owned(t) => Some(BorrowedResourceGuard {
+                _flag: None,
+                reference: t,
+            }),
+            ResourceEntry::Borrowed(flag, t) => {
+                let guard = flag.read();
+                // If a mutex that is just protecting us from our own
+                // mistakes is poisoned, something is so seriously
+                // wrong that dying is a sensible response.
+                #[allow(clippy::unwrap_used)]
+                let flag = {
+                    #[cfg(feature = "std")]
+                    {
+                        guard.unwrap()
+                    }
+                    #[cfg(not(feature = "std"))]
+                    {
+                        guard
+                    }
+                };
+                if *flag {
+                    Some(BorrowedResourceGuard {
+                        _flag: Some(flag),
+                        reference: unsafe { &**t },
+                    })
+                } else {
+                    None
+                }
+            }
+        }
+    }
+    pub fn take(&mut self) -> Option<T> {
+        match core::mem::replace(self, ResourceEntry::Empty) {
+            ResourceEntry::Owned(t) => Some(t),
+            _ => None,
+        }
+    }
+}