feat: added docs

Author: mayank-microsoft

opentmk/src/uefi/hypercall.rs

@@ -11,7 +11,6 @@ use hvdef::HvRegisterGuestVsmPartitionConfig;
 use hvdef::HvRegisterValue;
 use hvdef::HvRegisterVsmPartitionConfig;
 use hvdef::HvX64RegisterName;
-use minimal_rt::arch::hypercall::{invoke_hypercall_vtl};
 use zerocopy::FromZeros;
 use core::arch;
 use core::cell::RefCell;
@@ -21,7 +20,7 @@ use hvdef::hypercall::HvInputVtl;
 use hvdef::Vtl;
 use hvdef::HV_PAGE_SIZE;
 use memory_range::MemoryRange;
-use minimal_rt::arch::hypercall::invoke_hypercall;
+use minimal_rt::arch::hypercall::{invoke_hypercall, HYPERCALL_PAGE};
 use zerocopy::IntoBytes;
 use zerocopy::FromBytes;
 
@@ -32,6 +31,19 @@ struct HvcallPage {
 
 }
 
+pub fn invoke_hypercall_vtl(control: hvdef::hypercall::Control) {
+    // SAFETY: the caller guarantees the safety of this operation.
+    unsafe {
+        core::arch::asm! {
+            "call {hypercall_page}",
+            hypercall_page = sym HYPERCALL_PAGE,
+            inout("rcx") u64::from(control) => _,
+            in("rdx") 0,
+            in("rax") 0,
+        }
+    }
+}
+
 impl HvcallPage {
     pub const fn new() -> Self {
         HvcallPage {
@@ -52,6 +64,59 @@ impl HvcallPage {
 }
 
 /// Provides mechanisms to invoke hypercalls within the boot shim.
+/// 
+/// This module defines the `HvCall` struct and associated methods to interact with
+/// hypervisor functionalities through hypercalls. It includes utilities for managing
+/// hypercall pages, setting and getting virtual processor (VP) registers, enabling
+/// VTL (Virtual Trust Levels), and applying memory protections.
+///
+/// # Overview
+///
+/// - **Hypercall Pages**: Manages page-aligned buffers for hypercall input and output.
+/// - **VP Registers**: Provides methods to set and get VP registers.
+/// - **VTL Management**: Includes methods to enable VTLs, apply VTL protections, and
+///   manage VTL-specific operations.
+/// - **Memory Protections**: Supports applying VTL protections and accepting VTL2 pages.
+///
+/// # Safety
+///
+/// Many methods in this module involve unsafe operations, such as invoking hypercalls
+/// or interacting with low-level memory structures. The caller must ensure the safety
+/// of these operations by adhering to the requirements of the hypervisor and the
+/// underlying architecture.
+///
+/// # Usage
+///
+/// This module is designed for use in single-threaded environments, such as the boot
+/// shim. It uses static buffers for hypercall pages, so it is not thread-safe.
+///
+/// # Features
+///
+/// - **Architecture-Specific Implementations**: Some methods are only available for
+///   specific architectures (e.g., `x86_64` or `aarch64`).
+/// - **Error Handling**: Methods return `Result` types to handle hypervisor errors.
+///
+/// # Examples
+///
+/// ```rust
+/// let mut hv_call = HvCall::new();
+/// hv_call.initialize();
+/// let vtl = hv_call.vtl();
+/// println!("Current VTL: {:?}", vtl);
+/// hv_call.uninitialize();
+/// ```
+///
+/// # Modules and Types
+///
+/// - `HvCall`: Main struct for managing hypercalls.
+/// - `HvcallPage`: Struct for page-aligned buffers.
+/// - `HwId`: Type alias for hardware IDs (APIC ID on `x86_64`, MPIDR on `aarch64`).
+///
+/// # Notes
+///
+/// - This module assumes the presence of a hypervisor that supports the required
+///   hypercalls.
+/// - The boot shim must ensure that hypercalls are invoked in a valid context.
 /// Internally uses static buffers for the hypercall page, the input
 /// page, and the output page, so this should not be used in any
 /// multi-threaded capacity (which the boot shim currently is not).
@@ -62,13 +127,6 @@ pub struct HvCall {
     output_page: HvcallPage,
 }
 
-/// Returns an [`HvCall`] instance.
-///
-/// Panics if another instance is already in use.
-// #[track_caller]
-// pub fn hvcall() -> core::cell::RefMut<'static, HvCall> {
-//     HVCALL.borrow_mut()
-// }
 
 #[expect(unsafe_code)]
 impl HvCall {
@@ -384,7 +442,7 @@ impl HvCall {
         Ok(context)
     }
 
-    pub fn high_vtl() {
+    pub fn vtl_call() {
         let control: hvdef::hypercall::Control = hvdef::hypercall::Control::new()
             .with_code(hvdef::HypercallCode::HvCallVtlCall.0)
             .with_rep_count(0);
@@ -397,7 +455,7 @@ impl HvCall {
         }
     }
 
-    pub fn low_vtl() {
+    pub fn vtl_return() {
         let control: hvdef::hypercall::Control = hvdef::hypercall::Control::new()
             .with_code(hvdef::HypercallCode::HvCallVtlReturn.0)
             .with_rep_count(0);

opentmk/src/uefi/hypvctx.rs

@@ -2,8 +2,8 @@ use super::{
     context::{TestCtxTrait, VpExecutor},
     hypercall::HvCall,
 };
-use crate::{debuglog, slog::AssertResult};
 use crate::uefi::alloc::ALLOCATOR;
+use crate::{debuglog, slog::AssertResult};
 use crate::{
     infolog,
     slog::AssertOption,
@@ -46,10 +46,7 @@ fn register_command_queue(vp_index: u32) {
             CMD.lock().insert(vp_index, LinkedList::new());
             debuglog!("registered command queue for vp: {}", vp_index);
         } else {
-            debuglog!(
-                "command queue already registered for vp: {}",
-                vp_index
-            );
+            debuglog!("command queue already registered for vp: {}", vp_index);
         }
     }
 }
@@ -67,6 +64,71 @@ impl Drop for HvTestCtx {
     }
 }
 
+/// Implementation of the `TestCtxTrait` for the `HvTestCtx` structure, providing
+/// various methods to manage and interact with virtual processors (VPs) and
+/// Virtual Trust Levels (VTLs) in a hypervisor context.
+///
+/// # Methods
+///
+/// - `start_on_vp(&mut self, cmd: VpExecutor)`:
+///   Starts a virtual processor (VP) on a specified VTL. Handles enabling VTLs,
+///   switching between high and low VTLs, and managing VP execution contexts.
+///
+/// - `queue_command_vp(&mut self, cmd: VpExecutor)`:
+///   Queues a command for a specific VP and VTL.
+///
+/// - `switch_to_high_vtl(&mut self)`:
+///   Switches the current execution context to a high VTL.
+///
+/// - `switch_to_low_vtl(&mut self)`:
+///   Switches the current execution context to a low VTL.
+///
+/// - `setup_partition_vtl(&mut self, vtl: Vtl)`:
+///   Configures the partition to enable a specified VTL.
+///
+/// - `setup_interrupt_handler(&mut self)`:
+///   Sets up the interrupt handler for the architecture.
+///
+/// - `setup_vtl_protection(&mut self)`:
+///   Enables VTL protection for the current partition.
+///
+/// - `setup_secure_intercept(&mut self, interrupt_idx: u8)`:
+///   Configures secure intercept for a specified interrupt index, including
+///   setting up the SIMP and SINT0 registers.
+///
+/// - `apply_vtl_protection_for_memory(&mut self, range: Range<u64>, vtl: Vtl)`:
+///   Applies VTL protections to a specified memory range.
+///
+/// - `write_msr(&mut self, msr: u32, value: u64)`:
+///   Writes a value to a specified Model-Specific Register (MSR).
+///
+/// - `read_msr(&mut self, msr: u32) -> u64`:
+///   Reads the value of a specified Model-Specific Register (MSR).
+///
+/// - `start_running_vp_with_default_context(&mut self, cmd: VpExecutor)`:
+///   Starts a VP with the default execution context.
+///
+/// - `set_default_ctx_to_vp(&mut self, vp_index: u32, vtl: Vtl)`:
+///   Sets the default execution context for a specified VP and VTL.
+///
+/// - `enable_vp_vtl_with_default_context(&mut self, vp_index: u32, vtl: Vtl)`:
+///   Enables a VTL for a specified VP using the default execution context.
+///
+/// - `set_interupt_idx(&mut self, interrupt_idx: u8, handler: fn())`:
+///   Sets an interrupt handler for a specified interrupt index. (x86_64 only)
+///
+/// - `get_vp_count(&self) -> u32`:
+///   Retrieves the number of virtual processors available on the system.
+///
+/// - `get_register(&mut self, reg: u32) -> u128`:
+///   Retrieves the value of a specified register. Supports both x86_64 and
+///   aarch64 architectures.
+///
+/// - `get_current_vp(&self) -> u32`:
+///   Returns the index of the current virtual processor.
+///
+/// - `get_current_vtl(&self) -> Vtl`:
+///   Returns the current Virtual Trust Level (VTL).
 impl TestCtxTrait for HvTestCtx {
     fn start_on_vp(&mut self, cmd: VpExecutor) {
         let (vp_index, vtl, cmd) = cmd.get();
@@ -145,11 +207,11 @@ impl TestCtxTrait for HvTestCtx {
     }
 
     fn switch_to_high_vtl(&mut self) {
-        HvCall::high_vtl();
+        HvCall::vtl_call();
     }
 
     fn switch_to_low_vtl(&mut self) {
-        HvCall::low_vtl();
+        HvCall::vtl_return();
     }
 
     fn setup_partition_vtl(&mut self, vtl: Vtl) {

opentmk/src/uefi/mod.rs

@@ -32,5 +32,5 @@ use uefi::Status;
 fn uefi_main() -> Status {
     init().expect_assert("Failed to initialize environment");
     tests::run_test();
-    loop {}
+    Status::SUCCESS
 }

opentmk/src/uefi/rt.rs

@@ -7,17 +7,17 @@
 // UNSAFETY: Raw assembly needed for panic handling to abort.
 #![expect(unsafe_code)]
 
-use crate::arch::serial::{Serial, InstrIoAccess};
-use core::fmt::Write;
+use crate::arch::serial::{InstrIoAccess, Serial};
 use crate::slog;
 use crate::sync::Mutex;
+use core::arch::asm;
+use core::fmt::Write;
 
 #[panic_handler]
 fn panic_handler(panic: &core::panic::PanicInfo<'_>) -> ! {
-
-    let io = InstrIoAccess {};
-    let mut ser = Mutex::new(Serial::new(io));
     crate::errorlog!("Panic at runtime: {}", panic);
-    crate::errorlog!("Could not shut down... falling back to invoking an undefined instruction");
-    loop{}
+    unsafe {
+        asm!("int 8H");
+    }
+    loop {}
 }