Explain why it sometimes looks like pass() fails.

[pintos-anon] / doc / debug.texi

diff --git a/doc/debug.texi b/doc/debug.texi
index 1c6d7a39e584aa4577b58bed2e80a4092e98b70f..8fbc7d53bd6b7bdcb16950754de7c47bd8fd70b5 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