[common,guest] moved outb functionality to hyperlight_common and added a DebugPrint OutBAction

- the mechanism for causing VM exits and its abstractions over host functions should be
exposed in the common library so they can be used externally.
- 'PrintOutput' should not be a special host function. Instead, we should provide functionality for
debug prints—i.e., the DebugPrint OutBAction.

Signed-off-by: danbugs <[email protected]>

Author: danbugs

src/hyperlight_common/src/host_calling.rs

@@ -0,0 +1,69 @@
+use crate::flatbuffer_wrappers::function_types::{ParameterValue, ReturnType, ReturnValue};
+use crate::input_output::{InputDataSection, OutputDataSection};
+use anyhow::Result;
+use crate::flatbuffer_wrappers::function_call::{FunctionCall, FunctionCallType};
+use crate::outb::{outb, OutBAction};
+use crate::PEB;
+
+use alloc::vec::Vec;
+use alloc::string::ToString;
+use core::ffi::c_char;
+
+/// Get a return value from a host function call.
+/// This usually requires a host function to be called first using `call_host_function`.
+pub fn get_host_return_value<T: TryFrom<ReturnValue>>() -> Result<T> {
+    let input_data_section: InputDataSection =
+        unsafe { (*PEB).clone() }.get_input_data_region().into();
+    let return_value = input_data_section
+        .try_pop_shared_input_data_into::<ReturnValue>()
+        .expect("Unable to deserialize a return value from host");
+
+    T::try_from(return_value).map_err(|_| {
+        anyhow::anyhow!("Host return value was not a {} as expected", core::any::type_name::<T>())
+    })
+}
+
+/// Calls a host function.
+// TODO: Make this generic, return a Result<T, ErrorCode> this should allow callers to call this function and get the result type they expect
+// without having to do the conversion themselves
+pub fn call_host_function(
+    function_name: &str,
+    parameters: Option<Vec<ParameterValue>>,
+    return_type: ReturnType,
+) -> Result<()> {
+    let host_function_call = FunctionCall::new(
+        function_name.to_string(),
+        parameters,
+        FunctionCallType::Host,
+        return_type,
+    );
+
+    let host_function_call_buffer: Vec<u8> = host_function_call
+        .try_into()
+        .expect("Unable to serialize host function call");
+
+    let output_data_section: OutputDataSection =
+        unsafe { (*PEB).clone() }.get_output_data_region().into();
+    output_data_section
+        .push_shared_output_data(host_function_call_buffer)?;
+
+    outb(OutBAction::CallFunction as u16, 0);
+
+    Ok(())
+}
+
+/// Uses `hloutb` to issue multiple `DebugPrint` `OutBAction`s to print a message.
+pub fn print(message: &str) {
+    for byte in message.bytes() {
+        outb(OutBAction::DebugPrint as u16, byte);
+    }
+}
+
+/// Exposes a C API to allow the guest to print a string, byte by byte
+///
+/// # Safety
+/// This function is not thread safe and assumes `outb` is safe to call directly.
+#[no_mangle]
+pub unsafe extern "C" fn _putchar(c: c_char) {
+    outb(OutBAction::DebugPrint as u16, c as u8);
+}

src/hyperlight_common/src/input_output.rs

@@ -13,12 +13,9 @@ 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::boxed::Box;
-use alloc::format;
-use alloc::string::ToString;
+use anyhow::{bail, Result};
 use alloc::vec::Vec;
 use core::any::type_name;
