From 8e1d1ec934d5ebcd4d8208f88857be12c8a97a06 Mon Sep 17 00:00:00 2001
From: kaashoek <kaashoek>
Date: Fri, 8 Sep 2006 14:36:44 +0000
Subject: [PATCH] some comment changes

---
 bootasm.S  |  2 +-
 buf.h      |  4 ++--
 fs.c       |  2 +-
 init.c     |  4 ++--
 kalloc.c   |  2 +-
 main.c     |  4 ++--
 spinlock.c | 13 ++++++-------
 7 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/bootasm.S b/bootasm.S
index 9f03c4d..aa462b9 100644
--- a/bootasm.S
+++ b/bootasm.S
@@ -5,7 +5,7 @@
 .set CR0_PE_ON,0x1              # protected mode enable flag
 
 #########################################################################
-# ENTRY POINT
+# ENTRY POINT for the bootstrap processor
 #   This code should be stored in the first sector of the hard disk.
 #   After the BIOS initializes the hardware on startup or system reset,
 #   it loads this code at physical address 0x7c00 - 0x7d00 (512 bytes).
diff --git a/buf.h b/buf.h
index a2a3ec1..ccf7f8b 100644
--- a/buf.h
+++ b/buf.h
@@ -6,5 +6,5 @@ struct buf {
   struct buf *next;
   uchar data[512];
 };
-#define B_BUSY 0x1
-#define B_VALID 0x2
+#define B_BUSY 0x1  // buffer is locked by some process
+#define B_VALID 0x2 // buffer contains the data of the sector
diff --git a/fs.c b/fs.c
index 3ba0858..3f0a71d 100644
--- a/fs.c
+++ b/fs.c
@@ -160,7 +160,7 @@ iget(uint dev, uint inum)
   return nip;
 }
 
-// Copy ip->d, which has changed, to disk.
+// Copy inode in memory, which has changed, to disk.
 // Caller must have locked ip.
 void
 iupdate(struct inode *ip)
diff --git a/init.c b/init.c
index ff6feaf..909ee80 100644
--- a/init.c
+++ b/init.c
@@ -17,8 +17,8 @@ main(void)
     mknod("console", T_DEV, 1, 1);
     open("console", O_RDWR);
   }
-  dup(0);
-  dup(0);
+  dup(0);  // stdout
+  dup(0);  // stderr
 
   for(;;){
     pid = fork();
diff --git a/kalloc.c b/kalloc.c
index 7d3ca0c..bfa9207 100644
--- a/kalloc.c
+++ b/kalloc.c
@@ -35,7 +35,7 @@ kinit(void)
   initlock(&kalloc_lock, "kalloc");
   start = (char*) &end;
   start = (char*) (((uint)start + PAGE) & ~(PAGE-1));
-  mem = 256; // assume 256 pages of RAM
+  mem = 256; // assume computer has 256 pages of RAM
   cprintf("mem = %d\n", mem * PAGE);
   kfree(start, mem * PAGE);
 }
diff --git a/main.c b/main.c
index c18fc08..cd893d5 100644
--- a/main.c
+++ b/main.c
@@ -15,7 +15,7 @@ extern uchar _binary__init_start[], _binary__init_size[];
 
 void process0();
 
-// CPU 0 starts running C code here.
+// Bootstrap processor starts running C code here.
 // This is called main0 not main so that it can have
 // a void return type.  Gcc can't handle functions named
 // main that don't return int.  Really.
@@ -28,7 +28,7 @@ main0(void)
   // clear BSS
   memset(edata, 0, end - edata);
 
-  // switch to cpu0's cpu stack
+  // switch to bootstrap processor's stack
   asm volatile("movl %0, %%esp" : : "r" (cpus[0].mpstack + MPSTACK - 32));
   asm volatile("movl %0, %%ebp" : : "r" (cpus[0].mpstack + MPSTACK));
 
diff --git a/spinlock.c b/spinlock.c
index 2e604b7..f814632 100644
--- a/spinlock.c
+++ b/spinlock.c
@@ -51,10 +51,9 @@ acquire(struct spinlock *lock)
   while(cmpxchg(0, 1, &lock->locked) == 1)
     ;
 
-  // Now that lock is acquired, make sure 
-  // we wait for all pending writes from other
-  // processors.
-  cpuid(0, 0, 0, 0, 0);  // memory barrier
+  // Serialize instructions: now that lock is acquired, make sure 
+  // we wait for all pending writes from other processors.
+  cpuid(0, 0, 0, 0, 0);  // memory barrier (see Ch 7 of IA-32 manual, vol 3)
   
   // Record info about lock acquisition for debugging.
   // The +10 is only so that we can tell the difference
@@ -74,9 +73,9 @@ release(struct spinlock *lock)
   lock->pcs[0] = 0;
   lock->cpu = 0xffffffff;
   
-  // Before unlocking the lock, make sure to flush
-  // any pending memory writes from this processor.
-  cpuid(0, 0, 0, 0, 0);  // memory barrier
+  // Serialize instructions: before unlocking the lock, make sure
+  // to flush any pending memory writes from this processor.
+  cpuid(0, 0, 0, 0, 0);  // memory barrier (see Ch 7 of IA-32 manual, vol 3)
 
   lock->locked = 0;
   if(--cpus[cpu()].nlock == 0)