From 9981bb227093373649acd019d378dfccb54189c8 Mon Sep 17 00:00:00 2001
From: Robert Morris <rtm@csail.mit.edu>
Date: Wed, 10 Jul 2019 08:57:51 -0400
Subject: [PATCH] tweak some comments.

---
 kernel/proc.c       | 20 ++++++++------------
 kernel/proc.h       | 32 ++++++++++++++++++--------------
 kernel/trampoline.S |  2 +-
 kernel/trap.c       |  2 +-
 4 files changed, 28 insertions(+), 28 deletions(-)

diff --git a/kernel/proc.c b/kernel/proc.c
index a947f7f..5c2d4ce 100644
--- a/kernel/proc.c
+++ b/kernel/proc.c
@@ -6,20 +6,16 @@
 #include "proc.h"
 #include "defs.h"
 
-struct proc proc[NPROC];
-
 struct cpu cpus[NCPU];
 
+struct proc proc[NPROC];
+
 struct proc *initproc;
 
-struct spinlock pid_lock;
 int nextpid = 1;
+struct spinlock pid_lock;
 
 extern void forkret(void);
-
-// for returning  out of the kernel
-extern void sysexit(void);
-
 static void wakeup1(struct proc *chan);
 
 extern char trampout[]; // trampoline.S
@@ -287,8 +283,8 @@ fork(void)
   return pid;
 }
 
-// Pass p's abandoned children to init. p and p's parent
-// are locked.
+// Pass p's abandoned children to init.
+// Caller must hold p->lock and parent->lock.
 void
 reparent(struct proc *p, struct proc *parent) {
   struct proc *pp;
@@ -536,7 +532,7 @@ sleep(void *chan, struct spinlock *lk)
 
 //PAGEBREAK!
 // Wake up p, used by exit()
-// Caller should lock p.
+// Caller must hold p->lock.
 static void
 wakeup1(struct proc *p)
 {
@@ -545,8 +541,8 @@ wakeup1(struct proc *p)
   }
 }
 
-// Wake up all processes sleeping on chan. Never
-// called when holding a p->lock
+// Wake up all processes sleeping on chan.
+// Must be called without any p->lock.
 void
 wakeup(void *chan)
 {
diff --git a/kernel/proc.h b/kernel/proc.h
index 687fdd1..373b605 100644
--- a/kernel/proc.h
+++ b/kernel/proc.h
@@ -18,33 +18,37 @@ struct context {
   uint64 s11;
 };
 
-// Per-CPU state
+// Per-CPU state.
 struct cpu {
-  struct proc *proc;           // The process running on this cpu or null
-  struct context scheduler;   // swtch() here to enter scheduler
-  int noff;                    // Depth of push_off() nesting.
-  int intena;                  // Were interrupts enabled before push_off()?
+  struct proc *proc;          // The process running on this cpu, or null.
+  struct context scheduler;   // swtch() here to enter scheduler().
+  int noff;                   // Depth of push_off() nesting.
+  int intena;                 // Were interrupts enabled before push_off()?
 };
 
 extern struct cpu cpus[NCPU];
 
 //PAGEBREAK: 17
 
-// per-process data for the early trap handling code in trampoline.S.
+// per-process data for the trap handling code in trampoline.S.
 // sits in a page by itself just under the trampoline page in the
 // user page table. not specially mapped in the kernel page table.
 // the sscratch register points here.
-// trampoline.S saves user registers, then restores kernel_sp and
-// kernel_satp.
-// includes callee-saved registers like s0-s11 because the
+// trampin in trampoline.S saves user registers in the trapframe,
+// then initializes registers from the trapframe's
+// kernel_sp, kernel_hartid, kernel_satp, and jumps to kernel_trap.
+// usertrapret() and trampout in trampoline.S set up
+// the trapframe's kernel_*, restore user registers from the
+// trapframe, switch to the user page table, and enter user space.
+// the trapframe includes callee-saved user registers like s0-s11 because the
 // return-to-user path via usertrapret() doesn't return through
 // the entire kernel call stack.
 struct trapframe {
-  /*   0 */ uint64 kernel_satp;
-  /*   8 */ uint64 kernel_sp;
-  /*  16 */ uint64 kernel_trap; // usertrap()
-  /*  24 */ uint64 epc; // saved user program counter
-  /*  32 */ uint64 hartid;
+  /*   0 */ uint64 kernel_satp;   // kernel page table
+  /*   8 */ uint64 kernel_sp;     // top of process's kernel stack
+  /*  16 */ uint64 kernel_trap;   // usertrap()
+  /*  24 */ uint64 epc;           // saved user program counter
+  /*  32 */ uint64 kernel_hartid; // saved kernel tp
   /*  40 */ uint64 ra;
   /*  48 */ uint64 sp;
   /*  56 */ uint64 gp;
diff --git a/kernel/trampoline.S b/kernel/trampoline.S
index dd4eb02..b992ea6 100644
--- a/kernel/trampoline.S
+++ b/kernel/trampoline.S
@@ -120,7 +120,7 @@ trampin:
         # restore kernel stack pointer from p->tf->kernel_sp
         ld sp, 8(a0)
 
-        # make tp hold the current hartid, from p->tf->hartid
+        # make tp hold the current hartid, from p->tf->kernel_hartid
         ld tp, 32(a0)
 
         # remember the address of usertrap(), p->tf->kernel_trap
diff --git a/kernel/trap.c b/kernel/trap.c
index 018b7db..27cfd32 100644
--- a/kernel/trap.c
+++ b/kernel/trap.c
@@ -100,7 +100,7 @@ usertrapret(void)
   p->tf->kernel_satp = r_satp();
   p->tf->kernel_sp = (uint64)p->kstack + PGSIZE;
   p->tf->kernel_trap = (uint64)usertrap;
-  p->tf->hartid = r_tp();
+  p->tf->kernel_hartid = r_tp();
 
   // set up the registers that trampoline.S's sret will use
   // to get to user space.