From: Ben Pfaff <blp@cs.stanford.edu>
Date: Sat, 1 Jan 2005 19:35:14 +0000 (+0000)
Subject: Comments.
X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f0ad7eb8b43516c7a2999fd217ec85d954dfc791;p=pintos-anon

Comments.
---

diff --git a/src/threads/init.c b/src/threads/init.c
index 1135ae7..cf7a896 100644
--- a/src/threads/init.c
+++ b/src/threads/init.c
@@ -190,6 +190,10 @@ paging_init (void)
       pt[pte_idx] = pte_create_kernel (vaddr, true);
     }
 
+  /* Store the physical address of the page directory into CR3
+     aka PDBR (page directory base register).  This activates our
+     new page tables immediately.  See [IA32-v2a] "MOV--Move
+     to/from Control Registers" and [IA32-v3] 3.7.5. */
   asm volatile ("movl %0,%%cr3" :: "r" (vtop (base_page_dir)));
 }
 
diff --git a/src/threads/interrupt.c b/src/threads/interrupt.c
index c886cc9..c6ca2bd 100644
--- a/src/threads/interrupt.c
+++ b/src/threads/interrupt.c
@@ -50,7 +50,10 @@ enum intr_level
 intr_get_level (void) 
 {
   uint32_t flags;
-  
+
+  /* Push the flags register on the processor stack, then pop the
+     value off the stack into `flags'.  See [IA32-v2b] "PUSHF"
+     and "POP" and [IA32-v3] 5.8.1. */
   asm volatile ("pushfl; popl %0" : "=g" (flags));
 
   return flags & FLAG_IF ? INTR_ON : INTR_OFF;
@@ -70,7 +73,11 @@ intr_enable (void)
 {
   enum intr_level old_level = intr_get_level ();
   ASSERT (!intr_context ());
+
+  /* Enable interrupts by setting the interrupt flag.
+     See [IA32-v2b] "STI" and [IA32-v3] 5.8.1. */
   asm volatile ("sti");
+
   return old_level;
 }
 
@@ -79,7 +86,11 @@ enum intr_level
 intr_disable (void) 
 {
   enum intr_level old_level = intr_get_level ();
+
+  /* Disable interrupts by clearing the interrupt flag.
+     See [IA32-v2b] "CLI" and [IA32-v3] 5.8.1. */
   asm volatile ("cli");
+
   return old_level;
 }
 
@@ -97,7 +108,8 @@ intr_init (void)
   for (i = 0; i < INTR_CNT; i++)
     idt[i] = make_intr_gate (intr_stubs[i], 0);
 
-  /* Load IDT register. */
+  /* Load IDT register.
+     See [IA32-v2a] "LIDT" and [IA32-v3] 5.10. */
   idtr_operand = make_idtr_operand (sizeof idt - 1, idt);
   asm volatile ("lidt %0" :: "m" (idtr_operand));
 
@@ -349,9 +361,14 @@ intr_handler (struct intr_frame *frame)
 void
 intr_dump_frame (const struct intr_frame *f) 
 {
-  uint32_t cr2, ss;
+  uint32_t cr2;
+
+  /* Store current value of CR2 into `cr2'.
+     CR2 is the linear address of the last page fault.
+     See [IA32-v2a] "MOV--Move to/from Control Registers" and
+     [IA32-v3] 5.14 "Interrupt 14--Page Fault Exception
+     (#PF)". */
   asm ("movl %%cr2, %0" : "=r" (cr2));
-  asm ("movl %%ss, %0" : "=r" (ss));
 
   printf ("Interrupt %#04x (%s) at eip=%p\n",
           f->vec_no, intr_names[f->vec_no], f->eip);
@@ -361,7 +378,7 @@ intr_dump_frame (const struct intr_frame *f)
   printf (" esi=%08"PRIx32" edi=%08"PRIx32" esp=%08"PRIx32" ebp=%08"PRIx32"\n",
           f->esi, f->edi, (uint32_t) f->esp, f->ebp);
   printf (" cs=%04"PRIx16" ds=%04"PRIx16" es=%04"PRIx16" ss=%04"PRIx16"\n",
-          f->cs, f->ds, f->es, f->cs != SEL_KCSEG ? f->ss : ss);
+          f->cs, f->ds, f->es, f->ss);
 }
 
 /* Returns the name of interrupt VEC. */
