Clarifications.

[pintos-anon] / doc / debug.texi

diff --git a/doc/debug.texi b/doc/debug.texi
index 1c6d7a39e584aa4577b58bed2e80a4092e98b70f..ce3e4bd0a35fb6ff38d70374c3cabfde1bab814e 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::           
@@ -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,7 @@ 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.
 
+@anchor{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: