Update docs.

[pintos-anon] / doc / debug.texi

diff --git a/doc/debug.texi b/doc/debug.texi
index e9bb4132d4814470c81a6f9f4d1726e256c1e722..754f5bc09c41692ad38e4ed0a377afaa9e8195c4 100644 (file)
--- a/doc/debug.texi
+++ b/doc/debug.texi
@@ -11,6 +11,7 @@ introduces you to a few of them.
 * Backtraces::                  
 * i386-elf-gdb::                
 * Modifying Bochs::             
+* Debugging Tips::              
 @end menu
 
 @node printf
@@ -177,3 +178,48 @@ that the third is less likely, but it is also possible.
 @node Modifying Bochs
 @section Modifying Bochs
 
+An advanced debugging technique is to modify and recompile the
+simulator.  This proves useful when the simulated hardware has more
+information than it makes available to the OS.  For example, page
+faults have a long list of potential causes, but the hardware does not
+report to the OS exactly which one is the particular cause.
+Furthermore, a bug in the kernel's handling of page faults can easily
+lead to recursive faults, but a ``triple fault'' will cause the CPU to
+reset itself, which is hardly conducive to debugging.
+
+In a case like this, you might appreciate being able to make Bochs
+print out more debug information, such as the exact type of fault that
+occurred.  It's not very hard.  You start by retrieving the source
+code for Bochs 2.1.1 from @uref{http://bochs.sourceforge.net} and
+extracting it into a directory.  Then read
+@file{pintos/src/misc/bochs-2.1.1.patch} and apply the patches needed.
+Then run @file{./configure}, supplying the options you want (some
+suggestions are in the patch file).  Finally, run @command{make}.
+This will compile Bochs and eventually produce a new binary
+@file{bochs}.  To use your @file{bochs} binary with @command{pintos},
+put it in your @env{PATH}, and make sure that it is earlier than
+@file{/usr/class/cs140/i386/bochs}.
+
+Of course, to get any good out of this you'll have to actually modify
+Bochs.  Instructions for doing this are firmly out of the scope of
+this document.  However, if you want to debug page faults as suggested
+above, a good place to start adding @code{printf()}s is
+@code{BX_CPU_C::dtranslate_linear()} in @file{cpu/paging.cc}.
+
+@node Debugging Tips
+@section Tips
+
+The page allocator in @file{threads/palloc.c} clears all the bytes in
+pages to @t{0xcc} when they are freed.  Thus, if you see an attempt to
+dereference a pointer like @t{0xcccccccc}, or some other reference to
+@t{0xcc}, there's a good chance you're trying to reuse a page that's
+already been freed.  Also, byte @t{0xcc} is the CPU opcode for
+``invoke interrupt 3,'' so if you see an error like @code{Interrupt
+0x03 (#BP Breakpoint Exception)}, Pintos tried to execute code in a
+freed page.
+
+Similarly, the block allocator in @file{threads/malloc.c} clears all
+the bytes in freed blocks to @t{0xcd}.  The two bytes @t{0xcdcd} are
+a CPU opcode for ``invoke interrupt @t{0xcd},'' so @code{Interrupt
+0xcd (unknown)} is a good sign that you tried to execute code in a
+block freed with @code{free()}.