-use core::error::Error;
 use core::slice::from_raw_parts_mut;
 
 pub struct InputDataSection {
@@ -31,16 +28,14 @@ impl InputDataSection {
         InputDataSection { ptr, len }
     }
 
-    pub fn try_pop_shared_input_data_into<T>(&self) -> Result<T, Box<dyn Error>>
+    pub fn try_pop_shared_input_data_into<T>(&self) -> Result<T>
     where
         T: for<'a> TryFrom<&'a [u8]>,
     {
         let input_data_buffer = unsafe { from_raw_parts_mut(self.ptr, self.len) };
 
         if input_data_buffer.is_empty() {
-            return Err("Got a 0-size buffer in pop_shared_input_data_into"
-                .to_string()
-                .into());
+            bail!("Got a 0-size buffer in pop_shared_input_data_into");
         }
 
         // get relative offset to next free address
@@ -51,11 +46,7 @@ impl InputDataSection {
         );
 
         if stack_ptr_rel > self.len || stack_ptr_rel < 16 {
-            return Err(format!(
-                "Invalid stack pointer: {} in pop_shared_input_data_into",
-                stack_ptr_rel
-            )
-            .into());
+            bail!("Invalid stack pointer: {} in pop_shared_input_data_into", stack_ptr_rel);
         }
 
         // go back 8 bytes and read. This is the offset to the element on top of stack
@@ -71,7 +62,7 @@ impl InputDataSection {
         let type_t = match T::try_from(buffer) {
             Ok(t) => Ok(t),
             Err(_e) => {
-                return Err(format!("Unable to convert buffer to {}", type_name::<T>()).into());
+                bail!("Unable to convert buffer to {}", type_name::<T>());
             }
         };
 
@@ -95,13 +86,11 @@ impl OutputDataSection {
         OutputDataSection { ptr, len }
     }
 
-    pub fn push_shared_output_data(&self, data: Vec<u8>) -> Result<(), Box<dyn Error>> {
+    pub fn push_shared_output_data(&self, data: Vec<u8>) -> Result<()> {
         let output_data_buffer = unsafe { from_raw_parts_mut(self.ptr, self.len) };
 
         if output_data_buffer.is_empty() {
-            return Err("Got a 0-size buffer in push_shared_output_data"
-                .to_string()
-                .into());
+            bail!("Got a 0-size buffer in push_shared_output_data");
         }
 
         // get offset to next free address on the stack
@@ -119,22 +108,14 @@ impl OutputDataSection {
         // It can be equal to the size, but never greater
         // It can never be less than 8. An empty buffer's stack pointer is 8
         if stack_ptr_rel > self.len || stack_ptr_rel < 8 {
-            return Err(format!(
-                "Invalid stack pointer: {} in push_shared_output_data",
-                stack_ptr_rel
-            )
-            .into());
+            bail!("Invalid stack pointer: {} in push_shared_output_data", stack_ptr_rel);
         }
 
         // check if there is enough space in the buffer
         let size_required = data.len() + 8; // the data plus the pointer pointing to the data
         let size_available = self.len - stack_ptr_rel;
         if size_required > size_available {
-            return Err(format!(
-                "Not enough space in shared output buffer. Required: {}, Available: {}",
-                size_required, size_available
-            )
-            .into());
+            bail!("Not enough space in shared output buffer. Required: {}, Available: {}", size_required, size_available);
         }
 
         // write the actual data

src/hyperlight_common/src/lib.rs

@@ -23,6 +23,9 @@ limitations under the License.
 pub const PAGE_SIZE: usize = 0x1_000; // 4KB
 
 extern crate alloc;
+extern crate core;
+
+use crate::hyperlight_peb::{HyperlightPEB, RunMode};
 
 pub mod flatbuffer_wrappers;
 /// cbindgen:ignore
@@ -43,6 +46,14 @@ mod flatbuffers;
 /// be able to communicate via function calls.
 pub mod hyperlight_peb;
 
+/// We keep track of the PEB address in a global variable that references a region of
+/// shared memory.
+pub static mut PEB: *mut HyperlightPEB = core::ptr::null_mut();
+
+/// Hyperlight supports running in both hypervisor mode and in process mode. We keep track of that
+/// state in this global variable.
+pub static mut RUNNING_MODE: RunMode = RunMode::None;
+
 /// Hyperlight operates with a host-guest execution model.
 ///
 /// The host is who creates the hypervisor partition, and the guest is whatever runs
@@ -53,3 +64,11 @@ pub mod hyperlight_peb;
 /// push data to the output section. On the other hand, the host can push data to the
 /// input section and pop data from the output section.
 pub mod input_output;
+
+/// `outb` is the mechanism that Hyperlight uses to cause a VM exit to execute host functions and
+/// similar functionality.
+pub mod outb;
+
+/// Hyperlight provides abstractions for performing a VM exits with the intent of calling
+/// functionality in the host.
+pub mod host_calling;

src/hyperlight_common/src/outb.rs

@@ -0,0 +1,62 @@
+use core::arch;
+use anyhow::{bail, Result};
+use crate::hyperlight_peb::RunMode;
+use crate::RUNNING_MODE;
+
+/// Supported actions when issuing an OUTB actions by Hyperlight.
+/// - Log: for logging,
+/// - CallFunction: makes a call to a host function,
+/// - Abort: aborts the execution of the guest,
+/// - DebugPrint: prints a message to the host console.
+pub enum OutBAction {
+    Log = 99,
+    CallFunction = 101,
+    Abort = 102,
+    DebugPrint = 103,
+}
+
+impl TryFrom<u16> for OutBAction {
+    type Error = anyhow::Error;
+    fn try_from(val: u16) -> Result<Self> {
+        match val {
+            99 => Ok(OutBAction::Log),
+            101 => Ok(OutBAction::CallFunction),
+            102 => Ok(OutBAction::Abort),
+            103 => Ok(OutBAction::DebugPrint),
+            _ => bail!("Invalid OutB value: {}", val),
+        }
+    }
+}
+
+/// Issues an OUTB instruction to the specified port with the given value.
+fn hloutb(port: u16, val: u8) {
+    unsafe { arch::asm!("out dx, al", in("dx") port, in("al") val, options(preserves_flags, nomem, nostack)); }
+}
+
+pub fn outb(port: u16, value: u8) {
+    unsafe {
+        match RUNNING_MODE {
+            RunMode::Hypervisor => {
+                hloutb(port, value);
+            }
+            RunMode::InProcessLinux | RunMode::InProcessWindows => {
+                // TODO(danbugs:297): bring back
+                // if let Some(outb_func) = OUTB_PTR_WITH_CONTEXT {
+                //     if let Some(peb_ptr) = PEB {
+                //         outb_func((*peb_ptr).pOutbContext, port, value);
+                //     }
+                // } else if let Some(outb_func) = OUTB_PTR {
+                //     outb_func(port, value);
+                // } else {
+                //     panic!("Tried to call outb without hypervisor and without outb function ptrs");
+                // }
+            }
+            _ => {
+                panic!("Tried to call outb in invalid runmode");
+            }
+        }
+
+        // TODO(danbugs:297): bring back
+        // check_for_host_error();
+    }
+}

src/hyperlight_guest/src/chkstk.rs

@@ -18,9 +18,10 @@ use core::arch::global_asm;
 use core::mem::size_of;
 
 use hyperlight_common::hyperlight_peb::RunMode;
+use hyperlight_common::RUNNING_MODE;
 
 use crate::guest_error::{set_invalid_runmode_error, set_stack_allocate_error};
-use crate::{MIN_STACK_ADDRESS, RUNNING_MODE};
+use crate::MIN_STACK_ADDRESS;
 
 extern "win64" {
     fn __chkstk();

src/hyperlight_guest/src/entrypoint.rs

@@ -20,14 +20,14 @@ use core::ptr::copy_nonoverlapping;
 use hyperlight_common::hyperlight_peb::{HyperlightPEB, RunMode};
 use log::LevelFilter;
 use spin::Once;
-
+use hyperlight_common::outb::{outb, OutBAction};
+use hyperlight_common::{PEB, RUNNING_MODE};
 use crate::gdt::load_gdt;
 use crate::guest_error::reset_error;
 use crate::guest_function_call::dispatch_function;
 use crate::guest_logger::init_logger;
-use crate::host_function_call::{outb, OutBAction};
 use crate::idtr::load_idt;
-use crate::{__security_cookie, HEAP_ALLOCATOR, MIN_STACK_ADDRESS, PEB, RUNNING_MODE};
+use crate::{__security_cookie, HEAP_ALLOCATOR, MIN_STACK_ADDRESS};
 
 #[inline(never)]
 pub fn halt() {

src/hyperlight_guest/src/guest_error.rs

@@ -20,10 +20,9 @@ use core::ffi::{c_char, CStr};
 
 use hyperlight_common::flatbuffer_wrappers::guest_error::{ErrorCode, GuestError};
 use log::error;
-
+use hyperlight_common::outb::{outb, OutBAction};
+use hyperlight_common::PEB;
 use crate::entrypoint::halt;
-use crate::host_function_call::{outb, OutBAction};
-use crate::PEB;
 
 pub(crate) fn write_error(error_code: ErrorCode, message: Option<&str>) {
     let peb = unsafe { (*PEB).clone() };