From 45928b97a8c925b0f86672beceaec6f1d95eed02 Mon Sep 17 00:00:00 2001
From: Ali Mashtizadeh <mashti@uwaterloo.ca>
Date: Sun, 20 Aug 2023 19:06:38 -0400
Subject: [PATCH] Document initialization on AMD64

---
 sys/amd64/machine.c | 74 ++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 70 insertions(+), 4 deletions(-)

diff --git a/sys/amd64/machine.c b/sys/amd64/machine.c
index 2f538bf..c3aeb07 100644
--- a/sys/amd64/machine.c
+++ b/sys/amd64/machine.c
@@ -40,7 +40,16 @@ static PseudoDescriptor GDTDescriptor[MAX_CPUS];
 TaskStateSegment64 TSS[MAX_CPUS];
 
 static char df_stack[4096];
-
+ 
+/*
+ * Machine_GDTInit --
+ *  
+ *	Configures the Global Descriptor Table (GDT) that lists all segments 
+ *	and privilege levels in x86.  64-bit mode uses flat 64-bit segments and 
+ *	doesn't support offsets and limits except for the special FS/GS segment 
+ *	registers.  We create four segments for the kernel code/data and user 
+ *	code/data.
+ */
 static void
 Machine_GDTInit()
 {
@@ -76,6 +85,12 @@ Machine_GDTInit()
     kprintf("Done!\n");
 }
 
+/*
+ * Machine_TSSInit --
+ *
+ *	Configures the Task State Segment (TSS) that specifies the kernel stack 
+ *	pointer during an interrupt.
+ */
 static void
 Machine_TSSInit()
 {
@@ -104,6 +119,13 @@ Machine_TSSInit()
     kprintf("Done!\n");
 }
 
+/*
+ * Machine_SyscallInit --
+ *
+ *	Configure the model specific registers (MSRs) that specify how to 
+ *	transfer control to the operating system when the system call 
+ *	instruction is invoked.
+ */
 static void
 Machine_SyscallInit()
 {
@@ -117,6 +139,11 @@ Machine_SyscallInit()
     kprintf("Done!\n");
 }
 
+/*
+ * Machine_EarlyInit --
+ *
+ *	Initializes early kernel state.
+ */
 void
 Machine_EarlyInit()
 {
@@ -133,23 +160,42 @@ Machine_IdleThread(void *test)
     while (1) { enable_interrupts(); hlt(); }
 }
 
+/*
+ * Machine_Init --
+ *
+ *	At this point the assembly startup code has setup temporary processor 
+ *	data structures sufficient to execute C code and make it through this 
+ *	initialization routine.
+ */
 void Machine_Init()
 {
+    /*
+     * Initialize Processor State
+     */
     Machine_GDTInit();
     Machine_TSSInit();
     Trap_Init();
     Machine_SyscallInit();
     clts(); // Enable FPU/XMM
 
+    /*
+     * Initialize Memory Allocation and Virtual Memory
+     */
     PAlloc_AddRegion(DMPA2VA(16*1024*1024), 16*1024*1024);
     PMap_Init();
     XMem_Init();
     PAlloc_LateInit();
     MachineBoot_AddMem();
 
+    /*
+     * Initialize Time Keeping
+     */
     KTime_Init();
     RTC_Init(); // Finishes initializing KTime
 
+    /*
+     * Initialize Interrupts
+     */
     IRQ_Init();
     LAPIC_Init();
     IOAPIC_Init();
@@ -158,13 +204,22 @@ void Machine_Init()
 
     KTimer_Init(); // Depends on RTC and KTime
 
+    /*
+     * Initialize Additional Processors
+     */
     MP_Init();
 
-    PS2_Init();
-    PCI_Init();
-    IDE_Init();
+    /*
+     * Initialize Basic Devices
+     */
+    PS2_Init(); // PS2 Keyboard
+    PCI_Init(); // PCI BUS
+    IDE_Init(); // IDE Disk Controller
     BufCache_Init();
 
+    /*
+     * Open the primary disk and mount the root file system
+     */
     Disk *root = Disk_GetByID(0, 0);
     if (!root)
 	Panic("No boot disk!");
@@ -172,17 +227,28 @@ void Machine_Init()
 
     Critical_Exit();
 
+    /*
+     * Create the idle thread
+     */
     Thread *thr = Thread_KThreadCreate(&Machine_IdleThread, NULL);
     if (thr == NULL) {
 	kprintf("Couldn't create idle thread!\n");
     }
     Sched_SetRunnable(thr);
 
+    /*
+     * Load the init processor
+     */
     Loader_LoadInit();
 
     breakpoint();
 }
 
+/*
+ * Machine_InitAP --
+ *
+ *	Shorter initialization routine for co-processors.
+ */
 void Machine_InitAP()
 {
     Critical_Enter();