kernel/{,mm,sys}: add docs for asm procedures (#94)

README.md

@@ -76,7 +76,7 @@ $ mage qemu
 
 # Build your own unikernel
 
-eggos has the ability to convert normal go program into an `ELF unikernel` which an be running on bare metal. 
+eggos has the ability to convert normal go program into an `ELF unikernel` which can be running on bare metal.
 
 First, get the `egg` binary, which can be accessed through https://github.com/icexin/eggos/releases, or directly through `go install github.com/icexin/eggos/cmd/egg`
 

boot/boot64.S

@@ -31,7 +31,7 @@ _start:
   mov $512, %ecx
 ptbl_loop:
   mov %eax, (%ebx)
-  add $0x200000, %eax
+  add $0x200000, %eax # 2 MB
   add $0x8, %ebx
   dec %ecx
   jnz ptbl_loop
@@ -133,4 +133,4 @@ wrmsr:
   shr $32, %rsi
   mov %rsi, %rdx     # val.high -> edx
   wrmsr
-  retq
+  retq

boot/multiboot.c

@@ -77,7 +77,7 @@ uint64 loadKernelElf(multiboot_info_t *info)
         return 0;
     }
     multiboot_module_t *mod = (multiboot_module_t *)(info->mods_addr);
-    char *new_addr = (char *)(100 << 20);
+    char *new_addr = (char *)(100 << 20); // 100 MB
     memcpy(new_addr, (char *)(mod->mod_start), mod->mod_end - mod->mod_start + 1);
     return loadelf(new_addr);
 }
@@ -98,4 +98,4 @@ void memset(char *addr, char data, int count)
     {
         *addr++ = data;
     }
-}
+}

kernel/asm_amd64.s

@@ -4,6 +4,7 @@
 #define get_tls(r)	MOVL TLS, r
 #define g(r)	0(r)(TLS*1)
 
+// rt0 is the entry point of the kernel, which invokes kernel.preinit.
 TEXT ·rt0(SB), NOSPLIT, $0-0
 	// switch to new stack
 	MOVQ $0x80000, SP
@@ -18,6 +19,7 @@ TEXT ·rt0(SB), NOSPLIT, $0-0
 
 	// never return
 
+// go_entry invokes _rt0_amd64_linux of the Go runtime.
 TEXT ·go_entry(SB), NOSPLIT, $0
 	SUBQ  $256, SP
 	PUSHQ SP
@@ -25,6 +27,7 @@ TEXT ·go_entry(SB), NOSPLIT, $0
 	ADDQ  $8, SP
 	JMP   _rt0_amd64_linux(SB)
 
+// sseInit initializes the SSE instruction set.
 TEXT ·sseInit(SB), NOSPLIT, $0
 	MOVL CR0, AX
 	ANDW $0xFFFB, AX
@@ -35,6 +38,7 @@ TEXT ·sseInit(SB), NOSPLIT, $0
 	MOVL AX, CR4
 	RET
 
+// avxInit initializes the AVX instruction set.
 TEXT ·avxInit(SB), NOSPLIT, $0
 	// enable XGETBV and XSETBV
 	MOVL CR4, AX
@@ -50,6 +54,7 @@ TEXT ·avxInit(SB), NOSPLIT, $0
 	XSETBV
 	RET
 
+// rdmsr(reg uint32) (ax, dx uint32) - Read from Model Specific Register.
 TEXT ·rdmsr(SB), NOSPLIT, $0-16
 	MOVL reg+0(FP), CX
 	RDMSR
@@ -57,6 +62,7 @@ TEXT ·rdmsr(SB), NOSPLIT, $0-16
 	MOVL DX, hi+12(FP)
 	RET
 
+// wrmsr(reg, lo, hi uint32) - Write to Model Specific Register.
 TEXT ·wrmsr(SB), NOSPLIT, $0-16
 	MOVL reg+0(FP), CX
 	MOVL lo+8(FP), AX
@@ -64,12 +70,14 @@ TEXT ·wrmsr(SB), NOSPLIT, $0-16
 	WRMSR
 	RET
 
+// getg() uint64 - returns G from thread local storage of the current thread.
 TEXT ·getg(SB), NOSPLIT, $0-8
 	get_tls(CX)
 	MOVQ g(CX), BX
 	MOVQ BX, ret+0(FP)
 	RET
 
+// cpuid(fn, cx uint32) (ax, bx, cx, dx uint32) - CPU Identification.
 TEXT ·cpuid(SB), NOSPLIT, $0-24
 	MOVL fn+0(FP), AX
 	MOVL cx+4(FP), CX

kernel/mm/mm.s

@@ -1,5 +1,7 @@
 #include "textflag.h"
 
+// pageEnable enables translation from virtual address (linear address) to
+// physical address, based on the page directory set in the CR3 register.
 TEXT ·pageEnable(SB), NOSPLIT, $0-0
 	// enable PAE
 	MOVQ CR4, AX
@@ -12,6 +14,7 @@ TEXT ·pageEnable(SB), NOSPLIT, $0-0
 	MOVQ AX, CR0
 	RET
 
+// lcr3(topPage uint64) sets the CR3 register.
 TEXT ·lcr3(SB), NOSPLIT, $0-8
 	// setup page dir
 	MOVQ topPage+0(FP), AX

kernel/seg.s

@@ -1,20 +1,24 @@
 #include "textflag.h"
 
+// lgdt(gdtptr uint64) - Load Global Descriptor Table Register.
 TEXT ·lgdt(SB), NOSPLIT, $0-8
 	MOVQ gdtptr+0(FP), AX
 	LGDT (AX)
 	RET
 
+// lidt(idtptr uint64) - Load Interrupt Descriptor Table Register.
 TEXT ·lidt(SB), NOSPLIT, $0-8
 	MOVQ idtptr+0(FP), AX
 	LIDT (AX)
 	RET
 
+// ltr(sel uint64) - Load Task Register.
 TEXT ·ltr(SB), NOSPLIT, $0-8
 	MOVQ sel+0(FP), AX
 	LTR  AX
 	RET
 
+// reloadCS returns from the current interrupt handler.
 TEXT ·reloadCS(SB), NOSPLIT, $0
 	// save ip
 	MOVQ 0(SP), AX

kernel/thread.s

@@ -32,11 +32,13 @@ TEXT ·swtch(SB), NOSPLIT, $0-16
 	POPQ BP
 	RET
 
+// Mythread() uint64
 TEXT ·Mythread(SB), NOSPLIT, $0-8
 	MOVQ tls_my(GS), AX
 	MOVQ AX, ret+0(FP)
 	RET
 
+// ksysClone(pc, stack, flags uint64) (ax uint64) invokes SYS_clone.
 TEXT ·ksysClone(SB), NOSPLIT, $0-32
 	MOVQ $SYS_clone, AX
 	MOVQ pc+0(FP), R12
@@ -57,6 +59,7 @@ TEXT ·ksysClone(SB), NOSPLIT, $0-32
 	NOP SP  // tell vet SP changed - stop checking offsets
 	JMP R12
 
+// ksysYield invokes SYS_sched_yield.
 TEXT ·ksysYield(SB), NOSPLIT, $0
 	MOVQ $SYS_sched_yield, AX
 	INT  $0x80