From d6dd26c67e1317ab3d67483c447500400f689089 Mon Sep 17 00:00:00 2001
From: Imbus <>
Date: Fri, 9 Aug 2024 07:59:03 +0200
Subject: [PATCH] Documentation

---
 kernel/defs.h    | 30 +++++++++++++++++++++++++++---
 kernel/kalloc.c  | 15 +++++----------
 kernel/kernel.ld | 16 +++++++++++++++-
 kernel/proc.c    |  5 ++---
 4 files changed, 49 insertions(+), 17 deletions(-)

diff --git a/kernel/defs.h b/kernel/defs.h
index a89c445..ecbcf26 100644
--- a/kernel/defs.h
+++ b/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 *);
diff --git a/kernel/kalloc.c b/kernel/kalloc.c
index a3de3d5..b880933 100644
--- a/kernel/kalloc.c
+++ b/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.
-                   // defined by kernel.ld.
+/** first address after kernel. 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)
 {
diff --git a/kernel/kernel.ld b/kernel/kernel.ld
index 7ab21d8..2844edf 100644
--- a/kernel/kernel.ld
+++ b/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 = .);
 }
diff --git a/kernel/proc.c b/kernel/proc.c
index 58a3160..ccccf79 100644
--- a/kernel/proc.c
+++ b/kernel/proc.c
@@ -650,9 +650,8 @@ either_copyin(void *dst, int user_src, u64 src, u64 len)
 void
 procdump(void)
 {
-  static char *states[] = {
-    [UNUSED] "unused", [USED] "used", [SLEEPING] "sleep ", [RUNNABLE] "runble", [RUNNING] "run   ", [ZOMBIE] "zombie"
-  };
+  static char *states[] = { [UNUSED] = "unused",   [USED] = "used",      [SLEEPING] = "sleep ",
+                            [RUNNABLE] = "runble", [RUNNING] = "run   ", [ZOMBIE] = "zombie" };
   struct proc *p;
   char        *state;