fixup! amd64: add exception stack at top of scratch memory

Add comments

Signed-off-by: Lucy Menon <168595099+syntactically@users.noreply.github.com>

Author: syntactically

src/hyperlight_guest_bin/src/arch/amd64/init.rs

@@ -20,6 +20,17 @@ use core::mem;
 use super::exception::entry::init_idt;
 use super::machine::{GDT, GdtEntry, GdtPointer, ProcCtrl, TSS};
 
+/// See AMD64 Architecture Programmer's Manual, Volume 2: System Programming
+///     Section 4: Segmented Virtual Memory
+///         §4.6: Descriptor Tables
+/// for the functions of the GDT.
+///
+/// Hyperlight's GDT consists of:
+/// - A null first entry, which is architecturally required
+/// - A single code segment descriptor, used for all code accesses
+/// - A single data segment descriptor, used for all data accesses
+/// - A TSS System descriptor that outlines the location of the TSS
+///   (see [`init_tss`], below)
 #[repr(C)]
 struct HyperlightGDT {
     null: GdtEntry,
@@ -68,6 +79,14 @@ unsafe fn init_gdt(pc: *mut ProcCtrl) {
     }
 }
 
+/// Hyperlight's TSS contains only a single IST entry, which is used
+/// to set up the stack switch to the exception stack whenever we take
+/// an exception (including page faults, which are important, since
+/// the fault might be due to needing to grow the stack!)
+///
+/// This function sets up the TSS and then points the processor at the
+/// system segment descriptor, initialized in [`init_gdt`] above,
+/// which describes the location of the TSS.
 unsafe fn init_tss(pc: *mut ProcCtrl) {
     unsafe {
         let tss_ptr = &raw mut (*pc).tss;
@@ -77,7 +96,6 @@ unsafe fn init_tss(pc: *mut ProcCtrl) {
             - hyperlight_common::layout::SCRATCH_TOP_EXN_STACK_OFFSET
             + 1;
         ist1_ptr.write_volatile(exn_stack.to_ne_bytes());
-        // see init_gdt: 0x18 points to the tss set up above
         asm!(
             "ltr ax",
             in("ax") core::mem::offset_of!(HyperlightGDT, tss),

src/hyperlight_guest_bin/src/arch/amd64/machine.rs

@@ -56,6 +56,19 @@ impl GdtEntry {
         }
     }
 
+    /// Create a new entry that describes the Task State Segment
+    /// (TSS).
+    ///
+    /// The segment descriptor for the TSS needs to be wider than
+    /// other segments, because its base address is actually used &
+    /// must therefore be able to encode an entire 64-bit VA.  Because
+    /// of this, it uses two adjacent descriptor entries.
+    ///
+    /// See AMD64 Architecture Programmer's Manual, Volume 2: System Programming
+    ///     Section 4: Segmented Virtual Memory
+    ///         §4.8: Long-Mod Segment Descriptors
+    ///             §4.8.3: System Descriptors
+    /// for details of the layout
     pub const fn tss(base: u64, limit: u32) -> [Self; 2] {
         [
             Self {
@@ -89,6 +102,12 @@ pub(super) struct GdtPointer {
     pub(super) base: u64,
 }
 
+/// Task State Segment
+///
+/// See AMD64 Architecture Programmer's Manual, Volume 2: System Programming
+///     Section 12: Task Management
+///         §12.2: Task-Management Resources
+///             §12.2.5: 64-bit Task State Segment
 #[allow(clippy::upper_case_acronyms)]
 #[repr(C, packed)]
 pub(super) struct TSS {