From d0acf5a7184016a0fa216e9f94feaadabc50f080 Mon Sep 17 00:00:00 2001
From: Josh Holtrop <jholtrop@gmail.com>
Date: Sun, 20 Mar 2022 22:38:42 -0400
Subject: [PATCH] Comment hello.hello module a bit better

---
 src/hello/hello.d | 54 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 52 insertions(+), 2 deletions(-)

diff --git a/src/hello/hello.d b/src/hello/hello.d
index b10e383..d1ac80f 100644
--- a/src/hello/hello.d
+++ b/src/hello/hello.d
@@ -1,3 +1,6 @@
+/**
+ * HELLO, the HOS EFI Lightweight LOader.
+ */
 module hello.hello;
 
 import uefi;
@@ -9,11 +12,14 @@ import hos.cpu;
 import hos.memory;
 
 __gshared EFI_SYSTEM_TABLE * st;
-__gshared BootInfo bootinfo;
-__gshared UINTN memory_map_key;
+private __gshared BootInfo bootinfo;
+private __gshared UINTN memory_map_key;
 extern extern(C) __gshared ubyte hulk_start;
 extern extern(C) __gshared ubyte hulk_end;
 
+/**
+ * Detect if we're running in QEMU.
+ */
 private bool in_qemu()
 {
     ulong * firmware_vendor = cast(ulong *) st.FirmwareVendor;
@@ -25,6 +31,9 @@ private bool in_qemu()
          (cast(ulong)' ' << 48));
 }
 
+/**
+ * Set a graphics mode.
+ */
 private bool set_graphics_mode()
 {
     uint max_horizontal_resolution = in_qemu() ? 1920u : 0xFFFFFFFFu;
@@ -82,6 +91,11 @@ private bool set_graphics_mode()
     return true;
 }
 
+/**
+ * Walk the EFI memory map and translate it to the HULK bootinfo format.
+ *
+ * @return Maximum physical address to identity map.
+ */
 private ulong get_memory_map()
 {
     UINTN memory_map_size = scratch.free();
@@ -132,6 +146,9 @@ private ulong get_memory_map()
     return max_physical_address;
 }
 
+/**
+ * Allocate a new page table.
+ */
 private PageTableEntry * new_page_table()
 {
     PageTableEntry * pt = cast(PageTableEntry *)scratch.alloc(1u);
@@ -139,6 +156,13 @@ private PageTableEntry * new_page_table()
     return pt;
 }
 
+/**
+ * Map a virtual address to a physical address using 4KB pages.
+ *
+ * @param source_page Source page address.
+ * @param dest_page Destination page address.
+ * @param pt_base Page table base address.
+ */
 private void map4k(ulong source_page, ulong dest_page, PageTableEntry * pt_base)
 {
     PageTableEntry * pt = pt_base;
@@ -169,6 +193,13 @@ private void map4k(ulong source_page, ulong dest_page, PageTableEntry * pt_base)
     }
 }
 
+/**
+ * Map a virtual address to a physical address using 2MB pages.
+ *
+ * @param source_page Source page address.
+ * @param dest_page Destination page address.
+ * @param pt_base Page table base address.
+ */
 private void map2m(ulong source_page, ulong dest_page, PageTableEntry * pt_base)
 {
     PageTableEntry * pt = pt_base;
@@ -198,6 +229,11 @@ private void map2m(ulong source_page, ulong dest_page, PageTableEntry * pt_base)
     }
 }
 
+/**
+ * Map HULK virtual addresses to physical kernel location.
+ *
+ * @param pt_base Page table base address.
+ */
 private void map_hulk(PageTableEntry * pt_base)
 {
     ulong virt = HULK_VIRTUAL_START;
@@ -210,6 +246,11 @@ private void map_hulk(PageTableEntry * pt_base)
     }
 }
 
+/**
+ * Build page tables in preparation to jump to HULK.
+ *
+ * @param max_physical_address Maximum physical address to identity map.
+ */
 private void build_page_tables(ulong max_physical_address)
 {
     PageTableEntry * pt_base = new_page_table();
@@ -243,12 +284,21 @@ private void build_page_tables(ulong max_physical_address)
     write_cr3(cast(ulong)pt_base);
 }
 
+/**
+ * Jump to HULK entry point.
+ */
 private void jump_to_hulk()
 {
     void function(BootInfo *) hulk_start = cast(void function(BootInfo *))HULK_VIRTUAL_START;
     hulk_start(&bootinfo);
 }
 
+/**
+ * EFI application entry point.
+ *
+ * @param image_handle EFI application handle.
+ * @param st Pointer to EFI system table.
+ */
 extern (C) EFI_STATUS efi_main(EFI_HANDLE image_handle, EFI_SYSTEM_TABLE * st)
 {
     .st = st;