Explain why it sometimes looks like pass() fails.

diff --git a/doc/debug.texi b/doc/debug.texi
index 6432ca3a1fa530a9a13af7710a4d4f8d3f535ef1..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::           

diff --git a/doc/threads.texi b/doc/threads.texi
index 314ee61ca865aef58c4cb51cc4260eea8a965001..1093f335636dcc13c85e3bebe944129d97c7beae 100644 (file)
--- a/doc/threads.texi
+++ b/doc/threads.texi
@@ -591,6 +591,34 @@ to cause many of the tests to fail.
 @item How do I run the tests?
 
 @xref{Testing}.
+
+@item Why do I get a test failure in @func{pass}?
+
+@anchor{The pass function fails}
+You are probably looking at a backtrace that looks something like this:
+
+@example
+0xc0108810: debug_panic (../../lib/kernel/debug.c:32)
+0xc010a99f: pass (../../tests/threads/tests.c:93)
+0xc010bdd3: test_mlfqs_load_1 (../../tests/threads/mlfqs-load-1.c:33)
+0xc010a8cf: run_test (../../tests/threads/tests.c:51)
+0xc0100452: run_task (../../threads/init.c:283)
+0xc0100536: run_actions (../../threads/init.c:333)
+0xc01000bb: main (../../threads/init.c:137)
+@end example
+
+This is just confusing output from the @command{backtrace} program.  It
+does not actually mean that @func{pass} called @func{debug_panic}.  In
+fact, @func{fail} called @func{debug_panic} (via the @func{PANIC}
+macro).  GCC knows that @func{debug_panic} does not return, because it
+is declared @code{NO_RETURN} (@pxref{Function and Parameter
+Attributes}), so it doesn't include any code in @func{pass} to take
+control when @func{debug_panic} returns.  This means that the return
+address on the stack looks like it is at the beginning of the function
+that happens to follow @func{fail} in memory, which in this case happens
+to be @func{pass}.
+
+@xref{Backtraces}, for more information.
 @end table
 
 @menu