Add documentation for the assembly stages

Author: phil-opp

src/stage_1.s

@@ -3,6 +3,9 @@
 .intel_syntax noprefix
 .code16
 
+# This stage initializes the stack, enables the A20 line, loads the rest of
+# the bootloader from disk, and jumps to stage_2.
+
 _start:
     # zero segment registers
     xor ax, ax

src/stage_2.s

@@ -2,6 +2,10 @@
 .intel_syntax noprefix
 .code16
 
+# This stage sets the target operating mode, loads the kernel from disk,
+# creates an e820 memory map, enters protected mode, and jumps to the
+# third stage.
+
 second_stage_start_str: .asciz "Booting (second stage)..."
 kernel_load_failed_str: .asciz "Failed to load kernel from disk"
 

src/stage_3.s

@@ -2,6 +2,11 @@
 .intel_syntax noprefix
 .code32
 
+# This stage performs some checks on the CPU (cpuid, long mode), sets up an
+# initial page table mapping (identity map the bootloader, map the P4
+# recursively, map the kernel blob to 4MB), enables paging, switches to long
+# mode, and jumps to stage_4.
+
 stage_3:
     mov bx, 0x10
     mov ds, bx # set data segment

src/stage_4.s

@@ -2,6 +2,8 @@
 .intel_syntax noprefix
 .code64
 
+# This stage calls into Rust code, passing various values as arguments.
+
 stage_4:
     # call load_elf with kernel start address, size, and memory map as arguments
     movabs rdi, 0x400000 # move absolute 64-bit to register