diff --git a/src/threads/io.h b/src/threads/io.h
index a3889c2..b493299 100644
--- a/src/threads/io.h
+++ b/src/threads/io.h
@@ -48,6 +48,7 @@
 static inline uint8_t
 inb (uint16_t port)
 {
+  /* See [IA32-v2a] "IN". */
   uint8_t data;
   asm volatile ("inb %w1,%0" : "=a" (data) : "d" (port));
   return data;
@@ -58,6 +59,7 @@ inb (uint16_t port)
 static inline void
 insb (uint16_t port, void *addr, size_t cnt)
 {
+  /* See [IA32-v2a] "INS". */
   asm volatile ("cld; repne; insb"
                 : "=D" (addr), "=c" (cnt)
                 : "d" (port), "0" (addr), "1" (cnt)
@@ -69,6 +71,7 @@ static inline uint16_t
 inw (uint16_t port)
 {
   uint16_t data;
+  /* See [IA32-v2a] "IN". */
   asm volatile ("inw %w1,%0" : "=a" (data) : "d" (port));
   return data;
 }
@@ -78,6 +81,7 @@ inw (uint16_t port)
 static inline void
 insw (uint16_t port, void *addr, size_t cnt)
 {
+  /* See [IA32-v2a] "INS". */
   asm volatile ("cld; repne; insw"
                 : "=D" (addr), "=c" (cnt)
                 : "d" (port), "0" (addr), "1" (cnt)
@@ -88,6 +92,7 @@ insw (uint16_t port, void *addr, size_t cnt)
 static inline uint32_t
 inl (uint16_t port)
 {
+  /* See [IA32-v2a] "IN". */
   uint32_t data;
   asm volatile ("inl %w1,%0" : "=a" (data) : "d" (port));
   return data;
@@ -98,6 +103,7 @@ inl (uint16_t port)
 static inline void
 insl (uint16_t port, void *addr, size_t cnt)
 {
+  /* See [IA32-v2a] "INS". */
   asm volatile ("cld; repne; insl"
                 : "=D" (addr), "=c" (cnt)
                 : "d" (port), "0" (addr), "1" (cnt)
@@ -108,6 +114,7 @@ insl (uint16_t port, void *addr, size_t cnt)
 static inline void
 outb (uint16_t port, uint8_t data)
 {
+  /* See [IA32-v2b] "OUT". */
   asm volatile ("outb %0,%w1" : : "a" (data), "d" (port));
 }
 
@@ -116,6 +123,7 @@ outb (uint16_t port, uint8_t data)
 static inline void
 outsb (uint16_t port, const void *addr, size_t cnt)
 {
+  /* See [IA32-v2b] "OUTS". */
   asm volatile ("cld; repne; outsb"
                 : "=S" (addr), "=c" (cnt)
                 : "d" (port), "0" (addr), "1" (cnt)
@@ -126,6 +134,7 @@ outsb (uint16_t port, const void *addr, size_t cnt)
 static inline void
 outw (uint16_t port, uint16_t data)
 {
+  /* See [IA32-v2b] "OUT". */
   asm volatile ("outw %0,%w1" : : "a" (data), "d" (port));
 }
 
@@ -134,6 +143,7 @@ outw (uint16_t port, uint16_t data)
 static inline void
 outsw (uint16_t port, const void *addr, size_t cnt)
 {
+  /* See [IA32-v2b] "OUTS". */
   asm volatile ("cld; repne; outsw"
                 : "=S" (addr), "=c" (cnt)
                 : "d" (port), "0" (addr), "1" (cnt)
@@ -144,6 +154,7 @@ outsw (uint16_t port, const void *addr, size_t cnt)
 static inline void
 outl (uint16_t port, uint32_t data)
 {
+  /* See [IA32-v2b] "OUT". */
   asm volatile ("outl %0,%w1" : : "a" (data), "d" (port));
 }
 
@@ -152,6 +163,7 @@ outl (uint16_t port, uint32_t data)
 static inline void
 outsl (uint16_t port, const void *addr, size_t cnt)
 {
+  /* See [IA32-v2b] "OUTS". */
   asm volatile ("cld; repne; outsl"
                 : "=S" (addr), "=c" (cnt)
                 : "d" (port), "0" (addr), "1" (cnt)
diff --git a/src/threads/thread.c b/src/threads/thread.c
index ee83e0d..0a606b7 100644
--- a/src/threads/thread.c
+++ b/src/threads/thread.c
@@ -285,7 +285,8 @@ idle (void *aux UNUSED)
       thread_block ();
       intr_enable ();
 
-      /* Use CPU `hlt' instruction to wait for interrupt. */
+      /* Use CPU `hlt' instruction to wait for interrupt.
+         See [IA32-v2a] "HLT" and [IA32-v3] 7.7. */
       asm ("hlt");
     }
 }
diff --git a/src/userprog/exception.c b/src/userprog/exception.c
index 8b2e8b6..745adaa 100644
--- a/src/userprog/exception.c
+++ b/src/userprog/exception.c
@@ -132,7 +132,10 @@ page_fault (struct intr_frame *f)
   /* Obtain faulting address, the virtual address that was
      accessed to cause the fault.  It may point to code or to
      data.  It is not necessarily the address of the instruction
-     that caused the fault (that's f->eip).  */
+     that caused the fault (that's f->eip).
+     See [IA32-v2a] "MOV--Move to/from Control Registers" and
+     [IA32-v3] 5.14 "Interrupt 14--Page Fault Exception
+     (#PF)". */
   asm ("movl %%cr2, %0" : "=r" (fault_addr));
 
   /* Turn interrupts back on (they were only off so that we could
diff --git a/src/userprog/pagedir.c b/src/userprog/pagedir.c
index 937f433..000aefe 100644
--- a/src/userprog/pagedir.c
+++ b/src/userprog/pagedir.c
@@ -187,6 +187,11 @@ pagedir_activate (uint32_t *pd)
 {
   if (pd == NULL)
     pd = base_page_dir;
+
+  /* Store the physical address of the page directory into CR3
+     aka PDBR (page directory base register).  This activates our
+     new page tables immediately.  See [IA32-v2a] "MOV--Move
+     to/from Control Registers" and [IA32-v3] 3.7.5. */
   asm volatile ("movl %0,%%cr3" :: "r" (vtop (pd)));
 }
 
@@ -196,6 +201,9 @@ active_pd (void)
 {
   uint32_t *pd;
 
+  /* Copy CR3, the page directory base register (PDBR), into `pd'
+     for us to exmaine.  See [IA32-v2a] "MOV--Move to/from
+     Control Registers" and [IA32-v3] 3.7.5. */
   asm ("movl %%cr3,%0" : "=r" (pd));
   return pd;
 }