Wordsmithing.

[pintos-anon] / doc / debug.texi

diff --git a/doc/debug.texi b/doc/debug.texi
index 1c6d7a39e584aa4577b58bed2e80a4092e98b70f..bd1aa6af1c601a3e805573550e08a37e21df0b32 100644 (file)
--- a/doc/debug.texi
+++ b/doc/debug.texi
@@ -119,9 +119,15 @@ Alternatively, it could be that the @file{kernel.o} you passed to
 the backtrace.
 
 Sometimes backtraces can be confusing without implying corruption.
-Compiler optimizations can cause surprising behavior.  For example, when
-a function has called another function as its final action (a @dfn{tail
-call}), the calling function may not appear in a backtrace at all.
+Compiler optimizations can cause surprising behavior.  When a function
+has called another function as its final action (a @dfn{tail call}), the
+calling function may not appear in a backtrace at all.  Similarly, when
+function A calls another function B that never returns, the compiler may
+optimize such that an unrelated function C appears in the backtrace
+instead of A.  Function C is simply the function that happens to be in
+memory just after A.  In the threads project, this is commonly seen in
+backtraces for test failures; see @ref{The pass function fails, ,
+@func{pass} Fails}, for more information.
 
 @menu
 * Backtrace Example::           
@@ -164,9 +170,9 @@ The backtrace output would then look something like this:
 0x8048ac8: ?? (??:0)
 @end example
 
-(You will probably not get the same results if you run the command above
-on your own kernel binary, because the source code you compiled from is
-different from the source code that panicked.)
+(You will probably not see exactly the same addresses if you run the
+command above on your own kernel binary, because the source code you
+compiled and the compiler you used are probably different.)
 
 The first line in the backtrace refers to @func{debug_panic}, the
 function that implements kernel panics.  Because backtraces commonly
@@ -250,6 +256,12 @@ gdb kernel.o
 target remote localhost:1234
 @end example
 
+(If the @command{target remote} command fails, then make sure that both
+@command{gdb} and @command{pintos} are running on the same machine by
+running @command{hostname} in each terminal.  If the names printed
+differ, then you need to open a new terminal for @command{gdb} on the
+machine running @command{pintos}.)
+
 Now @command{gdb} is connected to the simulator over a local
 network connection.  You can now issue any normal @command{gdb}
 commands.  If you issue the @samp{c} command, the simulated BIOS will take
@@ -302,6 +314,13 @@ a bug in the original Pintos code.  The first and second
 are quite likely, and you should seriously consider both.  We hope
 that the third is less likely, but it is also possible.
 
+@menu
+* Debugging User Programs::     
+@end menu
+
+@node Debugging User Programs
+@subsection Debugging User Programs
+
 You can also use @command{gdb} to debug a user program running under
 Pintos.  Start by issuing this @command{gdb} command to load the
 program's symbol table: