Add some code coments to stage0.

Change-Id: I25cf9317b2fdfe4891c72cf12456d00c0b59ea93

stage0/src/paging.rs

@@ -33,9 +33,14 @@ use x86_64::{
 
 use crate::{hal::PageAssignment, BootAllocator, Platform, BOOT_ALLOC};
 
+/// The root page-map level 4 table coverting virtual memory ranges 0..128TiB
+/// and (16EiB-128TiB)..16EiB.
 pub static mut PML4: PageTable = PageTable::new();
+/// The page-directory pointer table covering virtual memory range 0..512GiB.
 pub static mut PDPT: PageTable = PageTable::new();
+/// The page directory covering virtual memory range 0..1GiB.
 pub static mut PD_0: PageTable = PageTable::new();
+/// The page directory covering virtual memory range 3..4GiB.
 pub static mut PD_3: PageTable = PageTable::new();
 
 /// Wrapper for the page table references so that we can access them via a mutex
@@ -181,22 +186,27 @@ pub fn init_page_table_refs<P: Platform>() {
     // Safety: accessing the mutable statics here is safe since we only do it once
     // and protect the mutable references with a mutex. This function can only
     // be called once, since updating `PAGE_TABLE_REFS` twice will panic.
-    let pml4 = unsafe { &mut *addr_of_mut!(PML4) };
-    let pdpt = unsafe { &mut *addr_of_mut!(PDPT) };
-    let pd_0 = unsafe { &mut *addr_of_mut!(PD_0) };
-    let pd_3 = unsafe { &mut *addr_of_mut!(PD_3) };
-
-    // Set up a new page table that maps the first 2MiB as 4KiB pages, so that we
-    // can share individual 4KiB pages with the hypervisor as needed. We are
-    // using an identity mapping between virtual and physical addresses.
+    let pml4: &mut PageTable = unsafe { &mut *addr_of_mut!(PML4) };
+    let pdpt: &mut PageTable = unsafe { &mut *addr_of_mut!(PDPT) };
+    let pd_0: &mut PageTable = unsafe { &mut *addr_of_mut!(PD_0) };
+    let pd_3: &mut PageTable = unsafe { &mut *addr_of_mut!(PD_3) };
+
+    // Set up a new page table that maps the first 2MiB as 4KiB pages (except for
+    // the lower 4KiB), so that we can share individual 4KiB pages with the
+    // hypervisor as needed. We are using an identity mapping between virtual
+    // and physical addresses.
     let mut pt_0 = Box::new_in(PageTable::new(), &BOOT_ALLOC);
+    // Let entry 1 map to 4KiB, entry 2 to 8KiB, ... , entry 511 to 2MiB-4KiB:
+    // We leave [0,4K) unmapped to make sure null pointer dereferences crash
+    // with a page fault.
     pt_0.iter_mut().enumerate().skip(1).for_each(|(i, entry)| {
         entry.set_address::<P>(
             PhysAddr::new((i as u64) * Size4KiB::SIZE),
             PageTableFlags::PRESENT | PageTableFlags::WRITABLE,
             PageEncryption::Encrypted,
         );
     });
+    // Let the first entry of PD_0 point to pt_0:
     pd_0[0].set_address::<P>(
         PhysAddr::new(pt_0.as_ref() as *const _ as usize as u64),
         PageTableFlags::PRESENT | PageTableFlags::WRITABLE,

stage0_bin_tdx/src/main.rs

@@ -80,6 +80,9 @@ const EFI_HOB_TYPE_HANDOFF: u16 = 0x0001;
 const EFI_HOB_TYPE_RESOURCE_DESCRIPTOR: u16 = 0x0003;
 const EFI_HOB_TYPE_END_OF_HOB_LIST: u16 = 0xFFFF;
 
+/// UEFI Standard HoB Header.
+/// See UEFI Platform Initialization Specification, section 5.2.
+/// https://uefi.org/sites/default/files/resources/PI_Spec_1_6.pdf
 #[repr(C)]
 #[derive(Copy, Clone, Debug)]
 pub struct Header {
@@ -88,6 +91,9 @@ pub struct Header {
     pub reserved: u32,
 }
 
+/// UEFI Standard Handoff Info Table (PHIT HOB).
+/// See UEFI Platform Initialization Specification, section 5.3.
+/// https://uefi.org/sites/default/files/resources/PI_Spec_1_6.pdf
 #[repr(C)]
 #[derive(Copy, Clone, Debug)]
 pub struct HandoffInfoTable {
@@ -101,6 +107,9 @@ pub struct HandoffInfoTable {
     end_of_hob_list: u64,
 }
 
+/// UEFI Standard Resource Descriptor (HoB)
+/// See UEFI Platform Initialization Specification, section 5.5.
+/// https://uefi.org/sites/default/files/resources/PI_Spec_1_6.pdf
 #[repr(C)]
 #[derive(Copy, Clone, Debug)]
 pub struct ResourceDescription {