Documentation

kernel/defs.h

@@ -64,10 +64,34 @@ void ramdiskinit(void);
 void ramdiskintr(void);
 void ramdiskrw(struct buf *);
 
-// kalloc.c
+/**
+ * Kernel memory allocator
+ *
+ * Allocate one 4096-byte page of physical memory.
+ * Returns a pointer that the kernel can use.
+ * Returns 0 if the memory cannot be allocated.
+ * See: kalloc.c
+ */
 void *kalloc(void);
-void  kfree(void *);
+
-void  kinit(void);
+/**
+ * Kernel memory allocator
+ *
+ * Free the page of physical memory pointed at by pa,
+ * which normally should have been returned by a
+ * call to kalloc().  (The exception is when
+ * initializing the allocator; see kinit above.)
+ * See: kalloc.c
+ */
+void kfree(void *);
+
+/**
+ * Initialize kernel memory allocator
+ *
+ * Called by main() on the way to the kernel's main loop.
+ * See: kalloc.c
+ */
+void kinit(void);
 
 // log.c
 void initlog(int, struct superblock *);

kernel/kalloc.c

@@ -3,21 +3,23 @@
 // and pipe buffers. Allocates whole 4096-byte pages.
 
 #include "types.h"
-#include "param.h"
 #include "memlayout.h"
 #include "spinlock.h"
 #include "riscv.h"
 #include "defs.h"
 
+/** Free list of physical pages. */
 void freerange(void *pa_start, void *pa_end);
 
-extern char end[]; // first address after kernel.
+/** first address after kernel. defined by kernel.ld. */
-                   // defined by kernel.ld.
+extern char end[];
 
+/** A run is a node in the free list. */
 struct run {
   struct run *next;
 };
 
+/** Kernel memory allocator. */
 struct {
   struct spinlock lock;
   struct run     *freelist;
@@ -39,10 +41,6 @@ freerange(void *pa_start, void *pa_end)
     kfree(p);
 }
 
-// Free the page of physical memory pointed at by pa,
-// which normally should have been returned by a
-// call to kalloc().  (The exception is when
-// initializing the allocator; see kinit above.)
 void
 kfree(void *pa)
 {
@@ -62,9 +60,6 @@ kfree(void *pa)
   release(&kmem.lock);
 }
 
-// Allocate one 4096-byte page of physical memory.
-// Returns a pointer that the kernel can use.
-// Returns 0 if the memory cannot be allocated.
 void *
 kalloc(void)
 {

kernel/kernel.ld

@@ -15,12 +15,25 @@ SECTIONS
    * that reference the functions in your object file.
    */
   .text : {
+    /* Match any section that starts with .text. */
     *(.text .text.*)
+
+    /* Align the next section to a 4KB (page) boundary. */
     . = ALIGN(0x1000);
+
+    /* Put the trampoline code here. */
     _trampoline = .;
+
+    /* Match any section that starts with .trampsec. */
     *(trampsec)
+
+    /* Align the next section to a 4KB (page) boundary. */
     . = ALIGN(0x1000);
+
+    /* Assert that the trampoline code is exactly 4KB (page) in size. */
     ASSERT(. - _trampoline == 0x1000, "error: trampoline larger than one page");
+
+    /* Define symbol etext to be the current location. */
     PROVIDE(etext = .);
   }
 
@@ -29,6 +42,7 @@ SECTIONS
    * It is not unusual to find this data interleaved with the text section.
    */
   .rodata : {
+    /* Align on quadword boundary. */
     . = ALIGN(16);
     *(.srodata .srodata.*) /* do not need to distinguish this from .rodata */
     . = ALIGN(16);
@@ -59,6 +73,6 @@ SECTIONS
     *(.bss .bss.*)
   }
 
-  /* PROVIDE, see vm.c */
+  /* Define symbol end as current location, note that this is not aligned, see vm.c */
   PROVIDE(end = .);
 }

kernel/proc.c

@@ -650,9 +650,8 @@ either_copyin(void *dst, int user_src, u64 src, u64 len)
 void
 procdump(void)
 {
-  static char *states[] = {
+  static char *states[] = { [UNUSED] = "unused",   [USED] = "used",      [SLEEPING] = "sleep ",
-    [UNUSED] "unused", [USED] "used", [SLEEPING] "sleep ", [RUNNABLE] "runble", [RUNNING] "run   ", [ZOMBIE] "zombie"
+                            [RUNNABLE] = "runble", [RUNNING] = "run   ", [ZOMBIE] = "zombie" };
-  };
   struct proc *p;
   char        *state;