Guest function improvements and macros (#851)

* move function type traits to hyperlight_common

Signed-off-by: Jorge Prendes <[email protected]>

* Use function type traits to improve registration ergonomics

Signed-off-by: Jorge Prendes <[email protected]>

* Add from_result method to ResultType

Signed-off-by: Jorge Prendes <[email protected]>

* Add guest macro crate

Signed-off-by: Jorge Prendes <[email protected]>

* use guest_function and host_function macros in simpleguest

Signed-off-by: Jorge Prendes <[email protected]>

* update test guests Cargo.lock files

Signed-off-by: Jorge Prendes <[email protected]>

* Move result unwrap used in host_function macro from hl-common to hl-guest-bin

Signed-off-by: Jorge Prendes <[email protected]>

* Add comments on tricky areas

Signed-off-by: Jorge Prendes <[email protected]>

* update README.md to use new macros

Signed-off-by: Jorge Prendes <[email protected]>

---------

Signed-off-by: Jorge Prendes <[email protected]>

Author: jprendes

Cargo.lock

@@ -14,6 +14,7 @@ members = [
     "src/hyperlight_testing",
     "fuzz",
     "src/hyperlight_guest_bin",
+    "src/hyperlight_guest_macro",
     "src/hyperlight_component_util",
     "src/hyperlight_component_macro",
     "src/trace_dump",
@@ -28,7 +29,7 @@ exclude = [
 [workspace.package]
 version = "0.11.0"
 edition = "2024"
-rust-version = "1.88"
+rust-version = "1.89"
 license = "Apache-2.0"
 homepage = "https://github.com/hyperlight-dev/hyperlight"
 repository = "https://github.com/hyperlight-dev/hyperlight"
@@ -39,6 +40,7 @@ hyperlight-common = { path = "src/hyperlight_common", version = "0.11.0", defaul
 hyperlight-host = { path = "src/hyperlight_host", version = "0.11.0", default-features = false }
 hyperlight-guest = { path = "src/hyperlight_guest", version = "0.11.0", default-features = false }
 hyperlight-guest-bin = { path = "src/hyperlight_guest_bin", version = "0.11.0", default-features = false }
+hyperlight-guest-macro = { path = "src/hyperlight_guest_macro", version = "0.11.0", default-features = false }
 hyperlight-testing = { path = "src/hyperlight_testing", default-features = false }
 hyperlight-guest-tracing = { path = "src/hyperlight_guest_tracing", version = "0.11.0", default-features = false }
 hyperlight-component-util = { path = "src/hyperlight_component_util", version = "0.11.0", default-features = false }

Cargo.toml

@@ -261,6 +261,7 @@ clippy-exhaustive target=default-target: (witguest-wit)
     ./hack/clippy-package-features.sh hyperlight-host {{ target }} {{ target-triple }}
     ./hack/clippy-package-features.sh hyperlight-guest {{ target }} 
     ./hack/clippy-package-features.sh hyperlight-guest-bin {{ target }}
+    ./hack/clippy-package-features.sh hyperlight-guest-macro {{ target }}
     ./hack/clippy-package-features.sh hyperlight-common {{ target }} {{ target-triple }}
     ./hack/clippy-package-features.sh hyperlight-testing {{ target }} {{ target-triple }}
     ./hack/clippy-package-features.sh hyperlight-component-macro  {{ target }} {{ target-triple }}

Justfile

@@ -74,54 +74,33 @@ fn main() -> hyperlight_host::Result<()> {
 #![no_main]
 extern crate alloc;
 
-use alloc::string::ToString;
 use alloc::vec::Vec;
+use alloc::string::String;
 use hyperlight_common::flatbuffer_wrappers::function_call::FunctionCall;
-use hyperlight_common::flatbuffer_wrappers::function_types::{
-    ParameterType, ParameterValue, ReturnType,
-};
 use hyperlight_common::flatbuffer_wrappers::guest_error::ErrorCode;
-use hyperlight_common::flatbuffer_wrappers::util::get_flatbuffer_result;
-
-use hyperlight_guest::error::{HyperlightGuestError, Result};
-use hyperlight_guest_bin::guest_function::definition::GuestFunctionDefinition;
-use hyperlight_guest_bin::guest_function::register::register_function;
-use hyperlight_guest_bin::host_comm::call_host_function;
-
-fn print_output(function_call: &FunctionCall) -> Result<Vec<u8>> {
-    if let ParameterValue::String(message) = function_call.parameters.clone().unwrap()[0].clone() {
-        let result = call_host_function::<i32>(
-            "HostPrint",
-            Some(Vec::from(&[ParameterValue::String(message.to_string())])),
-            ReturnType::Int,
-        )?;
-        Ok(get_flatbuffer_result(result))
-    } else {
-        Err(HyperlightGuestError::new(
-            ErrorCode::GuestFunctionParameterTypeMismatch,
-            "Invalid parameters passed to simple_print_output".to_string(),
-        ))
-    }
+
+use hyperlight_guest::bail;
+use hyperlight_guest::error::Result;
+use hyperlight_guest_bin::{guest_function, host_function};
+
+#[host_function("HostPrint")]
+fn host_print(message: String) -> Result<i32>;
+
+#[guest_function("PrintOutput")]
+fn print_output(message: String) -> Result<i32> {
+    let result = host_print(message)?;
+    Ok(result)
 }
 
 #[no_mangle]
 pub extern "C" fn hyperlight_main() {
-    let print_output_def = GuestFunctionDefinition::new(
-        "PrintOutput".to_string(),
-        Vec::from(&[ParameterType::String]),
-        ReturnType::Int,
-        print_output as usize,
-    );
-    register_function(print_output_def);
+    // any initialization code goes here
 }
 
 #[no_mangle]
 pub fn guest_dispatch_function(function_call: FunctionCall) -> Result<Vec<u8>> {
-    let function_name = function_call.function_name.clone();
-    return Err(HyperlightGuestError::new(
-        ErrorCode::GuestFunctionNotFound,
-        function_name,
-    ));
+    let function_name = function_call.function_name;
+    bail!(ErrorCode::GuestFunctionNotFound => "{function_name}");
 }
 ```
 

README.md

@@ -21,13 +21,15 @@ log = "0.4.29"
 tracing = { version = "0.1.43", optional = true }
 arbitrary = {version = "1.4.2", optional = true, features = ["derive"]}
 spin = "0.10.0"
+thiserror = { version = "2.0.16", default-features = false }
 
 [features]
 default = ["tracing"]
+tracing = ["dep:tracing"]
 fuzzing = ["dep:arbitrary"]
 trace_guest = []
 mem_profile = []
-std = []
+std = ["thiserror/std", "log/std", "tracing/std"]
 
 [lib]
 bench = false # see https://bheisler.github.io/criterion.rs/book/faq.html#cargo-bench-gives-unrecognized-option-errors-for-valid-command-line-options

src/hyperlight_common/Cargo.toml

@@ -0,0 +1,45 @@
+/*
+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.
+*/
+
+use alloc::string::String;
+
+use thiserror::Error;
+
+use crate::func::{ParameterValue, ReturnValue};
+
+/// The error type for Hyperlight operations
+#[derive(Error, Debug)]
+pub enum Error {
+    /// Failed to get value from parameter value
+    #[error("Failed To Convert Parameter Value {0:?} to {1:?}")]
+    ParameterValueConversionFailure(ParameterValue, &'static str),
+
+    /// Failed to get value from return value
+    #[error("Failed To Convert Return Value {0:?} to {1:?}")]
+    ReturnValueConversionFailure(ReturnValue, &'static str),
+
+    /// A function was called with an incorrect number of arguments
+    #[error("The number of arguments to the function is wrong: got {0:?} expected {1:?}")]
+    UnexpectedNoOfArguments(usize, usize),
+
+    /// The parameter value type is unexpected
+    #[error("The parameter value type is unexpected got {0:?} expected {1:?}")]
+    UnexpectedParameterValueType(ParameterValue, String),
+
+    /// The return value type is unexpected
+    #[error("The return value type is unexpected got {0:?} expected {1:?}")]
+    UnexpectedReturnValueType(ReturnValue, String),
+}

src/hyperlight_common/src/func/error.rs

@@ -0,0 +1,40 @@
+/*
+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.
+*/
+
+use super::utils::for_each_tuple;
+use super::{Error, ParameterTuple, ResultType, SupportedReturnType};
+
+pub trait Function<Output: SupportedReturnType, Args: ParameterTuple, E: From<Error>> {
+    fn call(&self, args: Args) -> Result<Output, E>;
+}
+
+macro_rules! impl_function {
+    ([$N:expr] ($($p:ident: $P:ident),*)) => {
+        impl<F, R, E, $($P),*> Function<R::ReturnType, ($($P,)*), E> for F
+        where
+            F: Fn($($P),*) -> R,
+            ($($P,)*): ParameterTuple,
+            R: ResultType<E>,
+            E: From<Error> + core::fmt::Debug,
+        {
+            fn call(&self, ($($p,)*): ($($P,)*)) -> Result<R::ReturnType, E> {
+                (self)($($p),*).into_result()
+            }
+        }
+    };
+}
+
+for_each_tuple!(impl_function);

src/hyperlight_common/src/func/functions.rs

@@ -0,0 +1,49 @@
+/*
+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.
+*/
+
+/// Error types related to function support
+pub(crate) mod error;
+/// Definitions and functionality to enable guest-to-host function calling,
+/// also called "host functions"
+///
+/// This module includes functionality to do the following
+///
+/// - Define several prototypes for what a host function must look like,
+///   including the number of arguments (arity) they can have, supported argument
+///   types, and supported return types
+/// - Registering host functions to be callable by the guest
+/// - Dynamically dispatching a call from the guest to the appropriate
+///   host function
+pub(crate) mod functions;
+/// Definitions and functionality for supported parameter types
+pub(crate) mod param_type;
+/// Definitions and functionality for supported return types
+pub(crate) mod ret_type;
+
+pub use error::Error;
+/// Re-export for `HostFunction` trait
+pub use functions::Function;
+pub use param_type::{ParameterTuple, SupportedParameterType};
+pub use ret_type::{ResultType, SupportedReturnType};
+
+/// Re-export for `ParameterValue` enum
+pub use crate::flatbuffer_wrappers::function_types::ParameterValue;
+/// Re-export for `ReturnType` enum
+pub use crate::flatbuffer_wrappers::function_types::ReturnType;
+/// Re-export for `ReturnType` enum
+pub use crate::flatbuffer_wrappers::function_types::ReturnValue;
+
+mod utils;